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

# Balances and payouts

> How a vendor's funds mature, and how to pay them out.

A vendor's money goes through three states before reaching their payout destination.

```
charge → pending balance → (maturation) → available balance → payout → vendor destination
```

## The three balances

Every wallet carries three amounts, and their sum is what the account actually holds.

<ResponseField name="pending_balance" type="number">
  **Credited, not yet matured.** Every vendor credit lands here. Not payable, but **seizable by
  a refund**.
</ResponseField>

<ResponseField name="balance" type="number">
  **Available.** This is the only amount that can be paid out.
</ResponseField>

<ResponseField name="held_balance" type="number">
  **Committed to a payout in flight.** The money still belongs to the account, but it is reserved
  while the operator responds.
</ResponseField>

<Warning>
  Do not confuse `pending_balance` and `held_balance`: "not yet matured" and "payout in progress"
  are two different states. Mixing them up produces no error. It simply falsifies your
  reconciliation.
</Warning>

## The availability delay

A vendor credit carries an `available_at` date. At maturity, a sweep moves it from
`pending_balance` to `balance`, and emits
[`connect.funds.available`](/en/connect/webhooks).

The default delay is **7 days**.

<Warning>
  **The delay is not only an anti-fraud guard: it is the funding source for refunds.** Pending
  funds are seizable; funds already paid out are not. Shortening the delay moves the refund risk
  onto your own balance.
</Warning>

You read the maturity date on the vendor's account:

```bash theme={null}
GET /v1/connect/accounts/{acct}
```

```json theme={null}
{
  "balances": [
    {
      "currency": "xaf",
      "balance": 4000,
      "pending_balance": 8975,
      "held_balance": 0,
      "next_maturity_at": "2026-09-11T00:00:00.000Z"
    }
  ]
}
```

## Pay out to a vendor

```bash theme={null}
POST https://pay.sandbox.yabetoopay.com/v1/connect/accounts/{acct}/withdrawals   # Sandbox
POST https://pay.api.yabetoopay.com/v1/connect/accounts/{acct}/withdrawals       # Production
```

**You** are the one who orders the payout: a connected vendor has no dashboard.

### Headers

| Header                       | Required | Rule                                     |
| ---------------------------- | -------- | ---------------------------------------- |
| `Authorization: Bearer sk_…` | Yes      |                                          |
| `Idempotency-Key`            | **Yes**  | Non-empty string, 255 characters maximum |

### Body

**Empty.** A Connect payout transfers **the entire available balance**.

<Warning>
  `amount` is **refused with a 422**: there is no partial payout. The amount is the vendor's
  `balance` at the moment of the lock.
</Warning>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    https://pay.sandbox.yabetoopay.com/v1/connect/accounts/acct_01HZVENDOR0000000000000000/withdrawals \
    -H "Authorization: Bearer YOUR_SECRET_KEY" \
    -H "Idempotency-Key: payout-ada-2026-09-04"
  ```
</CodeGroup>

```json 201 theme={null}
{
  "id": "wd_01HZ00000000000000000000",
  "object": "connect_withdrawal",
  "connected_account_id": "acct_01HZVENDOR0000000000000000",
  "amount": 4000,
  "currency": "xaf",
  "destination": "24****4567",
  "status": "succeeded",
  "created_at": "2026-09-04T12:00:00.000Z"
}
```

<Warning>
  **The call is synchronous and waits for the operator.** Expect several seconds. The `status`
  returned is the **final** state: `succeeded` or `failed`, never `processing`.

  An operator refusal returns **`201` with `status: "failed"`**, not an HTTP error. Always read
  the `status`.
</Warning>

<Note>
  A connected vendor's payout is **free**: no commission is taken on it. The `destination` is
  masked: you do not need to read your vendor's number.
</Note>

### Preconditions

A payout is refused as long as any of these conditions is not met:

<AccordionGroup>
  <Accordion title="The vendor's KYC is approved">
    Otherwise `403 E_VERIFICATION_REQUIRED`. It is the **vendor's** policy that is evaluated,
    not yours.
  </Accordion>

  <Accordion title="The vendor has a registered payout destination">
    Otherwise `422 E_CONNECT_VENDOR_PAYOUT_METHOD_UNAVAILABLE`. It is collected during
    [onboarding](/en/connect/accounts/onboarding).
  </Accordion>

  <Accordion title="Their available balance is not empty">
    Otherwise `422 E_CONNECT_VENDOR_EMPTY_BALANCE`. This is a **nominal state** (before the
    first allocation, or right after a payout), not an error to retry.
  </Accordion>

  <Accordion title="No payout is already in flight on this wallet">
    Otherwise `422 E_PENDING_WITHDRAW`.
  </Accordion>
</AccordionGroup>

### Replay

<Warning>
  **The replay contract differs from the other money routes.** Within 24 h, replaying the same
  `Idempotency-Key` returns the **same `201`**. Beyond that, you get
  **`409 E_DUPLICATE_OPERATION`**: the service does not rebuild the original response.

  The same key on **two different vendors** does pay both: the key is scoped by endpoint and by
  vendor.
</Warning>

## Automatic cadence

Rather than calling the route by hand, you can have your vendors paid automatically as soon as
their balance is positive.

```bash theme={null}
GET  /v1/connect/payout_schedule
POST /v1/connect/payout_schedule
```

| Parameter | Type      | Required | Description         |
| --------- | --------- | -------- | ------------------- |
| `cadence` | `string`  | Yes      | `daily` or `weekly` |
| `enabled` | `boolean` | No       | `true` by default   |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://pay.sandbox.yabetoopay.com/v1/connect/payout_schedule \
    -H "Authorization: Bearer YOUR_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "cadence": "weekly", "enabled": true }'
  ```
</CodeGroup>

```json 200 theme={null}
{
  "object": "connect_payout_schedule",
  "account": "acct_01HZMARKETPLACE00000000000",
  "cadence": "weekly",
  "enabled": true
}
```

<Note>
  The read always returns **200**, with `cadence: null` and `enabled: false` when nothing is
  configured. The write returns **200**, not 201: the resource is your account, it already exists.
  Posting again simply replaces the configuration.
</Note>

<Tip>
  The cadence is the only way to **guarantee** your vendors a payment rhythm. In manual mode, they
  depend entirely on you to get paid.
</Tip>

## Payout errors

| Status | Code                                         | Cause                                                             |
| ------ | -------------------------------------------- | ----------------------------------------------------------------- |
| `401`  | n/a                                          | Test key targeting a `live` vendor                                |
| `403`  | `E_VERIFICATION_REQUIRED`                    | The vendor's KYC is not approved                                  |
| `403`  | n/a                                          | Unknown or malformed vendor, or a vendor from another marketplace |
| `409`  | `E_DUPLICATE_OPERATION`                      | Idempotency key already consumed (outside the cache window)       |
| `409`  | `E_IDEMPOTENCY_CONFLICT`                     | A request with the same key is in progress                        |
| `422`  | `rule: "unsupported"`                        | `amount` sent                                                     |
| `422`  | `E_CONNECT_VENDOR_EMPTY_BALANCE`             | Available balance empty, nominal state                            |
| `422`  | `E_CONNECT_VENDOR_PAYOUT_METHOD_UNAVAILABLE` | No payout destination                                             |
| `422`  | `E_PENDING_WITHDRAW`                         | A payout is already in flight                                     |
| `503`  | `E_SERVICE_UNAVAILABLE`                      | Upstream service unavailable                                      |