Skip to content
ABUNA
DocsConnecting a payment provider

Guides

Connecting a payment provider

Connect your own MeSomb, pawaPay, Notch Pay, Flutterwave or Fapshi account, or use Abuna payments.

View as Markdown

This guide shows you how to take mobile money payments in Live mode and try them in Test mode. In Live mode, customers pay through your own MeSomb, pawaPay, Notch Pay, Flutterwave or Fapshi account. With your own provider account, customers pay straight into it, and Abuna never holds the money.

No provider account? Use Abuna payments. Abuna then collects the money and pays it out to you each morning at 08:00 Cameroon time, for the payments of the day before.

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 and use them in Test mode, beside the simulator. See Test with your provider's sandbox.

Abuna payments

Abuna payments lets your app take Live payments without a provider account of your own. Customers pay on the same checkout and pay pages, with MTN Mobile Money or Orange Money, and pay exactly the invoice amount. Abuna collects the money and pays it out to your mobile money number every day.

  1. In Live mode, open your app's Settings, then Payments, and choose Abuna payments.
  2. Accept the terms.
  3. Enter the MTN Mobile Money or Orange Money number in Cameroon that Abuna should pay, and the name on that account.

Only a team owner can turn it on. The app can take payments right away: there's no account to connect and no provider webhook URL to set.

Fee: Abuna keeps 3.5% of each successful payment, and you get 96.5%. No provider fee comes on top, and a failed payment costs nothing. The fee is rounded down to the whole franc, so you always get at least 96.5%.

On a FCFA 2,990 payment, the fee is FCFA 104 and you get FCFA 2,886. Each payment shows both, as fee and net on the payment object.

Payouts: each day at 08:00 Cameroon time (WAT), Abuna pays out what it owes you for the payments of the day before. It goes to your mobile money number when your balance is above FCFA 100. A smaller balance waits for a later payout.

Your operator's SMS confirms each payout, and the dashboard lists them with their references. Early each month, team owners get a statement by email for the month before. It lists the payouts, the number of payments, the amount collected, the fee and what you got.

If a payout can't be sent, usually because the number is wrong or inactive, the money stays owed to you. Team owners get an email saying what to check. Correct the number in the app's Payments settings, and the amount goes out with the next payout.

An app uses either Abuna payments or one of your own provider accounts, never both. If you switch to your own account, what Abuna owes you is still paid at the next payout, if it's above FCFA 100. Abuna payments is for Live mode only. Test mode keeps the Abuna simulator and your sandboxes.

Choose a provider

Prices can be in XAF, XOF or USD, and customers always pay in FCFA, in their network's currency. pawaPay, Notch Pay, MeSomb and Flutterwave take payments in XAF and XOF. Fapshi and Abuna payments take XAF only: prices in XOF or USD still pay through them on Cameroon numbers, converted to XAF. A USD price is charged at the day's rate plus 2%, and XOF converts 1 to 1. See Paying in FCFA.

Customers approve each payment on their phone. If no prompt reaches them, the pay page shows how to approve the waiting payment from their phone's menu, in their language. The networks each provider offers through Abuna:

  • MeSomb: MTN Mobile Money and Orange Money in Cameroon and Côte d'Ivoire, and Moov Money in Burkina Faso. MeSomb takes its fee from what you receive, so the customer pays exactly the invoice amount. Each successful payment shows MeSomb's fee.
  • pawaPay: MTN Mobile Money and Orange Money in Cameroon and 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.
  • 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, MTN Mobile Money and Moov Money in Côte d'Ivoire, and Moov Money in Burkina Faso.
  • Fapshi: MTN Mobile Money and Orange Money in Cameroon. Fapshi takes payments of FCFA 100 or more, so an invoice for less can't be paid through Fapshi.
  • Abuna payments: MTN Mobile Money and Orange Money in Cameroon.

Checkout takes phone numbers from Cameroon, Côte d'Ivoire, Senegal, Benin and Burkina Faso, on its payment step, for the countries where your provider has a network. With Fapshi or Abuna payments, that is Cameroon only. In Cameroon and Côte d'Ivoire the network comes from the number, and the customer chooses it only when the number doesn't tell. In Senegal, Benin and Burkina Faso the customer chooses the network. MeSomb's own wallet isn't offered.

Coming soon: more countries, and more providers.

