Cost+Docs

Node.js / TypeScript

Uradni Node.js SDK za plačilni prehod Cost+

Uradni Node.js/TypeScript SDK za plačilni prehod Cost+. Poenostavlja tok preusmeritve HPP (gostovane plačilne strani), HMAC podpisovanje koristnih podatkov in preverjanje webhook-ov.

Lastnosti

  • Brez odvisnosti — uporablja le vgrajeni Node.js crypto in fetch
  • Polni TypeScript tipi z mapami deklaracij
  • HMAC-SHA256 generiranje podpisov in preverjanje s konstantnim časom
  • Samodejno preslikavanje snake_case/camelCase med API-jem in SDK-jem
  • Razčlenjevanje webhook-ov + preverjanje naročil na osnovi API-ja
  • Testirano na Node.js 18, 20 in 22

Zahteve

Namestitev

npm install nopayn-node-sdk

Hitri začetek

1. Inicializirajte odjemalca

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. Ustvarite plačilo in preusmerite na 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',
});

// Preusmerite stranko
// result.orderUrl   → HPP (stranka izbere plačilno metodo)
// result.paymentUrl → neposredna povezava do plačilne metode prve transakcije
// result.signature  → HMAC-SHA256 za preverjanje
// result.orderId    → NoPayn UUID naročila

3. Obdelajte 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') {
    // Izpolnite naročilo
  }

  res.sendStatus(200);
});

API referenca

new NoPaynClient(config)

ParameterTipObveznoPrivzeto
apiKeystringDa—
merchantIdstringDa—
baseUrlstringNehttps://api.nopayn.co.uk

client.createOrder(params)

Ustvari naročilo prek POST /v1/orders/.

ParameterTipObveznoOpis
amountnumberjaZnesek v manjši enoti ISO 4217 valute (na primer centi za EUR)
currencystringDaKoda ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchantOrderIdstringNeVaša interna referenca naročila
descriptionstringNeOpis naročila
returnUrlstringNePreusmeritev po uspešnem plačilu
failureUrlstringNePreusmeritev ob preklicu/poteku/napaki
webhookUrlstringNeAsinhrona obvestila o spremembi statusa
localestringNeJezik HPP (en-GB, de-DE, nl-NL itd.)
paymentMethodsPaymentMethod[]NeFiltriraj metode HPP
expirationPeriodstringNeTrajanje ISO 8601 (PT30M)

Razpoložljive plačilne metode: credit-card, apple-pay, google-pay, vipps-mobilepay

client.getOrder(orderId)

Pridobi podrobnosti naročila prek GET /v1/orders/{id}/.

client.createRefund(orderId, amount, description?)

Izda celotno ali delno vračilo prek POST /v1/orders/{id}/refunds/.

client.generatePaymentUrl(params)

Priročna metoda, ki ustvari naročilo in vrne:

{
  orderId: string;     // NoPayn UUID naročila
  orderUrl: string;    // HPP URL
  paymentUrl?: string; // Neposredni plačilni URL (prva transakcija)
  signature: string;   // HMAC-SHA256 od amount:currency:orderId
  order: Order;        // Celoten objekt naročila
}

client.generateSignature(amount, currency, orderId)

Generira HMAC-SHA256 šestnajstiški podpis. Kanonično sporočilo je ${amount}:${currency}:${orderId}, podpisano z API ključem.

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

Preverjanje HMAC-SHA256 podpisa s konstantnim časom. Vrne true, če je veljaven.

client.verifyWebhook(rawBody)

Razčleni telo webhook-a, nato pokliče GET /v1/orders/{id}/ za preverjanje dejanskega statusa. Vrne:

{
  orderId: string;
  order: Order;     // Preverjeno prek API-ja
  isFinal: boolean; // true za completed/cancelled/expired/error
}

client.parseWebhookBody(rawBody)

Razčleni in validira telo webhook-a brez klicanja API-ja.

Samostojne HMAC pripomočke

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

Obravnava napak

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

Statusi naročil

StatusKončni?Opis
newNeNaročilo ustvarjeno
processingNePlačilo v teku
completedDaPlačilo uspešno — dostavite blago
cancelledDaPlačilo preklicano s strani stranke
expiredDaPlačilna povezava je potekla
errorDaTehnična napaka

Najboljše prakse za webhook-e

  1. Vedno preverite prek API-ja — koristni podatki webhook-a vsebujejo samo ID naročila, nikoli statusa. SDK-jev verifyWebhook() to naredi samodejno.
  2. Vrnite HTTP 200 za potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
  3. Implementirajte rezervno poizvedovanje — za naročila, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte getOrder() kot varnostno mrežo.
  4. Bodite idempotentni — isti webhook lahko prejmete večkrat.

Testne kartice

Uporabite te kartice v testnem načinu Cost+ (spletno mesto peskovnika):

KarticaŠtevilkaOpombe
Visa (uspeh)4111 1111 1111 1111Katerikoli CVV
Mastercard (uspeh)5544 3300 0003 7Katerikoli CVV
Visa (zavrnjena)4111 1111 1111 1105Zavrnitev
Visa (nezadostna sredstva)4111 1111 1111 1151Nezadostna sredstva

Uporabite katerikoli prihodnji datum veljavnosti in katerokoli 3-mestno CVC kodo.

Predstavitvena aplikacija

Predstavitvena aplikacija na osnovi Docker je vključena v GitHub repozitorij za testiranje celotnega plačilnega toka:

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

Odprite http://localhost:3000 za ogled predstavitvene strani za zaključek nakupa.

Podpora

Potrebujete pomoč? Obrnite se na našo ekipo za podporo na support@costplus.io.

On this page