Node.js / TypeScript

Oficialus Node.js/TypeScript SDK Cost+ mokėjimų šliuzui. Supaprastina HPP (mokėjimo puslapio) nukreipimo procesą, HMAC turinio pasirašymą ir webhook patvirtinimą.

Savybės

Jokių priklausomybių — naudoja tik integruotus Node.js crypto ir fetch
Pilni TypeScript tipai su deklaracijų žemėlapiais
HMAC-SHA256 parašo generavimas ir pastovaus laiko patikrinimas
Automatinis snake_case/camelCase atitikimas tarp API ir SDK
Webhook analizė + API pagrįstas užsakymo patikrinimas
Testuota Node.js 18, 20 ir 22 versijose

Reikalavimai

Node.js 18 arba naujesnė (naudoja integruotą fetch)
Cost+ prekybininko paskyra — dashboard.costplus.io

Diegimas

npm install nopayn-node-sdk

Greitas startas

1. Inicializuokite klientą

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. Sukurkite mokėjimą ir nukreipkite į 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. Apdorokite 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 nuoroda

`new NoPaynClient(config)`

Parametras	Tipas	Privalomas	Numatytasis
`apiKey`	`string`	Taip	—
`merchantId`	`string`	Taip	—
`baseUrl`	`string`	Ne	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Sukuria užsakymą per POST /v1/orders/.

Parametras	Tipas	Privalomas	Aprašymas
`amount`	`number`	Taip	Suma mažiausiu valiutos vienetu (centais)
`currency`	`string`	Taip	ISO 4217 kodas (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Ne	Jūsų vidinis užsakymo nuorodos ID
`description`	`string`	Ne	Užsakymo aprašymas
`returnUrl`	`string`	Ne	Nukreipimas po sėkmingo mokėjimo
`failureUrl`	`string`	Ne	Nukreipimas atšaukimo/galiojimo pabaigos/klaidos atveju
`webhookUrl`	`string`	Ne	Asinchroniniai būsenos pakeitimo pranešimai
`locale`	`string`	Ne	HPP kalba (`en-GB`, `de-DE`, `nl-NL` ir kt.)
`paymentMethods`	`PaymentMethod[]`	Ne	Filtruoti HPP mokėjimo būdus
`expirationPeriod`	`string`	Ne	ISO 8601 trukmė (`PT30M`)

Prieinami mokėjimo būdai: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId)`

Gauna užsakymo detales per GET /v1/orders/{id}/.

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

Atlieka pilną arba dalinį grąžinimą per POST /v1/orders/{id}/refunds/.

`client.generatePaymentUrl(params)`

Patogus metodas, kuris sukuria užsakymą ir grąžina:

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

Generuoja HMAC-SHA256 hex parašą. Kanoninė žinutė yra ${amount}:${currency}:${orderId}, pasirašyta API raktu.

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

Pastovaus laiko HMAC-SHA256 parašo patikrinimas. Grąžina true, jei galiojantis.

`client.verifyWebhook(rawBody)`

Analizuoja webhook turinį, tada iškviečia GET /v1/orders/{id}/, kad patikrintų tikrąją būseną. Grąžina:

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

`client.parseWebhookBody(rawBody)`

Analizuoja ir patvirtina webhook turinį nekviečiant API.

Atskiros HMAC priemonės

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

Klaidų tvarkymas

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

Užsakymo būsenos

Būsena	Galutinė?	Aprašymas
`new`	Ne	Užsakymas sukurtas
`processing`	Ne	Mokėjimas vykdomas
`completed`	Taip	Mokėjimas sėkmingas — pristatykite prekes
`cancelled`	Taip	Mokėjimas atšauktas kliento
`expired`	Taip	Mokėjimo nuorodos laikas baigėsi
`error`	Taip	Techninė klaida

Webhook geriausios praktikos

Visada patikrinkite per API — webhook turinys pateikia tik užsakymo ID, niekada būsenos. SDK verifyWebhook() tai atlieka automatiškai.
Grąžinkite HTTP 200, kad patvirtintumėte gavimą. Bet koks kitas kodas suaktyvina iki 10 pakartotinių bandymų (kas 2 minutes).
Įgyvendinkite atsarginį tikrintuvą — užsakymams, senesniems nei 10 minučių, kurie nepasiekė galutinės būsenos, naudokite getOrder() kaip saugos tinklą.
Būkite idempotentiški — galite gauti tą patį webhook kelis kartus.

Testinės kortelės

Naudokite šias korteles Cost+ testavimo režimu (testavimo svetainė):

Kortelė	Numeris	Pastabos
Visa (sėkminga)	`4111 1111 1111 1111`	Bet koks CVV
Mastercard (sėkminga)	`5544 3300 0003 7`	Bet koks CVV
Visa (atmesta)	`4111 1111 1111 1105`	Do Not Honor
Visa (nepakankamos lėšos)	`4111 1111 1111 1151`	Insufficient Funds

Naudokite bet kurią ateities galiojimo datą ir bet kokį 3 skaitmenų CVC.

Demonstracinė programa

Docker pagrįsta demonstracinė programa įtraukta į GitHub saugyklą pilnam mokėjimo proceso testavimui:

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

Atidarykite http://localhost:3000, kad pamatytumėte demonstracinį atsiskaitymo puslapį.

Palaikymas

Reikia pagalbos? Kreipkitės į mūsų palaikymo komandą adresu support@costplus.io.

On this page