Node.js / TypeScript

SDK oficial Node.js/TypeScript pentru gateway-ul de plăți Cost+. Simplifică fluxul de redirecționare HPP (pagina de plată găzduită), semnarea HMAC a payload-ului și verificarea webhook-urilor.

Funcționalități

Zero dependențe — folosește doar crypto și fetch integrate în Node.js
Tipuri complete TypeScript cu hărți de declarații
Generare semnătură HMAC-SHA256 și verificare cu timp constant
Mapare automată snake_case/camelCase între API și SDK
Parsare webhook + verificare comenzi bazată pe API
Testat pe Node.js 18, 20 și 22

Cerințe

Node.js 18 sau mai nou (folosește fetch integrat)
Un cont de comerciant Cost+ — dashboard.costplus.io

Instalare

npm install nopayn-node-sdk

Pornire rapidă

1. Inițializați clientul

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. Creați o plată și redirecționați către 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. Gestionați webhook-ul

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);
});

Referință API

`new NoPaynClient(config)`

Parametru	Tip	Obligatoriu	Implicit
`apiKey`	`string`	Da	—
`merchantId`	`string`	Da	—
`baseUrl`	`string`	Nu	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Creează o comandă prin POST /v1/orders/.

Parametru	Tip	Obligatoriu	Descriere
`amount`	`number`	Da	Suma în cea mai mică unitate monetară (cenți)
`currency`	`string`	Da	Cod ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nu	Referința dvs. internă de comandă
`description`	`string`	Nu	Descrierea comenzii
`returnUrl`	`string`	Nu	Redirecționare după plata reușită
`failureUrl`	`string`	Nu	Redirecționare la anulare/expirare/eroare
`webhookUrl`	`string`	Nu	Notificări asincrone de schimbare status
`locale`	`string`	Nu	Limba HPP (`en-GB`, `de-DE`, `nl-NL`, etc.)
`paymentMethods`	`PaymentMethod[]`	Nu	Filtrare metode HPP
`expirationPeriod`	`string`	Nu	Durată ISO 8601 (`PT30M`)

Metode de plată disponibile: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId)`

Preia detaliile comenzii prin GET /v1/orders/{id}/.

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

Emite o rambursare totală sau parțială prin POST /v1/orders/{id}/refunds/.

`client.generatePaymentUrl(params)`

Metodă de convenință care creează o comandă și returnează:

{
  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)`

Generează o semnătură hex HMAC-SHA256. Mesajul canonic este ${amount}:${currency}:${orderId}, semnat cu cheia API.

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

Verificare cu timp constant a unei semnături HMAC-SHA256. Returnează true dacă este validă.

`client.verifyWebhook(rawBody)`

Parsează corpul webhook-ului, apoi apelează GET /v1/orders/{id}/ pentru a verifica statusul real. Returnează:

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

`client.parseWebhookBody(rawBody)`

Parsează și validează un corp webhook fără a apela API-ul.

Utilitare HMAC independente

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);

Gestionarea erorilor

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
  }
}

Statusuri comandă

Status	Final?	Descriere
`new`	Nu	Comandă creată
`processing`	Nu	Plată în curs
`completed`	Da	Plată reușită — livrați marfa
`cancelled`	Da	Plată anulată de client
`expired`	Da	Linkul de plată a expirat
`error`	Da	Eroare tehnică

Bune practici pentru webhook-uri

Verificați întotdeauna prin API — payload-ul webhook conține doar ID-ul comenzii, niciodată statusul. Metoda verifyWebhook() a SDK-ului face acest lucru automat.
Returnați HTTP 200 pentru a confirma recepția. Orice alt cod declanșează până la 10 reîncercări (la 2 minute distanță).
Implementați un poller de rezervă — pentru comenzile mai vechi de 10 minute care nu au ajuns la un status final, interogați getOrder() ca rețea de siguranță.
Fiți idempotent — puteți primi același webhook de mai multe ori.

Carduri de test

Folosiți aceste carduri în modul de test Cost+ (site web sandbox):

Card	Număr	Note
Visa (succes)	`4111 1111 1111 1111`	Orice CVV
Mastercard (succes)	`5544 3300 0003 7`	Orice CVV
Visa (refuzat)	`4111 1111 1111 1105`	Do Not Honor
Visa (fonduri insuficiente)	`4111 1111 1111 1151`	Insufficient Funds

Folosiți orice dată de expirare viitoare și orice CVC de 3 cifre.

Aplicație demo

O aplicație demo bazată pe Docker este inclusă în depozitul GitHub pentru testarea fluxului complet de plată:

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

Deschideți http://localhost:3000 pentru a vedea pagina demo de checkout.

Suport

Aveți nevoie de ajutor? Contactați echipa noastră de suport la support@costplus.io.

On this page