Capacités du compte

Les trois modes

account_type dit ce que le marchand possède chez Wajub et où se trouve l'argent. Les capacités, la commission et le consentement à un changement de conditions fonctionnent de la même façon dans les trois ; ce qui découle du mode est listé sous le tableau. Le mode est choisi à la création de la connexion et ne change jamais ensuite : en changer modifierait ce que le marchand a accepté, c'est donc une nouvelle connexion qu'il accepte à nouveau.

Ce qui découle du mode :

• une connexion lite refuse de lancer un paiement tant que le marchand n'est pas sur le rail Wajub (409). Elle existe pour que la commission soit prélevée à la source et le versement automatique, et les deux exigent que l'argent passe par Wajub ;
• une connexion relay n'a pas d'onboarding : il n'y a aucun compte marchand à revendiquer. Elle se crée uniquement avec POST /accounts, car le formulaire du Dashboard la refuse, et elle n'a pas de lien d'autorisation : authorization_url vaut null, et POST /accounts/{id}/token répond 422. Personne ne revendique donc la connexion : elle reste pending, son payment_status reste inactive, et X-Sync la refuse avec 403, comme toute connexion qui n'est pas active. Une marketplace Relay s'utilise avec votre propre clé, en payant vos vendeurs depuis votre propre solde ;
• une connexion relay ne porte pas de date d'invitation : expires_at vaut null et elle ne s'affiche jamais expired ;
• sur un compte Relay, le portefeuille de chaque nouveau vendeur est comparé au nom enregistré chez l'opérateur avant son premier versement. Les vendeurs sont vérifiés avant leur premier versement

Les sept capacités

Une connexion reçoit un sous-ensemble de cette liste fermée. Au moins une capacité est obligatoire à la création. Une valeur inconnue est refusée avec 422.

write, settings, subscriptions et analytics ne sont plus proposées : elles n'ouvraient aucune ressource. Les demander à la création ou à la modification d'une connexion répond 422. Une connexion qui en porte déjà une continue de fonctionner, et la valeur n'accorde rien.

Chaque ressource déclare ce qu'elle exige

Chaque route déclare la capacité qu'elle exige, et une route qui n'en déclare aucune ne peut pas être appelée avec X-Sync. Le refus est la règle par défaut : une capacité non accordée est une capacité que la plateforme n'a pas, et une requête X-Sync qui l'exige est refusée avec 403.

Une ressource qui ne peut pas être appelée avec X-Sync répond 403 avec This endpoint cannot be called on behalf of a Sync account, quelles que soient les capacités de la connexion.

Une capacité ne couvre que ce que la connexion a apporté

Les capacités disent quoi ; la connexion dit à qui. Avec X-Sync, une plateforme atteint ce que cette connexion a apporté et rien d'autre du marchand : ni ses ventes directes, ni ses propres liens, factures ou bénéficiaires, ni ce qu'une autre plateforme a apporté.

Tout le reste répond 404, comme s'il n'existait pas. Un bénéficiaire que le marchand paie déjà ne fait pas exception : en créer un pour le même compte avec X-Sync donne à la connexion le sien, et payer celui du marchand répond 422.

Les clients sont partagés avec le marchand

