SDK Node

@drwintech/sandpay est le SDK officiel TypeScript pour Node.js 20+. Il enveloppe l’API HTTP, normalise les erreurs et expose un helper de vérification des signatures webhook.

Prefer a ready-to-run starter? See Stack Builder — il génère un projet Next.js/Express/Hono avec @drwintech/sandpay déjà câblé et vos clés pré-remplies.

Installation

npm install @drwintech/sandpay
# ou
pnpm add @drwintech/sandpay

Import et constructeur

import { SandPay } from "@drwintech/sandpay";

const sp = new SandPay({
  apiKey: process.env.SANDPAY_API_KEY!,
  // baseUrl: "https://api.sandbox.sandpay.dev", // optionnel — défaut: https://api.sandpay.dev
});

Option	Type	Défaut	Description
`apiKey`	string	—	Requis. Clé `sp_sk_test_...`.
`baseUrl`	string	`https://api.sandpay.dev`	URL racine de l’API. Pour pointer un environnement custom.

`payments.create(input)`

Crée un paiement simulé.

const tx = await sp.payments.create({
  amount: 25000,
  currency: "FCFA",
  operator: "orange",
  country: "CI",
  msisdn: "+22507123456",
  reference: "ORDER-2026-A1",
  scenario: "success", // optionnel — défaut: "success"
});

Champ	Type	Requis	Notes
`amount`	number	oui	Entier positif, unité minimale (FCFA = unité entière).
`currency`	string	oui	`FCFA`, `XOF`, `XAF`, `RWF`…
`operator`	`mtn`/`orange`/`moov`/`airtel`	oui	Voir guides opérateurs.
`country`	string (2 lettres)	oui	ISO-3166. `CI`, `BJ`, `TG`, `RW`.
`msisdn`	string	oui	Format E.164 (`+225…`).
`reference`	string	oui	Votre référence interne (idempotence).
`description`	string	non	Description libre (max 200 caractères).
`scenario`	`PaymentScenario`	non	Voir Scénarios.

`payments.get(id)`

const tx = await sp.payments.get("TX_8K3M9F");

Retourne le même objet Payment que create. Lève SandPayApiError avec status: 404 si l’id est inconnu.

`payments.list(params?)`

const page = await sp.payments.list({
  limit: 50,
  country: "CI",
  operator: "orange",
  status: "SUCCESS",
  cursor: previousPage.nextCursor ?? undefined,
});

console.log(page.data.length, page.hasMore, page.nextCursor);

Param	Type	Défaut	Notes
`limit`	number (1–100)	50
`country`	string	—	Filtre 2 lettres.
`operator`	`PaymentOperator`	—
`status`	`PaymentStatus`	—	Voir scénarios pour les 11 valeurs.
`cursor`	string	—	Opaque, fourni par la page précédente.

`webhooks.verify(header, payload, secret)`

Vérifie la signature HMAC-SHA256 d’un webhook. Le payload doit être le corps brut, exactement comme reçu.

const ok = sp.webhooks.verify(
  req.headers["x-sandpay-signature"] as string,
  rawBody,
  process.env.SANDPAY_WEBHOOK_SECRET!,
);

Récupérer le `rawBody`

// app/api/webhooks/sandpay/route.ts
export async function POST(req: Request) {
  const rawBody = await req.text();
  const ok = sp.webhooks.verify(
    req.headers.get("x-sandpay-signature") ?? "",
    rawBody,
    process.env.SANDPAY_WEBHOOK_SECRET!,
  );
  if (!ok) return new Response("invalid", { status: 401 });
  const event = JSON.parse(rawBody);
  // ...
  return Response.json({ received: true });
}

import express from "express";
app.post(
  "/webhooks/sandpay",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const rawBody = req.body.toString("utf8");
    const ok = sp.webhooks.verify(
      req.header("x-sandpay-signature") ?? "",
      rawBody,
      process.env.SANDPAY_WEBHOOK_SECRET!,
    );
    if (!ok) return res.status(401).end();
    const event = JSON.parse(rawBody);
    res.json({ received: true });
  },
);

app.post("/webhooks/sandpay", async (c) => {
  const rawBody = await c.req.text();
  const ok = sp.webhooks.verify(
    c.req.header("x-sandpay-signature") ?? "",
    rawBody,
    process.env.SANDPAY_WEBHOOK_SECRET!,
  );
  if (!ok) return c.text("invalid", 401);
  const event = JSON.parse(rawBody);
  return c.json({ received: true });
});

`webhooks.parseEvent(rawBody)`

Parse un corps webhook déjà vérifié en payload typé WebhookPayload. Appeler après verify(...).

const rawBody = await req.text();
const signature = req.headers.get("x-sandpay-signature") ?? "";

if (!sp.webhooks.verify(signature, rawBody, process.env.SANDPAY_WEBHOOK_SECRET!)) {
  return new Response("invalid signature", { status: 401 });
}

const event = sp.webhooks.parseEvent(rawBody);
// event.event === "payment.completed"
// event.tx_id, event.status, event.amount, etc. — tous typés

Lève une Error si :

le corps n’est pas du JSON valide (Invalid JSON in webhook body),
le corps n’est pas un objet JSON (Webhook body must be a JSON object),
le nom d’événement est inconnu (Unknown webhook event: ...),
un champ requis est manquant ou n’a pas le bon type (Missing or invalid field: ...).

Le contrôle est volontairement minimal — il valide la forme suffisamment pour donner un typage sûr en aval. Pour une validation exhaustive, composer avec zod.

Types exportés

WebhookEventName — union littérale des noms d’événements ("payment.completed" aujourd’hui).
WebhookPayload — interface du payload renvoyé par parseEvent.

`SandPayApiError`

Lancée sur tout statut HTTP non-2xx.

import { SandPay, SandPayApiError } from "@drwintech/sandpay";

try {
  await sp.payments.create({ /* ... */ });
} catch (err) {
  if (err instanceof SandPayApiError) {
    console.error(err.status, err.code, err.message, err.requestId);
    console.error(err.detail); // payload structuré éventuel (erreurs Zod par champ)
  }
}

Propriété	Type	Description
`status`	number	Status HTTP (400, 401, 402, 404, 429, 5xx).
`code`	string	Code machine (voir Erreurs).
`message`	string	Texte humain.
`detail`	unknown	Payload structuré optionnel.
`requestId`	string?	En-tête `X-Request-Id` de la réponse (utile pour le support).

Code source

Le SDK est open source : github.com/htleclerc/sandpay. PRs bienvenues.

Démarrer

Concepts

Intégration

Guides opérateurs

SDKs

Référence API

Installation

Import et constructeur

`payments.create(input)`

`payments.get(id)`

`payments.list(params?)`

`webhooks.verify(header, payload, secret)`

Récupérer le `rawBody`

`webhooks.parseEvent(rawBody)`

Types exportés

`SandPayApiError`

Code source

​Installation

​Import et constructeur

​payments.create(input)

​payments.get(id)

​payments.list(params?)

​webhooks.verify(header, payload, secret)

​Récupérer le rawBody

​webhooks.parseEvent(rawBody)

​Types exportés

​SandPayApiError

​Code source

Installation

Import et constructeur

`payments.create(input)`

`payments.get(id)`

`payments.list(params?)`

`webhooks.verify(header, payload, secret)`

Récupérer le `rawBody`

`webhooks.parseEvent(rawBody)`

Types exportés

`SandPayApiError`

Code source