> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bachs.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Money is always a decimal string at the currency's precision (for example "29.00"), paired with an ISO 4217 currency field. Never use minor units.
> Build against the sandbox first: base URL https://sandbox-api.bachs.io with sk_sandbox_ keys. Production is https://api.bachs.io with sk_live_ keys; going live is a key swap.
> Treat webhooks (for example collection.succeeded) as the source of truth for fulfilment, never client-side events or redirects.
> Subscriptions are created by completing a checkout for a recurring product. There is no direct create-subscription endpoint.
> IDs carry resource prefixes (cust_, prod_, sub_, chk_, inv_, ref_) and timestamps are ISO 8601 UTC.

# How payouts work

> What a payout needs, how one moves from your balance to your destination, and how to tell when it has arrived.

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](https://docs.bachs.io/guides/payouts/global-payouts.md) 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](https://docs.bachs.io/api-reference/accounts/get-balances.md).
* **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](https://docs.bachs.io/for-you/supported-currencies.md#balance-currencies).

> [!NOTE]
>
> 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

| Method | Use it when | Start here |
| - | - | - |
| Dashboard | You want to pay out and track it without writing code | **Balances → Withdraw**, in the Dashboard tab of [Create a payout](https://docs.bachs.io/guides/payouts/payout-using-api.md) |
| API | Your application creates and tracks payouts | The API tab of [Create a payout](https://docs.bachs.io/guides/payouts/payout-using-api.md) |
| Automatic payouts | You want settled collections paid out on a schedule | [Set up automatic payouts](https://docs.bachs.io/guides/payouts/payout-schedules.md), from the dashboard or the API |

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](https://docs.bachs.io/api-reference/payouts/create-payout-destination.md). 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](https://docs.bachs.io/api-reference/payouts/create-payout-quote.md) 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](https://docs.bachs.io/api-reference/payouts/create-payout.md) 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`](https://docs.bachs.io/guides/webhooks/events/payout-paid) and [`payout.failed`](https://docs.bachs.io/guides/webhooks/events/payout-failed), or retrieve the payout with [Get Payout](https://docs.bachs.io/api-reference/payouts/get-payout.md). 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:

| Request | What `amount` means |
| - | - |
| Same-currency Create Payout | What your destination receives. The fee is charged on top. |
| Create Payout Quote | The source amount to convert, before the fee. The quote returns what the destination receives as `to_amount`. |

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](https://docs.bachs.io/for-you/fees.md#withdrawal-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:

| Status | What your integration should do |
| - | - |
| `pending` | Keep tracking. |
| `processing` | Keep tracking. |
| `completed` | Record the payout as completed. |
| `failed` | Read `failure_reason` and reconcile the returned funds before you decide what to do next. |

To reconcile a period, use the dashboard's payout history or [List Payouts](https://docs.bachs.io/api-reference/payouts/list-payouts.md). 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](mailto:support@bachs.io).

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](mailto:support@bachs.io) 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](https://docs.bachs.io/connect/payouts.md) and [Onboarding requirements](https://docs.bachs.io/connect/requirements.md).

## Next steps

* [Create a payout](https://docs.bachs.io/guides/payouts/payout-using-api.md): save a destination, send a payout and track it, from the dashboard or the API.
* [Set up automatic payouts](https://docs.bachs.io/guides/payouts/payout-schedules.md): pay out settled collections on a schedule.
* [Payout currencies and methods](https://docs.bachs.io/guides/payouts/global-payouts.md): where you can pay out and the details each route needs.
* [Introducing Global Payouts on Bachs](https://bachs.io/blog/introducing-global-payouts) on the Bachs blog: what launched and who it is for.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.