Mode différé : allocations

Quand vous ne connaissez pas le vendeur au moment de la vente (panier multi-vendeurs, répartition calculée après coup, commission variable), encaissez normalement sur votre propre compte, puis allouez au vendeur. Une allocation transfère des fonds de votre portefeuille vers celui d’un vendeur.

L’endpoint ne s’appelle pas transfers. Yabetoo expose déjà /v1/transfers, qui signifie l’inverse : une sortie vers une destination externe. allocations dit ce que l’opération fait : attribuer à un vendeur une part de fonds déjà encaissés.

Créer une allocation

POST https://pay.sandbox.yabetoopay.com/v1/connect/allocations   # Sandbox
POST https://pay.api.yabetoopay.com/v1/connect/allocations       # Production

En-têtes

En-tête	Obligatoire	Règle
`Authorization: Bearer sk_…`	Oui
`Idempotency-Key`	Recommandé	Sans elle, aucune déduplication n’est faite : un retry réseau alloue deux fois.

Contrairement à la création de vendeur, Idempotency-Key est optionnelle ici, mais son absence n’est pas neutre. Une allocation déplace de l’argent : envoyez toujours une clé.

Corps de la requête

Paramètre	Type	Obligatoire	Description
`destination`	`string`	Oui	L’identifiant du vendeur, `acct_…`
`amount`	`number`	Oui	Montant strictement positif

Il n’y a pas de champ currency : la devise est celle de votre portefeuille, lue côté serveur.

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 dans la réponse est ce que le VENDEUR a reçu, pas ce que vous avez demandé.Une allocation porte la surcharge Connect de 1 %, calculée sur le montant alloué :

`fee_payer`	Vous êtes débité de	Le vendeur reçoit (`amount`)
`account`	9 000	8 910 (= 9 000 − 90)
`controller`	9 090 (= 9 000 + 90)	9 000

C’est cet amount qui plafonne une éventuelle reprise.

Pourquoi l’allocation est facturée. Sans cela, « encaisser sans vendeur puis allouer » atteindrait le même résultat économique que le mode direct en payant 1 % de moins. Le 1 % paie la relation Connect (vérification des vendeurs, onboarding, rails de versement), pas le mécanisme de partage.L’assiette est le montant alloué, pas le brut d’origine : votre propre commission n’est donc pas taxée par Connect.

Les fonds alloués arrivent en solde en attente du vendeur, avec une available_at.

Reprendre une allocation

Vous vous êtes trompé de vendeur, ou de montant. Une reprise rend tout ou partie d’une allocation.

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

Paramètre	Type	Obligatoire	Description
`amount`	`number`	Non	Montant à reprendre. Omis, la totalité du reliquat est reprise.

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

Les reprises successives se cumulent : reversed_total ne peut jamais dépasser l’amount de l’allocation.

Comment les fonds sont repris

Deux étages, dans cet ordre, et jamais un troisième :

Le solde en attente du vendeur

Les fonds pas encore mûrs sont saisis en premier.

Le solde disponible du vendeur

Pour le reliquat, borné au montant de la reprise.

Vous n’êtes jamais le payeur de dernier ressort sur une reprise. Si le vendeur ne peut pas rendre les fonds (parce qu’il les a déjà retirés), la reprise est refusée en 402. Une allocation dont le vendeur a été payé est structurellement irréprenable.C’est l’inverse d’un remboursement, où vous êtes le dernier recours.

La surcharge Connect de 1 % n’est pas rendue par une reprise : reprendre intégralement 9 000 vous ramène à 9 910, pas 10 000.

Erreurs

Statut	Code	Cause
`400`	n/a	L’en-tête `Yabetoo-Account` a été envoyé : le vendeur se nomme dans le corps
`401`	n/a	Clé de test visant un vendeur `live`
`403`	n/a	Vendeur ou allocation inconnu, malformé, appartenant à une autre marketplace, ou allocation vers vous-même
`402`	`connect.insufficient_funds_for_reversal`	Le vendeur ne peut pas rendre les fonds. Le corps porte `required`, `seller_available`, `shortfall`, `currency`.
`409`	`E_DUPLICATE_OPERATION`	La même `Idempotency-Key` a déjà produit une opération
`409`	`E_IDEMPOTENCY_CONFLICT`	Une requête avec la même clé est en cours
`422`	validation	`destination` vide, `amount` nul ou négatif
`422`	`connect.fee_payer_unset`	Connect n’est pas activé sur votre compte
`422`	`connect.vendor_net_not_positive`	La surcharge absorbe toute l’allocation
`422`	`connect.country_unsupported`	Aucun opérateur n’est configuré pour votre pays
`422`	`connect.reversal_exceeds_remaining`	La reprise dépasse le reliquat. Le corps porte `requested` et `remaining`.
`422`	`E_CURRENCY_MISMATCH`	Vos deux portefeuilles ne sont pas dans la même devise
`503`	`E_CONNECT_PRICING_UNAVAILABLE`	La surcharge Connect n’a pas pu être résolue : l’opération est refusée plutôt que facturée zéro
`503`	`E_CONNECT_AVAILABILITY_DELAY_UNSET`	Le délai de disponibilité n’est pas configuré

Pour commencer

Comptes connectés

Encaisser

Reverser

Ressources

Mode différé : allocations

Créer une allocation

En-têtes

Corps de la requête

Reprendre une allocation

Comment les fonds sont repris

Erreurs

​Créer une allocation

​En-têtes

​Corps de la requête

​Reprendre une allocation

​Comment les fonds sont repris

​Erreurs

Créer une allocation

En-têtes

Corps de la requête

Reprendre une allocation

Comment les fonds sont repris

Erreurs