Intégration des marchands
Le cycle de vie d'une connexion et ce qui est figé dès son acceptation par un marchand.
Une connexion possède deux statuts qui évoluent indépendamment. status indique si le marchand a
accepté la connexion. payment_status indique si elle peut déplacer de l'argent. Une connexion peut
être active tout en refusant tous les paiements. C'est la surprise la plus fréquente de cette
section.
Le cycle de vie
status | Signification | Origine |
|---|---|---|
pending | Créée, personne ne l'a acceptée | POST /accounts |
active | Un marchand s'est connecté et l'a autorisée | Il a ouvert le lien d'autorisation |
cancelled | Arrêtée par vous | DELETE /accounts/{id} |
expired | L'invitation a expiré avant son acceptation | Le temps |
Il n'existe ni statut restricted ni état intermédiaire. Le statut lu est calculé, pas enregistré.
Une connexion annulée renvoie cancelled, une connexion expirée renvoie expired, une connexion
associée à un marchand renvoie active, et toutes les autres renvoient pending.
Le lien d'autorisation
La création d'une connexion génère un jeton d'autorisation à usage unique et le renvoie dans une URL.
Le marchand ouvre le lien, se connecte à son propre compte Wajub, consulte les capacités demandées, puis accepte. Votre plateforme ne manipule jamais ses identifiants et ne crée rien de son côté.
Le lien est un identifiant d'accès
Toute personne qui possède cette URL peut associer un compte à votre plateforme. Envoyez-la par
un canal que vous contrôlez et traitez-la comme un secret. Si elle est divulguée,
POST /accounts/{id}/token révoque l'ancien jeton et en génère un nouveau. Cet appel est refusé
avec 400 dès qu'un marchand a revendiqué la connexion — qu'elle soit encore active ou déjà
déconnectée — car ce marchand y reste rattaché et le nouveau lien ne pourrait pas servir. Pour le
joindre à nouveau, créez une nouvelle connexion qu'il accepte à nouveau.
Une invitation ne reste pas ouverte indéfiniment : elle expire 30 jours après avoir été créée, et un rappel part trois jours avant à l'adresse que vous avez indiquée pour le marchand. Passé ce délai, le nettoyage l'annule et révoque son jeton : le lien qui dort dans la boîte du marchand cesse de fonctionner.
Une fois la connexion revendiquée, authorization_url disparaît de la réponse. slave apparaît à
sa place avec le nom et l'adresse e-mail de l'entreprise du marchand.
Activer ensuite les paiements
L'acceptation ne donne pas l'autorisation de débiter. payment_status commence à inactive et le
reste.
payment_status | Effet sur les requêtes qui contiennent X-Sync |
|---|---|
inactive | Paiements et transferts refusés avec 403 |
active | Paiements et transferts exécutés |
suspended | Paiements et transferts refusés avec 403 |
Wajub le fait automatiquement passer à active lorsque le contrôle de conformité du marchand est
validé, puis émet account.payment_activated. C'est le parcours normal en mode live.
La sandbox est l'exception
La vérification de conformité ne s'exécute pas dans la sandbox. Une connexion de sandbox ne
s'active donc jamais seule. Après sa revendication, définissez vous-même payment_status sur
active avec PUT /accounts/{id}. Le même appel renvoie 400 lorsque la connexion est encore au
statut pending.
Vous pouvez ensuite utiliser la suspension. Définir payment_status sur suspended arrête en même
temps les paiements entrants et les transferts sortants. Ce comportement est volontaire : une
connexion figée après l'échec d'un nouveau contrôle de conformité ne doit pas pouvoir vider son
solde alors qu'elle ne peut plus recevoir d'argent.
Le portail du vendeur Lite
Un vendeur lite n'a pas de dashboard marchand : c'est tout l'objet du mode. Son onboarding se
termine sur la demande d'accès au rail Wajub, et il utilise ensuite un portail qui lui est propre,
à vos couleurs.
| Ce qu'il y fait | Comment |
|---|---|
| Se connecter | Un code à usage unique envoyé à l'adresse de la boutique — sans mot de passe, avec une session courte |
| Voir ses ventes et ses versements | Uniquement ceux de cette connexion : jamais son autre activité, jamais celle d'une autre plateforme |
| Demander l'accès au rail Wajub | Étape hébergée de l'onboarding ; la connexion ne peut pas encaisser tant qu'elle n'est pas approuvée |
| Déclarer où va son argent | La page des coordonnées de versement du portail |
Une nouvelle destination de versement est mise en attente
Une destination que le vendeur vient de déclarer ou de modifier ne peut recevoir aucun versement pendant un délai de carence (24 heures par défaut). La vérification dit que le compte existe et à quel nom ; l'attente laisse le temps à la notification d'atteindre une personne capable de dire non. Un transfert vers une destination en attente est refusé jusqu'à l'échéance.
Ce que le marchand doit accepter à nouveau
Dès l'acceptation du marchand, deux des quatre champs modifiables cessent de dépendre de vous seul.
| Champ | Après l'acceptation |
|---|---|
capabilities | 202 Accepted — proposé au marchand, renvoyé dans pending_changes |
pricing | 202 Accepted — proposé au marchand, renvoyé dans pending_changes |
callback | Reste librement modifiable |
payment_status | Reste librement modifiable, et ne l'est qu'à partir de ce moment |
Cette asymétrie est volontaire. Ce que le marchand a accepté sur l'écran d'autorisation ne peut pas être modifié à son insu : une connexion élargie ou une commission relevée devient une proposition qu'il accepte ou refuse depuis son dashboard, la connexion continuant entre-temps aux conditions en vigueur. La suspension, elle, reste la vôtre et ne se propose pas.
Mettre fin à une connexion
DELETE /accounts/{id} révoque les jetons, définit status sur cancelled et émet
account.deauthorized. Si le marchand avait accepté, payment_status passe également à inactive
et la réponse contient Account disconnected. Pour une invitation non revendiquée, elle contient
Account cancelled.
curl -X DELETE https://api.wajub.com/accounts/acc_7Yh2MpL4tRb3nP8sZcXv \
-H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…"La déconnexion ne modifie rien de ce qui s'est déjà produit. Le marchand conserve son compte, ses paiements et son solde. Les commissions déjà acquises restent acquises. Seule votre capacité à agir en son nom prend fin.
Les événements à écouter
Cinq webhooks décrivent le cycle de vie d'une connexion. Vous les recevez sur les endpoints de votre plateforme.
| Événement | Moment de l'émission |
|---|---|
account.created | Vous créez une connexion |
account.updated | Un élément de la connexion change, y compris son acceptation |
account.payment_activated | La connexion obtient la capacité de débiter |
account.payment_suspended | Vous suspendez la connexion |
account.deauthorized | La connexion est déconnectée ou annulée |
De plus, chaque paiement, remboursement et transfert effectué sur un compte connecté déclenche son webhook normal pour le marchand et une copie pour votre plateforme. Vous n'avez pas besoin d'interroger régulièrement une connexion pour connaître son activité.