Collections
Get paid from mobile money wallets: approval on the phone, codes by SMS, statuses.
A collection asks a customer to pay from their mobile money wallet. You give the amount, the phone number and the operator; the customer approves on their phone; the net amount lands on your balance. Collections are available in XAF, XOF, GNF, CDF, KES, GHS, UGX, TZS and RWF; in NGN they return 400 currency_unsupported. For a country that shares its currency with others (XAF, XOF), send country: see Coverage.
The flow
- Your server creates the collection.
- The operator contacts the customer. Depending on the operator, the customer either approves on the phone with their PIN, or receives a code by SMS that they give you.
- The collection reaches a final status. Monerail sends
collection.succeeded,collection.failedorcollection.expired.
Statuses
| Status | Meaning | Final |
|---|---|---|
pending |
Request sent, waiting for the customer to approve on the phone. | No |
requires_otp |
The customer received a code. Send it with authorize. | No |
processing |
The operator is processing the payment. | No |
succeeded |
Paid. fee and net are set and net is on your balance. |
Yes |
failed |
Not paid. | Yes |
expired |
The customer did not approve in time. | Yes |
Guide your customer
next_action tells you what to show in your app:
{"type": "customer_approval", "message": "…", "ussd_code": "*126#"}: show the message. If the customer did not get the prompt, they can dial the USSD code.{"type": "otp", "message": "…"}: ask the customer for the code they received, then call 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"}'If the code never arrived, resend it. A wrong code fails with 402 otp_invalid; the customer can try again.
To know in advance which operators use codes, read authorization in List operators: PIN means approval on the phone, OTP a code to send with authorize.
Phone numbers
Send the customer’s mobile money number in international format: 237670000999, +237 670 00 00 99 and 00237670000999 all work. A local number (670000999) is accepted when the country is known, from country or from the currency.
Follow the outcome
Use webhooks. If you must poll, call Retrieve a collection every few seconds: while the collection is not final, Monerail asks the operator for news before answering. A 202 on creation means the operator has not confirmed receipt yet: the collection is processing and its outcome arrives by webhook.
Put your order ID in client_reference and anything else in metadata: both come back on the collection and in every event, which makes matching easy.
In test mode, the payment partner’s sandbox decides how collections proceed: see Testing.
Failures
failure_code is failed or expired: the payment partner gives no finer reason for collections. failure_message carries a human-readable reason when one is available; show it, or your own generic message. A failed collection can simply be created again.