Recevoir les paiements Mobile Money en temps réel

Le webhook Mobile Money permet à Orange Money (ou MTN, à venir) d’envoyer une notification automatique à SynkriaOps à chaque transaction sur votre wallet marchand. Vos paiements clients apparaissent dans votre journal de banque en temps réel, sans aucun import manuel de relevé.

Webhook vs import manuel

Critère	Import manuel	Webhook temps réel
Délai	24 h à 7 jours (export manuel)	Quelques secondes après la transaction
Erreurs	Risque de doublon ou d’omission	Zéro — chaque paiement est enregistré une seule fois
Effort	Export + glisser-déposer + vérification	Aucun — automatique
Disponibilité	Orange Money CM (prod)	Orange Money CM (prod), MTN MoMo (roadmap)

Astuce

Activez le webhook si vous recevez plus de 10 paiements Mobile Money par mois. En dessous de ce seuil, l’import manuel mensuel reste suffisant.

Pré-requis

• Avoir un compte marchand Orange Money Business activé (contactez Orange Business Cameroun : +237 655 00 04 44 ou orangebusiness.cm).
• Le compte Mobile Money doit être configuré dans SynkriaOps (voir Configurer un compte bancaire).
• Disposer du rôle Administrateur sur le dossier SynkriaOps.

Activer le webhook côté SynkriaOps

1. Allez dans Paramètres → Mobile Money → Webhook.

2. Cliquez sur Activer le webhook pour le compte Orange Money concerné.

3. SynkriaOps génère une URL webhook unique pour votre dossier, de la forme :

   https://api.synkriaops.com/api/mobile-money/callback/cm-votre-tenant-id

4. Cliquez sur Copier l’URL — vous en aurez besoin lors de la configuration côté opérateur.

5. Notez également le secret HMAC affiché (visible une seule fois). Ce secret est utilisé pour vérifier que chaque notification provient bien d’Orange Money et non d’un tiers malveillant. Conservez-le en lieu sûr.

Attention

Le secret HMAC n’est affiché qu’une seule fois. Si vous le perdez, cliquez sur Régénérer le secret — l’ancien secret sera révoqué immédiatement et vous devrez le reconfigurer côté opérateur.

Configurer le webhook côté Orange Business Cameroun

1. Connectez-vous à votre espace Orange Business Cameroun.

2. Accédez à Mon compte marchand → Paramètres API → Webhooks.

3. Cliquez sur Ajouter un endpoint webhook.

4. Collez l’URL SynkriaOps copiée à l’étape précédente.

5. Dans le champ Clé secrète (ou Secret HMAC), collez le secret fourni par SynkriaOps.

6. Cochez les événements à notifier :

   • payment.received (paiement reçu sur votre wallet marchand) — obligatoire
   • payment.failed (paiement échoué) — optionnel, ignoré par SynkriaOps (règle R1)

7. Enregistrez. Orange Business envoie une notification de test — SynkriaOps répondra 200 OK si la configuration est correcte.

Tester la connexion

1. Dans Paramètres → Mobile Money → Webhook, cliquez sur Tester la connexion.

2. SynkriaOps envoie une requête de test vers Orange et vérifie la réponse.

3. Le statut passe à Actif (vert) si le test réussit, ou Erreur (rouge) avec le message d’erreur détaillé.

Sécurité du webhook

Chaque notification reçue est vérifiée en deux étapes :

1. Signature HMAC-SHA256

Orange Money signe chaque requête webhook avec le secret partagé. SynkriaOps vérifie cette signature avant tout traitement :

• Si la signature est invalide → 401 Unauthorized, aucun enregistrement.
• Si la signature est valide → traitement de la notification.

La vérification utilise une comparaison en temps constant (timingSafeEqual) pour éviter les attaques par timing.

2. IP allowlist (recommandé)

Pour renforcer la sécurité, renseignez dans Paramètres → Mobile Money → Webhook → IP autorisées les plages IP d’Orange Business Cameroun. Toute notification provenant d’une IP non autorisée est rejetée avant même la vérification HMAC.

Contactez Orange Business pour obtenir la liste des plages IP de leurs serveurs de notification.

Note

L’IP allowlist est facultative mais fortement recommandée pour les comptes marchands avec un volume important (> 100 paiements/jour).

Ce qui se passe à chaque paiement reçu

Lorsqu’un client vous paie via Orange Money :

1. Orange Business envoie une notification JSON à l’URL SynkriaOps.
2. SynkriaOps vérifie la signature HMAC et l’IP source.
3. La transaction est créée en statut À_TRAITER dans le journal BNQ lié au compte Mobile Money.
4. Si le paiement d’un montant de 150 000 XAF provient d’un client lié à une facture en attente, SynkriaOps propose automatiquement le rapprochement.
5. Un audit trail est enregistré (timestamp, IP source, statut de vérification).

Monitoring des webhooks

1. Dans Banque & trésorerie → Mobile Money → Historique webhooks, consultez la liste de toutes les notifications reçues.

2. Pour chaque notification, vous voyez :

   • Date et heure de réception
   • Montant et référence de la transaction
   • Statut de la vérification HMAC (VALIDE / INVALIDE)
   • Statut du traitement (SUCCÈS / DOUBLON / ERREUR)

3. En cas d’erreur, cliquez sur Détail pour voir le message d’erreur complet et relancer manuellement si nécessaire.

Dépannage

Problème	Cause probable	Solution
Statut webhook « Erreur » après test	URL mal copiée ou secret HMAC incorrect	Vérifier l’URL et régénérer le secret si nécessaire
Paiements reçus mais non enregistrés	IP source non autorisée (si IP allowlist active)	Ajouter les IP Orange Business dans la liste autorisée
Notifications en doublon	La même transaction notifiée deux fois	SynkriaOps déduplique automatiquement par référence de transaction — ignorer
« 401 Unauthorized » dans les logs Orange	Secret HMAC expiré ou régénéré sans mise à jour côté opérateur	Reconfigurer le secret dans le portail Orange Business

Pour aller plus loin

• Configurer un compte bancaire ou Mobile Money →
• Importer un relevé Mobile Money →