How to integrate a mobile money API
Collect mobile money from your own app with one REST API: test with sandbox keys, create a collection, then confirm it with a signed webhook.
Updated October 7, 2026
Create a collection in the sandbox
curl https://api.capayglobal.com/v1/collections \
-H "Authorization: Bearer sk_test_XXXXXXXXXXXX" \
-H "Idempotency-Key: 9f0c7a52-2b1e-4c55-9a43-1f6e0d2b8c11" \
-H "Content-Type: application/json" \
-d '{
"amount": "5000",
"currency": "XAF",
"country": "CM",
"method": "mobile_money",
"msisdn": "237670000000",
"merchant_reference": "order_1042"
}'Conventions worth knowing
- Amounts are decimal strings with an explicit currency, never floats. Zero-decimal currencies such as XAF have no fractional part.
- Every response, success or error, carries a request_id you can quote to support.
- Money-creating calls require an Idempotency-Key: replaying the same key returns the original result instead of a second charge.
Step by step
- 1Get your sandbox keySign up and create an app in the dashboard. Sandbox keys start with sk_test_ and only ever reach the simulator, never a real network.
- 2Create a collectionSend POST /v1/collections with the amount as a decimal string, the currency, the country, method mobile_money, the payer's number (msisdn) and your own merchant_reference. Add an Idempotency-Key header so a retry can never charge twice.
- 3Let the payer approveThe collection comes back pending while the payer approves the prompt on their phone.
- 4Confirm with a webhookRegister a webhook endpoint. Every delivery is signed with an X-Capay-Signature header: verify it before you mark an order as paid.
- 5Go liveAfter business verification, switch to your sk_live_ key. The environment comes from the key alone: there is no other switch to flip.
Frequently asked questions
Is there a free sandbox?
Yes. The sandbox is free and unlimited, opens the moment you sign up and simulates payers succeeding, failing and timing out.
Which countries does the API cover?
Collections are live in Cameroon, Gabon, Uganda, Kenya, Ghana, Tanzania, Côte d’Ivoire, Senegal, Congo - Brazzaville, Benin, Rwanda, Congo - Kinshasa, Zambia, Sierra Leone, Burkina Faso, Mali, Togo, Guinea, Niger, and Nigeria. The method available in each country is listed on its coverage page.
How do I know a payment succeeded?
From the signed webhook, or by reading the collection again with GET /v1/collections/{id}. Never mark an order paid from the browser redirect alone.
What does it cost?
No setup fee and no monthly fee. Collections are charged from 1.99% per successful collection, and every API response carries the full fee breakdown.
Related guides
Start in the sandbox today
Free, unlimited and open the moment you sign up. Live payments open after business verification.