PHP

SDK oficial de PHP para la pasarela de pago Cost+. Simplifica el flujo de redireccion HPP (pagina de pago alojada), la firma de payloads HMAC y la verificacion de webhooks.

Caracteristicas

Sin dependencias externas — usa solo extensiones PHP integradas (curl, json, hash)
PHP 8.1+ con propiedades readonly, argumentos con nombre y tipos estrictos
Generacion de firma HMAC-SHA256 y verificacion en tiempo constante via hash_equals
Mapeo automatico de snake_case/camelCase entre la API y el SDK
Analisis de webhooks + verificacion de pedidos basada en API
Probado en PHP 8.1, 8.2 y 8.3

Requisitos

PHP 8.1 o posterior
Extensiones: curl, json (ambas incluidas en PHP estandar)
Una cuenta de comerciante Cost+ — dashboard.costplus.io

Instalacion

composer require nopayn/sdk

Inicio rapido

1. Inicializar el cliente

use NoPayn\NoPaynClient;

$nopayn = new NoPaynClient([
    'apiKey'     => 'your-api-key',
    'merchantId' => 'your-project',
]);

2. Crear un pago y redirigir al HPP

$result = $nopayn->generatePaymentUrl([
    'amount'           => 1295,            // €12.95 in cents
    'currency'         => 'EUR',
    'merchantOrderId'  => 'ORDER-001',
    'description'      => 'Premium Widget',
    'returnUrl'        => 'https://shop.example.com/success',
    'failureUrl'       => 'https://shop.example.com/failure',
    'webhookUrl'       => 'https://shop.example.com/webhook',
    'locale'           => 'en-GB',
    'expirationPeriod' => 'PT30M',
]);

// Redirect the customer
// $result['orderUrl']   → HPP (customer picks payment method)
// $result['paymentUrl'] → direct link to the first transaction's payment method
// $result['signature']  → HMAC-SHA256 for verification
// $result['orderId']    → NoPayn order UUID
header('Location: ' . ($result['paymentUrl'] ?? $result['orderUrl']));

3. Gestionar el webhook

$rawBody  = file_get_contents('php://input');
$verified = $nopayn->verifyWebhook($rawBody);

echo $verified['order']['status']; // 'completed', 'cancelled', etc.
echo $verified['isFinal'];        // true when the order won't change

if ($verified['order']['status'] === 'completed') {
    // Fulfil the order
}

http_response_code(200);

Referencia de la API

`new NoPaynClient(array $config)`

Parametro	Tipo	Obligatorio	Predeterminado
`apiKey`	`string`	Si	—
`merchantId`	`string`	Si	—
`baseUrl`	`string`	No	`https://api.nopayn.co.uk`

`$client->createOrder(array $params): array`

Crea un pedido via POST /v1/orders/.

Parametro	Tipo	Obligatorio	Descripcion
`amount`	`int`	Si	Importe en la unidad monetaria mas pequena (centimos)
`currency`	`string`	Si	Codigo ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	No	Tu referencia interna de pedido
`description`	`string`	No	Descripcion del pedido
`returnUrl`	`string`	No	Redireccion despues de pago exitoso
`failureUrl`	`string`	No	Redireccion en cancelacion/expiracion/error
`webhookUrl`	`string`	No	Notificaciones asincronas de cambio de estado
`locale`	`string`	No	Idioma del HPP (`en-GB`, `de-DE`, `nl-NL`, etc.)
`paymentMethods`	`string[]`	No	Filtrar metodos del HPP
`expirationPeriod`	`string`	No	Duracion ISO 8601 (`PT30M`)

Metodos de pago disponibles: credit-card, apple-pay, google-pay, vipps-mobilepay

`$client->getOrder(string $orderId): array`

Obtiene los detalles del pedido via GET /v1/orders/{id}/.

`$client->createRefund(string $orderId, int $amount, ?string $description = null): array`

Emite un reembolso total o parcial via POST /v1/orders/{id}/refunds/.

`$client->generatePaymentUrl(array $params): array`

Metodo de conveniencia que crea un pedido y devuelve:

[
    'orderId'    => string,   // NoPayn order UUID
    'orderUrl'   => string,   // HPP URL
    'paymentUrl' => ?string,  // Direct payment URL (first transaction)
    'signature'  => string,   // HMAC-SHA256 of amount:currency:orderId
    'order'      => array,    // Full order object
]

`$client->generateSignature(int $amount, string $currency, string $orderId): string`

Genera una firma HMAC-SHA256 en hexadecimal.

`$client->verifySignature(int $amount, string $currency, string $orderId, string $signature): bool`

Verificacion en tiempo constante de una firma HMAC-SHA256.

`$client->verifyWebhook(string $rawBody): array`

Analiza el cuerpo del webhook, luego llama a GET /v1/orders/{id}/ para verificar el estado real.

Utilidades HMAC independientes

use NoPayn\Signature;

$sig = Signature::generate('your-api-key', 1295, 'EUR', 'order-uuid');
$ok  = Signature::verify('your-api-key', 1295, 'EUR', 'order-uuid', $sig);

Gestion de errores

use NoPayn\Exceptions\ApiException;
use NoPayn\Exceptions\NoPaynException;
use NoPayn\Exceptions\WebhookException;

try {
    $nopayn->createOrder(['amount' => 100, 'currency' => 'EUR']);
} catch (ApiException $e) {
    echo $e->getStatusCode(); // 401, 400, etc.
    print_r($e->getErrorBody()); // Raw API error response
} catch (NoPaynException $e) {
    echo $e->getMessage(); // Network or parsing error
}

Estados del pedido

Estado	Final?	Descripcion
`new`	No	Pedido creado
`processing`	No	Pago en curso
`completed`	Si	Pago exitoso — entregar los bienes
`cancelled`	Si	Pago cancelado por el cliente
`expired`	Si	El enlace de pago expiro
`error`	Si	Fallo tecnico

Mejores practicas para webhooks

Verifica siempre via la API — el payload del webhook solo contiene el ID del pedido, nunca el estado. El metodo verifyWebhook() del SDK hace esto automaticamente.
Devuelve HTTP 200 para confirmar la recepcion. Cualquier otro codigo activa hasta 10 reintentos (cada 2 minutos).
Implementa un poller de respaldo — para pedidos de mas de 10 minutos que no hayan alcanzado un estado final, consulta getOrder() como red de seguridad.
Se idempotente — puedes recibir el mismo webhook multiples veces.

Tarjetas de prueba

Usa estas tarjetas en modo de prueba de Cost+ (sitio web sandbox):

Tarjeta	Numero	Notas
Visa (exito)	`4111 1111 1111 1111`	Cualquier CVV
Mastercard (exito)	`5544 3300 0003 7`	Cualquier CVV
Visa (rechazada)	`4111 1111 1111 1105`	Do Not Honor
Visa (fondos insuficientes)	`4111 1111 1111 1151`	Insufficient Funds

Usa cualquier fecha de caducidad futura y cualquier CVC de 3 digitos.

App de demostracion

Se incluye una app de demostracion basada en Docker en el repositorio de GitHub para probar el flujo completo de pago.

Soporte

Necesitas ayuda? Contacta a nuestro equipo de soporte en support@costplus.io.

On this page