Node.js / TypeScript

Hivatalos Node.js/TypeScript SDK a Cost+ fizetési átjáróhoz. Egyszerűsíti a HPP (tárolt fizetési oldal) átirányítási folyamatot, a HMAC adatcsomag-aláírást és a webhook ellenőrzést.

Funkciók

Nulla függőség — csak a beépített Node.js crypto és fetch modulokat használja
Teljes TypeScript típusok deklarációs térképekkel
HMAC-SHA256 aláírás generálás és állandó idejű ellenőrzés
Automatikus snake_case/camelCase leképezés az API és az SDK között
Webhook feldolgozás + API-alapú rendelés ellenőrzés
Tesztelve Node.js 18, 20 és 22 verziókkal

Követelmények

Node.js 18 vagy újabb (beépített fetch-et használ)
Cost+ kereskedői fiók — dashboard.costplus.io

Telepítés

npm install nopayn-node-sdk

Gyorsindítás

1. A kliens inicializálása

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. Fizetés létrehozása és átirányítás a HPP-re

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. Webhook kezelése

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

API-referencia

`new NoPaynClient(config)`

Paraméter	Típus	Kötelező	Alapértelmezett
`apiKey`	`string`	Igen	—
`merchantId`	`string`	Igen	—
`baseUrl`	`string`	Nem	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Rendelést hoz létre a POST /v1/orders/ végponton.

Paraméter	Típus	Kötelező	Leírás
`amount`	`number`	Igen	Összeg a legkisebb pénznem-egységben (cent)
`currency`	`string`	Igen	ISO 4217 kód (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nem	Az Ön belső rendelési hivatkozása
`description`	`string`	Nem	Rendelés leírása
`returnUrl`	`string`	Nem	Átirányítás sikeres fizetés után
`failureUrl`	`string`	Nem	Átirányítás törlés/lejárat/hiba esetén
`webhookUrl`	`string`	Nem	Aszinkron állapotváltozási értesítések
`locale`	`string`	Nem	HPP nyelv (`en-GB`, `de-DE`, `nl-NL` stb.)
`paymentMethods`	`PaymentMethod[]`	Nem	HPP módok szűrése
`expirationPeriod`	`string`	Nem	ISO 8601 időtartam (`PT30M`)

Elérhető fizetési módok: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId)`

Rendelés részleteinek lekérdezése a GET /v1/orders/{id}/ végponton.

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

Teljes vagy részleges visszatérítés kiadása a POST /v1/orders/{id}/refunds/ végponton.

`client.generatePaymentUrl(params)`

Kényelmi metódus, amely rendelést hoz létre és visszaadja:

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

HMAC-SHA256 hex aláírást generál. A kanonikus üzenet: ${amount}:${currency}:${orderId}, az API-kulccsal aláírva.

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

HMAC-SHA256 aláírás állandó idejű ellenőrzése. true értéket ad vissza, ha érvényes.

`client.verifyWebhook(rawBody)`

Feldolgozza a webhook törzset, majd meghívja a GET /v1/orders/{id}/ végpontot az aktuális állapot ellenőrzéséhez. Visszaadja:

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

`client.parseWebhookBody(rawBody)`

Feldolgozza és érvényesíti a webhook törzset API-hívás nélkül.

Önálló HMAC segédeszközök

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

Hibakezelés

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

Rendelés állapotok

Állapot	Végleges?	Leírás
`new`	Nem	Rendelés létrehozva
`processing`	Nem	Fizetés folyamatban
`completed`	Igen	Fizetés sikeres — szállítsa az árut
`cancelled`	Igen	Fizetés törölve az ügyfél által
`expired`	Igen	A fizetési link lejárt
`error`	Igen	Technikai hiba

Webhook bevált gyakorlatok

Mindig ellenőrizze az API-n keresztül — a webhook adatcsomag csak a rendelés azonosítóját tartalmazza, soha nem az állapotot. Az SDK verifyWebhook() metódusa ezt automatikusan elvégzi.
Válaszoljon HTTP 200-zal a fogadás nyugtázásához. Bármely más kód legfeljebb 10 újrapróbálkozást vált ki (2 percenként).
Alkalmazzon tartalék lekérdezést — a 10 percnél régebbi, végleges állapotot még el nem ért rendelésekhez kérdezze le a getOrder() metódust biztonsági hálóként.
Legyen idempotens — ugyanazt a webhookot többször is megkaphatja.

Tesztkártyák

Használja ezeket a kártyákat Cost+ teszt módban (sandbox weboldal):

Kártya	Szám	Megjegyzés
Visa (sikeres)	`4111 1111 1111 1111`	Bármely CVV
Mastercard (sikeres)	`5544 3300 0003 7`	Bármely CVV
Visa (elutasítva)	`4111 1111 1111 1105`	Do Not Honor
Visa (elégtelen fedezet)	`4111 1111 1111 1151`	Insufficient Funds

Használjon bármely jövőbeli lejárati dátumot és bármely 3 számjegyű CVC-t.

Demo alkalmazás

Egy Docker-alapú demo alkalmazás található a GitHub tárolóban a teljes fizetési folyamat teszteléséhez:

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

Nyissa meg a http://localhost:3000 címet a demo pénztári oldal megtekintéséhez.

Támogatás

Segítségre van szüksége? Forduljon ügyfélszolgálatunkhoz: support@costplus.io.

On this page