Node.js / TypeScript

SDK officiel Node.js/TypeScript pour la passerelle de paiement Cost+. Simplifie le flux de redirection HPP (page de paiement hébergée), la signature de payload HMAC et la vérification des webhooks.

Fonctionnalités

Zéro dépendance — utilise uniquement les modules natifs Node.js crypto et fetch
Types TypeScript complets avec declaration maps
Génération de signature HMAC-SHA256 et vérification en temps constant
Mappage automatique snake_case/camelCase entre l'API et le SDK
Analyse des webhooks + vérification des commandes via l'API
Testé sur Node.js 18, 20 et 22

Prérequis

Node.js 18 ou ultérieur (utilise le fetch natif)
Un compte marchand Cost+ — dashboard.costplus.io

Installation

npm install nopayn-node-sdk

Démarrage rapide

1. Initialiser le client

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. Créer un paiement et rediriger vers la 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. Gérer le 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);
});

Référence API

`new NoPaynClient(config)`

Paramètre	Type	Obligatoire	Par défaut
`apiKey`	`string`	Oui	—
`merchantId`	`string`	Oui	—
`baseUrl`	`string`	Non	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Crée une commande via POST /v1/orders/.

Paramètre	Type	Obligatoire	Description
`amount`	`number`	Oui	Montant dans la plus petite unité monétaire (centimes)
`currency`	`string`	Oui	Code ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Non	Votre référence interne de commande
`description`	`string`	Non	Description de la commande
`returnUrl`	`string`	Non	Redirection après paiement réussi
`failureUrl`	`string`	Non	Redirection en cas d'annulation/expiration/erreur
`webhookUrl`	`string`	Non	Notifications asynchrones de changement de statut
`locale`	`string`	Non	Langue de la HPP (`en-GB`, `de-DE`, `nl-NL`, etc.)
`paymentMethods`	`PaymentMethod[]`	Non	Filtrer les méthodes HPP
`expirationPeriod`	`string`	Non	Durée ISO 8601 (`PT30M`)

Méthodes de paiement disponibles : credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId)`

Récupère les détails de la commande via GET /v1/orders/{id}/.

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

Effectue un remboursement total ou partiel via POST /v1/orders/{id}/refunds/.

`client.generatePaymentUrl(params)`

Méthode utilitaire qui crée une commande et renvoie :

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

Génère une signature HMAC-SHA256 hexadécimale. Le message canonique est ${amount}:${currency}:${orderId}, signé avec la clé API.

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

Vérification en temps constant d'une signature HMAC-SHA256. Renvoie true si valide.

`client.verifyWebhook(rawBody)`

Analyse le corps du webhook, puis appelle GET /v1/orders/{id}/ pour vérifier le statut réel. Renvoie :

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

`client.parseWebhookBody(rawBody)`

Analyse et valide un corps de webhook sans appeler l'API.

Utilitaires HMAC autonomes

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

Gestion des erreurs

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

Statuts des commandes

Statut	Final ?	Description
`new`	Non	Commande créée
`processing`	Non	Paiement en cours
`completed`	Oui	Paiement réussi — livrez les marchandises
`cancelled`	Oui	Paiement annulé par le client
`expired`	Oui	Le lien de paiement a expiré
`error`	Oui	Erreur technique

Bonnes pratiques pour les webhooks

Vérifiez toujours via l'API — le payload du webhook contient uniquement l'identifiant de la commande, jamais le statut. Le verifyWebhook() du SDK le fait automatiquement.
Renvoyez HTTP 200 pour accuser réception. Tout autre code déclenche jusqu'à 10 tentatives (espacées de 2 minutes).
Implémentez un polling de secours — pour les commandes de plus de 10 minutes qui n'ont pas atteint un statut final, interrogez getOrder() comme filet de sécurité.
Soyez idempotent — vous pouvez recevoir le même webhook plusieurs fois.

Cartes de test

Utilisez ces cartes en mode test Cost+ (site web sandbox) :

Carte	Numéro	Notes
Visa (succès)	`4111 1111 1111 1111`	N'importe quel CVV
Mastercard (succès)	`5544 3300 0003 7`	N'importe quel CVV
Visa (refusée)	`4111 1111 1111 1105`	Do Not Honor
Visa (fonds insuffisants)	`4111 1111 1111 1151`	Insufficient Funds

Utilisez n'importe quelle date d'expiration future et n'importe quel CVC à 3 chiffres.

Application de démonstration

Une application de démonstration basée sur Docker est incluse dans le dépôt GitHub pour tester le flux de paiement complet :

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

Ouvrez http://localhost:3000 pour voir la page de démonstration du paiement.

Support

Besoin d'aide ? Contactez notre équipe de support à support@costplus.io.

On this page