Getting started
Test mode and Live mode
Build against Test data with the Abuna simulator or provider sandboxes, then switch to Live with the same code.
Test mode lets you build and try your whole billing flow with no money moving, then switch to Live with the same code. Every app has two modes, Test and Live. Each has its own app ID, secret keys, publishable key, webhook signing secret, webhook URL, and data. The app ID in the path picks the mode. There is no mode parameter.
In the dashboard, use the Test and Live switch to move between them. In the API, GET /v1/apps/{appID} returns the app's environment, test or live. Every webhook body carries it too.
Test mode
Build and test with the Test app ID and its sk_test_ key. Test mode works like Live mode, with these differences:
- Payments move no money. They go through the Abuna simulator, or through any provider sandbox you connect. See Test payments.
- You don't need a verified email.
- Plan limits on subscribers don't apply, and your plan never makes a Test app read-only.
- Customer emails, WhatsApp messages, and Telegram messages aren't sent, except three email codes that go out as in Live: the code that starts a free trial, the code that confirms a new email in the customer portal, and the code for a customer's saved details. Abuna records every message as a
notification.capturedevent, which never goes to your webhook URL. A code's event has it in the subject, so you can finish with a made-up address. The notices list holds only the free trial and email change codes. See Customer messages in Test mode. The code that confirms a customer's WhatsApp number isn't sent: the page shows it, so you can turn WhatsApp on. - A checkout session's
success_urlandcancel_urlcan behttpURLs onlocalhost,127.0.0.1, or[::1]. Live mode takes onlyhttps. - A new Test app doesn't copy the Live app's webhook URL. Set one for Test separately, under Webhooks in Test mode.
Test payments
A Test app can always take payments through the Abuna simulator. A team owner can also connect the sandbox of each provider, MeSomb, pawaPay, Notch Pay, Flutterwave, and Fapshi, as Test accounts on the team's Payment accounts page, and use them side by side, one per provider. The Payments page, under Settings in Test mode, lists the simulator and every sandbox the app uses. Each sandbox account has its own provider webhook URL, shared by every Test app that uses it.
On a Test pay page, the payer chooses under Test with: Abuna simulator, the default, or a connected sandbox, such as pawaPay sandbox. Live pay pages never offer this choice.
- Abuna simulator: you pick each outcome on the pay page. See Simulated payments.
- A provider sandbox: the pay page offers the provider's networks, a phone number field, and the provider's test numbers. Choosing a test number fills in the phone number and its network. Payments update and fail as the provider reports them. See Test numbers.
Connect a sandbox to see how your provider behaves before you go Live. Disconnecting one leaves the simulator and your other sandboxes as they are. Both are free and unlimited on every plan. See Test with your provider's sandbox.
Simulated payments
The Abuna simulator has one payment method per outcome. On the Test pay page, the customer picks one:
- Successful payment (
test): the payment succeeds. - Needs approval, then succeeds (
test_pending): the payment ispendingat first, like a mobile money prompt. It succeeds about 10 seconds later, and the pay page updates on its own. - Declined payment (
test_declined): fails with402and codepayment_declined. - Insufficient balance (
test_insufficient): fails with402and codeinsufficient_funds.
When your server charges an invoice with POST /v1/apps/{appID}/invoices/{id}/charge, a Test app always uses the simulator's test method, so the payment succeeds.
To try another outcome without the pay page, send it to the pay link's endpoint. This endpoint takes no key. Use the billing period's pay_token.
curl https://api.abuna.app/v1/pay/3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d \
-H "Content-Type: application/json" \
-d '{"method": "test_declined"}'{
"code": "payment_declined",
"error": "payment was declined"
}To pay through a connected sandbox instead, add provider: mesomb, pawapay, notchpay, flutterwave, or fapshi. Leave it out for the simulator. method is then one of the provider's networks, and phone_number is the number to charge instead of the customer's. A provider the Test app hasn't connected returns 422 with code payment_unavailable, and so does provider on a Live pay link.
curl https://api.abuna.app/v1/pay/3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d \
-H "Content-Type: application/json" \
-d '{"provider": "pawapay", "method": "MTN_MOMO_CMR", "phone_number": "+237653456039"}'Test numbers
Each provider's sandbox settles a payment according to the phone number charged. Test pay pages show the same numbers as these tables, for the network chosen. The failure reason your customer sees depends on what the provider reports.
- MeSomb: use a MeSomb application that's still in test mode. A Test app charges only these numbers. Each network has its own test numbers, and the same number can mean a different outcome on another network, so choose the number listed for the network you're testing. See MeSomb's test mode page.
- pawaPay: the sandbox never asks for a PIN. A number that gets no answer stays
pending. See pawaPay's test numbers. - Notch Pay: the last digit picks the outcome. Notch Pay checks for fraud in its sandbox too, so don't use one number for every test. See Notch Pay's testing page.
- Flutterwave: its test mode completes every mobile money payment after a few seconds, whatever the number. It has no number that fails a payment in Cameroon, so use the Abuna simulator to try failures. See Flutterwave's testing page.
- Fapshi: each network has three numbers that succeed and three that fail. Any other number gets a random result, so use a listed one. See Fapshi's test numbers.
MeSomb
| Number | Network | What happens |
|---|---|---|
+237600000001 | MTN Mobile Money Cameroon | Succeeds |
+237600000002 | MTN Mobile Money Cameroon | No answer, keeps waiting |
+237600000019 | MTN Mobile Money Cameroon | Fails: account limit reached |
+237600000029 | MTN Mobile Money Cameroon | Fails: no mobile money account |
+237600000039 | MTN Mobile Money Cameroon | Fails: declined |
+237600000069 | MTN Mobile Money Cameroon | Fails: declined |
+237600000001 | Orange Money Cameroon | Succeeds |
+237600000002 | Orange Money Cameroon | No answer, keeps waiting |
+237600000019 | Orange Money Cameroon | Fails: account limit reached |
+237600000029 | Orange Money Cameroon | Fails: no mobile money account |
+237600000039 | Orange Money Cameroon | Fails: declined |
+237600000049 | Orange Money Cameroon | Fails: balance too low |
+237600000069 | Orange Money Cameroon | Fails: declined |
+2250000000001 | MTN Mobile Money Côte d'Ivoire | Succeeds |
+2250000000002 | MTN Mobile Money Côte d'Ivoire | No answer, keeps waiting |
+2250000000029 | MTN Mobile Money Côte d'Ivoire | Fails: no mobile money account |
+2250000000039 | MTN Mobile Money Côte d'Ivoire | Fails: declined |
+2250000000069 | MTN Mobile Money Côte d'Ivoire | Fails: declined |
+2250000000001 | Orange Money Côte d'Ivoire | Succeeds |
+2250000000002 | Orange Money Côte d'Ivoire | No answer, keeps waiting |
+2250000000030 | Orange Money Côte d'Ivoire | Fails: declined |
+2250000000060 | Orange Money Côte d'Ivoire | Fails: declined |
+22600000001 | Moov Money Burkina Faso | Succeeds |
+22600000002 | Moov Money Burkina Faso | No answer, keeps waiting |
+22600000048 | Moov Money Burkina Faso | Fails: balance too low |
+22600000068 | Moov Money Burkina Faso | Fails: declined |
pawaPay
| Number | Network | What happens |
|---|---|---|
+237653456789 | MTN Mobile Money Cameroon | Succeeds |
+237653456129 | MTN Mobile Money Cameroon | No answer, keeps waiting |
+237653456019 | MTN Mobile Money Cameroon | Fails: account limit reached |
+237653456029 | MTN Mobile Money Cameroon | Fails: no mobile money account |
+237653456039 | MTN Mobile Money Cameroon | Fails: not approved on the phone |
+237653456069 | MTN Mobile Money Cameroon | Fails: declined |
+237693456789 | Orange Money Cameroon | Succeeds |
+237693456129 | Orange Money Cameroon | No answer, keeps waiting |
+237693456019 | Orange Money Cameroon | Fails: account limit reached |
+237693456029 | Orange Money Cameroon | Fails: no mobile money account |
+237693456039 | Orange Money Cameroon | Fails: not approved on the phone |
+237693456049 | Orange Money Cameroon | Fails: balance too low |
+237693456069 | Orange Money Cameroon | Fails: declined |
+2250503456789 | MTN Mobile Money Côte d'Ivoire | Succeeds |
+2250503456129 | MTN Mobile Money Côte d'Ivoire | No answer, keeps waiting |
+2250503456029 | MTN Mobile Money Côte d'Ivoire | Fails: no mobile money account |
+2250503456039 | MTN Mobile Money Côte d'Ivoire | Fails: not approved on the phone |
+2250503456069 | MTN Mobile Money Côte d'Ivoire | Fails: declined |
+2250734567890 | Orange Money Côte d'Ivoire | Succeeds |
+2250734567130 | Orange Money Côte d'Ivoire | No answer, keeps waiting |
+2250734567030 | Orange Money Côte d'Ivoire | Fails: not approved on the phone |
+2250734567060 | Orange Money Côte d'Ivoire | Fails: declined |
+221773456789 | Orange Money Senegal | Succeeds |
+221773456129 | Orange Money Senegal | No answer, keeps waiting |
+221773456029 | Orange Money Senegal | Fails: no mobile money account |
+221773456049 | Orange Money Senegal | Fails: balance too low |
+221773456069 | Orange Money Senegal | Fails: declined |
+221763456789 | Free Money Senegal | Succeeds |
+221763456129 | Free Money Senegal | No answer, keeps waiting |
+221763456049 | Free Money Senegal | Fails: balance too low |
+221763456069 | Free Money Senegal | Fails: declined |
+2290151345789 | MTN Mobile Money Benin | Succeeds |
+2290151345129 | MTN Mobile Money Benin | No answer, keeps waiting |
+2290151345029 | MTN Mobile Money Benin | Fails: no mobile money account |
+2290151345039 | MTN Mobile Money Benin | Fails: not approved on the phone |
+2290151345069 | MTN Mobile Money Benin | Fails: declined |
+2290195345789 | Moov Money Benin | Succeeds |
+2290195345639 | Moov Money Benin | No answer, keeps waiting |
+2290195345679 | Moov Money Benin | Fails: not approved on the phone |
+2290195345529 | Moov Money Benin | Fails: declined |
+22602345678 | Moov Money Burkina Faso | Succeeds |
+22602345138 | Moov Money Burkina Faso | No answer, keeps waiting |
+22602345048 | Moov Money Burkina Faso | Fails: balance too low |
+22602345068 | Moov Money Burkina Faso | Fails: declined |
Notch Pay
| Number | Network | What happens |
|---|---|---|
+237670000000 | MTN Mobile Money Cameroon | Succeeds |
+237670000001 | MTN Mobile Money Cameroon | Fails: balance too low |
+237670000002 | MTN Mobile Money Cameroon | Fails: declined |
+237670000003 | MTN Mobile Money Cameroon | No answer, keeps waiting |
+237670000004 | MTN Mobile Money Cameroon | Fails: not approved on the phone |
+237690000000 | Orange Money Cameroon | Succeeds |
+237690000001 | Orange Money Cameroon | Fails: balance too low |
+237690000002 | Orange Money Cameroon | Fails: declined |
+237690000003 | Orange Money Cameroon | No answer, keeps waiting |
+237690000004 | Orange Money Cameroon | Fails: not approved on the phone |
+225050000000 | MTN Mobile Money Côte d'Ivoire | Succeeds |
+225050000001 | MTN Mobile Money Côte d'Ivoire | Fails: balance too low |
+225050000002 | MTN Mobile Money Côte d'Ivoire | Fails: declined |
+225050000003 | MTN Mobile Money Côte d'Ivoire | No answer, keeps waiting |
+225050000004 | MTN Mobile Money Côte d'Ivoire | Fails: not approved on the phone |
+225070000000 | Orange Money Côte d'Ivoire | Succeeds |
+225070000001 | Orange Money Côte d'Ivoire | Fails: balance too low |
+225070000002 | Orange Money Côte d'Ivoire | Fails: declined |
+225070000003 | Orange Money Côte d'Ivoire | No answer, keeps waiting |
+225070000004 | Orange Money Côte d'Ivoire | Fails: not approved on the phone |
+225010000000 | Moov Money Côte d'Ivoire | Succeeds |
+225010000001 | Moov Money Côte d'Ivoire | Fails: balance too low |
+225010000002 | Moov Money Côte d'Ivoire | Fails: declined |
+225010000003 | Moov Money Côte d'Ivoire | No answer, keeps waiting |
+225010000004 | Moov Money Côte d'Ivoire | Fails: not approved on the phone |
+221770000000 | Orange Money Senegal | Succeeds |
+221770000001 | Orange Money Senegal | Fails: balance too low |
+221770000002 | Orange Money Senegal | Fails: declined |
+221770000003 | Orange Money Senegal | No answer, keeps waiting |
+221770000004 | Orange Money Senegal | Fails: not approved on the phone |
+221760000000 | Free Money Senegal | Succeeds |
+221760000001 | Free Money Senegal | Fails: balance too low |
+221760000002 | Free Money Senegal | Fails: declined |
+221760000003 | Free Money Senegal | No answer, keeps waiting |
+221760000004 | Free Money Senegal | Fails: not approved on the phone |
+2290190000000 | MTN Mobile Money Benin | Succeeds |
+2290190000001 | MTN Mobile Money Benin | Fails: balance too low |
+2290190000002 | MTN Mobile Money Benin | Fails: declined |
+2290190000003 | MTN Mobile Money Benin | No answer, keeps waiting |
+2290190000004 | MTN Mobile Money Benin | Fails: not approved on the phone |
+2290191000000 | Moov Money Benin | Succeeds |
+2290191000001 | Moov Money Benin | Fails: balance too low |
+2290191000002 | Moov Money Benin | Fails: declined |
+2290191000003 | Moov Money Benin | No answer, keeps waiting |
+2290191000004 | Moov Money Benin | Fails: not approved on the phone |
+226710000000 | Moov Money Burkina Faso | Succeeds |
+226710000001 | Moov Money Burkina Faso | Fails: balance too low |
+226710000002 | Moov Money Burkina Faso | Fails: declined |
+226710000003 | Moov Money Burkina Faso | No answer, keeps waiting |
+226710000004 | Moov Money Burkina Faso | Fails: not approved on the phone |
Flutterwave
| Number | Network | What happens |
|---|---|---|
+237670000000 | MTN Mobile Money Cameroon | Succeeds |
+237690000000 | Orange Money Cameroon | Succeeds |
+2250500000000 | MTN Mobile Money Côte d'Ivoire | Succeeds |
+2250100000000 | Moov Money Côte d'Ivoire | Succeeds |
+22660000000 | Moov Money Burkina Faso | Succeeds |
Fapshi
| Number | Network | What happens |
|---|---|---|
+237670000000 | MTN Mobile Money Cameroon | Succeeds |
+237670000002 | MTN Mobile Money Cameroon | Succeeds |
+237650000000 | MTN Mobile Money Cameroon | Succeeds |
+237670000001 | MTN Mobile Money Cameroon | Fails: declined |
+237670000003 | MTN Mobile Money Cameroon | Fails: declined |
+237650000001 | MTN Mobile Money Cameroon | Fails: declined |
+237690000000 | Orange Money Cameroon | Succeeds |
+237690000002 | Orange Money Cameroon | Succeeds |
+237656000000 | Orange Money Cameroon | Succeeds |
+237690000001 | Orange Money Cameroon | Fails: declined |
+237690000003 | Orange Money Cameroon | Fails: declined |
+237656000001 | Orange Money Cameroon | Fails: declined |
Live mode
Live mode bills real customers with the Live app ID and its sk_live_ key. Before it works, you need three things:
- A verified email for the team owner. Until then, every Live endpoint except
GET /v1/apps/{appID}returns403with codeemail_unverified. - A way to take payments. Connect your MeSomb, pawaPay, Notch Pay, Flutterwave, or Fapshi account to your team in the dashboard and choose it in the Live app, or turn on Abuna payments. Until then, you can set up products, prices, and customers. Starting a subscription or taking a payment returns
422with codenot_accepting_payments. - A support contact. Add a support email or URL under Settings, then General. Until then, starting a subscription or taking a payment returns
422with codenot_accepting_payments.
GET /v1/apps/{appID} shows where you stand. Its payments object has email_verified, provider_connected, support_contact, and ready.
In Live mode, the customer approves each payment on their phone. With your own provider account, customers pay straight into it, and Abuna never holds the money. With Abuna payments, Abuna collects the money and pays it out each morning at 08:00 Cameroon time, for a 3.5% fee. See Payment providers.
Switching to Live
Change the app ID and the secret key together. Your code stays the same. Live starts with no data: products, prices, customers, and subscriptions don't carry over from Test, so create them again in Live. Set your Live webhook URL and use the Live webhook signing secret to check signatures.
You can copy your products and prices from Test to Live, and from Live back to Test. In the dashboard, open Products in the mode you copy from, or use the API. See Copy between Test and Live.