PAY ONLINE · REST API · v1.0

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.

WaveOrange MoneyMixx by YasWizallCarte 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.

🔑
Clé API Bearer
Une clé suffit pour toutes les requêtes.
📡
REST + JSON
HTTP standard — compatible tout framework.
🔔
Webhooks HMAC
Notifications IPN signées SHA-256.
URL de base
https://bluepay.myfad.org

⚡ Démarrage rapide

Prêt en 3 étapes :

1

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 →
2

Initier un paiement

Appelez POST /api/v1/payments depuis votre serveur. Vous recevez une checkoutUrl que vous retournez à votre client.

3

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

🚨
Ne jamais exposer votre clé LIVE dans du code front-end (JS navigateur, application mobile). Effectuez toujours les appels API côté serveur.
HTTP Header
Authorization: Bearer sigmapay_live_xxxxxxxxxxxxxxxxxx
Content-Type: application/json
ChampTypeRequisDescription
sigmapay_test_…stringNonClé de test — aucun vrai paiement. À utiliser en développement.
sigmapay_live_…stringNonClé de production — vrais paiements. À activer depuis le dashboard.

🌍 Environnements

TestProduction
URL APIhttps://bluepay.myfad.orghttps://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
⚠️
Statut actuel : simulation active sur tous les canaux. Le branchement direct avec Wave, Orange Money et Mixx by Yas est en cours de finalisation — en attendant, toute clé (test comme production) passe par un simulateur : la confirmation de paiement est automatique et instantanée, sans réelle interaction opérateur ni mouvement d'argent. C'est idéal pour valider votre intégration (structure des requêtes, webhooks, gestion des statuts) avant le branchement définitif. Pour simuler un échec plutôt qu'un succès, ajoutez "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.

1Votre serveurPOST /api/v1/payments
2SigmaPaycheckoutUrl retournée
3Client paieWave · Orange · Carte…
4IPN WebhookPOST → votre serveur

💳 Créer un paiement

POST/api/v1/payments

Paramètres

ChampTypeRequisDescription
amountintegerOuiMontant en centimes XOF. Ex : 125000 = 1 250 XOF. Minimum : 1.
channelstringOuiWAVE | ORANGE_MONEY | FREE_MONEY | WIZALL | CARD
idempotencyKeystringOuiClé unique anti-doublons. Même clé = même résultat, sans double débit.
customerPhonestringNonTéléphone au format international. Ex : +221771234567
customerEmailstringNonEmail du client pour confirmation automatique
descriptionstringNonLibellé affiché sur la page de paiement SigmaPay
returnUrlstringNonURL de redirection après paiement
metadataobjectNonDonnées libres retournées dans le webhook. Ex : { studentId: "UCK-001" }
💡
Générez 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

JSON
{
  "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

GET/api/v1/payments/:id
PENDINGEn attente
PROCESSINGEn cours
SUCCESSConfirmé ✓
FAILEDÉchoué
REFUNDEDRemboursé
CANCELLEDAnnulé
const 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

POST/api/v1/payments/:id/refund
ChampTypeRequisDescription
amountintegerNonMontant à rembourser en centimes. Si absent : remboursement total.
reasonstringNonMotif 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.

⚠️
Votre endpoint doit répondre en moins de 5 secondes avec un statut 2xx. SigmaPay réessaie automatiquement jusqu'à 3 fois en cas d'échec.

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.

JSON
{
  "event": "transaction.updated",
  "transactionId": "clxyz1234abcd",
  "reference": "TXN-a1b2c3d4-...",
  "status": "SUCCESS",
  "amount": 125000,
  "currency": "XOF",
  "channel": "WAVE"
}
⚠️
Le webhook ne contient pas votre 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.

🚨
Ne traitez jamais un webhook sans vérifier sa signature. N'importe qui pourrait envoyer de faux événements à votre endpoint.
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 channelOpérateurTypeDisponibilité
WAVEWaveMobile Money⏳ Simulé (voir note ci-dessus)
ORANGE_MONEYOrange MoneyMobile Money⏳ Simulé (voir note ci-dessus)
FREE_MONEYMixx by YasMobile Money⏳ Simulé (voir note ci-dessus)
CARDCarte bancaireVisa / MC⏳ Simulé (voir note ci-dessus)

🚨 Codes d'erreur

HTTPCodeCauseSolution
400VALIDATION_ERRORBody invalideVérifier les champs requis et les types
400CHANNEL_UNAVAILABLECanal choisi pas encore branché à un opérateur réelRéessayer avec un autre canal, ou contacter support@sigmapay.sn pour connaître les canaux actifs
401UNAUTHORIZEDClé API manquante ou invalideVérifier le header Authorization
403KYC_REQUIREDClé live utilisée avant vérification KYCSoumettre le KYC depuis le dashboard, ou utiliser une clé test en attendant
404NOT_FOUNDTransaction introuvableVérifier l'ID ou qu'il vous appartient
409IDEMPOTENCYidempotencyKey déjà utiliséeRécupérer la transaction avec GET /api/v1/payments/:id
422UNPROCESSABLEMontant ≤ 0 ou opérateur invalideVérifier les valeurs envoyées
429RATE_LIMITTrop de requêtesImplémenter un backoff exponentiel
500SERVER_ERRORErreur interne SigmaPayContacter support@sigmapay.sn avec votre requestId

🧪 Testeur API interactif

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

ℹ️
Ce testeur appelle votre backend local (https://bluepay.myfad.org). Démarrez-le avec npm run start:dev dans le dossier racine.
🧪Testeur API InteractifPOST /api/v1/payments

125000 = 1 250 XOF

🇸🇳 +221

Prêt à intégrer ?

Créez votre compte, récupérez vos clés API et acceptez vos premiers paiements.