API de paiement pour votre site

1. Depuis Zepargn Business, ouvrez Paramètres puis Intégrations, et créez une clé de test (zp_test_…). Elle fonctionne immédiatement, sans dossier KYB ni activation.
2. Intégrez et testez : les paiements de test se « simulent », aucun argent ne circule.
3. Pour encaisser réellement : dossier KYB approuvé, numéro MTN de reversement renseigné, accès API ouvert par Zepargn, puis créez une clé réelle (zp_live_…).

La clé n’est affichée qu’une fois, à sa création. C’est un secret serveur : jamais dans une page web, une application mobile ou un dépôt public. Cinq clés actives par mode. Révocation immédiate depuis le même écran.

Ouvrir Intégrations dans Zepargn Business

Authorization: Bearer zp_live_0123456789abcdef0123456789abcdef01234567

ou X-Api-Key: zp_live_….

Portées d’une clé :

• payments:write : créer, encaisser, annuler, rembourser ;
• payments:read : lire, lister, solde, événements ;
• webhooks:manage : gérer les webhooks par l’API, jamais accordée par défaut.

Vérifiez votre clé : GET /me renvoie { livemode, business: { id, name, currency, kybStatus, kybLevel, limits, allowedReturnDomains }, apiKey: { id, name, prefix, scopes } }.

Mode test et mode réel. Le mode vient de la clé. Une clé de test ne voit que les paiements de test, une clé réelle que les paiements réels. Chaque paiement et chaque webhook porte livemode: true | false.

POST /payments, portée payments:write.

{
  "amount": 5000,
  "description": "Commande #1042",
  "reference": "CMD-1042",
  "customer": { "name": "Awa K.", "phone": "+2290197111111", "email": "[email protected]" },
  "returnUrl": "https://shop.example.com/retour?order=1042",
  "cancelUrl": "https://shop.example.com/panier",
  "metadata": { "orderId": "1042", "channel": "web" },
  "expiresInMinutes": 30,
  "idempotencyKey": "cmd-1042-v1"
}

Réponse 201 (ou 200 avec replayed: true au rejeu de la même clé d’idempotence) :

{ "success": true, "replayed": false,
  "payment": {
    "id": "6650…", "token": "k3Jd…", "link": "https://zepargn.com/pay/k3Jd…",
    "status": "pending", "livemode": true,
    "amount": 5000, "feeAmount": 150, "feeRate": 3, "customerTotal": 5150, "currency": "XOF",
    "description": "Commande #1042", "reference": "CMD-1042",
    "metadata": { "orderId": "1042", "channel": "web" },
    "returnUrl": "https://shop.example.com/retour?order=1042",
    "cancelUrl": "https://shop.example.com/panier",
    "payerPhone": "+2290197111111", "paidAt": null, "collectionRef": null,
    "refundedAmount": 0, "refundableAmount": 0, "lastRefundAt": null,
    "expiresAt": "2026-11-09T10:30:00.000Z", "createdAt": "2026-11-09T10:00:00.000Z" } }

customerTotal est ce que paie le client, frais inclus. amount est ce que vous touchez. Redirigez le client vers payment.link.

Statuts : pending (en attente), paid (encaissé), cancelled, expired.

Avant de créer : GET /fees?amount=5000 renvoie { feeRate, feeAmount, customerTotal, limits, usedToday, remainingToday, allowed, reason }, qui donne le total exact et dit si la création passerait à cet instant.

Après paiement, la page Zepargn renvoie le client vers returnUrl en ajoutant à sa query string :

?zp_token=k3Jd…&zp_status=paid

S’il renonce, vers cancelUrl avec zp_status=cancelled.

Ne validez jamais une commande sur ce seul retour : il vient du navigateur du client. Faites foi au webhook payment.succeeded ou à GET /payments/:id.

Pour encaisser sans quitter votre site : POST /payments/:id/charge { "phone": "+22901…" } pousse la demande de code PIN MTN sur le téléphone du client et répond 202 { status: "pending", collection: { provider: "mtn", referenceId }, payment }. Le résultat arrive par webhook ou par GET /payments/:id. En mode test : 200 { status: "paid", simulated: true }.

• GET /payments/:idOuToken renvoie { payment }. Un paiement d’une autre entreprise ou de l’autre mode : 404.
• GET /payments?status=&from=&to=&page=&limit= (100 au plus) renvoie { payments, total, page, limit }.
• POST /payments/:id/cancel renvoie { payment } en cancelled, sinon 409 ALREADY_PAID_OR_CANCELLED.

Déclarez une URL https dans Zepargn Business (Intégrations, onglet Webhooks) ou par l’API (portéewebhooks:manage). Vous recevez un secret whsec_…, affiché une fois. Cinq URL au plus.

Requête : POST sur votre URL, Content-Type: application/json, délai 10 s.

X-Zepargn-Event: payment.succeeded
X-Zepargn-Event-Id: 2c1c9e2e-…
X-Zepargn-Timestamp: 1762682400
X-Zepargn-Signature: v1=3f7a…

Corps :

{ "id": "2c1c9e2e-…", "type": "payment.succeeded", "createdAt": "2026-11-09T10:05:12.000Z",
  "businessId": "…", "livemode": true,
  "data": { "…même forme que payment, avec status paid, paidAt, collectionRef, payerPhone" } }

Vérifier la signature

X-Zepargn-Signature vaut v1= suivi de HMAC-SHA256(secret, timestamp + "." + corpsBrut) en hexadécimal, où timestamp est la valeur de X-Zepargn-Timestamp (secondes Unix) etcorpsBrut le corps exactement tel que reçu, avant tout parsing.

