> ## 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.

# Reconcile payouts

> Match every payout to your own records, check what left your balance against what arrived, and trace a transfer with the receiving bank.

Reconciling a payout means answering three questions: which payout is this in my records, how much left my balance, and did it arrive. Bachs gives you a field for each, so you never have to match payouts by amount and date.

## Tag each payout with your own reference

When you create a payout through the API, send `reference`: your own ID for it, such as an invoice or settlement number. It holds letters, digits, `.`, `-` and `_`, and must be unique on your account, so the same reference can never pay out twice.

```bash theme={"dark"}
curl -X POST https://sandbox-api.bachs.io/v1/payouts \
  -H "Authorization: Bearer $BACHS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: settlement-2026-10-26" \
  -d '{
    "destination": "pd_example_ngn",
    "amount": "9000.00",
    "reference": "settlement-2026-10-26",
    "narration": "Settle 26 Oct"
  }'
```

The reference comes back on the payout and on its [`payout.paid`](https://docs.bachs.io/guides/webhooks/events/payout-paid) and [`payout.failed`](https://docs.bachs.io/guides/webhooks/events/payout-failed) events. To find a payout by it, for example when you never stored the payout ID, list payouts with that reference. The result holds at most one payout:

```bash theme={"dark"}
curl "https://sandbox-api.bachs.io/v1/payouts?reference=settlement-2026-10-26" \
  -H "Authorization: Bearer $BACHS_API_KEY"
```

Payouts sent by an [automatic schedule](https://docs.bachs.io/guides/payouts/payout-schedules.md) get a generated reference that begins with `auto_`, so you can tell them from the ones you created. The schedule's `last_withdrawal_id` names the payout its last run created.

## Check what left your balance

Reconcile your books against `total_debited`, not `amount`:

| Field | Currency | Meaning |
| - | - | - |
| `amount` | `currency`, the destination's | What the destination receives. |
| `fee` | `source_currency`, your balance's | The payout fee. |
| `total_debited` | `source_currency` | Everything taken from your balance, fee included. |

On a same-currency payout, `total_debited` is `amount` plus `fee`. On a converted payout, `amount` is in the destination's currency, so the two never add up: a USD balance paying an NGN bank debits dollars and delivers naira. Book the dollars that left as `total_debited`, and the naira that arrived as `amount`.

The dashboard shows the same split before you confirm: **To receive**, the fee and **Total debited**.

## Know when it is final

A payout is final when its `status` is `completed` or `failed`, and `completed_at` records when it got there. Until then it is `pending` or `processing`, and you keep tracking it.

* **`completed`**: book it as paid. The `payout.paid` event tells you the moment it happens.
* **`failed`**: read `failure_reason`, and expect the funds back in your balance. Reconcile the returned money before you decide whether to pay out again.

To reconcile a whole period, use [List Payouts](https://docs.bachs.io/api-reference/payouts/list-payouts.md), which you can filter by status, or the history in **Balances → Withdrawals** on the dashboard. Listing also catches any payout whose webhook you missed.

## What the recipient's bank shows

`narration` is the short note sent with the payout, which the receiving bank may show on the statement. Keep it under 15 characters, with the part that matters first, such as an invoice number: you can send up to 100, but many banks show only the first few characters and some show their own label instead. Without one, a payout to a Nigerian bank account shows `Bachs Payout`.

## Trace a payout with the bank

When a payout to a Nigerian bank account completes, its `session_id` holds the NIP session ID: the number the receiving bank uses to find the transfer. If the recipient says the money hasn't arrived, give them that ID to take to their bank. The `payout.paid` event carries the same value, so you can store it as the payout completes.

Other payout types have no session ID, and `session_id` stays `null`. If you can't establish what happened to one, contact [support](mailto:support@bachs.io) with the payout ID and your reference.

## Next steps

* [Understand your balance](https://docs.bachs.io/guides/payouts/balances.md): when collected money becomes available to pay out.
* [How payouts work](https://docs.bachs.io/guides/payouts/how-payouts-work.md#recover-from-an-uncertain-request): what to do when a payout request times out.
* [The payout object](https://docs.bachs.io/api-reference/payouts/object.md): every field a payout returns.


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