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

# Deferred mode: allocations

> Charge on your own account, then split to your vendors when you decide.

When you do not know the vendor at the time of the sale (multi-vendor cart, split computed after
the fact, variable commission), charge normally on your own account, then **allocate** to the
vendor.

An allocation transfers funds from your wallet to a vendor's wallet.

<Note>
  **The endpoint is not called `transfers`.** Yabetoo already exposes `/v1/transfers`, which means
  the opposite: an outbound movement to an external destination. `allocations` says what the
  operation does: assign a vendor a share of funds already collected.
</Note>

## Create an allocation

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

### Headers

| Header                       | Required    | Rule                                                                            |
| ---------------------------- | ----------- | ------------------------------------------------------------------------------- |
| `Authorization: Bearer sk_…` | Yes         |                                                                                 |
| `Idempotency-Key`            | Recommended | Without it, **no deduplication is performed**: a network retry allocates twice. |

<Warning>
  Unlike vendor creation, `Idempotency-Key` is **optional** here, but its absence is not neutral.
  An allocation moves money: always send a key.
</Warning>

### Request body

| Parameter     | Type     | Required | Description                     |
| ------------- | -------- | -------- | ------------------------------- |
| `destination` | `string` | Yes      | The vendor identifier, `acct_…` |
| `amount`      | `number` | Yes      | Strictly positive amount        |

<Note>
  There is **no `currency` field**: the currency is the one of your wallet, read server side.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://pay.sandbox.yabetoopay.com/v1/connect/allocations \
    -H "Authorization: Bearer YOUR_SECRET_KEY" \
    -H "Idempotency-Key: order-4821-payout-ada" \
    -H "Content-Type: application/json" \
    -d '{
      "destination": "acct_01HZVENDOR0000000000000000",
      "amount": 9000
    }'
  ```

  ```javascript fetch theme={null}
  const res = await fetch(
    "https://pay.sandbox.yabetoopay.com/v1/connect/allocations",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.YABETOO_API_KEY}`,
        "Idempotency-Key": `order-${orderId}-payout-${sellerId}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ destination: sellerAccountId, amount: 9000 }),
    }
  );
  ```
</CodeGroup>

```json 201 theme={null}
{
  "id": "ctr_01HZ00000000000000000000",
  "object": "connect_allocation",
  "destination": "acct_01HZVENDOR0000000000000000",
  "amount": 8910,
  "fee": 90,
  "currency": "xaf",
  "available_at": "2026-09-11T09:20:00.000Z",
  "created_at": "2026-09-04T09:20:00.000Z"
}
```

<Warning>
  **`amount` in the response is what the SELLER received, not what you requested.**

  An allocation carries the 1% Connect surcharge, computed on the allocated amount:

  | `fee_payer`  |          You are debited | The vendor receives (`amount`) |
  | ------------ | -----------------------: | -----------------------------: |
  | `account`    |                    9,000 |       **8,910** (= 9,000 − 90) |
  | `controller` | **9,090** (= 9,000 + 90) |                          9,000 |

  It is this `amount` that caps any later reversal.
</Warning>

<Note>
  **Why an allocation is charged.** Without it, "charge with no vendor, then allocate" would reach
  the same economic result as [direct mode](/en/connect/payments/charges) while paying 1% less.
  The 1% pays for the Connect relationship (vendor verification, onboarding, payout rails), not
  for the split mechanism.

  The basis is the **allocated amount**, not the original gross: your own commission is therefore
  not taxed by Connect.
</Note>

Allocated funds arrive in the vendor's **pending balance**, with an `available_at`.

## Reverse an allocation

You picked the wrong vendor, or the wrong amount. A **reversal** returns all or part of an
allocation.

```bash theme={null}
POST /v1/connect/allocations/{allocationId}/reversals
```

| Parameter | Type     | Required | Description                                                       |
| --------- | -------- | -------- | ----------------------------------------------------------------- |
| `amount`  | `number` | No       | Amount to reverse. **Omitted, the entire remainder is reversed.** |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    https://pay.sandbox.yabetoopay.com/v1/connect/allocations/ctr_01HZ00000000000000000000/reversals \
    -H "Authorization: Bearer YOUR_SECRET_KEY" \
    -H "Idempotency-Key: reversal-order-4821" \
    -H "Content-Type: application/json" \
    -d '{ "amount": 4000 }'
  ```
</CodeGroup>

```json 201 theme={null}
{
  "id": "ctrr_01HZ00000000000000000000",
  "object": "connect_reversal",
  "allocation": "ctr_01HZ00000000000000000000",
  "destination": "acct_01HZVENDOR0000000000000000",
  "amount": 4000,
  "currency": "xaf",
  "reversed_total": 4000,
  "created_at": "2026-09-04T11:00:00.000Z"
}
```

Successive reversals accumulate: `reversed_total` can never exceed the allocation's `amount`.

### How the funds are taken back

Two tiers, in this order, and never a third:

<Steps>
  <Step title="The vendor's pending balance">
    Funds that have not matured yet are seized first.
  </Step>

  <Step title="The vendor's available balance">
    For the remainder, capped at the reversal amount.
  </Step>
</Steps>

<Warning>
  **You are never the payer of last resort on a reversal.** If the vendor cannot return the funds
  (because they have already been paid out), the reversal is **refused with a `402`**. An
  allocation whose vendor has been paid is structurally irreversible.

  This is the opposite of a [refund](/en/connect/refunds), where you are the last resort.
</Warning>

<Note>
  The 1% Connect surcharge is **not returned** by a reversal: reversing 9,000 in full brings you
  back to 9,910, not 10,000.
</Note>

## Errors

| Status | Code                                      | Cause                                                                                                         |
| ------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `400`  | n/a                                       | The `Yabetoo-Account` header was sent: the vendor is named in the body                                        |
| `401`  | n/a                                       | Test key targeting a `live` vendor                                                                            |
| `403`  | n/a                                       | Unknown or malformed vendor or allocation, belonging to another marketplace, **or an allocation to yourself** |
| `402`  | `connect.insufficient_funds_for_reversal` | The vendor cannot return the funds. The body carries `required`, `seller_available`, `shortfall`, `currency`. |
| `409`  | `E_DUPLICATE_OPERATION`                   | The same `Idempotency-Key` has already produced an operation                                                  |
| `409`  | `E_IDEMPOTENCY_CONFLICT`                  | A request with the same key is in progress                                                                    |
| `422`  | validation                                | `destination` empty, `amount` zero or negative                                                                |
| `422`  | `connect.fee_payer_unset`                 | Connect is not activated on your account                                                                      |
| `422`  | `connect.vendor_net_not_positive`         | The surcharge absorbs the whole allocation                                                                    |
| `422`  | `connect.country_unsupported`             | No operator is configured for your country                                                                    |
| `422`  | `connect.reversal_exceeds_remaining`      | The reversal exceeds the remainder. The body carries `requested` and `remaining`.                             |
| `422`  | `E_CURRENCY_MISMATCH`                     | Your two wallets are not in the same currency                                                                 |
| `503`  | `E_CONNECT_PRICING_UNAVAILABLE`           | The Connect surcharge could not be resolved: the operation is refused rather than charged zero                |
| `503`  | `E_CONNECT_AVAILABILITY_DELAY_UNSET`      | The availability delay is not configured                                                                      |