Node.js / TypeScript

Offisiell Node.js/TypeScript SDK for Cost+ betalingsgateway. Forenkler HPP (Hosted Payment Page) videresendingsflyten, HMAC-signering av innhold og webhook-verifisering.

Funksjoner

Null avhengigheter — bruker kun innebygde Node.js crypto og fetch
Fulle TypeScript-typer med deklarasjonskart
HMAC-SHA256 signaturgenerering og konstanttids-verifisering
Automatisk snake_case/camelCase-kartlegging mellom API og SDK
Webhook-parsing + API-basert ordreverifisering
Testet på tvers av Node.js 18, 20 og 22

Krav

Node.js 18 eller nyere (bruker innebygd fetch)
En Cost+ forhandlerkonto — dashboard.costplus.io

Installasjon

npm install nopayn-node-sdk

Hurtigstart

1. Initialiser klienten

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. Opprett en betaling og videresend til 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. Håndter webhooken

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

`new NoPaynClient(config)`

Parameter	Type	Påkrevd	Standard
`apiKey`	`string`	Ja	—
`merchantId`	`string`	Ja	—
`baseUrl`	`string`	Nei	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Oppretter en ordre via POST /v1/orders/.

Parameter	Type	Påkrevd	Beskrivelse
`amount`	`number`	Ja	Beløp i minste valutaenhet (øre/cent)
`currency`	`string`	Ja	ISO 4217-kode (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Nei	Din interne ordrereferanse
`description`	`string`	Nei	Ordrebeskrivelse
`returnUrl`	`string`	Nei	Videresending etter vellykket betaling
`failureUrl`	`string`	Nei	Videresending ved avbrudd/utløp/feil
`webhookUrl`	`string`	Nei	Asynkrone statusendringsvarsler
`locale`	`string`	Nei	HPP-språk (`en-GB`, `de-DE`, `nl-NL`, osv.)
`paymentMethods`	`PaymentMethod[]`	Nei	Filtrer HPP-metoder
`expirationPeriod`	`string`	Nei	ISO 8601-varighet (`PT30M`)

Tilgjengelige betalingsmetoder: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId)`

Henter ordredetaljer via GET /v1/orders/{id}/.

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

Utsteder en full eller delvis refusjon via POST /v1/orders/{id}/refunds/.

`client.generatePaymentUrl(params)`

Bekvemmelighetsmetode som oppretter en ordre og returnerer:

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

Genererer en HMAC-SHA256 hex-signatur. Den kanoniske meldingen er ${amount}:${currency}:${orderId}, signert med API-nøkkelen.

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

Konstanttids-verifisering av en HMAC-SHA256-signatur. Returnerer true hvis gyldig.

`client.verifyWebhook(rawBody)`

Parser webhook-kroppen, kaller deretter GET /v1/orders/{id}/ for å verifisere faktisk status. Returnerer:

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

`client.parseWebhookBody(rawBody)`

Parser og validerer en webhook-kropp uten å kalle API-et.

Frittstående HMAC-verktøy

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

Feilhåndtering

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

Ordrestatuser

Status	Endelig?	Beskrivelse
`new`	Nei	Ordre opprettet
`processing`	Nei	Betaling pågår
`completed`	Ja	Betaling vellykket — lever varene
`cancelled`	Ja	Betaling avbrutt av kunden
`expired`	Ja	Betalingslenken utløp
`error`	Ja	Teknisk feil

Beste praksis for webhooks

Verifiser alltid via API-et — webhook-innholdet inneholder kun ordre-ID-en, aldri statusen. SDK-ens verifyWebhook() gjør dette automatisk.
Returner HTTP 200 for å bekrefte mottak. Enhver annen kode utløser opptil 10 nye forsøk (2 minutters mellomrom).
Implementer en reservepoller — for ordrer eldre enn 10 minutter som ikke har nådd en endelig status, poll getOrder() som sikkerhetsnett.
Vær idempotent — du kan motta samme webhook flere ganger.

Testkort

Bruk disse kortene i Cost+ testmodus (sandbox-nettsted):

Kort	Nummer	Merknader
Visa (vellykket)	`4111 1111 1111 1111`	Valgfritt CVV
Mastercard (vellykket)	`5544 3300 0003 7`	Valgfritt CVV
Visa (avvist)	`4111 1111 1111 1105`	Do Not Honor
Visa (utilstrekkelige midler)	`4111 1111 1111 1151`	Insufficient Funds

Bruk en hvilken som helst fremtidig utløpsdato og en hvilken som helst 3-sifret CVC.

Demoapp

En Docker-basert demoapp er inkludert i GitHub-repositoriet for testing av den fullstendige betalingsflyten:

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

Åpne http://localhost:3000 for å se demoutsjekkingssiden.

Kundestøtte

Trenger du hjelp? Kontakt kundestøtteteamet vårt på support@costplus.io.

On this page