API de paiement
Intégrez BluePay dans votre application en quelques lignes. Une seule API pour accepter Wave, Orange Money, Free Money, Wizall et carte bancaire.
Introduction
BluePay 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. BluePay 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 bluepay_live_xxxxxxxxxxxxxxxxxx
Content-Type: application/json| Champ | Type | Requis | Description |
|---|---|---|---|
| bluepay_test_… | string | Non | Clé de test — aucun vrai paiement. À utiliser en développement. |
| bluepay_live_… | string | Non | Clé de production — vrais paiements. À activer depuis le dashboard. |
🌍 Environnements
| Test | Production | |
|---|---|---|
| URL API | https://bluepay.myfad.org | https://api.bluepay.sn |
| Préfixe clé | bluepay_test_… | bluepay_live_… |
| Vrais paiements | ❌ Non | ✅ Oui |
| Données réelles | ❌ Non | ✅ Oui |
🔄 Flux de paiement hébergé
BluePay fonctionne en mode checkout hébergé : vous créez le paiement depuis votre serveur, redirigez le client vers la page BluePay, 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 BluePay |
| 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 bluepay_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 bluepay_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 bluepay_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 bluepay_live_votre_cle', 'Content-Type': 'application/json' },
body: JSON.stringify({ amount: 50000, reason: 'Remboursement partiel' }),
});🔔 Webhooks (IPN)
BluePay envoie un POST HTTP à votre URL webhook à chaque changement de statut. Configurez-la depuis Dashboard → Paramètres → Webhooks.
Payload
{
"event": "payment.success",
"data": {
"id": "clxyz1234abcd",
"reference": "TXN-a1b2c3d4-...",
"status": "SUCCESS",
"amount": 125000,
"currency": "XOF",
"channel": "WAVE",
"customerPhone": "+221771234567",
"metadata": { "studentId": "UCK-2026-1042" },
"createdAt": "2026-06-30T10:30:00.000Z",
"paidAt": "2026-06-30T10:30:42.000Z"
}
}Événements disponibles :
payment.successPaiement confirmépayment.failedPaiement échouépayment.refundedRemboursement effectuépayment.cancelledAnnulé par le client🔐 Vérifier la signature
Chaque webhook contient le header X-BluePay-Signature — un HMAC-SHA256 du body signé avec votre webhook secret.
const crypto = require('crypto');
app.post('/webhook/bluepay', express.raw({ type: 'application/json' }), (req, res) => {
const sig = req.headers['x-bluepay-signature'];
const secret = process.env.BLUEPAY_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 { event, data } = JSON.parse(req.body.toString());
if (event === 'payment.success') {
// ✅ Valider l'inscription, débloquer la commande
console.log('Paiement reçu :', data.amount, 'XOF — étudiant :', data.metadata?.studentId);
}
res.json({ received: true });
});📱 Opérateurs supportés
| Valeur channel | Opérateur | Type | Disponibilité |
|---|---|---|---|
WAVE | Wave | Mobile Money | ✅ Disponible |
ORANGE_MONEY | Orange Money | Mobile Money | ✅ Disponible |
FREE_MONEY | Free Money | Mobile Money | ✅ Disponible |
WIZALL | Wizall Money | Mobile Money | ✅ Disponible |
CARD | Carte bancaire | Visa / MC | ✅ Disponible |
🚨 Codes d'erreur
| HTTP | Code | Cause | Solution |
|---|---|---|---|
| 400 | VALIDATION_ERROR | Body invalide | Vérifier les champs requis et les types |
| 401 | UNAUTHORIZED | Clé API manquante ou invalide | Vérifier le header Authorization |
| 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 BluePay | Contacter support@bluepay.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.