# 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` :

```bash title="Une vente bloquée jusqu'à votre libération"
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é](https://docs.wajub.com/fr/sync/split-payments#one-payment-several-sellers), `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.

```bash title="Seule la première part est bloquée, 60 jours au plus"
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](https://docs.wajub.com/fr/sync/split-payments#installment-splitting).
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.

```bash title="Chaque paiement de ce lien est bloqué jusqu'à votre libération"
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.

```json title="L'objet hold"
{
"status": "held",
"max_days": 30,
"currency": "XAF",
"amount": 19000,
"held": 14250,
"given_back": 4750,
"held_at": "2026-11-20T09:12:04+00:00",
"release_at": "2026-12-20T09:12:04+00:00",
"released_at": null,
"release_reason": null
}
```

| 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` :

```bash title="Libérer un paiement bloqué"
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. &#x2A;*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](https://docs.wajub.com/fr/sync/payouts#your-exposure-cap) : 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`.

```json title="Réponse · 200 OK"
{
"code": 200,
"status": "OK",
"message": "Holds released",
"action": "expire_holds",
"account": "acc_test_Gt6yU3nE8rM1kS5vX9bQ",
"released": { "holds": 2, "payments": 2 }
}
```

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

- [Payer les vendeurs](https://docs.wajub.com/fr/sync/payouts): Les versements, la réserve et ce qui retient un versement.
- [Un paiement, plusieurs vendeurs](https://docs.wajub.com/fr/sync/split-payments#one-payment-several-sellers): Les paiements partagés, part par part.
- [Libérer un paiement](https://docs.wajub.com/fr/api/subaccounts/release-payment): La spécification de l'endpoint.
