Connecting a payment provider

In Live mode, customers pay with mobile money through your own pawaPay, Notch Pay, or Flutterwave account. The money goes from the customer's wallet to your provider account. Abuna starts each charge and tracks it, but never holds the money.

Test mode needs no provider: Test payments can always go through the Abuna simulator. To see how your providers behave before you go Live, connect their sandboxes to your Test app, beside the simulator. See Test with your provider's sandbox.

Choose a provider

pawaPay and Notch Pay take payments in XAF and XOF, and Flutterwave in XAF. Customers approve each payment on their phone. The networks each one offers through Abuna:

• pawaPay: MTN Mobile Money and Orange Money in Cameroon and Côte d'Ivoire, Free Money and Orange Money in Senegal, MTN Mobile Money and Moov Money in Benin, Moov Money in Burkina Faso, MTN Mobile Money and Airtel Money in Congo, and Airtel Money in Gabon. Customers can also pick Detect my network, and pawaPay works out the network from their number.
• Notch Pay: MTN Mobile Money and Orange Money in Cameroon, MTN Mobile Money, Orange Money, and Moov Money in Côte d'Ivoire, Orange Money and Free Money in Senegal, MTN Mobile Money and Moov Money in Benin, and Moov Money in Burkina Faso.
• Flutterwave: MTN Mobile Money and Orange Money in Cameroon.

More providers are coming.

Wave and Orange Money Burkina Faso aren't offered with any provider. They need a step the pay link doesn't have.

Get your credentials

A Live app takes only production credentials, and a Test app takes only sandbox credentials. From your provider's dashboard, copy:

• pawaPay: your API token. Abuna doesn't sign its requests to pawaPay, so turn off signed requests on your pawaPay account. If it only accepts signed requests, Abuna refuses the token. pawaPay doesn't document a collection-only token option. Before sharing a token, ask pawaPay to disable payouts and refunds on a separate account for Abuna. A separate account alone doesn't stop money going out. pawaPay won't create a token until a callback URL is set, and Abuna shows your Webhook URL only after you connect. So set a temporary Deposits callback URL first, such as your own website's address, then create the token. After you connect, replace the temporary URL with Abuna's Webhook URL.
• Notch Pay: your Public key and your Webhook hash key. Use your live keys. Abuna refuses Notch Pay sandbox keys on a Live app, because they would mark invoices paid with no money moved. Find your Public key under Settings, then API Keys. Don't share your Private key: Notch Pay requires it for transfers and refunds, but Abuna doesn't need it.
• Flutterwave: your Secret key and a Secret hash. If you don't have a Flutterwave account yet, sign up for one. Find your Secret key under Settings, then API Keys. Live keys start with FLWSECK-, and test keys with FLWSECK_TEST-. Abuna doesn't need your Public key or Encryption key. The Secret hash is a phrase you make up. Choose a long random one and keep a copy: you enter the same one in Flutterwave when you set the webhook URL. Flutterwave has no key that can only collect payments. Its Secret key can do anything on your account, including send money. Before sharing it, open Settings, then Business Preferences, then Security, and set transfers to Dashboard only. This turns off Transfer via API. If a key leaks, use Generate new keys to replace it. Your old keys stop working, so enter the new Secret key in Abuna right away.

Connect your account

1. In the dashboard, switch to Live mode and open Settings, then Payments.
2. Click Connect a provider, choose your provider, and paste your credentials.
3. Click Check and save. Abuna checks the credentials with your provider before it saves them.
4. Set the Webhook URL in your provider's dashboard. This step is required: see Set the webhook URL in your provider.

Only a team owner can connect a provider, and only from the dashboard. Each app has one provider at a time. Connecting another one replaces it. To edit a saved connection, leave a secret field empty to keep its saved value.

Abuna stores your secret credentials encrypted and never shows them again, only a short hint. If the provider refuses the credentials, saving fails with code provider_credentials_rejected. If Abuna can't reach the provider to check them, it fails with provider_unreachable. Try again in a moment.

Credentials from the wrong environment fail with 422:

• provider_sandbox_credentials_required: Notch Pay or Flutterwave live keys on a Test app. Use your sandbox or test keys.
• provider_live_credentials_required: Notch Pay sandbox keys or Flutterwave test keys on a Live app. Use your live keys.
• provider_credentials_rejected: a pawaPay production token on a Test app, or a sandbox token on a Live app. pawaPay refuses tokens from its other environment.

Set the webhook URL in your provider

Once you're connected, the Payments page shows a Webhook URL. Your provider calls it when a payment changes, so the payment updates in Abuna as soon as the customer approves it. This step is required: until it's set, payments may not update in Abuna, and paid invoices can stay open.

https://api.abuna.app/v1/providers/pawapay/3f9c0a7d5e2b4c18a6f1e9d2b7c4a051/webhook

