Node.js / TypeScript

Opinbert Node.js/TypeScript SDK fyrir greiðslugátt Cost+. Poenostavlja tok preusmeritve HPP (gostovane greiðslune strani), HMAC podpisovanje koristnih podatkov og staðfesting webhook-ov.

Eiginleikar

Engin dependency — uporablja le vgrajeni Node.js crypto og fetch
Full TypeScript týpur með mapami deklaracij
HMAC-SHA256 býr tilnje podpisov og staðfesting með konstantnim časom
Samodejno preslikavanje snake_case/camelCase med API-jem og SDK-jem
Razčlenjevanje webhook-ov + staðfesting pantana á osnovi API-ja
Prófað á Node.js 18, 20 og 22

Kröfur

Node.js 18 eða nýrri (uporablja vgrajeni fetch)
Söluaðilareikningur Cost+ — dashboard.costplus.io

Uppsetning

npm install nopayn-node-sdk

Flýtiræsing

1. Frumstilltu biðlarann

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 greiðsla og preusmerite á HPP

const result = await nopayn.generatePaymentUrl({
  amount: 1295,            // €12.95 og 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 viðskiptavin
// result.orderUrl   → HPP (viðskiptavinur izbere greiðslumáta)
// result.paymentUrl → neposredna povezava do greiðslumátar prve transakcije
// result.signature  → HMAC-SHA256 til staðfesting
// result.orderId    → NoPayn UUID pantanir

3. Meðhöndlaðu 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') {
    // Uppfylldu pöntunina
  }

  res.sendStatus(200);
});

API tilvísun

`new NoPaynClient(config)`

Parameter	Tip	Obvezno	Privzeto
`apiKey`	`string`	Da	—
`merchantId`	`string`	Da	—
`baseUrl`	`string`	Ne	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Stofnar pöntun gegnum POST /v1/orders/.

Parameter	Tip	Obvezno	Opis
`amount`	`number`	Da	Znesek í najmanjši valutni enoti (centi)
`currency`	`string`	Da	Koda ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Ne	Vaša interna referenca pantanir
`description`	`string`	Ne	Opis pantanir
`returnUrl`	`string`	Ne	Preusmeritev eftir uspešnem greiðsluu
`failureUrl`	`string`	Ne	Preusmeritev ob preklicu/poteku/napaki
`webhookUrl`	`string`	Ne	Asinhrona obvestila o spremembi statusa
`locale`	`string`	Ne	Jezik HPP (`en-GB`, `de-DE`, `nl-NL` itd.)
`paymentMethods`	`PaymentMethod[]`	Ne	Filtriraj metode HPP
`expirationPeriod`	`string`	Ne	Trajanje ISO 8601 (`PT30M`)

Tiltækir greiðslumátar: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId)`

Sækir upplýsingar pöntunar gegnum GET /v1/orders/{id}/.

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

Gefðu út fulla eða hluta endurgreiðslu gegnum POST /v1/orders/{id}/refunds/.

`client.generatePaymentUrl(params)`

Þægileg aðferð, ki ustvari pöntun og vrne:

{
  orderId: string;     // NoPayn UUID pantanir
  orderUrl: string;    // HPP URL
  paymentUrl?: string; // Neposredni greiðsluni URL (prva transakcija)
  signature: string;   // HMAC-SHA256 od amount:currency:orderId
  order: Order;        // Celoten objekt pantanir
}

`client.generateSignature(amount, currency, orderId)`

Býr til HMAC-SHA256 šestnajstiški podpis. Kanonično sporočilo er ${amount}:${currency}:${orderId}, podpisano með API lykillem.

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

Staðfesting HMAC-SHA256 podpisa með konstantnim časom. Vrne true, ef er veljaven.

`client.verifyWebhook(rawBody)`

Greinir telo webhook-a, nato poklief GET /v1/orders/{id}/ til staðfesting dejanskega statusa. Vrne:

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

`client.parseWebhookBody(rawBody)`

Greinir og validira telo webhook-a brez klicanja API-ja.

Sjálfstæð HMAC tól

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

Villum meðhöndlun

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 pantana

Status	Končni?	Opis
`new`	Ne	Pöntun ustvarjeno
`processing`	Ne	Greiðsla í teku
`completed`	Da	Greiðsla uspešno — dostavite blago
`cancelled`	Da	Greiðsla preklicano með strani viðskiptavinar
`expired`	Da	Plačilna povezava er potekla
`error`	Da	Tehnična napaka

Bestu venjur fyrir webhook-a

Vedno preverite gegnum API-ja — koristni podatki webhook-a vsebujejo aðeins ID pantanir, nikoli statusa. SDK-jev verifyWebhook() to naredi samodejno.
Vrnite HTTP 200 til potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
Implementirajte rezervno poizvedovanje — til pantanir, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte getOrder() kot varnostno mrežo.
Vertu idempotent — isti webhook lahþegar prejmete večkrat.

Prófunarkort

Uporabite te kartice í testnem načinu Cost+ (vefsíðu sandboxa):

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

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

Sýnisforrit

Sýnisforrit á osnovi Docker er vključena í GitHub repozitorij til testiranje celotnega greiðslunega 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 til ogled predstavitvene strani til zaključek nakupa.

Aðstoð

Þarftu aðstoð? Hafðu samband við þjónustudeild okkar á support@costplus.io.

On this page