# Relay

> Encaissez pour des vendeurs sans compte Wajub, et laissez Wajub calculer et verser ce qui revient à chacun.

En `relay`, vous êtes le marchand de référence. Vos vendeurs n'ont pas de compte Wajub : chacun est
une connexion liée à son portefeuille mobile money. Vous encaissez chaque vente sur votre propre
solde, et Wajub tient, vente par vente, ce qui revient à chaque vendeur, puis le lui verse au rythme
que vous fixez.

> [!NOTE]
> **Ouvert en live une fois votre plateforme examinée par Wajub**
>
> Tous les appels de cette page fonctionnent avec une clé de sandbox. En live, Relay est ouvert à
> toute plateforme que Wajub a approuvée pour lui : demandez la revue sous **Paramètres, Sync,
> Plateforme**. Tant qu'elle n'est pas approuvée, ou si l'approbation est retirée, `POST /accounts`
> avec `account_type: relay`, un appel portant `X-Sync` sur une connexion Relay live, et une part
> Relay d'un paiement partagé répondent `403` avec `error_code: sync_mode_not_approved`.

## Une connexion par vendeur

Créez la connexion avec le portefeuille du vendeur : un bénéficiaire que vous avez déjà, ou les
informations pour en créer un, avec les mêmes champs que `POST /beneficiaries`.

```bash title="Un vendeur Relay"
curl https://api.wajub.com/accounts \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "account_type": "relay",
    "capabilities": ["payments", "refunds"],
    "pricing": { "percentage_fee": 10, "currency": "XAF" },
    "payout_schedule": "weekly",
    "beneficiary": "ben_LRQqYvlhrgUOE225KMKU"
  }'
```

| Le portefeuille                                              | La connexion                                                                                                                                                |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Son nom est confirmé par l'opérateur                         | `active`, avec `payment_status: active`, tout de suite                                                                                                      |
| Pas encore vérifié, ou l'opérateur n'a pas pu être interrogé | `pending` ; `relay.pending_reason` dit pourquoi. Elle passe `active` dès qu'une vérification réussit, avec `POST /beneficiaries/{id}/verify` ou d'elle-même |
| Connu de l'opérateur sous un autre nom                       | `pending` avec `wallet_name_mismatch` : corrigez le nom, puis vérifiez de nouveau                                                                           |

Il n'y a ni onboarding ni `authorization_url`. Un portefeuille porte une seule connexion Relay par
plateforme : une seconde répond `409` avec `error_code: relay_wallet_taken`.

## Ce qui revient à chaque vendeur

Encaissez avec `X-Sync` comme pour toute connexion. Le paiement est le vôtre : il arrive sur votre
solde. Pour chaque vente réussie, Wajub enregistre le dû du vendeur :

