Documentation

Tout pour encaisser vos clients par Orange Money et MTN Mobile Money avec BindiPay : ouverture du compte, boutique WooCommerce, API et notifications.

Comment fonctionne BindiPay

BindiPay se place entre votre site et les opérateurs Mobile Money. Pour chaque commande :

  1. Votre site crée une demande de paiement (le plugin WooCommerce le fait pour vous) et reçoit un lien de paiement.
  2. Le client arrive sur votre page de paiement, à vos couleurs, choisit Orange Money ou MTN Mobile Money et saisit son numéro.
  3. Il valide sur son téléphone avec son code secret.
  4. BindiPay vérifie le paiement auprès de l’opérateur, le confirme et prévient votre site par une notification signée.

L’argent est versé sur votre compte de paiement, ouvert à votre nom auprès de notre prestataire agréé. BindiPay ne détient jamais vos fonds.

Ouvrir votre compte

  1. Remplissez le formulaire d’inscription : entreprise, activité, contact et mot de passe.
  2. Notre équipe vérifie votre activité, en général sous 48 h ouvrées. Vous recevez un message dès l’activation.
  3. Connectez-vous à votre espace marchand. À la première connexion, activez la double authentification avec une application comme Google Authenticator ou Microsoft Authenticator.
  4. Invitez votre équipe dans Utilisateurs → Inviter un membre. Chaque personne reçoit un lien personnel, valable 7 jours, pour créer son accès.
RôlePeut
AdministrateurGérer l’entreprise, les comptes de paiement, les applications, les clés et l’équipe ; consulter le relevé mensuel.
VérificateurTraiter les anomalies (montant différent, paiement en double, réclamation).
SupportConsulter les paiements et suivre les demandes des clients.

Configurer votre espace

1. Relier votre compte de paiement

Dans Comptes bénéficiaires → Nouveau, choisissez le type paiement en ligne, puis saisissez la clé API et le mot de passe API de votre compte de paiement. Nous vous les communiquons à l’ouverture de ce compte. Cliquez ensuite sur Tester les clés : un message confirme la connexion.

2. Créer une application

Une application représente un site ou un logiciel qui encaisse : votre boutique, votre SaaS… Dans Applications → Nouvelle :

  • donnez-lui un nom et l’adresse de notification de votre site (voir Notifications) ;
  • cochez votre compte de paiement et choisissez-le comme compte utilisé pour les nouvelles demandes ;
  • dans le menu de la ligne, créez une clé API (commence par bp_) et un secret de notification (commence par whsec_).

Clé et secret ne s’affichent qu’une seule fois : copiez-les aussitôt dans un endroit sûr. En cas de perte ou de fuite, créez-en de nouveaux ; les anciens peuvent être révoqués.

3. Personnaliser votre page de paiement

Dans Mon entreprise → Modifier :

  • nom affiché, couleur principale et logo (PNG, JPG ou WebP, 200 Ko au maximum) ;
  • montant minimum (100 FCFA au moins, limite des opérateurs) ;
  • délai pour payer, de 10 minutes à 24 heures (30 minutes par défaut).

Boutique WooCommerce

  1. Dans WordPress : Extensions → Ajouter → Téléverser, envoyez le plugin BindiPay, puis activez-le.
  2. WooCommerce → Réglages → Paiements → BindiPay : renseignez l’adresse https://pay.waziapps.com, votre clé API et votre secret de notification.
  3. Copiez l’adresse de notification affichée sous le champ du secret (elle se termine par /wp-json/bindipay/v1/webhook) et collez-la dans votre application BindiPay.
  4. Réglez la devise de la boutique sur Franc CFA (XAF), sans décimales.

Le plugin fonctionne avec la page de commande classique et avec le bloc de paiement de WooCommerce. Le nom et l’e-mail de l’acheteur sont transmis automatiquement.