Un client appartient au marchand, pas à la connexion. La connexion atteint un client dès qu'il a acheté par elle, ou dès que la plateforme l'a créé ou l'a désigné par son e-mail ou son téléphone. C'est la règle « trouver ou créer » : POST /customers avec l'e-mail ou le téléphone d'un client du marchand (l'e-mail quelle que soit sa casse, le téléphone quelle que soit son écriture) renvoie ce client avec 200 au lieu d'un doublon, et POST /payments lui rattache le paiement. L'un comme l'autre ne remplit que les champs que le marchand a laissés vides, jamais un champ qu'il a renseigné. Dès lors, la plateforme peut le lire, le retrouver dans la liste, le modifier et le bloquer, et l'utiliser sur ses paiements et ses factures, et le marchand en voit le résultat. Plusieurs connexions peuvent atteindre le même client. La plateforme ne peut pas le supprimer : DELETE /customers/{id} avec X-Sync répond 403, car effacer un client est une décision du marchand.

La plateforme voit l'identité, les coordonnées et les adresses d'un client, jamais les notes, le block_reason ni les metadata du marchand, et les notes qu'elle envoie sont ignorées. Les metadata qu'elle lit et écrit sont les siennes, séparées pour chaque connexion : sur un client que le marchand avait déjà, POST /customers et les paiements ajoutent les clés que la plateforme n'a pas encore définies, et PUT /customers/{id} les remplace. Les metadata du marchand ne changent jamais par X-Sync.

Le marchand voit sur la page du client, dans le Dashboard, quelles plateformes atteignent ce client et depuis quand, et peut retirer l'accès d'une plateforme. La plateforme n'atteint alors plus le client que par ses propres paiements, comme avant, et ses metadata sur ce client sont supprimées. Effacer un client retire l'accès de toutes les plateformes.

Un client que la connexion n'a ni vu ni désigné reste hors de portée : /customers/{id} répond 404, et son identifiant cus_ donné comme customer_id sur un paiement ou une facture répond 422, comme un identifiant inconnu. Remplacer l'e-mail ou le téléphone d'un client par ceux d'un autre client répond 422, comme pour le marchand.

Les liens et les factures encaissent pour la connexion

Un paiement fait sur un lien ou une facture créé par la connexion porte la connexion, comme un paiement fait avec POST /payments et X-Sync : la commission s'applique et la plateforme le voit dans /payments. Dès que la connexion ne peut plus encaisser (annulée, paiements suspendus, capacité retirée, ou Sync absent de votre plan), le lien répond 404 au payeur et la facture ne peut plus être payée. Ils encaissent de nouveau quand la connexion le peut.

Les événements, et leur renvoi

GET /events avec X-Sync liste les événements enregistrés sur ce que la connexion a apporté. Les événements enregistrés avant le 2026-10-10 ne portent aucune connexion, et ne sont donc pas listés.

POST /events/{id}/resend avec X-Sync envoie l'événement à vos endpoints, jamais à ceux du marchand : il renvoie la copie que vous avez reçue à l'époque, avec data.account, ou crée cette copie une fois si l'événement ne vous a jamais été copié, comme c'est le cas des liens, factures et bénéficiaires.

Modifier les conditions d'une connexion active

Les capacités et la tarification sont ce que le marchand a accepté : une fois la connexion active, elles se proposent au lieu de se modifier. PUT /accounts/{id} répond 202 Accepted et renvoie la proposition dans pending_changes ; la connexion continue de fonctionner aux conditions en vigueur jusqu'à ce que le marchand accepte ou refuse depuis son dashboard.

Les ventes déjà réalisées conservent les conditions sous lesquelles elles ont eu lieu : un changement de tarif ne retarife jamais une commission déjà prélevée. Tant que la connexion est pending, personne n'a rien accepté et PUT applique le changement directement, avec un 200.

Tarification

La tarification représente ce que votre plateforme retient sur l'activité du compte connecté. C'est une règle unique associée à la connexion, créée par POST /accounts à partir de l'objet pricing, puis modifiée avec PUT /accounts/{id} ou depuis le Dashboard.

Les deux types se cumulent au lieu de se concurrencer. Une règle qui contient un pourcentage et des frais fixes prélève le pourcentage du montant, puis ajoute la valeur fixe. Elle applique ensuite le plancher, puis le plafond, dans cet ordre.

Calcul des frais

Cette séquence explique tous les chiffres présents dans un événement fee.received.

Un paiement porte au plus une commission, quel que soit le comportement de l'événement qui l'a déclenchée. La commission circule dans la devise de règlement de la vente, convertie lorsque la règle utilise une autre devise.

Une commission est une part d'une vente : une vente défaite emporte sa part avec elle.

Quand la vente est remboursée

commission_refund_policy, défini sur la connexion, décide de ce qui revient.

Définissez-la avec POST /accounts, et ne la modifiez avec PUT /accounts/{id} que tant que la connexion est encore pending : c'est une condition commerciale que le marchand a acceptée. Rien n'est jamais rendu deux fois, et plusieurs remboursements sur une même vente ne peuvent jamais rendre plus que ce qui a été prélevé.

Quand un litige sur la vente est perdu

Un litige perdu défait la vente comme un remboursement, et la même politique s'applique au montant contesté : un chargeback que le fournisseur déclare perdu, un litige que votre marchand accepte, ou un litige clos après son échéance. Quand votre marchand accepte un litige, l'acheteur est remboursé par un remboursement ; le litige et ce remboursement rendent la commission une seule fois à eux deux, selon celui qui est enregistré en premier. Un litige gagné ne rend rien : la vente tient.

En sandbox

Une vente sandbox déplace la commission entre les deux soldes sandbox, et un remboursement sandbox ou un litige sandbox perdu la rend selon la même politique : vous pouvez vérifier ce que verront vos marchands. La réserve, la couverture d'un solde négatif et les commissions qu'un marchand doit lorsqu'il encaisse sur son propre contrat n'existent qu'en live.

Une seule règle, pour chaque paiement

Une connexion porte une seule règle de tarification, appliquée à chaque paiement effectué sur la connexion. Il n'existe aucun moyen de prélever une commission différente sur les petits paniers ou d'exempter une devise : aucun endpoint ni formulaire du Dashboard ne définit de conditions sur une règle.

Ce qui reste librement modifiable

Deux champs survivent à l'acceptation sans l'accord du marchand, et seulement ces deux-là.

La suspension d'une connexion arrête à la fois les paiements entrants et les transferts sortants. Elle émet account.payment_suspended. Utilisez-la lorsque vous auriez autrement besoin de révoquer une capacité. Contrairement à une capacité, elle est réversible.