|               |                                                                                                                                                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Le dû         | Ce que la vente vous a crédité, moins les frais de Wajub, moins votre commission (le `pricing` de la connexion)                                                                                                                      |
| Retenu        | Jusqu'à la fin de la rétention de la vente, comme l'argent lui-même                                                                                                                                                                  |
| À verser      | Ensuite, jusqu'à ce qu'un versement le prenne                                                                                                                                                                                        |
| Réserve carte | Une vente par carte garde 10 % de son dû pendant 120 jours par défaut, sur votre solde, contre les rétrofacturations : payée au vendeur par le premier versement après ce délai ([La réserve carte](https://docs.wajub.com/fr/sync/payouts#the-card-reserve)) |

Une vente encaissée sur votre propre compte chez un prestataire n'est jamais arrivée chez Wajub : elle
ne crée aucun dû.

## Les versements

`payout_schedule` (`manual`, `daily`, `weekly`, `monthly`) et `payout_min_amount` fonctionnent comme
en `lite`, et `POST /accounts/{id}/payouts` paie le vendeur tout de suite. Chaque versement envoie les
dus à verser du vendeur, du plus ancien au plus récent et entiers, **moins ce qu'il doit** après un
remboursement, de votre solde vers son portefeuille. Quand ce qu'il doit absorbe tout le versement, rien
n'est envoyé : l'appel répond `200` avec `transfer: null` et le montant `netted`.

Un vendeur Relay reçoit **un versement par jour** au plus. Quand deux passages se rencontrent le même
jour (le planifié et votre `POST /accounts/{id}/payouts`, ou un appel que vous avez rejoué), le second
répond avec le versement du jour et n'envoie rien de plus ; les dus enregistrés entre-temps partent
avec le versement du lendemain, par un versement à eux. Un dû n'est jamais marqué payé que par le
versement qui le portait.

| Ce qui retient un versement                                      | `payout_hold.reason`                                                           |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Votre solde ne contient pas le montant                           | `insufficient_balance` : rien ne part, le passage suivant réessaie             |
| Votre plafond d'exposition                                       | `exposure_cap` ([Votre plafond d'exposition](https://docs.wajub.com/fr/sync/payouts#your-exposure-cap)) |
| Wajub a retiré votre approbation                                 | `approval_withdrawn`                                                           |
| Le vendeur a dépassé le palier du nom seul                       | `identity_required` (ci-dessous)                                               |
| Le vendeur est nouveau, et seuls ses dus plus anciens sont payés | `new_seller` ([Risque vendeur](https://docs.wajub.com/fr/sync/seller-risk#new-sellers-are-paid-later))  |
| Vous, ou Wajub, avez gelé le vendeur                             | `frozen` ([Risque vendeur](https://docs.wajub.com/fr/sync/seller-risk#freezing-a-seller))               |

Une vente que vous [bloquez jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds) garde son dû impayé jusqu'à votre
libération, sans `payout_hold`.

Chaque retenue envoie `account.payout_limited` une fois, sauf `identity_required`, qui envoie
`account.identity_required`. Un versement passe tous les contrôles d'un
virement ordinaire, y compris votre réserve et les remboursements en route.

## Quand une vente est remboursée

Le remboursement sort de votre solde, comme pour tout paiement à vous : il attend avec
`insufficient_balance` si vous ne le détenez pas. Côté vendeur :

| Le dû            | Ce qui se passe                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------ |
| Pas encore versé | Il est réduit de la part remboursée, et annulé s'il ne reste rien                                |
| Déjà versé       | Ce que le vendeur doit est enregistré sur son bénéficiaire, et retenu sur son prochain versement |

Un litige perdu fonctionne de la même façon. Chaque remboursement ou litige ne compte qu'une fois, même
rejoué.

## L'identité du vendeur, au-delà d'un palier

Un vendeur est payé sur le seul nom de son portefeuille tant que ce que Wajub a versé à ce
portefeuille sur les 12 derniers mois reste sous un plafond (500 000 XAF ou XOF). Au-delà, la part
d'un versement qui dépasse le plafond attend une pièce d'identité : vous recevez
`account.identity_required`, et l'envoyez avec `POST /accounts/{id}/identity`, en
`multipart/form-data`.

| Champ                 |                                                                    |
| --------------------- | ------------------------------------------------------------------ |
| `full_name`           | Tel que la pièce l'imprime                                         |
| `document_type`       | `national_id`, `passport`, `driving_license` ou `residence_permit` |
| `document_number`     | Jamais conservé en clair                                           |
| `birth_date`          | `AAAA-MM-JJ`                                                       |
| `document_expires_at` | Facultatif ; une pièce expirée est refusée                         |
| `document`            | JPG, PNG ou PDF, 10 Mo au plus                                     |

Wajub l'examine, en général dans la journée ouvrée : `account.identity_verified`, et les versements
retenus partent au passage suivant, ou `account.identity_rejected` avec le motif. En sandbox, elle est
approuvée tout de suite. Le plafond peut changer : Wajub prévient les plateformes Relay avant.

- [Payer les vendeurs](https://docs.wajub.com/fr/sync/payouts): Versements Lite, plafond d'exposition et lots de versements.
- [Remboursements](https://docs.wajub.com/fr/sync/refunds): Qui rembourse quoi, mode par mode.
- [Bénéficiaires](https://docs.wajub.com/fr/payouts/beneficiaries): Les portefeuilles, et la vérification du nom.
