Create a payout

Send money from your Bachs balance to your own bank account or wallet using the dashboard or API. Choose the instructions below for how you want to create the payout. For either method, meet the Overview. Use a supported destination belonging to you and keep enough available funds to cover the payout and fee. International bank and mobile money routes use USD funds.

Dashboard
API

The dashboard currently labels the payout action Withdraw. The instructions below use the button and tab names you will see there. You do not need an API key or a separate API quote request to use this flow. Check that you are viewing the intended account and environment; sandbox payouts are simulated.

1. Open the payout form

Open Balances, select the balance you want to use and click Withdraw. Choose the Currency Balance and enter the amount, then click Continue.Use an available NGN balance for an NGN bank payout, or your available USD balance for an international bank or mobile money route. Pending funds are not available to pay out.

The Bachs dashboard Balance page showing the Withdraw and Manage payouts buttons above a USD balance card with Available now and Incoming amounts.

The Withdraw funds panel on its first step, with a Currency Balance selector set to USD, a Withdraw amount field and a Continue button.

2. Choose or add a destination

On Select destination, choose one of your saved, usable destinations.If you have not saved one, select Add payout destination. To add another alongside existing destinations, select Add new destination. Choose the bank, mobile money or crypto wallet type offered for the route and enter the requested details. For bank and mobile money destinations, select the country; for a crypto wallet, choose the supported asset and network.You can also manage saved destinations in Settings → Payout Destinations and Currencies. See Supported currencies for the details to prepare.Check the saved destination’s review status. If it is still under review, wait until it is approved and usable before sending the payout. Save it once and reuse it for future payouts.Select your usable destination and click Continue.

The Select destination step of Withdraw funds, with the Payout Destination list open showing two saved bank accounts.

To add a destination from the payout form or from settings, use the Add payout destination panel.

The Add payout destination panel with Destination type, Name, Bank country, Bank and Account number fields.

The Payout Destinations and Currencies settings tab listing saved bank accounts with Approved and Default badges and Set as default, Edit and Delete actions.

3. Review and confirm

On Confirm withdrawal, check the destination and the displayed amounts:

To receive is the amount your bank account or wallet should receive.
Withdrawal fee or Conversion fee shows the fee for the route.
Total debited is the amount taken from the source balance, including the fee.
Exchange rate appears when currencies differ.

The dashboard prepares the estimate and conversion quote. Review the current figures before clicking Confirm withdrawal. If the form offers Retry quote, refresh the quote and review the new figures before confirming.

The Confirm withdrawal step listing Amount, Destination, Exchange rate, Conversion fee, To receive and Total debited for a USD to NGN withdrawal.

Your first payout can require a one-time account review. This can delay sending it; it does not change how you track its status.

4. Track the payout

Withdrawal started means the payout was initiated, not that the destination has received it.

The Withdrawal started confirmation showing the withdrawal amount, the estimated payout and a withdrawal reference.

Return to Balances → Withdrawals and open the record to inspect its status, timeline and details. Track it until it finishes. If the confirmation fails or its outcome is unclear, check the records before starting another payout; contact support if you cannot establish what happened.

The Withdrawal detail panel showing the source balance, destination account, a Requested, In review, In transit and Completed timeline, and the withdrawal ID.

Your key needs payouts:write to create destinations and payouts, and payouts:read to retrieve them. These examples use illustrative sandbox values. Replace the API key, account details and returned IDs with your own values. Sandbox does not move real money.The API flow is the same for every supported destination: save it, check usability, create the payout and track the result. Get a quote first if the source and destination currencies differ.

1. Save your destination

Choose a destination type and currency from Supported currencies. Use the fields required for that destination. The examples below show bank accounts; wallet destinations use the same endpoint with their own type and fields.For a local bank, get its bank_code from List Banks, using the destination country. For example, use country=NG for Nigeria.

curl -X POST https://sandbox-api.bachs.io/v1/payouts/destinations \
  -H 'Authorization: Bearer sk_sandbox_example' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "bank_account",
    "currency": "NGN",
    "bank_code": "058",
    "account_number": "0123456789"
  }'

curl -X POST https://sandbox-api.bachs.io/v1/payouts/destinations \
  -H 'Authorization: Bearer sk_sandbox_example' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "bank_account",
    "currency": "USD",
    "name": "US operating account",
    "scheme": "ach",
    "account_name": "Example Business LLC",
    "bank_name": "Bank of America",
    "routing_number": "026009593",
    "account_number": "3010001234567",
    "bank_address": {
      "line1": "100 North Tryon Street",
      "city": "Charlotte",
      "state": "NC",
      "postal_code": "28255",
      "country": "US"
    }
  }'

curl -X POST https://sandbox-api.bachs.io/v1/payouts/destinations \
  -H 'Authorization: Bearer sk_sandbox_example' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "bank_account",
    "currency": "GBP",
    "name": "UK operating account",
    "account_name": "Example Business Ltd",
    "bank_name": "Barclays",
    "sort_code": "20-00-00",
    "account_number": "55779911"
  }'

Store the returned destination ID (pd_...) and reuse it for future payouts. Check that the account details belong to you. For NGN banks, confirm that the resolved account_name matches your account; a separate bank-account resolve request is optional.For other bank routes and wallet types, see Supported currencies and Create Destination. USD and CAD banks require a scheme. The US bank_address describes the bank branch, not your personal address. A EUR swift_bic identifies the bank for SEPA; it does not select a SWIFT payout.

2. Check that the destination is usable