MomentÉtat de la commande
Commande passée, client redirigé vers la page de paiementEn attente de paiement
Paiement confirméEn cours (e-mails WooCommerce habituels envoyés)
Délai dépassé sans paiementÉchouée (le client peut relancer le paiement depuis son compte)
Paiement annulé après confirmationEn attente, avec une note : vérifiez avant d’expédier

Une commande dont le paiement est en cours de validation n’est jamais annulée automatiquement par WooCommerce.

API pour votre application

Adresse de base : https://pay.waziapps.com. Toutes les requêtes utilisent HTTPS et du JSON.

Authentification

Ajoutez votre clé API dans l’en-tête Authorization: Bearer bp_…. Ne la placez jamais dans une application mobile ou dans du code exécuté par le navigateur : les appels se font depuis votre serveur.

Créer une demande de paiement

POST /v1/payments avec l’en-tête Idempotency-Key : une valeur unique par commande. Si la requête est rejouée avec la même clé, la même demande est renvoyée au lieu d’en créer une seconde.

curl https://pay.waziapps.com/v1/payments \
  -H "Authorization: Bearer bp_votre_cle" \
  -H "Idempotency-Key: commande-1048" \
  -H "Content-Type: application/json" \
  -d '{
    "order_ref": "CMD-1048",
    "amount": 15000,
    "currency": "XAF",
    "return_url": "https://maboutique.cm/commande/1048",
    "customer": { "first_name": "Awa", "last_name": "Ngono", "email": "awa@exemple.cm" }
  }'
ChampObligatoireDescription
order_refOuiVotre référence de commande, unique pour votre application.
amountOuiMontant entier en FCFA (100 au minimum, multiple de 5).
currencyOuiXAF.
return_urlNonLien « Retour à la boutique » affiché au client.
customerNonPrénom, nom et e-mail de l’acheteur, transmis au prestataire de paiement.

Réponse 201 (ou 200 si la même demande existait déjà pour cette clé) :

{
  "payment_id": "0196f0c2-…",
  "order_ref": "CMD-1048",
  "amount": 15000,
  "currency": "XAF",
  "status": "pending",
  "version": 1,
  "expires_at": "2026-11-21T12:30:00Z",
  "support_ref": "BP-7K2M9QXA",
  "checkout_url": "https://pay.waziapps.com/checkout/…"
}

Enregistrez payment_id avec votre commande, puis redirigez le client vers checkout_url. Ce lien est personnel : ne le publiez pas.

Consulter une demande

GET /v1/payments/{payment_id} renvoie l’état à jour. C’est la source de vérité : relisez-la avant de livrer une commande si vous avez un doute.

Annuler une demande

POST /v1/payments/{payment_id}/cancel ferme une demande que le client n’a pas encore payée, par exemple si la commande est annulée chez vous.

États d’un paiement

ÉtatSignificationQue faire
pendingEn attente : le client n’a pas encore payé.Attendre.
awaiting_creditPaiement déclaré, en attente de réception.Attendre.
under_reviewPaiement à vérifier par votre équipe (anomalie détectée).Ne pas livrer ; traiter le dossier dans votre espace.
confirmedPayé et vérifié auprès de l’opérateur.Livrer la commande.
expiredDélai dépassé sans paiement.Proposer de payer à nouveau (nouvelle demande).
canceledDemande annulée.Rien.
reversedPaiement annulé après confirmation (litige, erreur).Suspendre la livraison et vérifier.

Le champ version augmente à chaque changement d’état : n’appliquez jamais un état dont la version est plus ancienne que celle que vous connaissez déjà.

Notifications (webhooks)

À chaque paiement confirmé ou annulé, BindiPay envoie une requête POST en JSON à l’adresse de notification de votre application. Événements : payment.confirmed et payment.reversed.

{
  "event_id": "0196f0c9-…",
  "type": "payment.confirmed",
  "occurred_at": "2026-11-21T11:05:12Z",
  "payment_id": "0196f0c2-…",
  "order_ref": "CMD-1048",
  "amount": 15000,
  "currency": "XAF",
  "status": "confirmed",
  "version": 3
}

