Skip to main content
A payout moves money from your Bachs balance to a bank account or wallet that belongs to you. You save each destination once, then pick a usable one for every payout. You can pay an NGN balance out to your Nigerian bank account, for example, or use your USD balance to send GBP to your UK bank account. Payout currencies and methods lists every route and the details each one needs. Payouts are open to every Bachs account that meets the payout requirements, to a destination that has been approved and is usable.

​
Before you start

  • The account. It needs an active payouts capability and its identity checks complete. International payouts also need the account holder’s name, contact email and address.
  • The balance. Check the available balance, with enough left over for the payout fee, in Balances on the dashboard or with Get Balances.
  • The destination. It must belong to the account holder. Check that it is approved and usable in the dashboard, or read its is_usable field through the API.
International bank and mobile money routes are funded from your available USD balance. An NGN balance cannot fund them. A currency you can pay out to is not always one you can hold as a balance; see Supported balance currencies.
The API examples in this section use https://sandbox-api.bachs.io and example values. Sandbox payouts are simulated and move no real money, so a sandbox test tells you nothing about live destination approval or bank delivery times.

​
Choose how to create payouts

The dashboard flow needs no API key. API integrations use a server-side secret key with the scopes each endpoint needs; keep secret keys out of browser code. The dashboard labels payout actions and history Withdraw and Withdrawals. The guides use those labels so you can find the controls.

​
How a payout works

1

Save your destination

Add your bank account or wallet in the dashboard, or register it with Create Destination. Reuse the saved destination for later payouts. Funds can only go to it once it is approved and usable.
2

Get a quote if the currencies differ

The dashboard prepares the estimate and any conversion quote for you. Through the API, call Create Payout Quote right before a cross-currency payout. A same-currency payout needs no quote.
3

Create the payout

In the dashboard, confirm the destination, the amount, the rate if there is one, and the total debit. Through the API, call Create Payout with amount for a same-currency payout, or with quote_id and no amount for a converted one. Send an Idempotency-Key and store the payout ID you get back.
4

Track the result

Find the record in Balances → Withdrawals on the dashboard. Through the API, listen for payout.paid and payout.failed, or retrieve the payout with Get Payout. A payout that has been accepted has not necessarily arrived.

​
Amounts, conversion and fees

In the dashboard, check To receive, the fee and Total debited before you confirm. Through the API, amount means something different in each of these two requests: With a quote, create the payout with quote_id and leave amount out. The quote fixes both the source and destination amounts. As an example, a 5000.00 NGN payout with a 100.00 NGN fee debits 5100.00 NGN. That fee is made up for the example, not a published rate. See Fees, and reconcile each payout against total_debited in source_currency.

​
Accepted is not completed

A successful API response, or the dashboard’s Withdrawal started screen, means the payout has started. It does not mean your bank account or wallet has the money yet. A payout’s status is one of these: To reconcile a period, use the dashboard’s payout history or List Payouts. API integrations can also retrieve and list payouts to catch up after a missed webhook.

​
Recover from an uncertain request

If a confirmation fails or a request is cut off, you may not know whether the payout was created. It may exist even though you never saw a success response. In the dashboard, check Balances → Withdrawals before you start another payout. If you still cannot tell what happened, contact support. After an API timeout or a 5xx response:
  1. Retrieve the payout if you have its ID. If you don’t, look through recent payouts and match them against the reference and details you stored.
  2. If the payout exists, track it rather than creating another.
  3. If you still cannot tell, find out before you send another payout. Contact support if you cannot establish what happened.
Use one Idempotency-Key per intended payout, and send the same key when you retry that request. A new payout needs a new key. Idempotency stores successful responses; it does not promise that repeating a request after every kind of error can never create a duplicate.

​
Connected accounts

When you act for a connected account, send its X-Account-Id on every call for its balance, destination and payout. Its payouts capability must be active, and the destination must belong to its account holder. Funding a connected account with a transfer and paying out from that account are two separate operations. See Connected account payouts and Onboarding requirements.

​
Next steps