Get your credentials

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

  • MeSomb: your Application key, Access key, and Secret key, and a Webhook signing secret. Find the three keys in your MeSomb dashboard under Developer settings. Leave the signing secret empty when you first connect: MeSomb shows it only after you add the webhook, as in Set the provider webhook URL. MeSomb uses the same keys for test and live payments. Your MeSomb application stays in test mode until MeSomb approves it for live payments. Test mode ends when you submit your MeSomb account for verification. Connect an application MeSomb has approved as a Live account, and one still in test mode as a Test account. Abuna can't tell the two apart when you connect, so check the application in MeSomb first: a Live account with an application in test mode collects no money. In Live mode, your app refuses MeSomb's test numbers. In Test mode, it charges only those numbers.
  • 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 provider 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 provider webhook URL.
  • Notch Pay: your Public key and your Webhook hash key. Use your live keys. Abuna refuses Notch Pay sandbox keys for a Live account, 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 provider 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.
  • Fapshi: your API user and API key, and a Webhook secret. Fapshi only lets activated accounts use its API, even to test, so activate yours first: see Fapshi's account activation guide. In your Fapshi dashboard, open Developers and create a collection service with New Service. A Fapshi service either collects payments or sends payouts, never both, so a collection service can't send money. Each service has two pairs of keys: the live pair under API, and the sandbox pair under Sandbox. Use the live pair here. Fapshi keeps one webhook URL per service, so keep this service for Live and test with a second collection service, as in Test with your provider's sandbox. The Webhook secret is a phrase you make up. Choose a long random one and keep a copy: you enter the same one in Fapshi when you set the provider webhook URL. Before your app can take Live payments through Fapshi, Fapshi must turn on Direct Pay for your account. Direct Pay sends the payment request to your customer's phone, and it's off by default. Test with your sandbox keys first, then email support@fapshi.com with the details Fapshi lists in How to activate Direct Pay. You need a live website that explains your business. Send your live API user only, never your API key. Fapshi reviews each request and publishes no approval time. Until it approves yours, Fapshi refuses your Live payments. Don't limit this service's payments to listed IP addresses in Fapshi: Fapshi would refuse the payments Abuna starts.

Connect your account

Provider accounts belong to your team. You connect each one once, for Live or for Test, and any of your team's apps in that mode can use it.

  1. In the dashboard, open your team's Provider accounts page.
  2. In Live mode, click Connect account, 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 Provider webhook URL in your provider's dashboard. This step is required: see Set the provider webhook URL.
  5. On the account, tick I've added this URL in your provider. For MeSomb, saving the signing secret does this for you.
  6. In Live mode, open your app's Settings, then Payments, click Choose account, and pick the account.

You can also click Connect a new account in an app's Payments settings. The account is saved to Provider accounts for the whole team, and that app uses it right away.

Several apps can use the same account. In Live mode, an app uses one account at a time: choosing another replaces it. When you replace an account's keys, leave a secret field empty to keep its saved value. New keys apply at once to every app that uses the account.

Only a team owner can connect, edit, or remove an account, or choose the one an app uses, and only from the dashboard. Other team members can see the accounts and which apps use them, but never their credentials.

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 for a Test account. Use your sandbox or test keys.
  • provider_live_credentials_required: Notch Pay sandbox keys or Flutterwave test keys for a Live account. Use your live keys.
  • provider_credentials_rejected: a pawaPay production token for a Test account, or a sandbox token for a Live account. pawaPay refuses tokens from its other environment.

MeSomb keys connect as a Test or Live account without this check, because MeSomb uses the same keys in both. Choose the MeSomb application as in Get your credentials.

Set the provider webhook URL

Each provider account has one Provider webhook URL. It shows on the account, in your team's Provider accounts, and in the Payments settings of every app that uses it. 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.

Provider webhook URL
https://api.abuna.app/v1/providers/pawapay/3f9c0a7d5e2b4c18a6f1e9d2b7c4a051/webhook
  • MeSomb: in your MeSomb dashboard, open Developer settings and add a webhook endpoint with this URL. MeSomb shows the endpoint's signing secret, which starts with whsec_, only once, so copy it right away. Then, on the account in Abuna, choose Replace keys and paste it as the Webhook signing secret. With it, MeSomb payments confirm within seconds. Until you do, they still confirm on their own, usually within the hour, but some can take several hours.
  • 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 Replace keys on the account in Abuna 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.
  • Fapshi: in your Fapshi dashboard, open Developers, then your collection service. Paste this URL as its webhook URL, enter the same Webhook secret you entered in Abuna, and save. Fapshi sends the secret with every update. Until the secrets match, Abuna can't check Fapshi's updates. A missed Fapshi update doesn't leave a paid invoice open.

