Test mode and Live mode

Every app has two environments, 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 and Telegram messages aren't sent. Abuna records each one as a notification.captured event, which never goes to your webhook endpoint. The notices list stays empty.
• 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, pawaPay, Notch Pay, and Flutterwave, side by side. The Payments page, under Settings in Test mode, lists the simulator and every connected sandbox. Each sandbox has its own Webhook URL.

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 on the first status check after 10 seconds. The pay page checks for you.
• 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 entry with POST /v1/apps/{appID}/entries/{id}/pay, 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 entry'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: pawapay, notchpay, or flutterwave. 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.

• 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. It has no test numbers for Benin or Burkina Faso. 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.

pawaPay

Notch Pay

Flutterwave

Live mode

Live mode bills real customers with the Live app ID and its sk_live_ key. Before it works, you need two 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 connected payment provider. Connect your pawaPay, Notch Pay, or Flutterwave account in the dashboard. Until then, you can set up products, prices, and customers. 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, and ready.

Live payments are charged to the customer's phone through your own provider account. Abuna never holds the money.

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 endpoint and use the Live webhook signing secret to check signatures.