Read is_usable before sending a payout. If it is false, retrieve the destination and resolve its review or account requirements:

curl https://sandbox-api.bachs.io/v1/payouts/destinations/pd_example \
  -H 'Authorization: Bearer sk_sandbox_example'

Replace pd_example with the saved ID. Check status and any status_reason, and proceed when is_usable is true. Creating a destination does not always make it usable immediately.

3. Create the payout

Choose the request based on the source balance and destination currency.

Same currency

Send the destination ID and the amount your destination should receive. The fee is charged on top. Do not request a conversion quote.

curl -X POST https://sandbox-api.bachs.io/v1/payouts \
  -H 'Authorization: Bearer sk_sandbox_example' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-ngn-payout-001' \
  -d '{
    "destination": "pd_example_ngn",
    "amount": "9000.00",
    "reference": "example-ngn-001"
  }'

curl -X POST https://sandbox-api.bachs.io/v1/payouts \
  -H 'Authorization: Bearer sk_sandbox_example' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-usd-payout-001' \
  -d '{
    "destination": "pd_example_usd",
    "amount": "500.00",
    "reference": "example-usd-001"
  }'

Different currencies

International bank and mobile money routes use your available USD balance. An NGN balance cannot fund those routes.For a supported conversion, request a quote immediately before the payout. This example converts USD to GBP; the quote’s amount is the source amount before the fee:

curl -X POST https://sandbox-api.bachs.io/v1/payouts/quotes \
  -H 'Authorization: Bearer sk_sandbox_example' \
  -H 'Content-Type: application/json' \
  -d '{
    "from_currency": "USD",
    "to_currency": "GBP",
    "amount": "500.00",
    "payout_method": "BANK_TRANSFER"
  }'

Read from_amount, to_amount, exchange_rate and expires_at. to_amount is what the destination receives. Quotes last 30 seconds. Use the returned quote_id to create the payout, leaving amount out:

curl -X POST https://sandbox-api.bachs.io/v1/payouts \
  -H 'Authorization: Bearer sk_sandbox_example' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-gbp-payout-001' \
  -d '{
    "destination": "pd_example_gbp",
    "quote_id": "pqt_example_usd_gbp",
    "reference": "example-gbp-001"
  }'

Replace the example destination and quote IDs with the returned values. Use the payout method corresponding to your destination when requesting a quote; this bank example uses BANK_TRANSFER.For either request, store the returned payout ID. In the response, amount is in the destination currency; fee and total_debited are in source_currency. Reconcile against total_debited.Use one Idempotency-Key per intended payout. If a request times out or returns 5xx, follow Overview before resubmitting. An expired quote does not establish that an earlier payout request failed.

4. Track the result

A successful create response means acceptance, not delivery. Listen for payout.paid and payout.failed, or retrieve the payout:

curl https://sandbox-api.bachs.io/v1/payouts/pay_example \
  -H 'Authorization: Bearer sk_sandbox_example'

Replace pay_example with the returned payout ID. Continue tracking pending and processing. Record completed as completion; for failed, inspect failure_reason and reconcile the returned funds.

Reuse or change a destination

Reuse its saved ID for another payout, with a new idempotency key. You can save several of your own destinations and choose any usable one.To switch bank accounts, create another destination. Changing routing or holder details on an existing destination requires renewed review. See Update Payout Destination for renaming a destination or making it the default.

Common problems

Error	What to check
`BANK_ROUTING_DETAILS_INVALID`	Required bank fields, their formats and the selected scheme. Use `detail` to identify the problem.
`PAYOUT_SOURCE_CURRENCY_UNSUPPORTED`	The source balance must be able to fund the route. International bank and mobile money routes require USD funds.
`PAYOUT_RECIPIENT_INCOMPLETE`	Complete the account’s required identity information, including name, contact email and address.
`PAYOUT_CURRENCY_NOT_ENABLED`	Check the supported route and contact support with the error details if it should be available.
`AMOUNT_NOT_ALLOWED_WITH_QUOTE`	Remove `amount` when sending `quote_id`.
`QUOTE_EXPIRED`	After establishing that no earlier payout was created, get a new quote immediately before a new attempt.

See Errors for the response format.

Connected accounts and automatic payouts

For a connected account, use X-Account-Id consistently for its own balance, destination and payout. Funding it with a transfer is a separate operation; see Connected account payouts.Automatic payouts apply to eligible settled customer collections. If your integration funds a connected account through transfers, initiate its payouts separately instead of enabling a schedule.

Get Started

Payouts

Virtual accounts

Products & pricing

Subscriptions

Customer portal

Payments

Dashboard

Developer Portal

CLI

For You and Your Customers

Create a payout

1. Open the payout form

2. Choose or add a destination

3. Review and confirm

4. Track the payout

1. Save your destination

2. Check that the destination is usable

3. Create the payout

Same currency

Different currencies

4. Track the result

Reuse or change a destination

Common problems

Connected accounts and automatic payouts

​1. Open the payout form

​2. Choose or add a destination

​3. Review and confirm

​4. Track the payout

​1. Save your destination

​2. Check that the destination is usable

​3. Create the payout

​Same currency

​Different currencies

​4. Track the result

​Reuse or change a destination

​Common problems

​Connected accounts and automatic payouts

1. Open the payout form

2. Choose or add a destination

3. Review and confirm

4. Track the payout

1. Save your destination

2. Check that the destination is usable

3. Create the payout

Same currency

Different currencies

4. Track the result

Reuse or change a destination

Common problems

Connected accounts and automatic payouts