Node.js / TypeScript

SDK oficial de Node.js/TypeScript 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 — usa solo crypto y fetch integrados de Node.js
Tipos TypeScript completos con mapas de declaracion
Generacion de firma HMAC-SHA256 y verificacion en tiempo constante
Mapeo automatico de snake_case/camelCase entre la API y el SDK
Analisis de webhooks + verificacion de pedidos basada en API
Probado en Node.js 18, 20 y 22

Requisitos

Node.js 18 o posterior (usa fetch integrado)
Una cuenta de comerciante Cost+ — dashboard.costplus.io

Instalacion

npm install nopayn-node-sdk

Inicio rapido

1. Inicializar el cliente

import { NoPaynClient } from 'nopayn-node-sdk';

const nopayn = new NoPaynClient({
  apiKey: 'your-api-key',      // From the NoPayn merchant portal
  merchantId: 'your-project',  // Your project/merchant ID
});

2. Crear un pago y redirigir al HPP

const result = await 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

3. Gestionar el webhook

app.post('/webhook', async (req, res) => {
  const verified = await nopayn.verifyWebhook(JSON.stringify(req.body));

  console.log(verified.order.status); // 'completed', 'cancelled', etc.
  console.log(verified.isFinal);      // true when the order won't change

  if (verified.order.status === 'completed') {
    // Fulfil the order
  }

  res.sendStatus(200);
});

Referencia de la API

`new NoPaynClient(config)`

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

`client.createOrder(params)`

Crea un pedido via POST /v1/orders/.

Parametro	Tipo	Obligatorio	Descripcion
`amount`	`number`	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`	`PaymentMethod[]`	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(orderId)`

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

`client.createRefund(orderId, amount, description?)`

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

`client.generatePaymentUrl(params)`

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: Order;        // Full order object
}

`client.generateSignature(amount, currency, orderId)`

Genera una firma HMAC-SHA256 en hexadecimal. El mensaje canonico es ${amount}:${currency}:${orderId}, firmado con la clave API.

`client.verifySignature(amount, currency, orderId, signature)`

Verificacion en tiempo constante de una firma HMAC-SHA256. Devuelve true si es valida.

`client.verifyWebhook(rawBody)`

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

{
  orderId: string;
  order: Order;     // Verified via API
  isFinal: boolean; // true for completed/cancelled/expired/error
}

`client.parseWebhookBody(rawBody)`

Analiza y valida un cuerpo de webhook sin llamar a la API.

Utilidades HMAC independientes

import { generateSignature, verifySignature } from 'nopayn-node-sdk';

const sig = generateSignature('your-api-key', 1295, 'EUR', 'order-uuid');
const ok  = verifySignature('your-api-key', 1295, 'EUR', 'order-uuid', sig);

Gestion de errores

import { NoPaynApiError, NoPaynError, NoPaynWebhookError } from 'nopayn-node-sdk';

try {
  await nopayn.createOrder({ amount: 100, currency: 'EUR' });
} catch (err) {
  if (err instanceof NoPaynApiError) {
    console.error(err.statusCode); // 401, 400, etc.
    console.error(err.errorBody);  // Raw API error response
  } else if (err instanceof NoPaynError) {
    console.error(err.message);    // 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:

cd demo

cat > .env << EOF
NOPAYN_API_KEY=your-api-key
NOPAYN_MERCHANT_ID=your-merchant-id
PUBLIC_URL=http://localhost:3000
EOF

docker compose up --build

Abre http://localhost:3000 para ver la pagina de checkout de demostracion.

Soporte

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

On this page