Cost+Docs

Node.js / TypeScript

SDK uffiċjali ta' Node.js għall-gateway tal-ħlas Cost+

SDK uffiċjali ta' Node.js/TypeScript għall-gateway tal-ħlas Cost+. Jissimplifika l-flusso ta' redirect tal-HPP (Paġna ta' Ħlas Ospitata), il-firma tal-payload HMAC, u l-verifika tal-webhooks.

Karatteristiċi

  • Żero dipendenzi — juża biss crypto u fetch integrati f'Node.js
  • Tipi sħaħ ta' TypeScript b'mapep tad-dikjarazzjonijiet
  • Ġenerazzjoni ta' firma HMAC-SHA256 u verifika b'ħin kostanti
  • Mappa awtomatika ta' snake_case/camelCase bejn l-API u l-SDK
  • Ipparsjar tal-webhooks + verifika tal-ordni bbażata fuq l-API
  • Ittestjat fuq Node.js 18, 20, u 22

Rekwiżiti

Installazzjoni

npm install nopayn-node-sdk

Bidu Malajr

1. Inizjalizza l-Klijent

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

const nopayn = new NoPaynClient({
  apiKey: 'your-api-key',      // Mill-portal tal-kummerċjant NoPayn
  merchantId: 'your-project',  // L-ID tal-proġett/kummerċjant tiegħek
});

2. Oħloq Ħlas u Irridirezzjona lejn il-HPP

const result = await nopayn.generatePaymentUrl({
  amount: 1295,            // €12.95 f'ċenteżmi
  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',
});

// Irridirezzjona l-klijent
// result.orderUrl   → HPP (il-klijent jagħżel il-metodu ta' ħlas)
// result.paymentUrl → link dirett lejn il-metodu ta' ħlas tal-ewwel tranżazzjoni
// result.signature  → HMAC-SHA256 għall-verifika
// result.orderId    → UUID tal-ordni NoPayn

3. Ittratta l-Webhook

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

  console.log(verified.order.status); // 'completed', 'cancelled', eċċ.
  console.log(verified.isFinal);      // true meta l-ordni ma tinbidilx aktar

  if (verified.order.status === 'completed') {
    // Issodisfa l-ordni
  }

  res.sendStatus(200);
});

Referenza tal-API

new NoPaynClient(config)

ParametruTipMeħtieġDefault
apiKeystringIva—
merchantIdstringIva—
baseUrlstringLehttps://api.nopayn.co.uk

client.createOrder(params)

Joħloq ordni permezz ta' POST /v1/orders/.

ParametruTipMeħtieġDeskrizzjoni
amountnumberIvaAmmont fl-unità minuri ISO 4217 tal-munita (per eżempju, ċenteżmi għal EUR)
currencystringIvaKodiċi ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchantOrderIdstringLeIr-referenza interna tal-ordni tiegħek
descriptionstringLeDeskrizzjoni tal-ordni
returnUrlstringLeRedirect wara ħlas li rnexxielu
failureUrlstringLeRedirect fuq kanċellazzjoni/skadenza/żball
webhookUrlstringLeNotifiki asinkroni ta' bidla fl-istatus
localestringLeLingwa tal-HPP (en-GB, de-DE, nl-NL, eċċ.)
paymentMethodsPaymentMethod[]LeIffiltra l-metodi tal-HPP
expirationPeriodstringLeTul ta' żmien ISO 8601 (PT30M)

Metodi ta' ħlas disponibbli: credit-card, apple-pay, google-pay, vipps-mobilepay

client.getOrder(orderId)

Jiġbed id-dettalji tal-ordni permezz ta' GET /v1/orders/{id}/.

client.createRefund(orderId, amount, description?)

Joħroġ rifużjoni sħiħa jew parzjali permezz ta' POST /v1/orders/{id}/refunds/.

client.generatePaymentUrl(params)

Metodu ta' konvenjenza li joħloq ordni u jirritorna:

{
  orderId: string;     // UUID tal-ordni NoPayn
  orderUrl: string;    // URL tal-HPP
  paymentUrl?: string; // URL ta' ħlas dirett (l-ewwel tranżazzjoni)
  signature: string;   // HMAC-SHA256 ta' amount:currency:orderId
  order: Order;        // Oġġett sħiħ tal-ordni
}

client.generateSignature(amount, currency, orderId)

Jiġġenera firma HMAC-SHA256 hex. Il-messaġġ kanoniku huwa ${amount}:${currency}:${orderId}, iffirmat biċ-ċavetta API.

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

Verifika b'ħin kostanti ta' firma HMAC-SHA256. Tirritorna true jekk valida.

client.verifyWebhook(rawBody)

Jipparsja l-korp tal-webhook, imbagħad isejjaħ GET /v1/orders/{id}/ biex jivverifika l-istatus attwali. Jirritorna:

{
  orderId: string;
  order: Order;     // Ivverifikata permezz tal-API
  isFinal: boolean; // true għal completed/cancelled/expired/error
}

client.parseWebhookBody(rawBody)

Jipparsja u jivvalida korp tal-webhook mingħajr ma jsejjaħ l-API.

Utilitajiet HMAC Standalone

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

Trattar tal-Żbalji

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, eċċ.
    console.error(err.errorBody);  // Risposta ta' żball mhux ipproċessata tal-API
  } else if (err instanceof NoPaynError) {
    console.error(err.message);    // Żball tan-network jew tal-ipparsjar
  }
}

Statuses tal-Ordni

StatusFinali?Deskrizzjoni
newLeOrdni maħluqa
processingLeĦlas qed isir
completedIvaĦlas irnexxielu — ikkonsenja l-prodotti
cancelledIvaĦlas ikkanċellat mill-klijent
expiredIvaLink tal-ħlas skada
errorIvaFalliment tekniku

L-Aħjar Prattiċi għall-Webhooks

  1. Dejjem ivverifika permezz tal-API — il-payload tal-webhook fih biss l-ID tal-ordni, qatt l-istatus. Il-verifyWebhook() tal-SDK jagħmel dan awtomatikament.
  2. Irritorna HTTP 200 biex tikkonferma r-riċevuta. Kwalunkwe kodiċi ieħor jiskatta sa 10 retries (2 minuti bejn xulxin).
  3. Implimenta backup poller — għal ordnijiet itqal minn 10 minuti li għadhom ma laħqux status finali, agħmel polling ta' getOrder() bħala xibka ta' sigurtà.
  4. Kun idempotenti — tista' tirċievi l-istess webhook aktar minn darba.

Karti tat-Test

Uża dawn il-karti f'modalità tat-test ta' Cost+ (website sandbox):

KartaNumruNoti
Visa (suċċess)4111 1111 1111 1111Kwalunkwe CVV
Mastercard (suċċess)5544 3300 0003 7Kwalunkwe CVV
Visa (miċħuda)4111 1111 1111 1105Do Not Honor
Visa (fondi insuffiċjenti)4111 1111 1111 1151Insufficient Funds

Uża kwalunkwe data ta' skadenza futura u kwalunkwe CVC ta' 3 ċifri.

App Demo

App demo bbażata fuq Docker hija inkluża fir-repożitorju ta' GitHub għall-ittestjar tal-flusso sħiħ tal-ħlas:

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

Iftaħ http://localhost:3000 biex tara l-paġna demo tal-checkout.

Appoġġ

Għandek bżonn l-għajnuna? Ikkuntattja t-tim tal-appoġġ tagħna fuq support@costplus.io.

On this page