Cost+Docs

Node.js / TypeScript

SDK oifigiúil Node.js do gheata íocaíochta Cost+

SDK oifigiúil Node.js/TypeScript do gheata íocaíochta Cost+. Simpliú an tsreabha atreoraithe HPP (Leathanach Íocaíochta Óstáilte), síniú sonraí HMAC, agus fíorú webhook.

Gnéithe

  • Nialas spleáchas -- ní úsáideann sé ach crypto agus fetch ionsuite Node.js
  • Cineálacha TypeScript iomlána le léarscáileanna dearbhaithe
  • Giniúint sínithe HMAC-SHA256 agus fíorú ama-leanúnaigh
  • Mapáil uathoibríoch snake_case/camelCase idir an API agus SDK
  • Parsáil webhook + fíorú ordaithe bunaithe ar API
  • Tástáilte ar fud Node.js 18, 20, agus 22

Riachtanais

  • Node.js 18 nó níos déanaí (úsáideann sé fetch ionsuite)
  • Cuntas ceannaithe Cost+ -- dashboard.costplus.io

Suiteáil

npm install nopayn-node-sdk

Mearthosnú

1. Túsaigh an Cliant

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. Cruthaigh Íocaíocht agus Atreorófar chuig an 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. Láimhseáil an 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);
});

Tagairt API

new NoPaynClient(config)

ParaiméadarCineálRiachtanachRéamhshocrú
apiKeystringTá--
merchantIdstringTá--
baseUrlstringNílhttps://api.nopayn.co.uk

client.createOrder(params)

Cruthaíonn ordú tríd an POST /v1/orders/.

ParaiméadarCineálRiachtanachCur Síos
amountnumberTáMéid i mionaonad ISO 4217 an airgeadra (mar shampla, cent le haghaidh EUR)
currencystringTáCód ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchantOrderIdstringNílDo thagairt inmheánach ordaithe
descriptionstringNílCur síos ar an ordú
returnUrlstringNílAtreorú tar éis íocaíochta rathúla
failureUrlstringNílAtreorú ar cheallú/éag/earráid
webhookUrlstringNílFógraí athraithe stádais asincrónach
localestringNílTeanga HPP (en-GB, de-DE, nl-NL, srl.)
paymentMethodsPaymentMethod[]NílScag modhanna HPP
expirationPeriodstringNílFad ISO 8601 (PT30M)

Modhanna íocaíochta ar fáil: credit-card, apple-pay, google-pay, vipps-mobilepay

client.getOrder(orderId)

Faigheann sonraí ordaithe tríd an GET /v1/orders/{id}/.

client.createRefund(orderId, amount, description?)

Eisíonn aisíocaíocht iomlán nó pháirteach tríd an POST /v1/orders/{id}/refunds/.

client.generatePaymentUrl(params)

Modh áise a chruthaíonn ordú agus a sheolann ar ais:

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

Gineann síniú HMAC-SHA256 hex. Is é an teachtaireacht chanónta ná ${amount}:${currency}:${orderId}, sínithe leis an eochair API.

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

Fíorú ama-leanúnaigh ar shíniú HMAC-SHA256. Seolann true ar ais má tá sé bailí.

client.verifyWebhook(rawBody)

Parsáileann corp an webhook, ansin glaonn GET /v1/orders/{id}/ chun an stádas iarbhír a fhíorú. Seolann ar ais:

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

client.parseWebhookBody(rawBody)

Parsáileann agus bailíochtaíonn corp webhook gan an API a ghlaoch.

Fóntais HMAC Neamhspleácha

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

Láimhseáil Earráidí

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

Stádais Ordaithe

StádasDeiridh?Cur Síos
newNílOrdú cruthaithe
processingNílÍocaíocht ar siúl
completedTáD'éirigh leis an íocaíocht -- seachaid na hearraí
cancelledTáCheal an custaiméir an íocaíocht
expiredTáD'éag an nasc íocaíochta
errorTáTeip theicniúil

Dea-Chleachtais Webhook

  1. Fíoraigh tríd an API i gcónaí -- ní bhíonn ach aitheantas an ordaithe sa sonraí webhook, ní an stádas riamh. Déanann verifyWebhook() an SDK é seo go huathoibríoch.
  2. Seol HTTP 200 ar ais chun fáiltiú a admháil. Spreagann aon chód eile suas le 10 n-atriail (2 nóiméad eatarthu).
  3. Cuir cúltaca pólaí i bhfeidhm -- d'orduithe atá níos sine ná 10 nóiméad nach bhfuil stádas deiridh bainte amach acu, pólail getOrder() mar líontán sábháilteachta.
  4. Bí idéimpotent -- d'fhéadfá an webhook céanna a fháil arís is arís eile.

Cártaí Tástála

Úsáid na cártaí seo i mód tástála Cost+ (suíomh gréasáin gaineamhchláir):

CártaUimhirNótaí
Visa (rath)4111 1111 1111 1111Aon CVV
Mastercard (rath)5544 3300 0003 7Aon CVV
Visa (diúltaithe)4111 1111 1111 1105Do Not Honor
Visa (cistí neamhleor)4111 1111 1111 1151Insufficient Funds

Úsáid aon dáta éaga amach anseo agus aon CVC 3 dhigit.

Aip Thaispeána

Tá aip thaispeána Docker-bhunaithe san áireamh sa stór GitHub chun an sreabhadh íocaíochta iomlán a thástáil:

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

Oscail http://localhost:3000 chun an leathanach seiceála amach taispeána a fheiceáil.

Tacaíocht

Cabhair ag teastáil? Déan teagmháil lenár bhfoireann tacaíochta ag support@costplus.io.

On this page