API de paiement

Introduction

SigmaPay est une passerelle de paiement multi-opérateurs pour le marché sénégalais. Elle expose une API REST JSON standard, compatible avec tous les langages et frameworks.

https://sigmapay.digital

Démarrage rapide

Prêt en 3 étapes :

Authentification

Toutes les requêtes authentifiées nécessitent le header Authorization: Bearer <clé_api>.

Authorization: Bearer sigmapay_live_xxxxxxxxxxxxxxxxxx
Content-Type: application/json

Environnements

Flux de paiement hébergé

SigmaPay fonctionne en mode checkout hébergé : vous créez le paiement depuis votre serveur, redirigez le client vers la page SigmaPay, il paie, et vous recevez un webhook de confirmation.

Créer un paiement

Paramètres

Exemples de code

const res = await fetch('https://sigmapay.digital/api/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sigmapay_live_votre_cle',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 125000,                      // 125 000 XOF
    channel: 'WAVE',
    idempotencyKey: crypto.randomUUID(),
    customerPhone: '+221771234567',
    description: 'Frais de scolarité S1 2026',
    returnUrl: 'https://votre-site.sn/merci',
    metadata: { studentId: 'UCK-2026-1042' },
  }),
});

const { checkoutUrl } = await res.json();
// → "https://sigmapay.digital/pay/cpay_8f26b1f3..."
window.location.href = checkoutUrl;

Réponse

{
  "id": "clxyz1234abcd",
  "reference": "TXN-a1b2c3d4-e5f6-...",
  "status": "PENDING",
  "amount": 125000,
  "currency": "XOF",
  "channel": "WAVE",
  "mode": "LIVE",
  "checkoutUrl": "https://sigmapay.digital/pay/cpay_8f26b1f3b9161d76...",
  "createdAt": "2026-06-30T10:30:00.000Z"
}

Statut d'une transaction

const res = await fetch('https://sigmapay.digital/api/v1/payments/clxyz1234abcd', {
  headers: { 'Authorization': 'Bearer sigmapay_live_votre_cle' },
});
const { id, status, amount } = await res.json();
console.log(status); // "SUCCESS"

Remboursement

// Remboursement total
await fetch('https://sigmapay.digital/api/v1/payments/clxyz1234abcd/refund', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sigmapay_live_votre_cle',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ reason: 'Cours annulé — remboursement automatique' }),
});

// Remboursement partiel — 50 000 XOF sur 125 000 XOF
await fetch('https://sigmapay.digital/api/v1/payments/clxyz1234abcd/refund', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sigmapay_live_votre_cle', 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: 50000, reason: 'Remboursement partiel' }),
});

Webhooks (IPN)

SigmaPay envoie un POST HTTP à votre URL webhook à chaque changement de statut. Configurez-la depuis Dashboard → Paramètres → Webhooks.

Payload

Structure à plat, sans enveloppe data. Le champ event vaut toujours transaction.updated — c'est le champ status qui indique le résultat réel.

{
  "event": "transaction.updated",
  "transactionId": "clxyz1234abcd",
  "reference": "TXN-a1b2c3d4-...",
  "status": "SUCCESS",
  "amount": 125000,
  "currency": "XOF",
  "channel": "WAVE",
  "mode": "LIVE"
}

mode vaut TEST pour un paiement créé avec votre clé de test : il est simulé, aucun argent n'a circulé. Vérifiez ce champ avant de livrer une commande, pour qu'un paiement de test ne débloque jamais un vrai produit.

Valeurs possibles du champ status :

Vérifier la signature

Chaque webhook contient le header X-SigmaPay-Signature — un HMAC-SHA256 du body signé avec votre webhook secret.

const crypto = require('crypto');

app.post('/webhook/sigmapay', express.raw({ type: 'application/json' }), (req, res) => {
  const sig      = req.headers['x-sigmapay-signature'];
  const secret   = process.env.SIGMAPAY_WEBHOOK_SECRET;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.body)           // req.body = buffer brut (express.raw obligatoire)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig ?? ''))) {
    return res.status(401).json({ error: 'Signature invalide' });
  }

  const { transactionId, status, amount } = JSON.parse(req.body.toString());

  if (status === 'SUCCESS') {
    // Retrouver votre commande via transactionId (stocké à la création du paiement)
    // puis la marquer payée.
    console.log('Paiement reçu :', amount, 'XOF — transaction :', transactionId);
  }

  res.json({ received: true });
});

Sécurité et bonnes pratiques

Ce que SigmaPay garantit, et ce que nous vous demandons de respecter dans votre intégration.

Côté SigmaPay

• Chiffrement en transit : HTTPS obligatoire (TLS 1.2 minimum, HSTS) sur toutes les routes.
• Chiffrement au repos : vos secrets de webhook et les documents de vérification (KYC) sont chiffrés en AES-256-GCM, avec une clé conservée hors de la base de données.
• Clés API et mots de passe stockés uniquement sous forme d'empreinte : même SigmaPay ne peut pas les relire.
• Données personnelles minimisées sur les pages publiques : la page de paiement et la facture n'affichent qu'un numéro masqué (77 ••• •• 67) et un nom abrégé.

Côté marchand

1. Suivez vos paiements par webhook, pas par des requêtes GET répétées. GET /api/v1/payments/:id sert à une vérification ponctuelle et est limité à 60 requêtes par minute.
2. Ne mettez jamais de donnée sensible dans une URL (clé API, téléphone, email) : les URL restent dans les historiques et les journaux. La clé API va dans l'en-tête Authorization, les données dans le corps des requêtes POST.
3. Vérifiez la signature de chaque webhook (X-SigmaPay-Signature, voir plus haut) avant de livrer quoi que ce soit, et vérifiez son champ mode.
4. Gardez votre clé API côté serveur, jamais dans une application mobile ou du code exécuté dans le navigateur.
5. Limites : 100 requêtes par minute et par adresse IP sur l'ensemble de l'API ; au-delà, réponse 429 : réessayez avec un délai croissant.

Stock limité : billets, places, dernier article

Si vous vendez un stock limité sur votre propre site, c'est votre site qui connaît ce stock : SigmaPay encaisse les paiements mais ne sait pas combien de billets il vous reste. Sans précaution, deux clients qui achètent le dernier billet au même moment peuvent être débités tous les deux. Voici comment l'éviter :

1. Réservez le billet avant de créer le paiement, en une seule opération dans votre base (par exemple UPDATE … SET stock = stock - 1 WHERE stock > 0). Si aucune ligne n'est modifiée, le billet est épuisé : n'appelez pas SigmaPay.
2. Créez ensuite le paiement, avec une idempotencyKey propre à la commande, et gardez le transactionId reçu.
3. Libérez le billet si vous recevez un webhook FAILED ou CANCELLED, ou si le client n'a pas payé au bout d'un délai que vous fixez (15 minutes, par exemple).
4. Ne livrez le billet qu'à la réception du webhook SUCCESS.

Opérateurs supportés

Codes d'erreur

Testeur API interactif

Testez l'API directement depuis cette page sans quitter la documentation.