• pawaPay: in your pawaPay dashboard, open System configuration, then Callback URLs, and paste it as the Deposits callback URL.
• Notch Pay: in your Notch Pay dashboard, open Settings, then Webhooks. Add an endpoint with this URL and turn on the payment events. Then, if Notch Pay shows a hash key for the endpoint that's different from the one you entered, click Edit on the Payments page and enter it as the Webhook hash key. Leave the Public key field empty to keep it. Until the hash keys match, Abuna can't check Notch Pay's updates.
• Flutterwave: in your Flutterwave dashboard, open Settings, then Webhooks. Paste this URL, and enter the same Secret hash you entered in Abuna. Tick Enable webhook retries and Enable webhook for failed transactions, then save. Until the Secret hashes match, Abuna can't check Flutterwave's updates.

The Payments page shows whether it works. It says Waiting for the first update until your first payment goes through, then Receiving updates with the time of the latest one. The dashboard reminds you to set the URL until then. If you switch to another provider, set its URL again.

The URL belongs to this app only, so keep it private. Your Test app and your Live app each have their own. For each call, Abuna asks your provider for the payment's status with your own credentials before it marks anything paid. Editing your credentials keeps the same URL. If you disconnect and connect again, you get a new one.

Try payments in Test mode

Every Test app has the Abuna simulator, listed first on the Payments page in Test mode. It is the default on Test pay links, which then offer four test methods instead of real networks. Each one gives a fixed result, and none moves money:

• Successful payment (test): the payment succeeds.
• Needs approval, then succeeds (test_pending): the payment waits about 10 seconds, as if for approval on a phone, then succeeds.
• Declined payment (test_declined): the payment fails with payment_declined.
• Insufficient balance (test_insufficient): the payment fails with insufficient_funds.

When you pay an invoice through the API in Test mode, Abuna uses the simulator's first method, so the payment succeeds. See Invoices and payments.

Test with your provider's sandbox

Before you go Live, you can test against your provider's sandbox from your Test app. You can connect one sandbox per provider, and the Abuna simulator stays available beside them. When a payer chooses a sandbox on a Test pay link, payments behave as they will in Live: the pay link offers the provider's networks, payments update as the provider reports them, and failed payments carry the provider's real reasons. No money moves. Test mode stays free and unlimited on every plan.

1. Get sandbox credentials. They are separate from your production ones.
   • pawaPay: sign in to the sandbox dashboard at dashboard.sandbox.pawapay.io. Set a temporary Deposits callback URL, then create an API token, as for Live.
   • Notch Pay: switch your dashboard to Sandbox, then copy your sandbox Public key and Webhook hash key.
   • Flutterwave: open Settings, then API Keys, and switch to Test. Copy your test Secret key, which starts with FLWSECK_TEST-, and make up a Secret hash.
2. Connect them in your Test app. In the dashboard, switch to Test mode, open Settings, then Payments. Click Connect a sandbox, choose your provider, and paste your sandbox credentials. Abuna checks them with your provider, as in Connect your account. Only a team owner can do this. The page then lists pawaPay sandbox, Notch Pay sandbox, or Flutterwave sandbox under Abuna simulator, with its own Webhook URL. Repeat for each provider you want to try.
3. Set the Webhook URL in the sandbox dashboard. Copy it from the Test app's Payments page.
   • pawaPay: in the sandbox dashboard, open System configuration, then Callback URLs, and replace the temporary Deposits callback URL with it.
   • Notch Pay: with your dashboard on Sandbox, open Settings, then Webhooks, and add an endpoint with the URL. Match the hash keys as in Set the webhook URL in your provider.
   • Flutterwave: open Settings, then Webhooks, and set the URL and Secret hash as in Set the webhook URL in your provider.
4. Pay a Test pay link with a test number. Under Test with, choose your provider's sandbox. The pay link then offers its networks and lists its test numbers: choose one to fill in the phone number. See Test phone numbers.
5. Watch the status change. The pay page follows the payment until it succeeds or fails. The Payments page changes from Waiting for the first update to Receiving updates, which shows your Webhook URL works.

Test phone numbers

Each provider's sandbox settles a payment according to the phone number charged. For MTN Mobile Money in Cameroon, pawaPay's +237653456789 succeeds and Notch Pay's +237670000001 fails for insufficient funds. Flutterwave's test mode completes every payment after a few seconds, whatever the number. For every number on each network, see Test numbers.

Sandbox credentials don't carry over to Live. When you go Live, connect production credentials in your Live app and set its own Webhook URL.

Disconnect a provider

A team owner can disconnect the provider from the Payments page. Until you connect one again, customers can't pay in Live, and new checkouts and payments fail with code not_accepting_payments. Payments already made aren't affected. In a Test app, disconnecting a sandbox removes it from Test pay links. The Abuna simulator and your other sandboxes stay.

While you're disconnected, nobody is canceled for not paying. Renewal invoices stay open, and payment reminders wait. Once you reconnect, customers with an unpaid renewal get a full grace period from that moment.