Encaissements
Faites-vous payer depuis les portefeuilles mobile money : validation sur le téléphone, codes par SMS, statuts.
Un encaissement demande à un client de payer depuis son portefeuille mobile money. Vous donnez le montant, le numéro et l’opérateur ; le client valide sur son téléphone ; le montant net arrive sur votre solde. Les encaissements sont disponibles en XAF, XOF, GNF, CDF, KES, GHS, UGX, TZS et RWF ; en NGN, ils renvoient 400 currency_unsupported. Pour un pays qui partage sa devise avec d’autres (XAF, XOF), envoyez country : voir Couverture.
Le parcours
- Votre serveur crée l’encaissement.
- L’opérateur contacte le client. Selon l’opérateur, le client valide sur son téléphone avec son code PIN, ou reçoit un code par SMS qu’il vous communique.
- L’encaissement atteint un statut définitif. Monerail envoie
collection.succeeded,collection.failedoucollection.expired.
Statuts
| Statut | Sens | Définitif |
|---|---|---|
pending |
Demande envoyée, en attente de la validation du client sur son téléphone. | Non |
requires_otp |
Le client a reçu un code. Transmettez-le avec authorize. | Non |
processing |
L’opérateur traite le paiement. | Non |
succeeded |
Payé. fee et net sont connus et net est sur votre solde. |
Oui |
failed |
Non payé. | Oui |
expired |
Le client n’a pas validé à temps. | Oui |
Guider votre client
next_action indique quoi afficher dans votre application :
{"type": "customer_approval", "message": "…", "ussd_code": "*126#"}: affichez le message. Si le client n’a pas reçu la demande, il peut composer le code USSD.{"type": "otp", "message": "…"}: demandez au client le code reçu, puis appelez authorize.
curl https://api.monerail.com/v1/collections/9e2d4a7b-61c3-4f08-8b5e-2d7f1a3c9b40/authorize \
-H "Authorization: Bearer $MONERAIL_KEY" \
-H "Content-Type: application/json" \
-d '{"otp": "482913"}'Si le code n’est jamais arrivé, renvoyez-le. Un mauvais code échoue avec 402 otp_invalid ; le client peut réessayer.
Pour savoir à l’avance quels opérateurs utilisent un code, lisez authorization dans Lister les opérateurs : PIN signifie une validation sur le téléphone, OTP un code à transmettre avec authorize.
Numéros de téléphone
Envoyez le numéro mobile money du client au format international : 237670000999, +237 670 00 00 99 et 00237670000999 fonctionnent tous. Un numéro local (670000999) est accepté quand le pays est connu, par country ou par la devise.
Suivre le résultat
Utilisez les webhooks. Si vous devez interroger l’API, appelez Consulter un encaissement toutes les quelques secondes : tant que l’encaissement n’est pas définitif, Monerail demande des nouvelles à l’opérateur avant de répondre. Un 202 à la création signifie que l’opérateur n’a pas encore accusé réception : l’encaissement est processing et son résultat arrive par webhook.
Mettez votre numéro de commande dans client_reference et le reste dans metadata : les deux reviennent sur l’encaissement et dans chaque événement, ce qui facilite le rapprochement.
En mode test, le bac à sable du partenaire de paiement décide du déroulé des encaissements : voir Tests.
Échecs
failure_code vaut failed ou expired : le partenaire de paiement ne donne pas de motif plus précis pour les encaissements. failure_message porte un motif lisible quand il existe ; affichez-le, ou votre propre message générique. Un encaissement échoué peut simplement être recréé.