# Risque vendeur

> Un score de risque par vendeur, un délai de versement pour les nouveaux vendeurs, et le gel d'un vendeur, avant que l'argent parte.

En `lite`, vous couvrez ce qu'un vendeur ne peut plus rembourser ; en `relay`, vous payez vos
vendeurs. Un vendeur qui encaisse puis disparaît vous coûte. Trois protections agissent **avant que
l'argent parte**, sur les comptes `lite` et `relay` seulement :

| Protection                                                 | Ce qu'elle fait                                                                    |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [Score de risque](#the-risk-score)                         | De 0 à 100 par vendeur, avec des raisons lisibles                                  |
| [Délai des nouveaux vendeurs](#new-sellers-are-paid-later) | Un nouveau vendeur n'est payé que de ses ventes plus anciennes. En live seulement  |
| [Gel](#freezing-a-seller)                                  | Un vendeur n'est plus payé, par votre décision, celle de Wajub, ou automatiquement |

Un marchand `direct` gère son propre compte : ni score, ni délai, ni gel, et son compte n'a ni
`risk`, ni `frozen`, ni `new_seller`.

## Le score de risque

Wajub évalue chaque vendeur après chacune de ses ventes, chaque remboursement et chaque litige, et
chaque nuit. Chaque signal ajoute des points ; le score est leur somme, plafonnée à 100.

| `code`                   | Signal                                                                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `refund_rate`            | Une part élevée des ventes du vendeur remboursée                                                                                           |
| `dispute_rate`           | Des litiges ouverts sur les ventes récentes du vendeur                                                                                     |
| `new_connection`         | Un vendeur connecté récemment                                                                                                              |
| `identity_unverified`    | Lite : la vérification du vendeur n'est pas terminée. Relay : le portefeuille n'est pas vérifié auprès de son opérateur. Jamais en sandbox |
| `payout_account_changed` | Le compte de versement a changé récemment (un premier compte n'est pas un changement)                                                      |
| `volume_spike`           | Des ventes bien au-dessus du volume habituel du vendeur, ou un vendeur qui revend après une longue période sans vente                      |
| `self_sales`             | Des ventes payées depuis le numéro sur lequel le vendeur est versé                                                                         |
| `shield_flags`           | Des ventes récentes que Shield a jugées risquées                                                                                           |

| `level`    | Score      |
| ---------- | ---------- |
| `normal`   | Sous 40    |
| `elevated` | 40 ou plus |
| `high`     | 70 ou plus |

Les ventes comptées sont celles faites avec `X-Sync` sur le compte, et les parts de paiements partagés
qu'il a reçues.

```json title="Le risque du compte"
"risk": {
"score": 80,
"level": "high",
"reasons": [
  { "code": "self_sales", "points": 30, "description": "3 sales over 90 days were paid from the phone number the seller is paid out to." },
  { "code": "payout_account_changed", "points": 20, "description": "The account the seller is paid on changed 0 day(s) ago." }
],
"updated_at": "2026-11-20T10:00:00+00:00"
}
```

`risk` vaut `null` tant que le vendeur n'a jamais été évalué, avant sa première vente ou la nuit
suivante. Les raisons sont triées par points, de la plus lourde à la plus légère ; `code` est stable,
`description` est en anglais.

`GET /accounts?risk_level=high` liste vos vendeurs d'un niveau (`normal` comprend un vendeur pas
encore évalué), et `frozen=true` ou `false` (`1` ou `0` aussi) les seuls vendeurs gelés, ou non
gelés.

| Événement               | Quand                                                                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `account.risk_elevated` | Le niveau passe de `normal` à `elevated`                                                                                                    |
| `account.risk_high`     | Le niveau atteint `high`. `suggestion: "freeze"` quand le gel n'est que suggéré ; `frozen: true` quand il a gelé le vendeur automatiquement |

Chacun est envoyé **une fois par franchissement** : un vendeur qui reste `high` n'envoie plus rien,
et un saut de `normal` à `high` n'envoie que `account.risk_high`. Il n'est renvoyé qu'une fois le score redescendu d'au moins 10 points sous le seuil (à 60 ou moins
pour 70, à 30 ou moins pour 40), puis de nouveau franchi. `data` porte
`account`, `risk`, `frozen` et `suggestion`.

## Les nouveaux vendeurs sont payés plus tard

Un vendeur `lite` ou `relay` est **nouveau** tant que sa connexion a moins de 14 jours, ou tant que
son identité n'est pas vérifiée (Lite : sa vérification ; Relay : son portefeuille auprès de son
opérateur). Tant qu'il est nouveau, il n'est payé **que des ventes plus anciennes que son délai** :
7 jours par défaut.

| Mode    | Ce qui attend                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------- |
| `lite`  | Ce que les ventes récentes lui ont laissé reste sur son solde, et part au premier versement où la vente a l'âge |
| `relay` | Les dus enregistrés depuis moins que le délai restent `payable` et impayés                                      |

Le délai s'applique en live seulement. Sur chaque vente, ce qui est gardé est le **plus grand** de la
réserve, du [blocage jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds) et du délai, jamais leur somme : une vente
récente de 6 000 avec une réserve de 600 sur elle garde 6 000, pas 6 600.

| La vente                                                       | Ce que le délai garde                                                                                                                                                                                                                        |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Créditée depuis moins que le délai                             | Ce qu'elle a laissé au vendeur, moins ce que les remboursements et les litiges perdus ont repris **une fois leur débit inscrit sur le solde du vendeur** : un remboursement encore `pending`, ou envoyé et pas encore débité, ne libère rien |
| Payée par échéances                                            | Ce que les échéances créditées ont laissé au vendeur, de la première à la dernière, quelles que soient leurs dates                                                                                                                           |
| Disponible en partie seulement (échéances encore en rétention) | Ce qui en est disponible : le reste attend de toute façon dans la rétention                                                                                                                                                                  |

| Réglage                 |                                                                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `new_seller_delay_days` | Sur `POST /accounts` et `PUT /accounts/{id}` : 0 à 30 jours, `null` pour la valeur par défaut (7). Refusé sur un compte `direct` |
| Plancher de Wajub       | Wajub peut fixer un plancher pour votre plateforme : le délai n'est jamais en dessous                                            |

```json title="Le new_seller du compte"
"new_seller": {
"is_new": true,
"delay_days": 7,
"delay_days_setting": null,
"until": "2026-12-03T10:00:00+00:00"
}
```

`until` dit quand le vendeur cesse d'être nouveau par l'âge seul ; `null` s'il attend sa
vérification, ou s'il n'est pas nouveau. `delay_days_setting` est votre choix pour la connexion.

Quand un versement n'a payé que les ventes anciennes, ou rien, à cause du délai, le
`payout_hold.reason` du compte vaut `new_seller` et vous recevez `account.payout_limited` avec
`reason: new_seller`, une fois par épisode. `POST /accounts/{id}/payouts` répond `409` avec
`error_code: new_seller_delay` quand aucune vente n'est assez ancienne. Le vendeur lit dans son
portail et ses composants qu'en tant que nouveau vendeur, chaque vente lui est versée une fois âgée
de N jours.

## Geler un vendeur

Un vendeur gelé **n'est plus payé** : ni versement automatique, ni `POST /accounts/{id}/payouts`, et
en `lite` aucun transfert depuis son solde. Son argent reste où il est, et ses remboursements et
litiges le trouvent.

Il **continue d'encaisser**, pour que votre boutique ne casse pas, et ce qu'il encaisse reste chez
Wajub, sauf si vous le gelez avec `block_payments: true` : il **n'encaisse alors plus par aucun
canal**, avec `403` `account_frozen`.

| Refusé avec `block_payments`                     |                                                                                                                                                                                                                                                          |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Les nouvelles ventes                             | `POST /payments`, `POST /links`, `POST /invoices` et `POST /payments/{id}/activate` avec `X-Sync` ; une part d'un paiement partagé                                                                                                                       |
| Les ventes préparées avant le gel                | Le débit d'un paiement fait pour lui, ou partagé avec lui : `POST /payments/{id}`, `POST /payments/{id}/splits`, la page de paiement, en live comme en sandbox                                                                                           |
| Les paiements déjà débités, en attente du payeur | Chaque étape après le débit, même si celui-ci a commencé longtemps avant le gel : un code, un PIN ou un code 3-D Secure (`POST /payments/{id}/confirm`, la page de paiement), un code renvoyé. Rien n'atteint le prestataire et aucun essai n'est compté |
| Les liens et factures émis avant                 | Plus payables : la page du lien répond « This payment link is not available. », la facture « This invoice is not available for payment. »                                                                                                                |

Le gel est lu à chaque encaissement et à chaque étape, sans délai, que vous l'ayez posé par l'API ou
dans le Dashboard. Les remboursements continuent.

Un payeur qui a déjà payé dans la fenêtre de son prestataire n'est pas refusé quand le paiement est
confirmé avec `client_session_id`. Un tel paiement, ou un paiement qu'un prestataire mène à bien
malgré tout, est encaissé : il reste sur le solde du vendeur, ou en dû Relay, et n'est pas versé tant
que le gel dure.

Sur un [paiement partagé](https://docs.wajub.com/fr/sync/split-payments#one-payment-several-sellers), un seul vendeur gelé
avec `block_payments` bloque tout le paiement, parts des autres vendeurs comprises, même créé avant le
gel : un paiement partagé est un seul débit, jamais encaissé en partie. Pour vendre quand même, créez
un nouveau paiement sans la part de ce vendeur, ou levez le blocage.

```bash title="Geler un vendeur"
curl https://api.wajub.com/accounts/acc_Gt6yU3nE8rM1kS5vX9bQ/freeze \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Commandes jamais livrées","block_payments":false}'
```

| Appel                          | Corps                                                                                                                                     |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /accounts/{id}/freeze`   | `reason` (requis, 500 caractères au plus, gardé dans l'historique et affiché dans votre Dashboard), `block_payments` (`false` par défaut) |
| `POST /accounts/{id}/unfreeze` | `reason` (facultatif). Le vendeur est de nouveau payé dès le passage suivant                                                              |

Les deux répondent `200` avec le compte. Geler un vendeur que vous avez déjà gelé de la même façon,
ou dégeler un vendeur qui ne l'est pas, ne change rien.

```json title="Le frozen du compte"
"frozen": {
"since": "2026-11-20T10:00:00+00:00",
"by": "platform",
"reason": "Commandes jamais livrées",
"block_payments": false
},
"auto_freeze": null
```

`by` vaut `platform`, `wajub` ou `auto`. `payout_hold.reason` vaut `frozen` dès le gel, sandbox
comprise.

> [!WARNING]
> **Un gel posé par Wajub appartient à Wajub**
>
> Quand Wajub a gelé un vendeur, vous ne pouvez ni lever ce gel ni le modifier, ni son
> `block_payments`, ni son motif, ni son `by` : `freeze` sur ce vendeur répond `409` avec
> `error_code: frozen_by_wajub`, et `unfreeze` aussi, sauf si vous l'aviez gelé avant (ci-dessous).
> Le gel automatique n'y touche pas non plus. Contactez le support de Wajub.

### Quand Wajub gèle un vendeur que vous avez gelé

Votre gel est **gardé sous celui de Wajub**. Le `frozen` du compte montre celui de Wajub
(`by: wajub`), et les paiements sont bloqués si l'un des deux gels les bloque.

| Ensuite                             | Ce qui se passe                                                                                                                                                  |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Wajub lève son gel                  | Le vôtre revient tel qu'il était : son motif, son `block_payments`, sa date. Le vendeur reste gelé                                                               |
| Vous levez le vôtre avec `unfreeze` | Seul le vôtre tombe : `200` avec `message: "Your freeze is lifted. Wajub's freeze stays in force."`, et `frozen.by` vaut toujours `wajub`. Le vendeur reste gelé |

Chaque levée envoie `account.unfrozen`, avec le gel qui reste dans `still_frozen`.

| `error_code`                 | Statut | Où                                                                                                                                                                                                            | Quand                                                      |
| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `account_type_not_freezable` | `400`  | `freeze`, `unfreeze`                                                                                                                                                                                          | Un compte `direct`                                         |
| `frozen_by_wajub`            | `409`  | `freeze`, `unfreeze`                                                                                                                                                                                          | Wajub a gelé ce vendeur, et vous ne l'aviez pas gelé avant |
| `account_frozen`             | `409`  | `POST /accounts/{id}/payouts`                                                                                                                                                                                 | Le vendeur est gelé                                        |
| `account_frozen`             | `422`  | `POST /transfers`                                                                                                                                                                                             | Un vendeur Lite gelé : aucun versement ne quitte son solde |
| `account_frozen`             | `403`  | `POST /payments`, `/links`, `/invoices`, `/payments/{id}/activate` avec `X-Sync` ; une part de `shares` ; le débit d'un paiement fait pour lui, et ses étapes de confirmation (`POST /payments/{id}/confirm`) | Un vendeur gelé dont les paiements sont bloqués            |

### Geler automatiquement

**Désactivé par défaut** : un vendeur qui atteint `high` envoie `account.risk_high` avec
`suggestion: "freeze"` et une suggestion dans votre Dashboard, et reste payé. Activez-le pour votre
plateforme sous **Sync, Risque vendeur**, ou par connexion avec `auto_freeze` sur `POST` et
`PUT /accounts` (`true`, `false`, ou `null` pour suivre votre plateforme). Activé, atteindre `high`
gèle le vendeur aussitôt (`by: auto`), `account.risk_high` porte `frozen: true`, et `account.frozen`
est envoyé.

| Événement          | Quand                                     | `data`                                                                                                 |
| ------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `account.frozen`   | Gelé par vous, par Wajub, ou par le score | `account`, `by`, `reason`, `block_payments` (le blocage en vigueur), `frozen_at`, `still_frozen: null` |
| `account.unfrozen` | Un gel levé                               | `account`, `by`, `reason`, `block_payments: false`, `frozen_at: null`, `still_frozen`                  |

`by` dit qui agit, `reason` est toujours présent (`null` sans motif). Sur `account.unfrozen`,
`still_frozen` est le gel qui reste quand un seul des deux a été levé, `null` quand le vendeur n'est
plus gelé : lisez-le avant de considérer le vendeur comme dégelé. Le corps est le même, que le gel ait
été posé par l'API, dans le Dashboard, par le score ou par Wajub.

```json title="Wajub a levé son gel : le vôtre reste"
{
"account": "acc_Gt6yU3nE8rM1kS5vX9bQ",
"by": "wajub",
"reason": null,
"block_payments": false,
"frozen_at": null,
"still_frozen": {
  "by": "platform",
  "reason": "Commandes jamais livrées",
  "block_payments": true,
  "since": "2026-11-18T10:00:00+00:00"
}
}
```

Un gel fait par l'API ou par le score arrive dans l'enveloppe habituelle ; un gel fait dans le
Dashboard, ou par Wajub, arrive comme une [livraison du cycle de vie Sync](https://docs.wajub.com/fr/developer-tools/webhooks/events#sync-lifecycle-deliveries).

## Dans le Dashboard

**Sync, Risque vendeur** liste vos vendeurs Lite et Relay actifs par score, avec leurs deux premières
raisons et leur état, et permet aux membres qui gèrent les versements de les geler et de les dégeler.
La page de chaque vendeur montre son score, ses raisons, son délai et son réglage de gel automatique,
et l'historique de son score et de ses gels. Vos vendeurs lisent « versements suspendus par votre
plateforme » dans leur portail : le nom de Wajub n'y apparaît pas.

- [Payer les vendeurs](https://docs.wajub.com/fr/sync/payouts): Ce qui retient un versement, et pourquoi.
- [Geler un vendeur](https://docs.wajub.com/fr/api/subaccounts/freeze): La spécification de l'endpoint.
- [Analyses](https://docs.wajub.com/fr/sync/analytics): Vos vendeurs à risque, à côté de votre volume et de votre commission.
