Deferred mode: allocations

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.

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.

Create an allocation

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.

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

Request body

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

There is no currency field: the currency is the one of your wallet, read server side.

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
  }'

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 }),
  }
);

201

{
  "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"
}

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.

Why an allocation is charged. Without it, “charge with no vendor, then allocate” would reach the same economic result as direct mode 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.

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.

POST /v1/connect/allocations/{allocationId}/reversals

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

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 }'

201

{
  "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:

The vendor's pending balance

Funds that have not matured yet are seized first.

The vendor's available balance

For the remainder, capped at the reversal amount.

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, where you are the last resort.

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

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

Get started

Connected accounts

Accept payments

Pay out

Resources

Deferred mode: allocations

Create an allocation

Headers

Request body

Reverse an allocation

How the funds are taken back

Errors

​Create an allocation

​Headers

​Request body

​Reverse an allocation

​How the funds are taken back

​Errors

Create an allocation

Headers

Request body

Reverse an allocation

How the funds are taken back

Errors