Vérifier la signature

L’en-tête BindiPay-Signature a la forme t=1763723112,v1=5f2a…. v1 est le HMAC-SHA256, en hexadécimal, de la chaîne t + "." + corps brut, calculé avec votre secret de notification. Votre traitement doit :

  1. vérifier la signature sur le corps brut de la requête, avec une comparaison en temps constant ;
  2. refuser un horodatage t de plus de 5 minutes ;
  3. ignorer un event_id déjà traité ;
  4. répondre rapidement par un code 2xx.

PHP

$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_BINDIPAY_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $sig);   // ['t' => …, 'v1' => …]

$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('BINDIPAY_WEBHOOK_SECRET'));
if (abs(time() - (int) ($sig['t'] ?? 0)) > 300 || ! hash_equals($expected, $sig['v1'] ?? '')) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
// … marquer la commande $event['order_ref'] comme payée si $event['status'] === 'confirmed'
http_response_code(200);

Node.js (Express)

const crypto = require('crypto');

app.post('/webhooks/bindipay', express.raw({ type: 'application/json' }), (req, res) => {
  const parts = Object.fromEntries(String(req.get('BindiPay-Signature') || '').split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', process.env.BINDIPAY_WEBHOOK_SECRET)
    .update(`${parts.t}.${req.body}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  const valid = parts.v1 && parts.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  if (!fresh || !valid) return res.sendStatus(401);

  const event = JSON.parse(req.body);
  // … traiter l'événement une seule fois (event.event_id)
  res.sendStatus(200);
});

Nouvelles tentatives

Si votre site ne répond pas par un code 2xx, BindiPay réessaie avec un délai croissant, de 30 secondes à 4 heures, puis vous alerte dans votre espace. Les redirections ne sont pas suivies, et l’adresse de notification doit être en HTTPS. En cas de doute, relisez GET /v1/payments/{payment_id}.

Erreurs

Les erreurs ont toujours la même forme. Le code est stable et peut être utilisé dans votre programme ; request_id est à communiquer au support.

{ "error": { "code": "validation_failed", "message": "…", "request_id": "…", "details": { … } } }
Statut HTTPCause fréquente
400JSON invalide, ou en-tête Idempotency-Key manquant.
401Clé API absente, révoquée ou erronée, ou compte suspendu.
404Demande introuvable pour cette application.
409order_ref ou Idempotency-Key déjà utilisés avec d’autres données.
422Champ invalide : montant, devise, adresse de retour…
429Trop de requêtes : réessayez après quelques secondes.

Tester avant d’ouvrir

  1. Créez une commande de 100 FCFA (le minimum) et payez-la avec votre propre numéro Orange Money ou MTN Mobile Money.
  2. Vérifiez que la page de paiement affiche « Paiement confirmé » et que la commande passe à « payée » sur votre site.
  3. Testez un refus : lancez un paiement puis ne le validez pas, ou annulez-le sur le téléphone. La page propose alors de réessayer, et rien n’est débité.
  4. Vérifiez dans votre espace que la demande apparaît avec le bon montant et la bonne référence.

Sécurité et bonnes pratiques

  • Ne livrez une commande qu’après une notification signée ou une relecture de l’API : le retour du client sur votre site ne prouve pas le paiement.
  • Gardez la clé API et le secret de notification côté serveur, jamais dans le code d’une page web ou d’une application mobile.
  • Une clé par application ; renouvelez-la dès qu’un collaborateur ayant eu accès quitte l’équipe.
  • Activez la double authentification pour chaque membre de votre équipe (elle est obligatoire).
  • Ne demandez jamais son code secret Mobile Money à un client : il le saisit uniquement sur son téléphone.

Obtenir de l’aide

Indiquez toujours la référence support de la demande (par exemple BP-7K2M9QXA, visible sur la page de paiement et dans votre espace) ou le request_id d’une erreur.

Écrire un e-mail