const crypto = require('crypto');

function verifyZepargn(rawBody, headers, secret) {
  const ts = headers['x-zepargn-timestamp'];
  const sig = String(headers['x-zepargn-signature'] || '').replace(/^v1=/, '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // 5 min
  const expected = crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  return sig.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
}

function verifyZepargn(string $rawBody, array $headers, string $secret): bool {
  $ts  = $headers['X-Zepargn-Timestamp'] ?? '';
  $sig = preg_replace('/^v1=/', '', $headers['X-Zepargn-Signature'] ?? '');
  if (abs(time() - (int)$ts) > 300) return false;
  $expected = hash_hmac('sha256', $ts . '.' . $rawBody, $secret);
  return hash_equals($expected, $sig);
}

Avec Express, lisez le corps brut (express.raw({ type: 'application/json' })) sur la route du webhook : un corps re-sérialisé ne donne pas la même signature.

Nouveaux essais

Répondez 2xx en moins de 10 s. Toute autre réponse, ou un délai dépassé, déclenche un nouvel essai, huit au total, avec un délai qui double à partir de 30 s : 30 s, 1 min, 2 min, 4 min, 8 min, 16 min, 32 min (environ 2 h au total). Au-delà, la livraison est marquée échouée et reste visible dans Intégrations, onglet Webhooks, bouton Livraisons.

Un même événement a le même id sur toutes vos URL et peut vous parvenir deux fois : traitez-le de façon idempotente (mémorisez les id traités).

Rattrapage

Votre serveur était indisponible ? GET /events?since=2026-11-09T00:00:00Z&type=payment.succeeded donne la liste des événements émis (30 jours d’historique), avec pour chacun l’état de livraison vers chaque URL. POST /webhooks/deliveries/:id/retry (portée webhooks:manage) remet une livraison en file. Le journal ne contient que ce qui a été émis vers au moins une URL : sans webhook déclaré, utilisezGET /payments?status=paid&from=….

Gérer les webhooks par l’API (portée webhooks:manage)

• POST /webhooks { url, events, description? } renvoie 201 { endpoint, secret }
• GET /webhooks, DELETE /webhooks/:id
• POST /webhooks/:id/rotate-secret renvoie un nouveau secret
• POST /webhooks/:id/test renvoie { delivered, statusCode }
• GET /webhooks/:id/deliveries?limit=50

POST /payments/:id/refunds { amount?, reason?, idempotencyKey? }, portée payments:write. Sans amount, tout ce qui reste remboursable est remboursé.

• Le paiement doit être paid. Remboursable jusqu’à customerTotal (ce que le client a payé, frais compris). Les frais Zepargn ne sont pas restitués : vous financez la totalité du remboursement. Minimum 100 FCFA.
• Le remboursement est viré au numéro qui a payé, et prélevé sur vos fonds retenus chez Zepargn (GET /balance, champ available). Si le paiement a déjà été reversé sur votre MoMo et que rien n’est retenu : 409 REFUND_FUNDS_UNAVAILABLE { available, requested }. Zepargn ne prélève jamais votre compte MoMo.
• Un seul remboursement en cours par paiement.

Réponse 201 (200 au rejeu) :

{ "success": true, "replayed": false,
  "refund": { "id": "…", "paymentId": "…", "amount": 5150, "currency": "XOF", "status": "sent",
              "reason": "Commande annulée", "toPhone": "+229******1111", "providerRef": "…",
              "livemode": true, "createdAt": "…", "sentAt": "…" },
  "payment": { "…", "refundedAmount": 5150, "refundableAmount": 0 } }

status : sent (viré), manual_review (virement échoué, vos fonds sont engagés, le support Zepargn termine et vous prévient), failed. Webhook payment.refunded.

Lecture : GET /payments/:id/refunds, GET /refunds/:refundId, GET /refunds?page&limit.

• GET /balance renvoie { currency, livemode, held, engaged, available, collectedToday: { count, gross, net, fees }, pendingPayoutCount, payoutNumber }.
• GET /payouts?from=&to=&page=&limit= : vos reversements, un par référence : { id, type: "automatic" | "withdrawal" | "refund", amount, sentAt, toPhone, paymentIds, paymentCount }.
• GET /payouts/:id : le détail avec la liste des paiements couverts.

• Clé zp_test_…, créée sans activation ni KYB. Même API, livemode: false.
• Le lien de paiement ouvre la page Zepargn avec les boutons « Simuler un paiement réussi » et « Simuler un échec ». Depuis votre serveur : POST /payments/:id/charge passe le paiement enpaid immédiatement ; POST https://prodapi.zepargn.com/v2/api/pay/:token/simulate { "outcome": "success" | "failure" } fonctionne sans clé.
• Les webhooks partent normalement avec livemode: false. Rien n’est reversé, rien n’entre dans vos plafonds, vos statistiques ni votre solde.
• Les remboursements de test sont immédiats.

Toute erreur a la forme { "success": false, "errorCode": "…", "message": "…", "messageEn": "…", …détails }.

1. Le client valide son panier sur votre site.
2. Votre serveur appelle POST /payments avec votre numéro de commande en reference et en Idempotency-Key.
3. Vous redirigez le client vers payment.link.
4. Il paie par MoMo ou Kkiapay, puis revient sur returnUrl avec zp_token et zp_status.
5. Votre serveur reçoit payment.succeeded, vérifie la signature, retrouve la commande par data.reference ou data.metadata, et la valide.
6. Le reversement vers votre numéro MTN suit les règles habituelles de Zepargn Business.

Une question sur l’intégration : [email protected].