Bloquer jusqu'à la livraison
Gardez l'argent d'une vente jusqu'à ce que l'acheteur ait la marchandise, puis libérez-le, ou laissez-le se libérer seul.
Une marketplace de biens physiques paie son vendeur une fois le colis entre les mains de l'acheteur. Avec Sync, vous le demandez à la création du paiement : l'argent de la vente revenant au vendeur reste bloqué jusqu'à ce que vous le libériez, et se libère seul au plus tard après un délai que vous avez choisi. Un lien de paiement ou une facture que vous créez pour le vendeur peut porter le même blocage, pour chaque paiement fait par son intermédiaire.
| Le mode du vendeur | Pendant le blocage |
|---|---|
lite | La vente est créditée au solde du vendeur comme toute vente, votre commission prise, mais la partie bloquée est exclue de tout versement : automatique, POST /accounts/{id}/payouts et simulateur de sandbox |
relay | Le dû du vendeur est enregistré comme d'habitude, et reste impayé |
direct | Refusé avec hold_not_available_for_direct : un marchand Direct retire depuis son propre solde, et Wajub ne le paie pas |
Une fois libérée, par vous ou à son échéance, la vente est versée au vendeur à son prochain versement.
Le blocage le plus long, par connexion
Chaque connexion lite ou relay porte hold_max_days : 30 (par défaut), 60 ou 90
jours. Réglez-le avec POST /accounts ou PUT /accounts/{id}, à tout moment, comme
payout_schedule ; une vente déjà bloquée garde sa propre échéance. L'envoyer pour un compte
direct répond 400, et toute autre valeur 422.
Le délai court à partir du succès du paiement, pas de sa création.
Bloquer une vente
Ajoutez hold à POST /payments. Sur une vente faite avec X-Sync :
curl https://api.wajub.com/payments \
-H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
-H "X-Sync: acc_Gt6yU3nE8rM1kS5vX9bQ" \
-H "Content-Type: application/json" \
-d '{
"amount": 20000,
"currency": "XAF",
"email": "buyer@example.com",
"hold": { "until": "released", "max_days": 30 }
}'Sur un paiement partagé, hold bloque toutes les
parts, et shares[].hold ne bloque qu'une part, ou lui donne son propre max_days : il l'emporte
sur le hold global.
curl https://api.wajub.com/payments \
-H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
-H "Content-Type: application/json" \
-d '{
"amount": 100000,
"currency": "XAF",
"email": "buyer@example.com",
"shares": [
{ "account": "acc_Gt6yU3nE8rM1kS5vX9bQ", "amount": 20000, "hold": { "until": "released", "max_days": 60 } },
{ "account": "acc_7Yh2MpL4tRb3nP8sZcXv", "amount": 10000 }
]
}'| Champ | |
|---|---|
hold.until | Requis avec hold. Seulement released |
hold.max_days | De 1 au hold_max_days du compte, qui est la valeur par défaut |
shares[].hold.until, shares[].hold.max_days | Les mêmes, pour une part |
error_code (422) | Quand |
|---|---|
hold_not_available_for_direct | hold sur un compte direct, par X-Sync ou sur une part direct d'un paiement partagé |
hold_max_days_exceeded | max_days au-dessus du hold_max_days du compte |
hold_requires_sync | hold sur un paiement ni fait avec X-Sync ni partagé |
hold_with_deferred | hold avec deferred: true |
Quand le blocage est refusé, rien n'est créé : ni le paiement, ni ses parts.
Une vente payée par échéances
hold fonctionne sur un paiement que l'acheteur règle par échéances.
Tant que le blocage est pending, chaque échéance est bloquée dès qu'elle est créditée : rien
n'en est versé. À la dernière échéance, la vente entière est bloquée (held), comme toute vente, et
son release_at court à partir de là.
Un paiement dont les échéances n'arrivent jamais toutes garde son blocage pending, et ce que ses
échéances ont crédité reste hors des versements, jusqu'à ce que vous fermiez le paiement
(POST /payments/{id}/close : la vente est alors bloquée) ou que vous le libériez
(POST /payments/{id}/release).
Sur un lien de paiement ou une facture
Un lien de paiement ou une facture que vous créez avec le X-Sync d'un compte lite ou relay
accepte le même hold. Chaque paiement fait par son intermédiaire est alors bloqué comme si vous
l'aviez créé avec hold : lu dans GET /payments/{id}, libéré avec POST /payments/{id}/release,
ou seul à son échéance. Sur une facture, chaque paiement compte, une partie du solde ou une
échéance, et une facture récurrente transmet le blocage à chaque facture qu'elle génère.
curl https://api.wajub.com/links \
-H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
-H "X-Sync: acc_Gt6yU3nE8rM1kS5vX9bQ" \
-H "Content-Type: application/json" \
-d '{
"type": "product",
"title": "Panier tressé",
"amount": 20000,
"currency": "XAF",
"cta_type": "buy_now",
"price": 20000,
"product_type": "physical",
"hold": { "until": "released", "max_days": 30 }
}'| Champ | |
|---|---|
hold.until | Requis avec hold. Seulement released |
hold.max_days | De 1 au hold_max_days du compte. Absent, chaque paiement est bloqué au plus le hold_max_days du compte au moment où il est ouvert. Si vous baissez hold_max_days ensuite, un paiement n'est jamais bloqué plus longtemps que la nouvelle valeur |
Le lien ou la facture renvoie son hold (until, et max_days, null pour celui du compte), ou
null quand ses paiements ne sont pas bloqués. Les refus sont ceux de POST /payments :
hold_requires_sync sans X-Sync, hold_not_available_for_direct sur un compte direct et
hold_max_days_exceeded.
Pour le changer, envoyez hold à PUT /links/{id} ou PUT /invoices/{id}, ou hold: null pour le
retirer ; absent, il reste tel quel.
| Règle | |
|---|---|
| Vous seul le changez | Avec le X-Sync du compte pour lequel le lien ou la facture a été créé ; sur un lien ou une facture relay, votre propre clé suffit aussi. La propre clé d'un vendeur Lite reçoit 403 avec error_code: hold_set_by_platform, pour retirer le blocage comme pour le raccourcir, et peut toujours changer les autres champs |
| Jusqu'à son premier paiement | Dès qu'un paiement est fait ou en cours par son intermédiaire, 409 avec error_code: hold_locked : chaque paiement garde le blocage avec lequel il a été ouvert. Un paiement annulé, expiré ou échoué ne compte pas |
| Le même blocage renvoyé | Jamais refusé |
Rien n'est bloqué par défaut : seulement les paiements que vous créez avec hold, et ceux faits par
un lien ou une facture que vous avez créés avec X-Sync et hold.
Ce que vous lisez
Une vente faite avec X-Sync porte hold, et chaque part d'un paiement partagé shares[].hold,
dans GET /payments/{id}, la réponse de création et les webhooks payment.*. Une clé publiable ne
le voit jamais.
| Champ | |
|---|---|
status | pending (le paiement n'a pas encore réussi), held, released, ou refunded et disputed quand un remboursement ou un litige perdu a tout repris pendant le blocage |
amount | Ce que la vente a laissé au vendeur, dans la devise de règlement : en lite, la vente moins les frais de Wajub et votre commission ; en relay, son dû. En unités majeures, avec des décimales pour une devise qui en a, comme held et given_back |
held | Ce qui reste bloqué |
given_back | Ce que les remboursements et les litiges perdus ont repris |
release_at | Quand il se libère seul |
release_reason | platform (vous) ou auto (l'échéance) |
Dans shares[].hold et dans les webhooks s'ajoutent account et account_type.
Le libérer
Une fois la marchandise chez l'acheteur, libérez le paiement, avec votre propre clé et sans
X-Sync :
curl -X POST https://api.wajub.com/payments/trx_Lw2Ka8Qd1Fz6Tn4Bc7Xm/release \
-H "Authorization: sk.xxxxxxxxxxxxxxxx…"Sans corps, toutes les parts bloquées sont libérées. Pour ne libérer que certaines parts d'un
paiement partagé, nommez leurs comptes : {"shares": [{"account": "acc_Gt6yU3nE8rM1kS5vX9bQ"}]}.
Une part est libérée entière, jamais un montant d'elle : shares[].amount est refusé.
| Règle | |
|---|---|
| Idempotent | Relibérer ce qui l'est déjà répond 200 avec les blocages tels quels, et n'envoie pas de second payment.released |
| Avant le succès | Une part encore pending peut être libérée : elle ne sera jamais bloquée |
| Depuis le Dashboard | La page du paiement a un bouton Libérer, pour les membres qui gèrent les versements |
| Réponse | Quand |
|---|---|
200 | Les holds du paiement, tels que la libération les a laissés |
404 | Pas un paiement à vous ni à vos comptes, ou de l'autre environnement |
409 payment_not_held | Rien de ce paiement n'est ni n'a été bloqué : jamais demandé, ou tout repris par un remboursement ou un litige |
422 release_share_not_held | Un compte de shares n'a pas de part bloquée dans ce paiement |
403 | Appel avec X-Sync |
Quand personne ne le libère
Un blocage encore pending sur une vente déjà créditée garde aussi cette vente hors des versements,
jusqu'à ce qu'il soit posé, au plus tard au passage horaire suivant. Une vente encaissée sur le rail
Wajub dont le crédit au vendeur tarde (une écriture échouée, pas encore de taux de change) garde son
blocage pending jusqu'à ce crédit, en lite comme en relay : elle n'est jamais libérée faute de
quoi bloquer. Seule une vente encaissée hors du solde Wajub, sur le contrat propre d'un marchand, est
libérée tout de suite : Wajub ne paie rien au vendeur pour elle. Chaque heure, Wajub libère les
blocages dont release_at est passé (payment.released avec
reason: auto). Trois jours avant, vous recevez payment.hold_expiring, une fois par blocage.
Remboursements et litiges pendant le blocage
Un remboursement est pris sur l'argent bloqué : en lite il est sur le solde du vendeur, en relay
le dû est réduit. Vous ne couvrez jamais la partie bloquée. Le blocage diminue de ce qui a été
repris :
| La vente | Le blocage diminue de |
|---|---|
Faite avec X-Sync | La part remboursée de la vente, tous remboursements et litiges perdus comptés |
| Une part d'un paiement partagé | Exactement ce que la part a repris au vendeur |
Le blocage diminue une fois le débit du remboursement inscrit, en sandbox comme en live ; d'ici là,
l'argent reste hors des versements, si bien que vous ne couvrez jamais la partie bloquée même quand le débit arrive en retard.
Remboursé en totalité, le blocage passe refunded, ou disputed après un litige perdu, avec
held: 0. Votre commission suit sa règle habituelle, prise à la vente et rendue selon
commission_refund_policy ; les frais de Wajub ne sont pas rendus, si bien qu'un blocage peut rester
un peu au-dessus de ce qui reste de la vente jusqu'à sa libération.
Par exemple, une vente Lite de 20 000 XAF avec 5 % de commission bloque 19 000. Un remboursement de 5 000 reprend 4 750 au vendeur (5 000 moins les 250 de commission que vous rendez) : 14 250 restent bloqués, et vous ne couvrez rien.
Un litige gagné pendant le blocage rend au vendeur ce que le litige retenait, et ne libère pas la vente : elle reste bloquée jusqu'à votre libération ou son échéance.
Une vente bloquée ne compte pas dans votre exposition : elle le devient quand elle est versée, après sa libération.
Les événements
Envoyés à votre plateforme, dans l'environnement de la vente, avec en data l'id du paiement,
object et les holds concernés.
| Événement | Quand |
|---|---|
payment.held | Un paiement que vous avez demandé à bloquer a réussi (un paiement partagé : une fois ses parts passées aux vendeurs) |
payment.released | Vous l'avez libéré, ou son échéance l'a fait ; reason vaut platform ou auto |
payment.hold_expiring | Trois jours avant qu'il se libère seul. Une fois par blocage |
Ils sont listés dans GET /events, et filtrables avec X-Sync.
En sandbox
Pour ne pas attendre 30 jours, POST /accounts/{id}/simulate avec {"action": "expire_holds"} amène
les ventes bloquées de la connexion à leur échéance tout de suite : elles sont libérées comme par le
passage horaire, avec payment.released et reason: auto.
Ce que voit le vendeur
Dans son portail et dans les composants payments, payouts et balance, un vendeur Lite lit un
montant « en attente de livraison », versé dès que vous confirmez la livraison et au plus tard à la
date indiquée, et sur chaque vente bloquée si elle attend encore ou a été libérée par vous.
L'estimation de son prochain versement laisse les ventes bloquées de côté.