Soldes et versements

L’argent d’un vendeur passe par trois états avant d’atteindre sa destination de versement.

encaissement → solde en attente → (maturation) → solde disponible → retrait → destination du vendeur

Les trois soldes

Chaque portefeuille porte trois montants, et leur somme est ce que le compte détient réellement.

number

Crédité, pas encore mûr. Tout crédit vendeur atterrit ici. Non retirable, mais saisissable par un remboursement.

number

Disponible. C’est le seul montant retirable.

number

Engagé dans un retrait en vol. L’argent appartient toujours au compte, mais il est réservé le temps que l’opérateur réponde.

Ne confondez pas pending_balance et held_balance : « pas encore mûr » et « en cours de retrait » sont deux états différents. Les mêler ne produit aucune erreur. Il fausse simplement votre réconciliation.

Le délai de disponibilité

Un crédit vendeur porte une date available_at. À échéance, un balayage le déplace de pending_balance vers balance, et émet connect.funds.available. Le délai par défaut est de 7 jours.

Le délai n’est pas qu’un garde-fou anti-fraude : c’est la source de financement des remboursements. Les fonds en attente sont saisissables ; les fonds retirés ne le sont plus. Raccourcir le délai déplace le risque de remboursement sur votre propre solde.

Vous lisez l’échéance sur le compte du vendeur :

GET /v1/connect/accounts/{acct}

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

Verser à un vendeur

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

C’est vous qui commandez le retrait : un vendeur connecté n’a pas de tableau de bord.

En-têtes

En-tête	Obligatoire	Règle
`Authorization: Bearer sk_…`	Oui
`Idempotency-Key`	Oui	Chaîne non vide, 255 caractères maximum

Corps

Vide. Un retrait Connect transfère la totalité du solde disponible.

amount est refusé en 422 : il n’existe pas de retrait partiel. Le montant est le balance du vendeur au moment du verrou.

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"

201

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

L’appel est synchrone et attend l’opérateur. Comptez plusieurs secondes. Le status rendu est l’état final : succeeded ou failed, jamais processing.Un refus de l’opérateur rend 201 avec status: "failed", pas une erreur HTTP. Lisez toujours le status.

Le retrait d’un vendeur connecté est gratuit : aucune commission n’est prélevée dessus. La destination est masquée : vous n’avez pas à lire le numéro de votre vendeur.

Préconditions

Un retrait est refusé tant que l’une de ces conditions n’est pas remplie :

Le KYC du vendeur est approuvé

Sinon 403 E_VERIFICATION_REQUIRED. C’est la politique du vendeur qui est évaluée, pas la vôtre.

Le vendeur a une destination de versement enregistrée

Sinon 422 E_CONNECT_VENDOR_PAYOUT_METHOD_UNAVAILABLE. Elle est collectée pendant l’onboarding.

Son solde disponible n'est pas vide

Sinon 422 E_CONNECT_VENDOR_EMPTY_BALANCE. C’est un état nominal (avant la première allocation, ou juste après un retrait), pas une erreur à réessayer.

Aucun retrait n'est déjà en vol sur ce portefeuille

Sinon 422 E_PENDING_WITHDRAW.

Rejeu

Le contrat de rejeu diffère des autres routes d’argent. Dans les 24 h, rejouer la même Idempotency-Key rend le même 201. Au-delà, vous obtenez 409 E_DUPLICATE_OPERATION : le service ne reconstruit pas la réponse d’origine.La même clé sur deux vendeurs différents paie bien les deux : la clé est scopée par endpoint et par vendeur.

Cadence automatique

Plutôt que d’appeler la route à la main, vous pouvez faire payer vos vendeurs automatiquement dès que leur solde est positif.

GET  /v1/connect/payout_schedule
POST /v1/connect/payout_schedule

Paramètre	Type	Obligatoire	Description
`cadence`	`string`	Oui	`daily` ou `weekly`
`enabled`	`boolean`	Non	`true` par défaut

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

200

{
  "object": "connect_payout_schedule",
  "account": "acct_01HZMARKETPLACE00000000000",
  "cadence": "weekly",
  "enabled": true
}

La lecture rend toujours 200, avec cadence: null et enabled: false quand rien n’est configuré. L’écriture rend 200, pas 201 : la ressource est votre compte, elle existe déjà. Reposter remplace simplement la configuration.

La cadence est le seul moyen de garantir à vos vendeurs un rythme de paiement. En mode manuel, ils dépendent entièrement de vous pour être payés.

Erreurs du retrait

Statut	Code	Cause
`401`	n/a	Clé de test visant un vendeur `live`
`403`	`E_VERIFICATION_REQUIRED`	Le KYC du vendeur n’est pas approuvé
`403`	n/a	Vendeur inconnu, malformé, ou d’une autre marketplace
`409`	`E_DUPLICATE_OPERATION`	Clé d’idempotence déjà consommée (hors fenêtre de cache)
`409`	`E_IDEMPOTENCY_CONFLICT`	Une requête avec la même clé est en cours
`422`	`rule: "unsupported"`	`amount` envoyé
`422`	`E_CONNECT_VENDOR_EMPTY_BALANCE`	Solde disponible vide, état nominal
`422`	`E_CONNECT_VENDOR_PAYOUT_METHOD_UNAVAILABLE`	Pas de destination de versement
`422`	`E_PENDING_WITHDRAW`	Un retrait est déjà en vol
`503`	`E_SERVICE_UNAVAILABLE`	Service amont indisponible

Pour commencer

Comptes connectés

Encaisser

Reverser

Ressources

Les trois soldes

Le délai de disponibilité

Verser à un vendeur

En-têtes

Corps

Préconditions

Rejeu

Cadence automatique

Erreurs du retrait

​Les trois soldes

​Le délai de disponibilité

​Verser à un vendeur

​En-têtes

​Corps

​Préconditions

​Rejeu

​Cadence automatique

​Erreurs du retrait

Les trois soldes

Le délai de disponibilité

Verser à un vendeur

En-têtes

Corps

Préconditions

Rejeu

Cadence automatique

Erreurs du retrait