Lire les confirmations mobile money en temps réel

Le besoin

Vous vendez en ligne dans un pays où l'on paie par mobile money. L'opérateur confirme chaque paiement par SMS au numéro du marchand, immédiatement. Une API, quand elle existe, demande des semaines de dossier, une société immatriculée, un volume minimum, et souvent une part de chaque transaction.

Pendant ce temps, la confirmation dont vous avez besoin arrive déjà, sur un téléphone, sous forme de message.

Comment cela marche

La SIM qui reçoit les confirmations de l'opérateur est l'une des cartes SIM appairées à votre passerelle. À partir de là :

1. Le message arrive sur le téléphone et la passerelle l'enregistre, sur votre propre machine. Un opérateur écrit depuis un code court ou un nom, pas depuis un numéro : ajoutez-le aux Expéditeurs à enregistrer dans Paramètres > Réception, sans quoi il sera refusé comme tout service inconnu. Le Journal affiche son orthographe exacte dès son premier message.
2. Un webhook appelle votre application dès l'arrivée du SMS : abonnez-le à message.received sur la page Webhooks. L'appel est signé en HMAC-SHA256, pour que vous puissiez prouver qu'il vient de votre passerelle, et il porte les identifiants du message, jamais son texte.
3. Votre code lit le message par l'API de la passerelle, avec une clé limitée à la portée Lecture : GET /api/v1/messages/{id} renvoie l'expéditeur et le texte.
4. Votre code vérifie l'expéditeur, lit le montant et la référence, et marque la commande payée.

Rien n'est interrogé en boucle et rien n'attend : le webhook part quand le SMS arrive.

Ce qu'il faut savoir avant de construire dessus

• Le format du message appartient à l'opérateur. Il peut en changer la formulation sans vous prévenir, et un analyseur écrit sur l'ancienne cesse alors de la reconnaître. Journalisez ce que vous n'avez pas su analyser, et surveillez ce journal.
• Un SMS n'est pas une preuve de paiement. Il dit ce que l'opérateur a envoyé à ce numéro. Pour un montant qui compte, confirmez sur le relevé ou l'API de l'opérateur avant de livrer quoi que ce soit d'irréversible.
• Réservez la SIM réceptrice à cet usage, sur un téléphone qui reste sur le chargeur. Une confirmation qui arrive téléphone éteint est lue au retour, elle n'est pas perdue, mais elle est lue en retard.
• Vérifiez les conditions de votre opérateur : ce que vous avez le droit d'automatiser sur un compte mobile money relève de sa règle, pas de la nôtre.

Ce que cela demande

Un téléphone appairé, la SIM qui reçoit les confirmations, l'expéditeur de l'opérateur enregistré dans Paramètres > Réception, un webhook sur message.received, une clé d'API de portée Lecture et un point d'entrée dans votre application. La passerelle tient les messages ; la décision d'accepter un paiement reste dans votre code.