Cost+Docs

Node.js / TypeScript

Službeni Node.js SDK za Cost+ platni pristupnik

Službeni Node.js/TypeScript SDK za Cost+ platni pristupnik. Pojednostavljuje tijek preusmjeravanja na HPP (hosted stranicu za plaćanje), HMAC potpisivanje podataka i verifikaciju webhookova.

Značajke

  • Bez ovisnosti — koristi samo ugrađene Node.js crypto i fetch
  • Potpuni TypeScript tipovi s mapama deklaracija
  • HMAC-SHA256 generiranje potpisa i verifikacija konstantnim vremenom
  • Automatsko mapiranje snake_case/camelCase između API-ja i SDK-a
  • Raščlamba webhookova + verifikacija narudžbe temeljena na API-ju
  • Testirano na Node.js 18, 20 i 22

Zahtjevi

Instalacija

npm install nopayn-node-sdk

Brzi početak

1. Inicijalizirajte klijent

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. Stvorite plaćanje i preusmjerite 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',
});

// 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. Obradite 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') {
    // Fulfil the order
  }

  res.sendStatus(200);
});

API referenca

new NoPaynClient(config)

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

client.createOrder(params)

Stvara narudžbu putem POST /v1/orders/.

ParametarTipObaveznoOpis
amountnumberDaIznos u manjoj jedinici ISO 4217 valute (na primjer, centi za EUR)
currencystringDaISO 4217 kod (EUR, GBP, USD, NOK, SEK)
merchantOrderIdstringNeVaša interna referenca narudžbe
descriptionstringNeOpis narudžbe
returnUrlstringNePreusmjeravanje nakon uspješnog plaćanja
failureUrlstringNePreusmjeravanje pri poništenju/isteku/grešci
webhookUrlstringNeAsinkrone obavijesti o promjeni statusa
localestringNeJezik HPP-a (en-GB, de-DE, nl-NL itd.)
paymentMethodsPaymentMethod[]NeFiltriranje HPP načina
expirationPeriodstringNeISO 8601 trajanje (PT30M)

Dostupni načini plaćanja: credit-card, apple-pay, google-pay, vipps-mobilepay

client.getOrder(orderId)

Dohvaća detalje narudžbe putem GET /v1/orders/{id}/.

client.createRefund(orderId, amount, description?)

Izdaje potpuni ili djelomični povrat putem POST /v1/orders/{id}/refunds/.

client.generatePaymentUrl(params)

Praktična metoda koja stvara narudžbu i vraća:

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

Generira HMAC-SHA256 heksadecimalni potpis. Kanonska poruka je ${amount}:${currency}:${orderId}, potpisana API ključem.

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

Verifikacija HMAC-SHA256 potpisa konstantnim vremenom. Vraća true ako je valjan.

client.verifyWebhook(rawBody)

Raščlanjuje tijelo webhooka, zatim poziva GET /v1/orders/{id}/ za provjeru stvarnog statusa. Vraća:

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

client.parseWebhookBody(rawBody)

Raščlanjuje i validira tijelo webhooka bez pozivanja API-ja.

Samostalni HMAC alati

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

Rukovanje greškama

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 narudžbe

StatusKonačan?Opis
newNeNarudžba stvorena
processingNePlaćanje u tijeku
completedDaPlaćanje uspjelo — isporučite robu
cancelledDaPlaćanje poništeno od strane kupca
expiredDaPoveznica za plaćanje je istekla
errorDaTehnički kvar

Najbolje prakse za webhookove

  1. Uvijek provjerite putem API-ja — webhook podaci sadrže samo ID narudžbe, nikada status. SDK-ov verifyWebhook() to radi automatski.
  2. Vratite HTTP 200 za potvrdu primitka. Bilo koji drugi kod pokreće do 10 ponovnih pokušaja (svake 2 minute).
  3. Implementirajte rezervno anketiranje — za narudžbe starije od 10 minuta koje nisu dosegle konačni status, anketirajte getOrder() kao sigurnosnu mrežu.
  4. Budite idempotentni — možete primiti isti webhook više puta.

Testne kartice

Koristite ove kartice u Cost+ testnom načinu (sandbox web stranica):

KarticaBrojNapomene
Visa (uspjeh)4111 1111 1111 1111Bilo koji CVV
Mastercard (uspjeh)5544 3300 0003 7Bilo koji CVV
Visa (odbijena)4111 1111 1111 1105Do Not Honor
Visa (nedovoljna sredstva)4111 1111 1111 1151Insufficient Funds

Koristite bilo koji budući datum isteka i bilo koji 3-znamenkasti CVC.

Demo aplikacija

Docker-bazirana demo aplikacija uključena je u GitHub repozitoriju za testiranje potpunog tijeka plaćanja:

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

Otvorite http://localhost:3000 za prikaz demo stranice blagajne.

Podrška

Trebate pomoć? Obratite se našem timu za podršku na support@costplus.io.

On this page