Skip to content
ABUNA
DocsTest mode and Live mode

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.

View as Markdown

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.captured event, 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_url and cancel_url can be http URLs on localhost, 127.0.0.1, or [::1]. Live mode takes only https.
  • 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 is pending at 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 with 402 and code payment_declined.
  • Insufficient balance (test_insufficient): fails with 402 and code insufficient_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.

Rehearse a declined payment
curl https://api.abuna.app/v1/pay/3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d \
  -H "Content-Type: application/json" \
  -d '{"method": "test_declined"}'
Response 402
{
  "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.

Rehearse a payment the payer doesn't approve
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

NumberNetworkWhat happens
+237600000001MTN Mobile Money CameroonSucceeds
+237600000002MTN Mobile Money CameroonNo answer, keeps waiting
+237600000019MTN Mobile Money CameroonFails: account limit reached
+237600000029MTN Mobile Money CameroonFails: no mobile money account
+237600000039MTN Mobile Money CameroonFails: declined
+237600000069MTN Mobile Money CameroonFails: declined
+237600000001Orange Money CameroonSucceeds
+237600000002Orange Money CameroonNo answer, keeps waiting
+237600000019Orange Money CameroonFails: account limit reached
+237600000029Orange Money CameroonFails: no mobile money account
+237600000039Orange Money CameroonFails: declined
+237600000049Orange Money CameroonFails: balance too low
+237600000069Orange Money CameroonFails: declined
+2250000000001MTN Mobile Money Côte d'IvoireSucceeds
+2250000000002MTN Mobile Money Côte d'IvoireNo answer, keeps waiting
+2250000000029MTN Mobile Money Côte d'IvoireFails: no mobile money account
+2250000000039MTN Mobile Money Côte d'IvoireFails: declined
+2250000000069MTN Mobile Money Côte d'IvoireFails: declined
+2250000000001Orange Money Côte d'IvoireSucceeds
+2250000000002Orange Money Côte d'IvoireNo answer, keeps waiting
+2250000000030Orange Money Côte d'IvoireFails: declined
+2250000000060Orange Money Côte d'IvoireFails: declined
+22600000001Moov Money Burkina FasoSucceeds
+22600000002Moov Money Burkina FasoNo answer, keeps waiting
+22600000048Moov Money Burkina FasoFails: balance too low
+22600000068Moov Money Burkina FasoFails: declined

pawaPay

NumberNetworkWhat happens
+237653456789MTN Mobile Money CameroonSucceeds
+237653456129MTN Mobile Money CameroonNo answer, keeps waiting
+237653456019MTN Mobile Money CameroonFails: account limit reached
+237653456029MTN Mobile Money CameroonFails: no mobile money account
+237653456039MTN Mobile Money CameroonFails: not approved on the phone
+237653456069MTN Mobile Money CameroonFails: declined
+237693456789Orange Money CameroonSucceeds
+237693456129Orange Money CameroonNo answer, keeps waiting
+237693456019Orange Money CameroonFails: account limit reached
+237693456029Orange Money CameroonFails: no mobile money account
+237693456039Orange Money CameroonFails: not approved on the phone
+237693456049Orange Money CameroonFails: balance too low
+237693456069Orange Money CameroonFails: declined
+2250503456789MTN Mobile Money Côte d'IvoireSucceeds
+2250503456129MTN Mobile Money Côte d'IvoireNo answer, keeps waiting
+2250503456029MTN Mobile Money Côte d'IvoireFails: no mobile money account
+2250503456039MTN Mobile Money Côte d'IvoireFails: not approved on the phone
+2250503456069MTN Mobile Money Côte d'IvoireFails: declined
+2250734567890Orange Money Côte d'IvoireSucceeds
+2250734567130Orange Money Côte d'IvoireNo answer, keeps waiting
+2250734567030Orange Money Côte d'IvoireFails: not approved on the phone
+2250734567060Orange Money Côte d'IvoireFails: declined
+221773456789Orange Money SenegalSucceeds
+221773456129Orange Money SenegalNo answer, keeps waiting
+221773456029Orange Money SenegalFails: no mobile money account
+221773456049Orange Money SenegalFails: balance too low
+221773456069Orange Money SenegalFails: declined
+221763456789Free Money SenegalSucceeds
+221763456129Free Money SenegalNo answer, keeps waiting
+221763456049Free Money SenegalFails: balance too low
+221763456069Free Money SenegalFails: declined
+2290151345789MTN Mobile Money BeninSucceeds
+2290151345129MTN Mobile Money BeninNo answer, keeps waiting
+2290151345029MTN Mobile Money BeninFails: no mobile money account
+2290151345039MTN Mobile Money BeninFails: not approved on the phone
+2290151345069MTN Mobile Money BeninFails: declined
+2290195345789Moov Money BeninSucceeds
+2290195345639Moov Money BeninNo answer, keeps waiting
+2290195345679Moov Money BeninFails: not approved on the phone
+2290195345529Moov Money BeninFails: declined
+22602345678Moov Money Burkina FasoSucceeds
+22602345138Moov Money Burkina FasoNo answer, keeps waiting
+22602345048Moov Money Burkina FasoFails: balance too low
+22602345068Moov Money Burkina FasoFails: declined

Notch Pay

NumberNetworkWhat happens
+237670000000MTN Mobile Money CameroonSucceeds
+237670000001MTN Mobile Money CameroonFails: balance too low
+237670000002MTN Mobile Money CameroonFails: declined
+237670000003MTN Mobile Money CameroonNo answer, keeps waiting
+237670000004MTN Mobile Money CameroonFails: not approved on the phone
+237690000000Orange Money CameroonSucceeds
+237690000001Orange Money CameroonFails: balance too low
+237690000002Orange Money CameroonFails: declined
+237690000003Orange Money CameroonNo answer, keeps waiting
+237690000004Orange Money CameroonFails: not approved on the phone
+225050000000MTN Mobile Money Côte d'IvoireSucceeds
+225050000001MTN Mobile Money Côte d'IvoireFails: balance too low
+225050000002MTN Mobile Money Côte d'IvoireFails: declined
+225050000003MTN Mobile Money Côte d'IvoireNo answer, keeps waiting
+225050000004MTN Mobile Money Côte d'IvoireFails: not approved on the phone
+225070000000Orange Money Côte d'IvoireSucceeds
+225070000001Orange Money Côte d'IvoireFails: balance too low
+225070000002Orange Money Côte d'IvoireFails: declined
+225070000003Orange Money Côte d'IvoireNo answer, keeps waiting
+225070000004Orange Money Côte d'IvoireFails: not approved on the phone
+225010000000Moov Money Côte d'IvoireSucceeds
+225010000001Moov Money Côte d'IvoireFails: balance too low
+225010000002Moov Money Côte d'IvoireFails: declined
+225010000003Moov Money Côte d'IvoireNo answer, keeps waiting
+225010000004Moov Money Côte d'IvoireFails: not approved on the phone
+221770000000Orange Money SenegalSucceeds
+221770000001Orange Money SenegalFails: balance too low
+221770000002Orange Money SenegalFails: declined
+221770000003Orange Money SenegalNo answer, keeps waiting
+221770000004Orange Money SenegalFails: not approved on the phone
+221760000000Free Money SenegalSucceeds
+221760000001Free Money SenegalFails: balance too low
+221760000002Free Money SenegalFails: declined
+221760000003Free Money SenegalNo answer, keeps waiting
+221760000004Free Money SenegalFails: not approved on the phone
+2290190000000MTN Mobile Money BeninSucceeds
+2290190000001MTN Mobile Money BeninFails: balance too low
+2290190000002MTN Mobile Money BeninFails: declined
+2290190000003MTN Mobile Money BeninNo answer, keeps waiting
+2290190000004MTN Mobile Money BeninFails: not approved on the phone
+2290191000000Moov Money BeninSucceeds
+2290191000001Moov Money BeninFails: balance too low
+2290191000002Moov Money BeninFails: declined
+2290191000003Moov Money BeninNo answer, keeps waiting
+2290191000004Moov Money BeninFails: not approved on the phone
+226710000000Moov Money Burkina FasoSucceeds
+226710000001Moov Money Burkina FasoFails: balance too low
+226710000002Moov Money Burkina FasoFails: declined
+226710000003Moov Money Burkina FasoNo answer, keeps waiting
+226710000004Moov Money Burkina FasoFails: not approved on the phone

Flutterwave

NumberNetworkWhat happens
+237670000000MTN Mobile Money CameroonSucceeds
+237690000000Orange Money CameroonSucceeds
+2250500000000MTN Mobile Money Côte d'IvoireSucceeds
+2250100000000Moov Money Côte d'IvoireSucceeds
+22660000000Moov Money Burkina FasoSucceeds

Fapshi

NumberNetworkWhat happens
+237670000000MTN Mobile Money CameroonSucceeds
+237670000002MTN Mobile Money CameroonSucceeds
+237650000000MTN Mobile Money CameroonSucceeds
+237670000001MTN Mobile Money CameroonFails: declined
+237670000003MTN Mobile Money CameroonFails: declined
+237650000001MTN Mobile Money CameroonFails: declined
+237690000000Orange Money CameroonSucceeds
+237690000002Orange Money CameroonSucceeds
+237656000000Orange Money CameroonSucceeds
+237690000001Orange Money CameroonFails: declined
+237690000003Orange Money CameroonFails: declined
+237656000001Orange Money CameroonFails: 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:

  1. A verified email for the team owner. Until then, every Live endpoint except GET /v1/apps/{appID} returns 403 with code email_unverified.
  2. 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 422 with code not_accepting_payments.
  3. A support contact. Add a support email or URL under Settings, then General. Until then, starting a subscription or taking a payment returns 422 with code not_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.

Next steps