Node.js / TypeScript

Oficjalny SDK Node.js/TypeScript dla bramki płatności Cost+. Upraszcza przepływ przekierowań HPP (hostowanej strony płatności), podpisywanie HMAC i weryfikację webhooków.

Funkcje

Zero zależności — używa tylko wbudowanych crypto i fetch Node.js
Pełne typy TypeScript z mapami deklaracji
Generowanie podpisów HMAC-SHA256 i weryfikacja w stałym czasie
Automatyczne mapowanie snake_case/camelCase między API a SDK
Parsowanie webhooków + weryfikacja zamówienia przez API
Testowany na Node.js 18, 20 i 22

Wymagania

Node.js 18 lub nowszy (używa wbudowanego fetch)
Konto sprzedawcy Cost+ — dashboard.costplus.io

Instalacja

npm install nopayn-node-sdk

Szybki start

1. Zainicjalizuj klienta

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

const nopayn = new NoPaynClient({
  apiKey: 'your-api-key',      // Z portalu sprzedawcy NoPayn
  merchantId: 'your-project',  // Twój identyfikator projektu/sprzedawcy
});

2. Utwórz płatność i przekieruj na HPP

const result = await nopayn.generatePaymentUrl({
  amount: 1295,            // 12,95 EUR w centach
  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',
});

// Przekieruj klienta
// result.orderUrl   → HPP (klient wybiera metodę płatności)
// result.paymentUrl → bezpośredni link do metody płatności pierwszej transakcji
// result.signature  → HMAC-SHA256 do weryfikacji
// result.orderId    → UUID zamówienia NoPayn

3. Obsłuż webhook

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

  console.log(verified.order.status); // 'completed', 'cancelled', itp.
  console.log(verified.isFinal);      // true gdy zamówienie się nie zmieni

  if (verified.order.status === 'completed') {
    // Zrealizuj zamówienie
  }

  res.sendStatus(200);
});

Dokumentacja API

`new NoPaynClient(config)`

Parametr	Typ	Wymagany	Domyślnie
`apiKey`	`string`	Tak	—
`merchantId`	`string`	Tak	—
`baseUrl`	`string`	Nie	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Tworzy zamówienie przez POST /v1/orders/.

Parametr	Typ	Wymagany	Opis
`amount`	`number`	Tak	Kwota w najmniejszej jednostce waluty (centy)
`currency`	`string`	Tak	Kod ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nie	Twoja wewnętrzna referencja zamówienia
`description`	`string`	Nie	Opis zamówienia
`returnUrl`	`string`	Nie	Przekierowanie po pomyślnej płatności
`failureUrl`	`string`	Nie	Przekierowanie przy anulowaniu/wygaśnięciu/błędzie
`webhookUrl`	`string`	Nie	Asynchroniczne powiadomienia o zmianie statusu
`locale`	`string`	Nie	Język HPP (`en-GB`, `de-DE`, `nl-NL`, itp.)
`paymentMethods`	`PaymentMethod[]`	Nie	Filtruj metody HPP
`expirationPeriod`	`string`	Nie	Czas trwania ISO 8601 (`PT30M`)

Dostępne metody płatności: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId)`

Pobiera szczegóły zamówienia przez GET /v1/orders/{id}/.

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

Dokonuje pełnego lub częściowego zwrotu przez POST /v1/orders/{id}/refunds/.

`client.generatePaymentUrl(params)`

Metoda pomocnicza, która tworzy zamówienie i zwraca:

{
  orderId: string;     // UUID zamówienia NoPayn
  orderUrl: string;    // URL HPP
  paymentUrl?: string; // Bezpośredni URL płatności (pierwsza transakcja)
  signature: string;   // HMAC-SHA256 z amount:currency:orderId
  order: Order;        // Pełny obiekt zamówienia
}

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

Generuje podpis HMAC-SHA256 w formacie hex. Kanoniczny komunikat to ${amount}:${currency}:${orderId}, podpisany kluczem API.

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

Weryfikacja HMAC-SHA256 w stałym czasie. Zwraca true, jeśli prawidłowy.

`client.verifyWebhook(rawBody)`

Parsuje treść webhooka, następnie wywołuje GET /v1/orders/{id}/, aby zweryfikować rzeczywisty status. Zwraca:

{
  orderId: string;
  order: Order;     // Zweryfikowane przez API
  isFinal: boolean; // true dla completed/cancelled/expired/error
}

`client.parseWebhookBody(rawBody)`

Parsuje i waliduje treść webhooka bez wywoływania API.

Samodzielne narzędzia HMAC

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

Obsługa błędów

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, itp.
    console.error(err.errorBody);  // Surowa odpowiedź błędu API
  } else if (err instanceof NoPaynError) {
    console.error(err.message);    // Błąd sieci lub parsowania
  }
}

Statusy zamówień

Status	Końcowy?	Opis
`new`	Nie	Zamówienie utworzone
`processing`	Nie	Płatność w toku
`completed`	Tak	Płatność zakończona sukcesem — wydaj towar
`cancelled`	Tak	Płatność anulowana przez klienta
`expired`	Tak	Link płatności wygasł
`error`	Tak	Błąd techniczny

Najlepsze praktyki dotyczące webhooków

Zawsze weryfikuj przez API — treść webhooka zawiera tylko identyfikator zamówienia, nigdy status. verifyWebhook() SDK robi to automatycznie.
Zwracaj HTTP 200, aby potwierdzić odbiór. Każdy inny kod powoduje do 10 ponowień (co 2 minuty).
Zaimplementuj zapasowe odpytywanie — dla zamówień starszych niż 10 minut, które nie osiągnęły końcowego statusu, odpytuj getOrder() jako zabezpieczenie.
Bądź idempotentny — możesz otrzymać ten sam webhook wielokrotnie.

Karty testowe

Użyj tych kart w trybie testowym Cost+ (strona testowa):

Karta	Numer	Uwagi
Visa (sukces)	`4111 1111 1111 1111`	Dowolny CVV
Mastercard (sukces)	`5544 3300 0003 7`	Dowolny CVV
Visa (odrzucona)	`4111 1111 1111 1105`	Do Not Honor
Visa (brak środków)	`4111 1111 1111 1151`	Insufficient Funds

Użyj dowolnej przyszłej daty ważności i dowolnego 3-cyfrowego CVC.

Aplikacja demonstracyjna

Aplikacja demonstracyjna oparta na Dockerze jest dołączona w repozytorium GitHub do testowania pełnego przepływu płatności:

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

Otwórz http://localhost:3000, aby zobaczyć demonstracyjną stronę kasy.

Wsparcie

Potrzebujesz pomocy? Skontaktuj się z naszym zespołem wsparcia pod adresem support@costplus.io.

On this page