Node.js / TypeScript

Offizielles Node.js/TypeScript SDK für das Cost+ Zahlungsgateway. Vereinfacht den HPP (Hosted Payment Page) Weiterleitungsablauf, die HMAC-Payload-Signierung und die Webhook-Verifizierung.

Funktionen

Keine Abhängigkeiten — verwendet nur die integrierten Node.js Module crypto und fetch
Vollständige TypeScript-Typen mit Declaration Maps
HMAC-SHA256-Signaturgenerierung und zeitkonstante Verifizierung
Automatisches snake_case/camelCase-Mapping zwischen API und SDK
Webhook-Parsing + API-basierte Bestellungsverifizierung
Getestet mit Node.js 18, 20 und 22

Voraussetzungen

Node.js 18 oder neuer (verwendet integriertes fetch)
Ein Cost+ Händlerkonto — dashboard.costplus.io

Installation

npm install nopayn-node-sdk

Schnellstart

1. Client initialisieren

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. Zahlung erstellen und zur HPP weiterleiten

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. Webhook verarbeiten

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

`new NoPaynClient(config)`

Parameter	Typ	Erforderlich	Standard
`apiKey`	`string`	Ja	—
`merchantId`	`string`	Ja	—
`baseUrl`	`string`	Nein	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Erstellt eine Bestellung über POST /v1/orders/.

Parameter	Typ	Erforderlich	Beschreibung
`amount`	`number`	Ja	Betrag in kleinster Währungseinheit (Cent)
`currency`	`string`	Ja	ISO 4217 Code (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nein	Ihre interne Bestellreferenz
`description`	`string`	Nein	Bestellbeschreibung
`returnUrl`	`string`	Nein	Weiterleitung nach erfolgreicher Zahlung
`failureUrl`	`string`	Nein	Weiterleitung bei Abbruch/Ablauf/Fehler
`webhookUrl`	`string`	Nein	Asynchrone Statusänderungs-Benachrichtigungen
`locale`	`string`	Nein	HPP-Sprache (`en-GB`, `de-DE`, `nl-NL` usw.)
`paymentMethods`	`PaymentMethod[]`	Nein	HPP-Methoden filtern
`expirationPeriod`	`string`	Nein	ISO 8601 Dauer (`PT30M`)

Verfügbare Zahlungsmethoden: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId)`

Ruft Bestellungsdetails über GET /v1/orders/{id}/ ab.

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

Stellt eine vollständige oder teilweise Erstattung über POST /v1/orders/{id}/refunds/ aus.

`client.generatePaymentUrl(params)`

Komfortmethode, die eine Bestellung erstellt und zurückgibt:

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

Generiert eine HMAC-SHA256-Hex-Signatur. Die kanonische Nachricht ist ${amount}:${currency}:${orderId}, signiert mit dem API-Schlüssel.

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

Zeitkonstante Verifizierung einer HMAC-SHA256-Signatur. Gibt true zurück, wenn gültig.

`client.verifyWebhook(rawBody)`

Parst den Webhook-Body und ruft dann GET /v1/orders/{id}/ auf, um den tatsächlichen Status zu verifizieren. Gibt zurück:

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

`client.parseWebhookBody(rawBody)`

Parst und validiert einen Webhook-Body ohne API-Aufruf.

Eigenständige HMAC-Hilfsfunktionen

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

Fehlerbehandlung

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

Bestellungsstatus

Status	Endgültig?	Beschreibung
`new`	Nein	Bestellung erstellt
`processing`	Nein	Zahlung in Bearbeitung
`completed`	Ja	Zahlung erfolgreich — Ware liefern
`cancelled`	Ja	Zahlung vom Kunden storniert
`expired`	Ja	Zahlungslink abgelaufen
`error`	Ja	Technischer Fehler

Webhook Best Practices

Immer über die API verifizieren — der Webhook-Payload enthält nur die Bestell-ID, niemals den Status. Die verifyWebhook()-Methode des SDK erledigt dies automatisch.
HTTP 200 zurückgeben, um den Empfang zu bestätigen. Jeder andere Code löst bis zu 10 Wiederholungsversuche aus (im 2-Minuten-Abstand).
Backup-Poller implementieren — für Bestellungen, die älter als 10 Minuten sind und noch keinen Endstatus erreicht haben, getOrder() als Sicherheitsnetz abfragen.
Idempotent sein — Sie können denselben Webhook mehrfach erhalten.

Testkarten

Verwenden Sie diese Karten im Cost+ Testmodus (Sandbox-Website):

Karte	Nummer	Hinweise
Visa (Erfolg)	`4111 1111 1111 1111`	Beliebiger CVV
Mastercard (Erfolg)	`5544 3300 0003 7`	Beliebiger CVV
Visa (abgelehnt)	`4111 1111 1111 1105`	Do Not Honor
Visa (unzureichendes Guthaben)	`4111 1111 1111 1151`	Insufficient Funds

Verwenden Sie ein beliebiges zukünftiges Ablaufdatum und eine beliebige 3-stellige CVC.

Demo-App

Eine Docker-basierte Demo-App ist im GitHub-Repository enthalten, um den vollständigen Zahlungsablauf zu testen:

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

Öffnen Sie http://localhost:3000, um die Demo-Checkout-Seite zu sehen.

Support

Brauchen Sie Hilfe? Kontaktieren Sie unser Support-Team unter support@costplus.io.

On this page