Cost+Docs

Node.js / TypeScript

Oficialne Node.js SDK pre platobnu branu Cost+

Oficialne Node.js/TypeScript SDK pre platobnu branu Cost+. Zjednodusuje proces presmerovania HPP (Hosted Payment Page), HMAC podpisovanie payloadov a overovanie webhookov.

Funkcie

  • Ziadne zavislosti -- pouziva len vstavane Node.js crypto a fetch
  • Uplne TypeScript typy s mapami deklaracii
  • HMAC-SHA256 generovanie podpisov a overovanie v konstantnom case
  • Automaticke mapovanie snake_case/camelCase medzi API a SDK
  • Parsovanie webhookov + overovanie objednavok na zaklade API
  • Testovane na Node.js 18, 20 a 22

Poziadavky

Instalacia

npm install nopayn-node-sdk

Rychly start

1. Inicializacia klienta

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

const nopayn = new NoPaynClient({
  apiKey: 'your-api-key',      // Z obchodneho portalu NoPayn
  merchantId: 'your-project',  // Vase ID projektu/obchodnika
});

2. Vytvorenie platby a presmerovanie na HPP

const result = await nopayn.generatePaymentUrl({
  amount: 1295,            // €12,95 v centoch
  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',
});

// Presmerujte zakaznika
// result.orderUrl   → HPP (zakaznik si vyberie platobnu metodu)
// result.paymentUrl → priamy odkaz na platobnu metodu prvej transakcie
// result.signature  → HMAC-SHA256 na overenie
// result.orderId    → NoPayn UUID objednavky

3. Spracovanie webhooku

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

  console.log(verified.order.status); // 'completed', 'cancelled', atd.
  console.log(verified.isFinal);      // true, ked sa objednavka uz nezmeni

  if (verified.order.status === 'completed') {
    // Vybavte objednavku
  }

  res.sendStatus(200);
});

API referencia

new NoPaynClient(config)

ParameterTypPovinnePredvolene
apiKeystringAno--
merchantIdstringAno--
baseUrlstringNiehttps://api.nopayn.co.uk

client.createOrder(params)

Vytvori objednavku cez POST /v1/orders/.

ParameterTypPovinnePopis
amountnumberánoSuma v menovej jednotke ISO 4217 meny (napríklad centy pre EUR)
currencystringAnoISO 4217 kod (EUR, GBP, USD, NOK, SEK)
merchantOrderIdstringNieVasa interna referencia objednavky
descriptionstringNiePopis objednavky
returnUrlstringNiePresmerovanie po uspesnej platbe
failureUrlstringNiePresmerovanie pri zruseni/exspiracii/chybe
webhookUrlstringNieAsynchronne notifikacie o zmene stavu
localestringNieJazyk HPP (en-GB, de-DE, nl-NL, atd.)
paymentMethodsPaymentMethod[]NieFilter platobnych metod HPP
expirationPeriodstringNieISO 8601 trvanie (PT30M)

Dostupne platobne metody: credit-card, apple-pay, google-pay, vipps-mobilepay

client.getOrder(orderId)

Ziskanie podrobnosti objednavky cez GET /v1/orders/{id}/.

client.createRefund(orderId, amount, description?)

Vydanie uplneho alebo ciastocneho vratenia cez POST /v1/orders/{id}/refunds/.

client.generatePaymentUrl(params)

Pomocna metoda, ktora vytvori objednavku a vrati:

{
  orderId: string;     // NoPayn UUID objednavky
  orderUrl: string;    // HPP URL
  paymentUrl?: string; // Priama platobna URL (prva transakcia)
  signature: string;   // HMAC-SHA256 z amount:currency:orderId
  order: Order;        // Uplny objekt objednavky
}

client.generateSignature(amount, currency, orderId)

Generuje HMAC-SHA256 hex podpis. Kanonicka sprava je ${amount}:${currency}:${orderId}, podpisana API klucom.

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

Overovanie HMAC-SHA256 podpisu v konstantnom case. Vracia true, ak je platny.

client.verifyWebhook(rawBody)

Parsuje telo webhooku, potom vola GET /v1/orders/{id}/ na overenie skutocneho stavu. Vracia:

{
  orderId: string;
  order: Order;     // Overene cez API
  isFinal: boolean; // true pre completed/cancelled/expired/error
}

client.parseWebhookBody(rawBody)

Parsuje a validuje telo webhooku bez volania API.

Samostatne HMAC nastroje

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

Spracovanie chyb

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, atd.
    console.error(err.errorBody);  // Surova API chybova odpoved
  } else if (err instanceof NoPaynError) {
    console.error(err.message);    // Sietova alebo parsovania chyba
  }
}

Stavy objednavok

StavKoncovy?Popis
newNieObjednavka vytvorena
processingNiePlatba prebieha
completedAnoPlatba uspesna -- doructe tovar
cancelledAnoPlatba zrusena zakaznikom
expiredAnoPlatobny odkaz vyprsal
errorAnoTechnicka chyba

Osvedcene postupy pre webhooky

  1. Vzdy overujte cez API -- payload webhooku obsahuje len ID objednavky, nikdy nie stav. SDK verifyWebhook() to robi automaticky.
  2. Vracajte HTTP 200 na potvrdenie prijatia. Akykolvek iny kod spusti az 10 opakovanych pokusov (2 minuty od seba).
  3. Implementujte zalohu dotazovanie -- pre objednavky starsie ako 10 minut, ktore nedosiahli konecny stav, dotazujte getOrder() ako bezpecnostnu siet.
  4. Budte idempotentni -- ten isty webhook mozete prijat viackrat.

Testovacie karty

Pouzite tieto karty v testovacom rezime Cost+ (sandbox webova stranka):

KartaCisloPoznamky
Visa (uspech)4111 1111 1111 1111Akekolvek CVV
Mastercard (uspech)5544 3300 0003 7Akekolvek CVV
Visa (zamietnutie)4111 1111 1111 1105Do Not Honor
Visa (nedostatok prostriedkov)4111 1111 1111 1151Insufficient Funds

Pouzite akykolvek buduci datum exspiracie a akykolvek 3-ciselny CVC.

Demo aplikacia

Demo aplikacia na baze Dockeru je zahrnuta v GitHub repozitari na testovanie uplneho platobneho procesu:

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

Otvorte http://localhost:3000 na zobrazenie demo pokladne.

Podpora

Potrebujete pomoc? Kontaktujte nas tym podpory na support@costplus.io.

On this page