Node.js / TypeScript

Officiele Node.js/TypeScript SDK voor de Cost+ betaalgateway. Vereenvoudigt de HPP (Hosted Payment Page) doorverwijzingsflow, HMAC-payloadondertekening en webhookverificatie.

Kenmerken

Geen afhankelijkheden — gebruikt alleen ingebouwde Node.js crypto en fetch
Volledige TypeScript-typen met declaration maps
HMAC-SHA256-handtekeninggeneratie en constant-time verificatie
Automatische snake_case/camelCase-mapping tussen de API en SDK
Webhook-parsing + API-gebaseerde bestellingsverificatie
Getest op Node.js 18, 20 en 22

Vereisten

Node.js 18 of hoger (gebruikt ingebouwde fetch)
Een Cost+ handelaarsaccount — dashboard.costplus.io

Installatie

npm install nopayn-node-sdk

Snelstart

1. De client initialiseren

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. Een betaling aanmaken en doorverwijzen naar de 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. De webhook afhandelen

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

`new NoPaynClient(config)`

Parameter	Type	Vereist	Standaard
`apiKey`	`string`	Ja	—
`merchantId`	`string`	Ja	—
`baseUrl`	`string`	Nee	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Maakt een bestelling aan via POST /v1/orders/.

Parameter	Type	Vereist	Beschrijving
`amount`	`number`	Ja	Bedrag in kleinste valuta-eenheid (centen)
`currency`	`string`	Ja	ISO 4217-code (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nee	Uw interne bestellingsreferentie
`description`	`string`	Nee	Bestellingsbeschrijving
`returnUrl`	`string`	Nee	Doorverwijzing na geslaagde betaling
`failureUrl`	`string`	Nee	Doorverwijzing bij annulering/verloop/fout
`webhookUrl`	`string`	Nee	Asynchrone statuswijzigingsmeldingen
`locale`	`string`	Nee	HPP-taal (`en-GB`, `de-DE`, `nl-NL`, enz.)
`paymentMethods`	`PaymentMethod[]`	Nee	HPP-methoden filteren
`expirationPeriod`	`string`	Nee	ISO 8601-duur (`PT30M`)

Beschikbare betaalmethoden: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId)`

Haalt bestellingsdetails op via GET /v1/orders/{id}/.

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

Voert een volledige of gedeeltelijke terugbetaling uit via POST /v1/orders/{id}/refunds/.

`client.generatePaymentUrl(params)`

Hulpmethode die een bestelling aanmaakt en retourneert:

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

Genereert een HMAC-SHA256 hex-handtekening. Het canonieke bericht is ${amount}:${currency}:${orderId}, ondertekend met de API-sleutel.

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

Constant-time verificatie van een HMAC-SHA256-handtekening. Retourneert true als geldig.

`client.verifyWebhook(rawBody)`

Parst de webhook-body en roept vervolgens GET /v1/orders/{id}/ aan om de werkelijke status te verifieren. Retourneert:

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

`client.parseWebhookBody(rawBody)`

Parst en valideert een webhook-body zonder de API aan te roepen.

Standalone HMAC-hulpmiddelen

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

Foutafhandeling

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

Bestellingsstatussen

Status	Definitief?	Beschrijving
`new`	Nee	Bestelling aangemaakt
`processing`	Nee	Betaling wordt verwerkt
`completed`	Ja	Betaling geslaagd — lever de goederen
`cancelled`	Ja	Betaling geannuleerd door klant
`expired`	Ja	Betaallink verlopen
`error`	Ja	Technische storing

Best practices voor webhooks

Verifieer altijd via de API — de webhook-payload bevat alleen het bestelling-ID, nooit de status. De verifyWebhook() van de SDK doet dit automatisch.
Retourneer HTTP 200 om de ontvangst te bevestigen. Elke andere code triggert tot 10 herhaalpogingen (2 minuten tussenpozen).
Implementeer een backup-poller — voor bestellingen ouder dan 10 minuten die nog geen definitieve status hebben bereikt, poll getOrder() als vangnet.
Wees idempotent — u kunt dezelfde webhook meerdere keren ontvangen.

Testkaarten

Gebruik deze kaarten in Cost+ testmodus (sandbox-website):

Kaart	Nummer	Opmerkingen
Visa (geslaagd)	`4111 1111 1111 1111`	Willekeurige CVV
Mastercard (geslaagd)	`5544 3300 0003 7`	Willekeurige CVV
Visa (geweigerd)	`4111 1111 1111 1105`	Do Not Honor
Visa (onvoldoende saldo)	`4111 1111 1111 1151`	Insufficient Funds

Gebruik een willekeurige toekomstige vervaldatum en een willekeurige 3-cijferige CVC.

Demo-app

Een op Docker gebaseerde demo-app is opgenomen in de GitHub-repository om de volledige betalingsflow te 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

Open http://localhost:3000 om de demo-afrekenpagina te zien.

Ondersteuning

Hulp nodig? Neem contact op met ons supportteam via support@costplus.io.

On this page