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
cryptoafetch - 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
- Node.js 18 alebo novsi (pouziva vstavany
fetch) - Ucet obchodnika Cost+ -- dashboard.costplus.io
Instalacia
npm install nopayn-node-sdkRychly 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 objednavky3. 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)
| Parameter | Typ | Povinne | Predvolene |
|---|---|---|---|
apiKey | string | Ano | -- |
merchantId | string | Ano | -- |
baseUrl | string | Nie | https://api.nopayn.co.uk |
client.createOrder(params)
Vytvori objednavku cez POST /v1/orders/.
| Parameter | Typ | Povinne | Popis |
|---|---|---|---|
amount | number | áno | Suma v menovej jednotke ISO 4217 meny (napríklad centy pre EUR) |
currency | string | Ano | ISO 4217 kod (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | string | Nie | Vasa interna referencia objednavky |
description | string | Nie | Popis objednavky |
returnUrl | string | Nie | Presmerovanie po uspesnej platbe |
failureUrl | string | Nie | Presmerovanie pri zruseni/exspiracii/chybe |
webhookUrl | string | Nie | Asynchronne notifikacie o zmene stavu |
locale | string | Nie | Jazyk HPP (en-GB, de-DE, nl-NL, atd.) |
paymentMethods | PaymentMethod[] | Nie | Filter platobnych metod HPP |
expirationPeriod | string | Nie | ISO 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
| Stav | Koncovy? | Popis |
|---|---|---|
new | Nie | Objednavka vytvorena |
processing | Nie | Platba prebieha |
completed | Ano | Platba uspesna -- doructe tovar |
cancelled | Ano | Platba zrusena zakaznikom |
expired | Ano | Platobny odkaz vyprsal |
error | Ano | Technicka chyba |
Osvedcene postupy pre webhooky
- Vzdy overujte cez API -- payload webhooku obsahuje len ID objednavky, nikdy nie stav. SDK
verifyWebhook()to robi automaticky. - Vracajte HTTP 200 na potvrdenie prijatia. Akykolvek iny kod spusti az 10 opakovanych pokusov (2 minuty od seba).
- Implementujte zalohu dotazovanie -- pre objednavky starsie ako 10 minut, ktore nedosiahli konecny stav, dotazujte
getOrder()ako bezpecnostnu siet. - Budte idempotentni -- ten isty webhook mozete prijat viackrat.
Testovacie karty
Pouzite tieto karty v testovacom rezime Cost+ (sandbox webova stranka):
| Karta | Cislo | Poznamky |
|---|---|---|
| Visa (uspech) | 4111 1111 1111 1111 | Akekolvek CVV |
| Mastercard (uspech) | 5544 3300 0003 7 | Akekolvek CVV |
| Visa (zamietnutie) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedostatok prostriedkov) | 4111 1111 1111 1151 | Insufficient 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 --buildOtvorte http://localhost:3000 na zobrazenie demo pokladne.
Podpora
Potrebujete pomoc? Kontaktujte nas tym podpory na support@costplus.io.