Once the URL is set, tick I've added this URL in your provider on the account. For MeSomb, saving the signing secret does this for you. The dashboard reminds you to set the URL until then. The account then says Waiting for first update until your provider reports a payment, then Receiving updates with the time of the latest one. If an app switches to an account whose URL isn't set yet, set that account's URL and tick the box.

The URL belongs to your provider account, not to one app, so keep it private. Every app that uses the account shares it, so you set it in your provider once. Your Test and Live accounts each have their own. Editing the account's credentials keeps the same URL, and a new account gets a new one.

Try payments in Test mode

Test mode always 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 in Test mode. Your app can use one sandbox account per provider in Test mode, and the Abuna simulator stays available beside them. When a customer 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.
    • MeSomb: MeSomb has no separate sandbox. Use an application that MeSomb hasn't approved for live payments yet, and copy its three keys from Developer settings.
    • 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.
    • Fapshi: once your account is activated, open Developers and create a collection service for testing with New Service. Fapshi keeps one webhook URL per service, so your Live service can't also update your Test account. Copy the API user and API key under Sandbox, and make up a Webhook secret.
  2. Connect them as Test accounts. On your team's Provider accounts page, switch to Test, click Connect account, choose your provider, and paste your sandbox credentials. Abuna checks them with your provider, as in Connect your account. Then, in the dashboard, switch to Test mode, open Settings, then Payments, click Add sandbox, and pick the account. You can also connect a new account from there in one step. Only a team owner can do this. The page then lists MeSomb sandbox, pawaPay sandbox, Notch Pay sandbox, Flutterwave sandbox, or Fapshi sandbox under Abuna simulator, with the account's provider webhook URL. Repeat for each provider you want to try.
  3. Set the provider webhook URL in the sandbox dashboard. Copy it from the Test account.
    • MeSomb: open Developer settings for your test-mode application, add a webhook endpoint with the URL, copy its signing secret, and paste it in Abuna with Replace keys, as in Set the provider webhook URL.
    • 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 provider webhook URL.
    • Flutterwave: open Settings, then Webhooks, and set the URL and Secret hash as in Set the provider webhook URL.
    • Fapshi: open Developers, then your test collection service, and set the URL and Webhook secret as in Set the provider webhook URL.
  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 account changes from Waiting for first update to Receiving updates, which shows your provider webhook URL works.

Test phone numbers

Each provider's sandbox settles a payment according to the phone number charged. MeSomb's test numbers depend on the network: the same number can succeed on one network and fail on another. 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. Fapshi's +237670000000 succeeds and +237670000001 fails, and any number Fapshi doesn't list gets a random result. For every number on each network, see Test numbers.

Sandbox credentials don't carry over to Live. When you go Live, connect a Live account with production credentials, set its provider webhook URL, and choose it in your app in Live mode. For MeSomb, that means an application MeSomb has approved for live payments, with its own webhook endpoint.

Disconnect a provider

A team owner can click Stop using on an app's Payments page. The account stays in Provider accounts, and other apps keep using it. Until the app uses another account in Live mode, its customers can't pay, and new checkouts and payments fail with code not_accepting_payments. Payments already made aren't affected. In Test mode, stopping a sandbox removes it from Test pay links. The Abuna simulator and your other sandboxes stay.

To delete an account, click Remove on it in Provider accounts. You can remove it once no app uses it and no payment through it is in progress. First switch every app that uses it to another account, or stop using it there. Until then, removing it fails with code provider_account_in_use. While a payment through it is in progress, removing it fails with code provider_account_payments_pending. A payment marked failed may count as in progress for up to 7 days after it started, while it could still go through. Try again once the payment has gone through, or once it can no longer go through. Once it's removed, its provider webhook URL stops working, so remove that URL from your provider's dashboard too.

Replace keys works the same way: while a payment through the account is in progress, including a payment marked failed that could still go through, saving different keys fails with code provider_account_credentials_pending. Try again once that payment has gone through, or once it can no longer go through. A webhook secret can change at any time: MeSomb's Webhook signing secret, Notch Pay's Webhook hash key, Flutterwave's Secret hash, and Fapshi's Webhook secret. So can a key the account doesn't have yet, and the account's name.

While your app has no account in Live mode, nobody is canceled for not paying. Renewal invoices stay open, and reminders wait. Once it uses an account again, customers with an unpaid renewal get their full days to pay from that moment.

Next steps