Payouts

Money → Payouts is “money you send from your balance to a mobile-money number or a bank account”: a supplier, a member of staff, a customer paid back outside a refund. It needs payout.read to see and payout.create to send. Owner, admin and finance hold both. Developers and members don’t, and can’t see the page.

A payout is not a withdrawal

A withdrawal pays your own verified destination and waits for our approval. A payout pays any number or account typed into the form, and leaves as soon as it is processed, with no second approver. That is the larger power, which is why it has its own permission and, on live, needs your authenticator code.

The list shows payouts sent from here. Payouts your server sends with POST /v1/payouts are in Transactions.

Sending one

An Available to send card shows your available balance, with Send a payout (Send a test payout in test). The form has two steps.

1. Details

Field	Notes
Send to	Mobile money or Bank account cards. A method your account can’t pay out over yet is greyed out; see below.
Network / Bank	Network buttons, or Search for the bank among payout-capable banks.
Number / Account number	The recipient’s.
Recipient’s name	Looked up from the network or bank once the number is complete (see below). A name found is filled in read-only and is the name sent with the payout. Otherwise you type it.
They receive	What the recipient gets. The fee is charged on top and is always yours, even if your customers bear fees on collections. A payout carries no commission. Use all fills in your available balance.
Description	Optional. May appear on their statement.
Your reference	Optional.

The name is looked up for you. Once the number is whole and its network or bank is chosen, the form asks who holds the account (“Looking up who holds this account…”). A found name shows “As the network or bank has it.” If no partner offers lookup for that bank or network (“Name lookup is not available for this bank or network yet. Enter the name yourself.”), the number has no account (“The bank or network has no account with that number. Check it.”), or the lookup is slow, you type the name. Review waits until the lookup has answered.

The lookup doesn’t run while you type. A mobile-money number is looked up only once it is a full Ghanaian number: 0 and nine digits, 233 and nine digits, or the nine digits alone, after a short pause (0.7s). An account number is looked up once it has at least 10 digits and you have stopped typing for 1.5s.

When a lookup fails for a passing reason (a partner error, a slow answer, a dropped connection, or the hourly limit), the hint under the name offers Try again, which asks the partner afresh. When the network or bank says there is no such account, there is no Try again: fix the number instead. Either way, you can type the name yourself. Check a found name before you send: a name you didn’t expect usually means a wrong digit. See Name lookups for the rules.

2. Review and send

“Check the recipient and the amounts. A payout cannot be called back once sent.” A recipient card, then:

Line	What it is
They receive	The amount.
Fee	Our fee, with any tax on it.
Taken from your balance	The two together.
Left afterwards	Your available balance after it.

The figures come from the same pricing as the payout itself. Send is disabled when the total is more than your balance (“Not enough balance”). On live, enter the Authenticator code here.

On live you need your authenticator. A recovery code is not accepted. If you have no authenticator set up, the dialog says so: turn on two-factor authentication in Settings first. Wrong codes count toward the same lockout as wrong codes at sign-in, and while you are locked out no code is accepted here either (“Too many wrong codes. Wait a few minutes, then try again.”, a 429). Each code authorises one payout: using it again gives “That code has already been used. Wait for your authenticator app to show a new one.” Your balance is checked before the code is used, so a payout refused for balance doesn’t spend it. Test payouts need no code and use the test balance; nothing real is sent.

Sending twice is safe. Each open form carries its own idempotency key, so a double click, or a retry after a timeout, returns the first request rather than paying twice. If an error leaves you unsure whether it went, check the list first. To send another payout, close the form and open it again.

Only methods you can use are offered. If your account can’t pay out over mobile money but can over a bank, the form starts on bank. When the chosen method is blocked, the form says “… payouts are not available on this account yet:” followed by the reason, and won’t send. The reasons are the same as on payment links.

The amount and its fee must fit your available balance, less payouts already waiting to be sent. A suspended account cannot send payouts.

Statuses

The form records a request, and the payment engine sends it within seconds, through the same path as POST /v1/payouts. So pricing, routing, risk checks, your verification and limits, and the balance debit all apply exactly as for an API payout. A row shows the request’s state, then the payout’s once one exists:

Status	Meaning
Sending	Waiting to be sent.
Submitted	A payout was created; its own status follows.
A payout status (pending, succeeded, failed…)	What happened to the money. A submitted request whose payout failed is not paid, and the reason is shown beneath.
Not sent	Refused before anything was sent: the reason is shown beneath, and nothing left your balance. A failed verification or limit check, a declined risk check, or a balance that ran short ends here.

The payout itself records the teammate who sent it, just as an API payout records its key. The recipient’s number and name are kept on the request only until it is sent or refused. After that they are held on the payout itself, like any payout’s.

Name lookups

Lookups from the portal are free, unlike the payment API’s POST /v1/name-enquiries, which charges your plan’s fee. They need payout.create, collection.create or billing.write, and are limited to 60 per person per hour (“You have looked up a lot of accounts in the last hour. Enter the name yourself, or try again later.”). The same question within ten minutes is answered from the first lookup, unless that one failed. Only the person who asked can read the answer, and lookups are deleted after a day. The Collect form uses the same lookups.

From the API

The portal’s API: GET /v1/payouts/quote?amount_minor=&channel= (payout.read) returns amount_minor (what the recipient gets), fee_minor (ours, always yours), and total_minor (what leaves your balance), or 409 unpriced_combination when no price applies. Also GET /v1/payouts/options (what the form needs, including whether a code is required and whether you have an authenticator), GET /v1/payouts, GET /v1/payouts/{id} and POST /v1/payouts. The POST requires an Idempotency-Key; the same key with a different body is refused. Name lookups: POST /v1/name-enquiries with channel (mobile_money or bank), account_number, and momo_network_id or bank_id, answers 202 with the lookup queued; GET /v1/name-enquiries/{id} then returns done with account_name, or failed with an outcome saying why there is none. The gateway worker answers in about two seconds. Your server’s payouts use the public API’s POST /v1/payouts with a secret key instead.