API de paiement
Intégrez SigmaPay dans votre application en quelques lignes. Une seule API pour accepter Wave, Orange Money, Mixx by Yas, Wizall et carte bancaire.
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://bluepay.myfad.org⚡ Démarrage rapide
Prêt en 3 étapes :
Obtenir vos clés API
Créez un compte sur le dashboard et récupérez vos clés TEST et LIVE dans Paramètres → Clés API.
Créer un compte →Initier un paiement
Appelez POST /api/v1/payments depuis votre serveur. Vous recevez une checkoutUrl que vous retournez à votre client.
Recevoir le webhook
Configurez votre URL IPN dans le dashboard. SigmaPay vous notifie dès la confirmation du paiement.
🔑 Authentification
Toutes les requêtes authentifiées nécessitent le header Authorization: Bearer <clé_api>.
Authorization: Bearer sigmapay_live_xxxxxxxxxxxxxxxxxx
Content-Type: application/json| Champ | Type | Requis | Description |
|---|---|---|---|
| sigmapay_test_… | string | Non | Clé de test — aucun vrai paiement. À utiliser en développement. |
| sigmapay_live_… | string | Non | Clé de production — vrais paiements. À activer depuis le dashboard. |
🌍 Environnements
| Test | Production | |
|---|---|---|
| URL API | https://bluepay.myfad.org | https://bluepay.myfad.org |
| Préfixe clé | sigmapay_test_… | sigmapay_live_… |
| Vrais paiements | ⏳ Simulés (voir note) | ⏳ Simulés (voir note) |
| Données réelles | ❌ Non | ✅ Oui |
"metadata": { "scenario": "fail" } au corps de la requête de création.🔄 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
/api/v1/paymentsParamètres
| Champ | Type | Requis | Description |
|---|---|---|---|
| amount | integer | Oui | Montant en centimes XOF. Ex : 125000 = 1 250 XOF. Minimum : 1. |
| channel | string | Oui | WAVE | ORANGE_MONEY | FREE_MONEY | WIZALL | CARD |
| idempotencyKey | string | Oui | Clé unique anti-doublons. Même clé = même résultat, sans double débit. |
| customerPhone | string | Non | Téléphone au format international. Ex : +221771234567 |
| customerEmail | string | Non | Email du client pour confirmation automatique |
| description | string | Non | Libellé affiché sur la page de paiement SigmaPay |
| returnUrl | string | Non | URL de redirection après paiement |
| metadata | object | Non | Données libres retournées dans le webhook. Ex : { studentId: "UCK-001" } |
idempotencyKey avec crypto.randomUUID() côté serveur pour éviter les doubles débits en cas de retry réseau.Exemples de code
const res = await fetch('https://bluepay.myfad.org/api/v1/payments', {
method: 'POST',
headers: {
'Authorization': 'Bearer sigmapay_live_votre_cle',
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 125000, // 1 250 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://bluepay.myfad.org/pay/cpay_8f26b1f3..."
window.location.href = checkoutUrl;Réponse
{
"id": "clxyz1234abcd",
"reference": "TXN-a1b2c3d4-e5f6-...",
"status": "PENDING",
"amount": 125000,
"currency": "XOF",
"channel": "WAVE",
"checkoutUrl": "https://bluepay.myfad.org/pay/cpay_8f26b1f3b9161d76...",
"createdAt": "2026-06-30T10:30:00.000Z"
}📋 Statut d'une transaction
/api/v1/payments/:idconst res = await fetch('https://bluepay.myfad.org/api/v1/payments/clxyz1234abcd', {
headers: { 'Authorization': 'Bearer sigmapay_live_votre_cle' },
});
const { id, status, amount } = await res.json();
console.log(status); // "SUCCESS"↩️ Remboursement
/api/v1/payments/:id/refund| Champ | Type | Requis | Description |
|---|---|---|---|
| amount | integer | Non | Montant à rembourser en centimes. Si absent : remboursement total. |
| reason | string | Non | Motif du remboursement. Affiché dans le dashboard et le webhook. |
// Remboursement total
await fetch('https://bluepay.myfad.org/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 — 500 XOF sur 1 250 XOF
await fetch('https://bluepay.myfad.org/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"
}metadata d'origine (studentId, order_id…). Pour retrouver votre commande, stockez l'association entre transactionId (retourné à la création du paiement) et votre propre identifiant, puis faites la correspondance à la réception du webhook — c'est ce que font nos plugins officiels (WooCommerce, Drupal, Moodle).Valeurs possibles du champ status :
SUCCESSPaiement confirméFAILEDPaiement échouéREFUNDEDRemboursement effectuéCANCELLEDAnnulé par le client🔐 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 });
});📱 Opérateurs supportés
| Valeur channel | Opérateur | Type | Disponibilité |
|---|---|---|---|
WAVE | Wave | Mobile Money | ⏳ Simulé (voir note ci-dessus) |
ORANGE_MONEY | Orange Money | Mobile Money | ⏳ Simulé (voir note ci-dessus) |
FREE_MONEY | Mixx by Yas | Mobile Money | ⏳ Simulé (voir note ci-dessus) |
CARD | Carte bancaire | Visa / MC | ⏳ Simulé (voir note ci-dessus) |
🚨 Codes d'erreur
| HTTP | Code | Cause | Solution |
|---|---|---|---|
| 400 | VALIDATION_ERROR | Body invalide | Vérifier les champs requis et les types |
| 400 | CHANNEL_UNAVAILABLE | Canal choisi pas encore branché à un opérateur réel | Réessayer avec un autre canal, ou contacter support@sigmapay.sn pour connaître les canaux actifs |
| 401 | UNAUTHORIZED | Clé API manquante ou invalide | Vérifier le header Authorization |
| 403 | KYC_REQUIRED | Clé live utilisée avant vérification KYC | Soumettre le KYC depuis le dashboard, ou utiliser une clé test en attendant |
| 404 | NOT_FOUND | Transaction introuvable | Vérifier l'ID ou qu'il vous appartient |
| 409 | IDEMPOTENCY | idempotencyKey déjà utilisée | Récupérer la transaction avec GET /api/v1/payments/:id |
| 422 | UNPROCESSABLE | Montant ≤ 0 ou opérateur invalide | Vérifier les valeurs envoyées |
| 429 | RATE_LIMIT | Trop de requêtes | Implémenter un backoff exponentiel |
| 500 | SERVER_ERROR | Erreur interne SigmaPay | Contacter support@sigmapay.sn avec votre requestId |
🧪 Testeur API interactif
Testez l'API directement depuis cette page sans quitter la documentation.
https://bluepay.myfad.org). Démarrez-le avec npm run start:dev dans le dossier racine.125000 = 1 250 XOF
Prêt à intégrer ?
Créez votre compte, récupérez vos clés API et acceptez vos premiers paiements.