Node.js / TypeScript

Oficiālais Node.js/TypeScript SDK Cost+ maksājumu vārtejai. Vienkāršo HPP (mitinātās maksājuma lapas) novirzīšanas plūsmu, HMAC datu parakstīšanu un webhook verifikāciju.

Funkcijas

Nulles atkarības — izmanto tikai iebūvētos Node.js crypto un fetch
Pilni TypeScript tipi ar deklarāciju kartēm
HMAC-SHA256 parakstu ģenerēšana un konstantā laika verifikācija
Automātiska snake_case/camelCase kartēšana starp API un SDK
Webhook parsēšana + API bāzēta pasūtījuma verifikācija
Testēts Node.js 18, 20 un 22

Prasības

Node.js 18 vai jaunāka versija (izmanto iebūvēto fetch)
Cost+ tirgotāja konts — dashboard.costplus.io

Instalācija

npm install nopayn-node-sdk

Ātrais sākums

1. Inicializējiet klientu

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. Izveidojiet maksājumu un novirziet uz 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. Apstrādājiet 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 atsauce

`new NoPaynClient(config)`

Parametrs	Tips	Obligāts	Noklusējums
`apiKey`	`string`	Jā	—
`merchantId`	`string`	Jā	—
`baseUrl`	`string`	Nē	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Izveido pasūtījumu caur POST /v1/orders/.

Parametrs	Tips	Obligāts	Apraksts
`amount`	`number`	Jā	Summa mazākajā valūtas vienībā (centos)
`currency`	`string`	Jā	ISO 4217 kods (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nē	Jūsu iekšējā pasūtījuma atsauce
`description`	`string`	Nē	Pasūtījuma apraksts
`returnUrl`	`string`	Nē	Novirzīšana pēc veiksmīga maksājuma
`failureUrl`	`string`	Nē	Novirzīšana atcelšanas/termiņa beigšanās/kļūdas gadījumā
`webhookUrl`	`string`	Nē	Asinhroniem statusa izmaiņu paziņojumiem
`locale`	`string`	Nē	HPP valoda (`en-GB`, `de-DE`, `nl-NL` utt.)
`paymentMethods`	`PaymentMethod[]`	Nē	Filtrēt HPP metodes
`expirationPeriod`	`string`	Nē	ISO 8601 ilgums (`PT30M`)

Pieejamās maksājumu metodes: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId)`

Iegūst pasūtījuma datus caur GET /v1/orders/{id}/.

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

Veic pilnu vai daļēju atmaksu caur POST /v1/orders/{id}/refunds/.

`client.generatePaymentUrl(params)`

Ērtuma metode, kas izveido pasūtījumu un atgriež:

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

Ģenerē HMAC-SHA256 heksadecimālo parakstu. Kanoniskais ziņojums ir ${amount}:${currency}:${orderId}, parakstīts ar API atslēgu.

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

Konstantā laika HMAC-SHA256 paraksta verifikācija. Atgriež true, ja derīgs.

`client.verifyWebhook(rawBody)`

Parsē webhook saturu, tad izsauc GET /v1/orders/{id}/, lai verificētu faktisko statusu. Atgriež:

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

`client.parseWebhookBody(rawBody)`

Parsē un validē webhook saturu, neizsaucot API.

Atsevišķās HMAC utilītas

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

Kļūdu apstrāde

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

Pasūtījumu statusi

Statuss	Galīgs?	Apraksts
`new`	Nē	Pasūtījums izveidots
`processing`	Nē	Maksājums procesā
`completed`	Jā	Maksājums veiksmīgs — piegādājiet preci
`cancelled`	Jā	Maksājums atcelts klienta
`expired`	Jā	Maksājuma saites termiņš beidzies
`error`	Jā	Tehniska kļūme

Webhook labākā prakse

Vienmēr verificējiet caur API — webhook saturs satur tikai pasūtījuma ID, nekad statusu. SDK verifyWebhook() to dara automātiski.
Atgrieziet HTTP 200, lai apstiprinātu saņemšanu. Jebkurš cits kods izsauc līdz 10 atkārtojumiem (2 minūtes starpā).
Ieviesiet rezerves aptaujātāju — pasūtījumiem, kas vecāki par 10 minūtēm un nav sasnieguši galīgo statusu, aptaujājiet getOrder() kā drošības tīklu.
Esiet idempotents — jūs varat saņemt vienu un to pašu webhook vairākas reizes.

Testa kartes

Izmantojiet šīs kartes Cost+ testa režīmā (sandbox vietne):

Karte	Numurs	Piezīmes
Visa (veiksmīgs)	`4111 1111 1111 1111`	Jebkurš CVV
Mastercard (veiksmīgs)	`5544 3300 0003 7`	Jebkurš CVV
Visa (noraidīts)	`4111 1111 1111 1105`	Do Not Honor
Visa (nepietiekami līdzekļi)	`4111 1111 1111 1151`	Insufficient Funds

Izmantojiet jebkuru nākotnes derīguma termiņu un jebkuru 3 ciparu CVC.

Demo lietotne

Docker bāzēta demo lietotne ir iekļauta GitHub repozitorijā pilnas maksājumu plūsmas testēšanai:

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

Atveriet http://localhost:3000, lai redzētu demo norēķinu lapu.

Atbalsts

Nepieciešama palīdzība? Sazinieties ar mūsu atbalsta komandu: support@costplus.io.

On this page