# Wajub, Developer Documentation > Payment orchestration for Africa: API, SDKs, webhooks, Mobile Money, marketplaces and routing. Toutes les pages de la documentation en Markdown, puis la référence de l'API. Chaque page commence par son titre et son adresse. Ajoutez `.md` à l'adresse d'une page pour n'obtenir qu'elle. # Activation du compte et KYC URL: https://docs.wajub.com/fr/getting-started/account-activation > Le dossier qui débloque les paiements live, le déroulement de la vérification et ce qu'elle change. Le sandbox ne vous demande rien d'autre qu'une adresse email. La production exige une identité vérifiée, parce que déplacer l'argent des autres est réglementé partout où Wajub opère. Tant que votre dossier de conformité n'est pas `verified`, votre équipe reste en sandbox. Le Dashboard refuse de passer en live, aucune clé live ne peut donc être créée, pas même par `wajub login`. C'est la vérification qui fait passer votre équipe en live. ## Commencez par choisir ce que vous êtes Ce premier choix détermine tout le dossier, alors faites-le en connaissance de cause. Wajub reconnaît huit types d'entité juridique : **particulier**, **entreprise**, **ONG**, **établissement d'enseignement**, **organisation religieuse**, **organisation politique**, **entité gouvernementale** et **autre**. Chacun a ses propres sous-types : une SARL et une SA sont deux formes du même type entreprise. La distinction qui compte pour votre charge de travail oppose le particulier à tous les autres. Un particulier, freelance ou entrepreneur individuel, ne fournit aucun document d'entreprise. Tous les autres types en fournissent quatre. Le type ne se change que dans un sens. Une fois vérifié comme particulier, vous pouvez passer à un autre type depuis **Paramètres → Conformité**. Votre dossier repasse alors à `unverified` et vous demande ce que le nouveau type exige en plus de ce que vous avez déjà fourni. Aucun autre changement de type n'est proposé. Le guide du tableau de bord montre [comment changer de type](https://docs.wajub.com/dashboard/activation/switch-to-business). ## Les six étapes La vérification se trouve dans le Dashboard, sous **Paramètres → Conformité** : un assistant en six étapes, où chaque étape débloque la suivante. Le guide du tableau de bord le parcourt écran par écran : [vérifier son entreprise](https://docs.wajub.com/dashboard/activation/verify-business) pour le dossier, [vérifier l'identité d'une personne](https://docs.wajub.com/dashboard/activation/verify-identity) pour chaque personne du dossier, puis [suivre sa vérification](https://docs.wajub.com/dashboard/activation/track-verification) une fois le dossier envoyé. ## Ce que contrôle vraiment le bouton Soumettre pour vérification Le bouton reste inactif tant que le dossier n'est pas complet, et les règles sont précises, pas indicatives. Les lire maintenant va plus vite que les découvrir un refus après l'autre. Tout le monde doit avoir une catégorie d'activité, une description des produits, une raison sociale avec une adresse complète, un email d'entreprise vérifié, un téléphone d'entreprise vérifié et au moins une présence en ligne. **Si vous êtes une entreprise, une ONG ou toute autre organisation**, vous envoyez quatre documents au niveau de l'entreprise, et le quatrième n'est dispensé que pour les entités gouvernementales. | Document | Ce que c'est | | ---------------------------- | ------------------------------------------------------------------------------------------- | | Certificat d'immatriculation | La preuve que l'entité est légalement enregistrée. | | Statuts | Le document fondateur qui décrit la structure et les règles. | | Plan de localisation | Une carte ou un plan qui montre où l'activité s'exerce physiquement. | | Attestation fiscale | La confirmation de l'immatriculation fiscale. Non exigée pour les entités gouvernementales. | Vous enregistrez aussi au moins une personne désignée comme représentant légal, et cette personne doit avoir une pièce d'identité au dossier. Passeport, carte nationale d'identité ou titre de séjour sont acceptés. Le représentant légal fait aussi la vérification de présence (liveness), la même session en temps réel qu'un particulier (décrite plus bas), et peut la faire via un lien que vous lui envoyez. **Si vous êtes un particulier**, il n'y a aucun document d'entreprise. Vous vous enregistrez vous-même et fournissez trois éléments : une pièce d'identité, un justificatif de domicile et une vérification de présence (liveness). Cette vérification est une session en temps réel, faite dans le Dashboard ou via un lien que vous envoyez, ce qui est plus simple quand la personne à vérifier n'est pas celle qui est devant le clavier. Un fichier vidéo que vous téléversez vous-même ne compte pas comme une vérification de présence. **Si votre activité est réglementée**, et c'est le cas du traitement de paiements, du transfert d'argent, du prêt, de l'échange de cryptomonnaies, de l'investissement, des jeux d'argent, de la loterie, de la télémédecine et de la pharmacie en ligne, vous devez joindre une licence valide en plus de tout ce qui précède. Une licence expirée ou déjà refusée ne compte pas, et le dossier ne peut pas être soumis sans licence. ## Règles pour les fichiers Les documents sont acceptés en PDF, JPG, JPEG ou PNG, jusqu'à 10 Mo chacun. Numérisez de façon lisible. Un document illisible est le refus le plus bête qui soit, et il vous coûte un cycle de vérification complet. ## Après la soumission Votre dossier passe en `pending` et le Dashboard vous indique d'attendre une réponse sous 48 heures. Vous recevez immédiatement un email de confirmation, et l'équipe conformité prend le relais. Pendant l'attente, le dossier passe en lecture seule : vous ne pouvez ni modifier de champ ni ajouter de personne tant qu'une décision n'est pas rendue. Votre intégration sandbox n'est pas touchée. C'est le bon moment pour la terminer, tester les cas d'échec et dérouler la [checklist pour passer en live](https://docs.wajub.com/fr/getting-started/going-live), afin que l'approbation soit la seule chose qui vous sépare de votre premier vrai paiement. ## Suivez la décision depuis votre code La conformité émet des webhooks : votre application peut donc réagir à une décision sans que personne n'actualise un onglet du Dashboard. Abonnez un endpoint aux événements qui vous intéressent, et ils arrivent dans l'enveloppe signée habituelle. | Événement | Déclenché quand | | ------------------------------ | ---------------------------------------------------------------- | | `compliance.submitted` | Votre dossier entre en vérification. | | `compliance.verified` | Vous êtes approuvé et le live s'ouvre. | | `compliance.rejected` | Le dossier est refusé, avec un motif. | | `compliance.changes_requested` | Un point précis doit être corrigé avant une décision. | | `compliance.inquiry.created` | La conformité ouvre une question de suivi après la vérification. | | `compliance.inquiry.resolved` | Cette question est close. | Le payload contient le nouveau statut, le statut précédent et le motif de refus quand il y en a un, ce qui suffit pour envoyer une alerte à la bonne personne de votre côté. ```json title="compliance.verified" { "id": "evt_7Yh2Mp4kQ9vB5nL6hR1cY8dF", "event": "compliance.verified", "livemode": true, "api_version": "2026-10-11", "created": "2026-05-24T10:21:08+00:00", "data": { "legal_name": "Boutique Amina SARL", "type": "company", "status": "verified", "previous_status": "pending", "rejection_reason": null, "submitted_at": "2026-05-22T09:04:11+00:00", "verified_at": "2026-05-24T10:21:08+00:00" } } ``` Ces événements n'atteignent que les endpoints **live** qui les citent par leur nom. Un endpoint sandbox ne les reçoit jamais, un endpoint abonné à `*` non plus : ajoutez-les donc explicitement à la configuration de votre endpoint live. ## Quand vous êtes approuvé Votre dossier de conformité passe en `verified`, votre équipe passe en live et vos plafonds live sont fixés. Les clés live se créent ensuite de la même façon que les clés sandbox : en changeant d'environnement dans le Dashboard et en générant une nouvelle clé. Consultez [Configurer votre compte](https://docs.wajub.com/fr/getting-started/dashboard-setup) pour savoir où cela se trouve. Une clé sandbox n'est jamais promue en clé live. Vos plafonds, par transaction, par jour et par mois, pour l'encaissement comme pour les payouts, dépendent de votre entreprise et de son activité, et sont affichés dans le Dashboard. La vérification n'est pas définitive. Wajub fixe une date de nouvelle vérification à douze mois et vous prévient trente jours avant l'échéance : prévoyez de mettre vos documents à jour une fois par an. ## Quand le dossier revient pour corrections Un refus n'est pas définitif. `rejected` s'accompagne d'un motif écrit, et `changes_requested` signifie qu'un élément précis manque ou est illisible. Dans les deux cas, le dossier redevient modifiable et vous soumettez à nouveau le même dossier. Voici les causes qui reviennent réellement. | Cause | Que faire | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Scan illisible ou partiel | Numérisez à nouveau la page entière, les quatre coins visibles. | | Le nom sur le document ne correspond pas à la raison sociale déclarée | Utilisez des documents au nom exact enregistré, ou corrigez la raison sociale. | | La présence en ligne est une page provisoire ou une URL hors ligne | Publiez quelque chose de réel avant de soumettre à nouveau, l'URL est ouverte. | | Description des produits trop vague | Dites ce que vous vendez, à qui, et pour quel montant habituel. | | Activité réglementée déclarée sans licence | Joignez la licence, ou corrigez l'activité si elle a été mal sélectionnée. | | Bénéficiaires effectifs manquants | Enregistrez chaque propriétaire, avec sa pièce d'identité et son pourcentage de détention. | Une fois vérifié, les questions supplémentaires arrivent par des **demandes de conformité** (compliance inquiries) plutôt que par une nouvelle vérification. Elles se trouvent dans le Dashboard à côté de votre dossier, s'enchaînent comme une conversation, et vous pouvez joindre des fichiers à une réponse. C'est le canal normal des suivis de lutte contre le blanchiment (AML), et elles ne suspendent pas votre compte à elles seules. Le guide du tableau de bord montre [comment y répondre](https://docs.wajub.com/dashboard/activation/track-verification#answer-an-inquiry). > [!WARNING] > **Certaines activités ne sont jamais éligibles** > > Les armes, les substances illicites et les jeux d'argent sans licence sont refusés quel que soit le > dossier, tout comme ce qui est illégal dans les pays où vous opérez. Si votre activité est > réglementée et que vous détenez la licence, déclarez-la dès la première étape au lieu d'espérer > que la question ne se pose pas. - [Passer en live](https://docs.wajub.com/fr/getting-started/going-live): La checklist à dérouler avant de changer de clés. - [Configurer votre compte](https://docs.wajub.com/fr/getting-started/dashboard-setup): Où les clés live sont générées une fois que vous êtes approuvé. - [Conformité et sécurité](https://docs.wajub.com/fr/resources/compliance): PCI-DSS, protection des données, réglementation régionale. - [Plafonds et quotas](https://docs.wajub.com/fr/resources/limits): Plafonds de montant, limites de requêtes, livraison des webhooks. --- # Structure des réponses URL: https://docs.wajub.com/fr/getting-started/api-structure > L'enveloppe JSON, le format des listes, la forme des erreurs et les identifiants communs à tous les endpoints. Chaque endpoint répond avec la même enveloppe JSON, en cas de succès comme d'échec. Trois clés sont toujours présentes : un seul handler de réponses couvre donc toute l'API, et vous ne distinguez que les parties qui changent. ## Les trois clés toujours présentes `code` répète le statut HTTP dans le corps, pour les clients qui lisent difficilement les en-têtes. `status` est le libellé HTTP de ce code (`OK`, `Created`, `Not Found`, `Unprocessable Content`), et jamais la chaîne littérale `error`. `message` est une courte phrase qui décrit ce qui s'est passé, destinée à vos logs plutôt qu'à vos clients. Tout le reste du corps dépend de ce que vous avez demandé. ## Une ressource Quand vous récupérez ou créez un seul objet, il arrive sous une clé qui porte le nom de son type. Un paiement revient sous `transaction`, un client sous `customer`, un transfert sous `transfer`. Il n'y a pas d'enveloppe générique `data` à déballer. Un champ sans valeur peut être omis ou envoyé à `null`. Traitez chaque champ facultatif comme pouvant être absent ou `null`, et lisez-le avec une valeur par défaut. ```json title="GET /payments/{id} · 200 OK" { "code": 200, "status": "OK", "message": "Payment retrieved", "transaction": { "id": "trx_test_CSUGajfv9xh0XQ5wu2lx", "reference": "order-4172", "status": "succeeded", "amount": 5000, "currency": "XAF", "created_at": "2026-05-24T10:21:08+00:00" } } ``` Un endpoint peut ajouter ses propres clés de premier niveau à côté de la ressource quand elles n'en sont pas des propriétés. La création d'un paiement est le premier cas que vous rencontrerez : l'URL de la page hébergée décrit la session que vous venez d'ouvrir, pas le paiement lui-même. Elle se place donc à côté de la ressource plutôt qu'à l'intérieur. Le jeton n'a pas de préfixe de type : c'est une chaîne aléatoire, précédée de `test_` dans la sandbox. ```json title="POST /payments · 201 Created" { "code": 201, "status": "Created", "message": "Payment initiated", "authorization_url": "https://pay.wajub.com/test_7Yh2Mp4kQ9xL4vR8tB3nW6yC1dF5sJ0aG…", "authorization_token": "test_7Yh2Mp4kQ9xL4vR8tB3nW6yC1dF5sJ0aG…", "transaction": { "id": "trx_test_CSUGajfv9xh0XQ5wu2lx", "status": "pending", "amount": 25000, "currency": "XAF" } } ``` ## Plusieurs ressources Les endpoints de liste dérogent volontairement à la règle de nommage. Le tableau s'appelle `items`, quel que soit son contenu, et un objet `meta` porte l'état de la pagination. Écrire une seule fonction de liste qui marche pour les paiements, les clients, les transferts et les autres ressources vaut donc la peine. Seule exception : `GET /events`, dont le tableau s'appelle `events` et qui ne pagine que par numéro. ```json title="GET /payments · 200 OK" { "code": 200, "status": "OK", "message": "Payments retrieved", "items": [ { "id": "trx_test_CSUGajfv9xh0XQ5wu2lx", "status": "succeeded", "amount": 5000 }, { "id": "trx_test_9Wm4Kd2pR7vB5nL6hY1c", "status": "pending", "amount": 12000 } ], "meta": { "current_page": 1, "last_page": 4, "per_page": 25, "total": 87, "next_cursor": "Q2t9mVxL4pRw8nZs...", "has_more": true } } ``` `meta` existe sous deux formes, et celle que vous recevez dépend de votre requête. Par défaut, vous paginez par numéro de page et `meta` vous indique où vous en êtes par rapport au total. Sur les listes qui prennent en charge les curseurs, il porte aussi `next_cursor` et `has_more`. Renvoyez ce `next_cursor` dans le paramètre `cursor` et l'API passe en pagination par curseur : c'est ce qu'il vous faut pour un gros export ou une reprise de données, car elle reste correcte pendant que de nouveaux objets arrivent. ```json title="meta, mode curseur" { "per_page": 25, "next_cursor": "Hj4kP9wQx2LmV7tRb3NcY6sD", "prev_cursor": null, "has_more": true } ``` La taille de page vaut 25 par défaut et plafonne à 100. [Pagination](https://docs.wajub.com/fr/api/pagination) explique comment parcourir une collection du début à la fin. ## Erreurs Une erreur garde les trois mêmes clés. Le code HTTP est dans la plage `4xx` ou `5xx`, `status` est le libellé de ce code, et `message` dit ce qui n'a pas marché. Comme l'enveloppe ne change pas, un appel en échec se lit avec le même code qu'un appel réussi. ```json title="422 Unprocessable Content" { "code": 422, "status": "Unprocessable Content", "message": "The amount field is required. (and 1 more error)", "errors": { "amount": ["The amount field is required."], "currency": ["The selected currency is invalid."] } } ``` Deux classes d'erreurs ajoutent un champ à traiter explicitement. Un `422` contient `errors`, un objet indexé par nom de champ dont les valeurs sont des tableaux de messages : un champ peut donc échouer sur plusieurs règles à la fois ; un refus qui ne vise aucun champ précis range son message sous `errors.request`. Le `message` de premier niveau est le premier d'entre eux, suivi de `(and 1 more error)` s'il y en a d'autres. Une réponse bloquée par la limite de requêtes contient `retry_after`, le nombre de secondes à attendre, ce qui vous évite de deviner un délai. Un `409 Conflict` qui contient `errors.idempotency_key` signifie que vous avez réutilisé une `Idempotency-Key` dont la première requête est encore en cours : renvoyez-la un instant plus tard pour obtenir la réponse enregistrée. Une `reference` n'est jamais contrôlée pour son unicité : la réutiliser ne provoque aucun conflit. Les autres `409` disent que la ressource n'est pas dans un état qui permet l'appel. `payment_in_progress`, sur un débit ou une annulation, signifie qu'un débit est en cours : attendez son issue, par webhook ou en relisant le paiement, puis rappelez si besoin. Un paiement préparé déjà activé, annulé ou expiré, l'annulation d'un paiement dont des échéances ont été payées (`payment_partly_paid`), et quelques cas Sync et CLI décrits sur leurs pages ne changent pas en attendant : relisez la ressource, puis décidez. Un `404` vous indique quelle ressource manquait, `Payment Not Found` plutôt qu'un message générique : le champ `message` suffit donc pour aiguiller l'erreur sans examiner l'URL appelée. Le catalogue complet des codes se trouve dans la [référence API](https://docs.wajub.com/fr/api/errors). > [!WARNING] > **N'analysez pas le message** > > `message` est du texte libre, et il change. Basez vos décisions sur `code`, et sur les clés de > `errors` quand vous avez besoin du détail par champ. ## Statuts de paiement Le `status` d'une transaction prend l'une de neuf valeurs. Les transitions entre elles, et celles qui sont finales, sont décrites dans [Concepts clés](https://docs.wajub.com/fr/getting-started/concepts#payment-lifecycle). | Statut | Signification | | -------------------- | ----------------------------------------------------------------- | | `pending` | Créé, en attente d'une action du client. | | `processing` | Confirmé auprès du prestataire, règlement en cours. | | `succeeded` | Fonds reçus. Vous pouvez livrer la commande. | | `failed` | Refusé par le prestataire ou par le portefeuille. | | `cancelled` | Annulé par le client ou par vous. | | `expired` | La fenêtre de paiement s'est fermée avant la fin. | | `partial` | Une partie du montant a été capturée, sur un paiement fractionné. | | `refunded` | Entièrement remboursé après un succès. | | `partially_refunded` | Partiellement remboursé après un succès. | ## Identifiants Chaque objet porte un `id` construit de la même façon : un préfixe qui nomme le type, puis `test_` quand l'objet vit dans la sandbox, puis une chaîne aléatoire. Le préfixe vous dit ce que vous avez entre les mains sans rien consulter, et le segment `test_` empêche de confondre un identifiant sandbox avec un identifiant live dans un log ou un ticket de support. | Préfixe | Objet | Partie aléatoire | | ------- | ----------------- | ---------------- | | `trx_` | Paiement | 20 caractères | | `po_` | Transfert sortant | 20 caractères | | `rfd_` | Remboursement | 20 caractères | | `dsp_` | Litige | 20 caractères | | `ben_` | Bénéficiaire | 20 caractères | | `acc_` | Sous-compte Sync | 20 caractères | | `cus_` | Client | 24 caractères | | `evt_` | Événement webhook | 24 caractères | Ainsi, un paiement sandbox s'écrit `trx_test_CSUGajfv9xh0XQ5wu2lx` et son jumeau en production `trx_CSUGajfv9xh0XQ5wu2lx`. Stockez les identifiants en texte de longueur illimitée, jamais dans une colonne fixe de 24 ou 32 caractères. Les factures et les liens de paiement suivent leurs propres règles, listées dans [Concepts clés](https://docs.wajub.com/fr/getting-started/concepts#resource-identifiers). ## Dates Chaque horodatage est au format ISO 8601 en UTC, avec un décalage explicite plutôt qu'un suffixe `Z`. ```json title="Format des horodatages" "created_at": "2026-05-24T10:21:08+00:00" ``` Les deux écritures désignent le même instant et tout parseur ISO 8601 les gère. Mais si vous comparez des horodatages sous forme de chaînes, ce que vous ne devriez pas faire, c'est ce décalage que vous recevrez réellement. ## Montants Les montants sont exprimés dans l'unité principale de la devise. `5000` dans une réponse signifie 5 000 XAF, et non 50 XAF, soit l'inverse de ce que font la plupart des API de paiement. Le franc CFA n'a pas de subdivision utilisée au quotidien : une convention en unité mineure inventerait une coupure qui n'existe pas. Les valeurs reviennent sous forme de nombres arrondis à deux décimales. Ce que vous pouvez débiter est borné par devise : de 25 à 2 000 000 en XAF et XOF, à partir de 100 en NGN, à partir de 0,50 en USD et EUR. Un montant hors de ces bornes est refusé avec un `422` dont le message les indique. Lisez le champ `currency` avant tout calcul, car un même chiffre signifie des choses très différentes en XAF et en USD. --- # Concepts clés URL: https://docs.wajub.com/fr/getting-started/concepts > Cycle de vie d'un paiement, environnements, jetons de session, API keys et modèle d'orchestration. Avant d'écrire du code, prenez quelques minutes pour comprendre les concepts de base. Ensuite, chaque appel d'API et chaque événement webhook vous paraîtra clair tout de suite. ## Cycle de vie d'un paiement Un paiement est une conversation entre trois parties : votre serveur, Wajub et la personne qui paie. Chaque changement d'état vient de l'action de l'une d'elles. Le plus rapide pour comprendre le cycle de vie est donc de regarder qui fait quoi, et dans quel ordre. ### Le parcours d'un paiement réussi Six mouvements, dont deux seulement vous reviennent. Vous ouvrez le paiement, vous redirigez, puis vous attendez. Wajub choisit un prestataire, encaisse l'argent et vous dit comment tout s'est terminé. 1. Votre serveur → Wajub: Vous déclarez l'intention d'encaisser (`POST /payments`, `pending`) 2. Wajub → Client: Vous redirigez le payeur vers la page hébergée (`authorization_url`) 3. Client → Wajub: Le payeur choisit un opérateur et confirme sur son téléphone (`processing`) 4. Wajub → Wajub: Wajub route vers un prestataire et les fonds arrivent (`succeeded`) 5. Wajub → Votre serveur: Wajub livre l'événement à votre endpoint (`payment.succeeded`) 6. Votre serveur → Wajub: Vous vérifiez le résultat avant de livrer la commande (`GET /payments/{id}`) ### Quand le paiement n'aboutit pas Les trois mêmes parties, le même ordre, mais le paiement quitte le parcours idéal. Chaque sortie produit son propre événement : votre endpoint l'apprend exactement comme il apprend un succès. 1. Client → Wajub: Le payeur abandonne et la fenêtre se ferme (`expired`) 2. Client → Wajub: Le payeur annule, ou vous annulez vous-même le paiement (`cancelled`) 3. Wajub → Wajub: Le prestataire refuse le débit ou ne répond pas à temps (`failed`) 4. Wajub → Wajub: Seule une partie du montant est réglée, le reste est encore en cours (`partial`) 5. Wajub → Wajub: Le reste est réglé, le paiement aboutit donc quand même (`succeeded`) 6. Wajub → Votre serveur: Wajub livre l'événement correspondant (`payment.failed`) Quatre états mettent fin à la tentative : `succeeded`, `failed`, `cancelled` et `expired`. Rien de ce que fait le client ne fait sortir un paiement de ces états. `pending`, `processing` et `partial` sont encore en cours : traitez-les comme ouverts, jamais comme un échec. Deux choses peuvent encore bouger après la fin. Un prestataire qui confirme une charge en retard fait passer un paiement `failed`, `cancelled` ou `expired` à `succeeded`, puisque l'argent a été prélevé. Et un paiement `succeeded` peut encore afficher `refunded` ou `partially_refunded` des jours plus tard. | État | Signification | Action suivante | | -------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------- | | `pending` | Initialisé, en attente d'une action du client. | Redirigez le client vers la page de paiement. | | `processing` | Le prestataire traite le débit. | Attendez. Le webhook `payment.*` vous indique comment il se termine. | | `succeeded` | Fonds reçus. Vous pouvez livrer la commande. | Livrez le produit ou le service. | | `failed` | Refusé, sans réponse à temps, ou jamais transmis à un prestataire. | Affichez une erreur, proposez de réessayer. | | `cancelled` | Annulé par le client ou le marchand. | Aucune action nécessaire. | | `expired` | La fenêtre de paiement s'est fermée avant la fin. | Relancez le paiement si nécessaire. | | `partial` | Une partie du montant est réglée, le reste est encore en cours. | Gardez la commande ouverte. Elle peut encore atteindre `succeeded`. | | `refunded` | Un paiement réussi a été entièrement remboursé. | Gérez le retour. | | `partially_refunded` | Un remboursement partiel a été appliqué. | Suivez le montant restant. | ### Comment un paiement passe d'un état à l'autre 1. **Vous** appelez `POST /payments`, ce qui crée une transaction en `pending`. 2. **Le client** effectue le paiement sur la page hébergée (`pay.wajub.com`). 3. **Wajub** traite le débit avec le meilleur prestataire disponible (voir [Orchestration](https://docs.wajub.com/fr/orchestration)). 4. **Wajub** envoie un webhook `payment.succeeded` à votre serveur. 5. **Vous** vérifiez le statut via `GET /payments/{id}` et livrez la commande. C'est à l'étape 4 que la machine à états vous atteint. Chaque transition enregistrée par Wajub émet un événement, et un événement livré à votre endpoint ressemble à ceci. Le type se trouve dans `event`, et `data` contient le paiement exactement tel que `GET /payments/{id}` le renverrait : ```json title="payment.succeeded" { "id": "evt_test_aio5DpN577tNU2vOxdmu", "event": "payment.succeeded", "data": { "id": "trx_test_CSUGajfv9xh0XQ5wu2lx", "amount": 5000, "amount_paid": 5000, "currency": "XAF", "status": "succeeded", "channel": "cm.mtn", "customer": { "id": "cus_test_sAaim5apjocIgtlhzJY3", "email": "amina@example.com" }, "sandbox": true, "created_at": "2026-09-11T10:24:00+00:00" }, "livemode": false, "pending_webhooks": 1, "api_version": "2026-10-11", "request": { "id": null, "idempotency_key": "idem_4kQ9xL2mR7vB5nW8tY3cZ6hJ1dF0sGaP" }, "created": "2026-09-11T10:26:13+00:00" } ``` ## Sandbox ou live Wajub fournit deux environnements entièrement isolés. Une seule URL de base sert les deux. L'environnement est déterminé par l'API key que vous utilisez. | | Sandbox | Live | | ------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | **Clés** | `pk_test.…` / `sk_test.…` | `pk.…` / `sk.…` | | **Argent** | Aucun mouvement de fonds réel | Paiements réels | | **Données de test** | [Numéros de téléphone de test](https://docs.wajub.com/fr/getting-started/quickstart#4-pay-it-with-a-sandbox-number) | Données clients réelles | | **Périmètre** | Paiements, remboursements, transferts, clients, webhooks | Tout, y compris les liens, les factures, les taxes et Shield | > [!WARNING] > **Ne mélangez jamais les environnements** > > Une clé sandbox ne peut pas accéder aux données live, et inversement. Stockez les clés dans des > variables d'environnement distinctes pour chaque environnement. ## API keys Trois types de clés, chacun avec un rôle précis : - `Clé publique (pk.… / pk_test.…)` (sûre côté client): Initialisez des paiements depuis le navigateur ou l'application mobile. N'a pas accès aux opérations sensibles. - `Clé privée (sk.… / sk_test.…)` (serveur uniquement): Accès complet à l'API : paiements, transferts, remboursements, solde. Ne doit jamais quitter votre backend. - `Clé restreinte (rk.… / rk_test.…)` (serveur uniquement): Limitée à des ressources précises (par ex. payment.read). Idéale pour les intégrations tierces ou les services à privilèges minimaux. > [!CAUTION] > **Les clés privées sont bloquées dans les navigateurs** > > N'utilisez jamais une clé privée `sk` depuis un navigateur ou une application mobile. Lorsque > Wajub détecte une clé privée utilisée depuis un navigateur, il refuse la requête et vous prévient > par e-mail. C'est un filet de sécurité, pas une garantie. Stockez `sk.…` dans des variables > d'environnement. Jamais dans du code côté client. ## Jetons de session `POST /payments` renvoie un **jeton de session**, `authorization_token`, déjà inclus dans l'`authorization_url` vers laquelle vous redirigez. Le jeton est limité à un seul paiement, il ne peut rien faire d'autre que payer ce paiement, et vous pouvez le confier sans risque à un navigateur. Sa durée de vie suit celle du paiement. La fenêtre de paiement est de 24 heures par défaut, ajustable de 5 minutes à 30 jours avec `expires.in`. Vous ne manipulez le jeton vous-même que si vous intégrez le checkout dans votre propre page au lieu de rediriger. Votre serveur crée le paiement comme d'habitude : ```typescript title="Serveur, créer le paiement" import { Wajub } from '@wajub/node'; const wajub = new Wajub({ apiKey: process.env.WAJUB_API_KEY! }); const payment = await wajub.payments.create({ amount: 5000, currency: 'XAF', customer: { email: 'amina@example.com' }, }); // Send payment.authorization_token to your frontend. ``` Votre frontend transmet ce jeton au SDK navigateur, qui est un package différent et ne voit jamais votre API key : ```typescript title="Navigateur, afficher le checkout" import { mount } from '@wajub/js'; await mount('#checkout', { sessionId: authorizationToken }); ``` Consultez [Wajub Components](https://docs.wajub.com/fr/libraries/components) pour le checkout intégré complet. ## Modèle d'orchestration Wajub route chaque paiement vers un prestataire selon le canal, le pays, le montant et vos règles de routage, et se replie sur le suivant si le premier échoue. Il vous suffit de créer un paiement et d'écouter le webhook. > [!TIP] > **Consultez chaque décision de routage** > > Une fois en live, ouvrez [Konsole → Journal de routage](https://docs.wajub.com/fr/developer-tools/konsole/routing-log) pour voir la > décision de routage et les prestataires essayés pour chaque paiement. Il n'existe pas en sandbox. ## Identifiants de ressources Chaque identifiant de ressource se compose d'un préfixe, puis de `test_` quand l'objet vit dans la sandbox, puis de 20 à 24 caractères aléatoires selon la ressource. Un identifiant vous indique donc deux choses d'un coup d'œil : ce qu'il désigne, et quel environnement l'a produit. Stockez les identifiants en texte, avec de la place pour 40 caractères. | Préfixe | Ressource | Live | Sandbox | | ------- | ----------------------- | ------------------------------ | ----------------------------------- | | `trx_` | Transaction de paiement | `trx_CSUGajfv9xh0XQ5wu2lx` | `trx_test_CSUGajfv9xh0XQ5wu2lx` | | `po_` | Transfert (payout) | `po_225KMKULRQqYvlhrgUOE` | `po_test_225KMKULRQqYvlhrgUOE` | | `rfd_` | Remboursement | `rfd_9xh0XQ5wu2lxCSUGajfv` | `rfd_test_9xh0XQ5wu2lxCSUGajfv` | | `ben_` | Bénéficiaire | `ben_LRQqYvlhrgUOE225KMKU` | `ben_test_LRQqYvlhrgUOE225KMKU` | | `dsp_` | Litige | `dsp_hrgUOE225KMKULRQqYvlh` | `dsp_test_hrgUOE225KMKULRQqYvlh` | | `pm_` | Moyen de paiement | `pm_sAaim5apjocIgtlhzJY3x` | `pm_test_sAaim5apjocIgtlhzJY3x` | | `cus_` | Client | `cus_sAaim5apjocIgtlhzJY3wQ8s` | `cus_test_sAaim5apjocIgtlhzJY3wQ8s` | | `evt_` | Événement webhook | `evt_aio5DpN577tNU2vOxdmuZGhT` | `evt_test_aio5DpN577tNU2vOxdmuZGhT` | Trois ressources suivent leur propre règle. Une facture commence toujours par `inv_`, sans segment d'environnement. Un lien de paiement n'a aucun préfixe : son identifiant fait neuf caractères, comme `kQ7vB4nL6`, car c'est aussi l'URL publique que reçoivent les gens. Un message de litige est un UUID. > [!TIP] > **Servez-vous du préfixe comme garde-fou** > > Un identifiant `test_` qui arrive dans votre base de données de production est un bug de > configuration, pas un paiement. Vérifier le préfixe avant de livrer une commande repère une API key > mal choisie bien avant votre comptable. ## Montants Contrairement à beaucoup de prestataires de paiement, Wajub exprime les montants dans l'**unité principale** de la devise (par ex. `5000` = 5 000 XAF, et non 500 000 centimes). Les devises en franc CFA n'ont pas de subdivision courante, ce qui évite toute confusion. ## « Paiement » ou « transaction » Wajub utilise les deux termes, et ils désignent le même objet : - **Paiement**. Le concept métier. Vous créez un paiement, un client paie, vous livrez la commande. - **Transaction**. Le nom que l'API donne à l'objet paiement. La réponse de l'API utilise `"transaction": {...}` comme clé racine, et le champ `id` est préfixé par `trx_`. En pratique : vous appelez `POST /payments`, recevez `transaction.id = "trx_xxx"`, et écoutez les webhooks `payment.succeeded`. Dans cette documentation, les deux termes sont interchangeables. ## Étapes suivantes - [Démarrage rapide](https://docs.wajub.com/fr/getting-started/quickstart) : codez votre premier paiement. - [Orchestration](https://docs.wajub.com/fr/orchestration) : le fonctionnement du routage et du repli. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks/quickstart) : recevez `payment.succeeded` de manière fiable. --- # Configurer votre compte URL: https://docs.wajub.com/fr/getting-started/dashboard-setup > Créez votre compte, générez une API key dans le bon environnement et branchez-la dans votre SDK. Chaque appel à l'API Wajub est authentifié par une clé, et une clé appartient à un compte et à un environnement. Cette page vous emmène de l'absence de compte à un SDK qui s'authentifie, soit l'état dans lequel le [démarrage rapide](https://docs.wajub.com/fr/getting-started/quickstart) suppose que vous êtes déjà. ## 1. Créez votre compte Inscrivez-vous sur **[dashboard.wajub.com](https://dashboard.wajub.com)** avec votre nom, votre email et un mot de passe, puis confirmez l'email que nous vous envoyons. Rien n'est payant à ce stade : un nouveau compte démarre sur le plan gratuit **Pay as you go**. Votre compte utilisateur vient d'abord, votre activité ensuite. Juste après la confirmation de votre email, le Dashboard vous demande de créer votre premier compte marchand, sur un écran intitulé **Parlez-nous de votre activité** : | Champ | Obligatoire | À quoi il sert | | ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- | | Nom du marchand | Oui | Le nom de votre entreprise, de votre projet ou de votre application. | | E-mail professionnel | Non | Imprimé sur les factures et les emails que reçoivent vos clients. Votre propre email est utilisé si vous le laissez vide. | | Téléphone de l'entreprise | Non | Affiché à vos clients à côté de cet email, pour qu'ils puissent vous joindre. | Vous êtes le propriétaire de ce compte. Le Dashboard reste sur cet écran tant qu'il n'existe pas, et vous pourrez créer d'autres comptes marchands plus tard avec le même utilisateur. Votre équipe est créée en **sandbox**, et elle y reste tant que la vérification de votre activité n'est pas approuvée. Rien de ce que vous faites maintenant ne peut déplacer de l'argent réel, et c'est tout l'intérêt : construisez et cassez librement avant que l'[activation](https://docs.wajub.com/fr/getting-started/account-activation) n'ouvre la production. L'accueil du Dashboard affiche une checklist de configuration adaptée à ce que vous avez dit vouloir construire. Elle suit les mêmes étapes que cette page, vous pouvez donc suivre l'une ou l'autre. ## 2. Choisissez l'environnement avant de générer une clé C'est l'étape que tout le monde saute. Une clé est générée pour l'environnement que le Dashboard affiche à ce moment-là. Basculez **d'abord** l'environnement sur **Test** ou sur **Production**, puis créez la clé. Créée dans le mauvais environnement, elle s'authentifiera sans problème tout en renvoyant les données d'un environnement auquel vous ne vouliez pas toucher. Le live reste indisponible tant que votre compte n'est pas vérifié : d'ici là, chaque clé que vous créez est une clé `_test`, quoi que vous fassiez. Changer d'environnement est en soi une permission. Le propriétaire du compte peut toujours le faire, les autres membres ont besoin d'un rôle qui le permet, **Administrator** ou **Developer** par défaut, et un membre au rôle **Sandbox User** ne peut jamais passer en live. ## 3. Créez votre première API key Ouvrez **Paramètres → Développeurs → Clés API** et créez une clé. Vous choisissez le type, et le préfixe découle de ce choix et de l'environnement sélectionné à l'étape 2. | Type | Préfixe sandbox | Préfixe production | À utiliser pour | | ---------- | --------------- | ------------------ | -------------------------------------------------------------------------------------------- | | Publique | `pk_test.` | `pk.` | Le code navigateur et mobile, pour créer un paiement. La détenir n'est pas une autorisation. | | Privée | `sk_test.` | `sk.` | Votre serveur. Accès complet à l'API. | | Restreinte | `rk_test.` | `rk.` | Votre serveur, limité aux scopes que vous accordez. | Commencez par une clé privée. Une clé restreinte vaut l'étape supplémentaire une fois que vous savez quels endpoints vous appelez réellement, et [Environnements et API keys](https://docs.wajub.com/fr/getting-started/environments) détaille les scopes, la liste d'IP autorisées et la date d'expiration que vous pouvez associer à chacune d'elles. > [!CAUTION] > **Copiez la valeur tout de suite** > > La valeur complète apparaît dans le bandeau juste après la création. Copiez-la dans votre > gestionnaire de secrets avant de quitter la page. La liste des clés n'en montre ensuite que les > premiers caractères. Vous pouvez afficher de nouveau une clé privée ou restreinte avec **Afficher**, > qui vous demande un code de vérification de sécurité, est limité en fréquence et est inscrit au > journal d'audit. Une clé publique reste copiable depuis la liste. Si vous avez installé la [CLI](https://docs.wajub.com/fr/developer-tools/cli/installation), `wajub login` le fait pour vous : la commande associe le terminal à votre compte via le navigateur, et le propriétaire, un Administrator ou un Developer (un Sandbox User aussi, pour une clé sandbox) approuve la demande et choisit l'environnement, Sandbox sauf s'il choisit Live. La CLI enregistre la clé dans un profil local. Cette clé expire au bout de 90 jours, et `wajub login` vous en donne une nouvelle. **Connexion avec Wajub**, dans le plugin WordPress, demande une clé de la même façon, et cette clé dure 90 jours sauf si la personne qui approuve choisit **Durée indéterminée**. Chaque clé créée par un appairage envoie un e-mail au propriétaire et à chaque Administrator. ## 4. Placez la clé dans votre environnement Les clés vont dans l'environnement, jamais dans le code et jamais dans le dépôt. Créez un fichier `.env` à la racine de votre projet et gardez-le hors de git. ```bash title=".env" WAJUB_API_KEY=sk_test.xxxxxxxxxxxxxxxx… WAJUB_WEBHOOK_SECRET=whsec_test_xxxxxxxxxxxxxxxx ``` `WAJUB_API_KEY` est le nom que tous les SDK reconnaissent : utilisez-le plutôt que d'inventer le vôtre. `WAJUB_WEBHOOK_SECRET` est le secret de signature d'un endpoint de webhook, un identifiant complètement différent, et c'est à l'étape 6 que vous en obtenez un. ## 5. Branchez la clé dans le SDK Deux des SDK lisent `WAJUB_API_KEY` dans l'environnement d'eux-mêmes. Python et Go construisent un client fonctionnel à partir d'une configuration vide, c'est pourquoi les exemples ci-dessous ne passent rien. Node et PHP ne lisent pas l'environnement et lèvent une erreur si la configuration est vide : vous leur passez donc la valeur vous-même. **Authentifier le SDK** ```javascript import { Wajub } from '@wajub/node'; const wajub = new Wajub({ apiKey: process.env.WAJUB_API_KEY }); ``` ```python from wajub import Wajub wajub = Wajub() ``` ```php getenv('WAJUB_API_KEY'), ]); ``` ```go package main import ( "log" "github.com/wajubhq/wajub-go" ) func main() { client, err := wajub.New(wajub.Config{}) if err != nil { log.Fatal(err) } _ = client } ``` Quel que soit votre SDK, les quatre lisent `WAJUB_WEBHOOK_SECRET` d'eux-mêmes pour vérifier les signatures : une fois cette variable définie, vous ne passez jamais le secret explicitement. ## 6. Enregistrez un endpoint de webhook Un paiement se confirme de façon asynchrone : votre serveur apprend donc le résultat par un webhook, et non par la réponse à l'appel qui l'a créé. Enregistrez l'endpoint maintenant, pendant que vous êtes dans le Dashboard, pour que le [démarrage rapide](https://docs.wajub.com/fr/getting-started/quickstart) ait une adresse où livrer. Ouvrez **Konsole → Webhooks → Points de terminaison**, ajoutez votre URL et copiez le secret de signature affiché sur l'endpoint. Il ressemble à `whsec_test_` suivi de 32 caractères en sandbox, et à `whsec_` suivi de 32 caractères en production. Ce secret est propre à chaque endpoint et à chaque environnement. Enregistrer à nouveau la même URL en live vous donne un secret différent : c'est pourquoi passer en production implique de copier un nouveau secret plutôt que de réutiliser celui que vous avez. Utilisez-le pour [vérifier chaque signature entrante](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification) avant de faire confiance à un payload. ## 7. Renouvelez une clé qui a fuité Le renouvellement remplace la valeur sur place. Le nom, les scopes et la liste d'IP autorisées sont conservés, l'ancienne valeur cesse de s'authentifier dès que vous confirmez, et il n'existe aucune période de grâce pendant laquelle les deux fonctionnent. Ayez donc la nouvelle valeur prête à déployer avant de cliquer, sinon vous subissez une interruption entre le renouvellement et la mise en production. Comme cette action est destructive, le renouvellement demande un code de vérification de sécurité si vous n'en avez pas saisi un récemment. La suppression d'une clé demande la même chose. ## 8. Qui peut le faire dans votre équipe Les API keys ne sont visibles que par le propriétaire du compte et par les membres qui ont la permission de gérer les API keys, que portent les rôles **Administrator**, **Developer** et **Sandbox User**. Les autres membres trouvent quand même **Paramètres → Développeurs → Clés API** dans le menu, mais la page répond « Vous n'avez pas la permission requise pour effectuer cette action. » : demandez à un admin de changer votre rôle. Le [tableau des rôles](https://docs.wajub.com/fr/dashboard#roles) du guide du tableau de bord liste ce que chaque rôle peut faire. ## 9. Quand la production s'ouvre Les comptes vérifiés obtiennent leurs clés live de la même façon, en changeant d'environnement et en créant une clé. Les clés live sont des objets distincts : une clé sandbox n'est jamais promue. Prévoyez de remplacer ensemble la clé, l'URL du webhook et son nouveau secret de signature, et déroulez la [checklist pour passer en live](https://docs.wajub.com/fr/getting-started/going-live) avant de le faire. - [Démarrage rapide](https://docs.wajub.com/fr/getting-started/quickstart): Votre premier paiement, avec la clé que vous venez de créer. - [Environnements et API keys](https://docs.wajub.com/fr/getting-started/environments): Formats de clés, scopes, listes d'IP autorisées, expiration. - [Activation du compte et KYC](https://docs.wajub.com/fr/getting-started/account-activation): Les documents qui débloquent la production. - [Bonnes pratiques de sécurité](https://docs.wajub.com/fr/best-practices/security): Stocker, renouveler et restreindre les identifiants. --- # Environnements et API keys URL: https://docs.wajub.com/fr/getting-started/environments > Comprendre les modes test et production, le format des clés et comment basculer sans risque. Wajub fait tourner deux environnements isolés derrière une seule API, avec la même URL de base, les mêmes endpoints et les mêmes payloads. C'est la clé que vous envoyez qui décide auquel vous vous adressez : changer d'environnement revient à changer d'identifiant, jamais à réécrire du code. ```bash title="URL de base (test et production)" https://api.wajub.com ``` ## Sandbox La sandbox est l'endroit où vous développez. Les opérateurs Mobile Money y sont simulés par des [numéros de test](https://docs.wajub.com/fr/getting-started/quickstart#4-pay-it-with-a-sandbox-number) dont les six derniers chiffres décident du résultat, les webhooks se déclenchent exactement comme en production, et aucun argent ne circule jamais. Elle ne partage aucune donnée avec le mode live, si bien qu'un client, un paiement ou un événement sandbox n'apparaît jamais dans votre compte live. Les clés sont `pk_test.…` et `sk_test.…`, et chaque objet créé dans la sandbox porte `test_` dans son id. ## Production La production déplace de l'argent réel. Elle s'ouvre une fois la vérification de votre entreprise approuvée : consultez [Activation du compte et KYC](https://docs.wajub.com/fr/getting-started/account-activation) pour les documents et les délais. Les clés sont `pk.…` et `sk.…`. Dans le Dashboard, chaque membre travaille dans un environnement à la fois : le guide du tableau de bord montre [comment passer en Production](https://docs.wajub.com/dashboard/getting-started/test-and-live) et ce qui y change. ## Ce que la sandbox ne couvre pas La sandbox reproduit fidèlement le parcours de paiement, mais cinq fonctionnalités n'existent qu'en live. Les appeler avec une clé de test renvoie `403` avec `This feature is only available in live mode.` | Fonctionnalité | Endpoints | Sandbox | | -------------------------------------------------------- | ----------------------------------- | --------------- | | Liens de paiement | `/links` | Live uniquement | | Factures | `/invoices` | Live uniquement | | Taxes | `/tax` et `/customers/{id}/tax_ids` | Live uniquement | | Shield | `/shield` | Live uniquement | | Paiements, remboursements, transferts, clients, webhooks | | Disponible | Une autre différence joue en sens inverse : la page de paiement sandbox propose toujours une carte de test pour que vous puissiez tester ce parcours de code, alors que la page live ne propose que les canaux couverts par vos prestataires actifs. Une carte n'y apparaît qu'une fois un prestataire qui accepte les cartes activé sur votre compte. Développez d'abord avec Mobile Money. ## Types de clés | Type | Préfixe | Où elle s'exécute | Ce qu'elle peut faire | | ---------- | ------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Publique | `pk.` / `pk_test.` | Navigateur, application mobile | Créer un paiement depuis la page. La détenir n'est pas une autorisation : voir [les endpoints qui l'acceptent](https://docs.wajub.com/fr/api/authentication#the-three-key-types). | | Privée | `sk.` / `sk_test.` | Votre serveur uniquement | Tout : paiements, remboursements, transferts, solde. | | Restreinte | `rk.` / `rk_test.` | Votre serveur uniquement | Uniquement les scopes que vous lui accordez, une ressource à la fois. | Une clé se compose d'un préfixe, d'un point, puis d'une longue partie secrète aléatoire. Stockez les clés en texte, jamais dans une colonne de longueur fixe de 32 ou 64 caractères. ```bash title="Format d'une clé" sk_test.xxxxxxxxxxxxxxxx… # prefix "sk_test", a dot, then the random secret ``` > [!CAUTION] > **Ne commitez jamais une clé privée** > > Gardez `sk.…` dans des variables d'environnement ou un gestionnaire de secrets. Si une clé fuite, > révoquez-la depuis **Paramètres → Développeurs → Clés API** dans le Dashboard. La rotation d'une clé génère > immédiatement une nouvelle valeur, et l'ancienne cesse de fonctionner dès la requête suivante. ## Limiter ce qu'une clé peut faire Trois contrôles existent sur chaque clé, et les activer ne coûte rien. **Des scopes, sur les clés restreintes.** Une clé restreinte porte une liste explicite de permissions `{resource}.{read|write}` : `payment.read`, `payment.write`, `customer.read`, `transfer.write`, `refund.write`, `recipient.*`, `invoice.*`, `dispute.*`, `webhook.*`, `event.*`, `link.*`, `identity.*`, `tax.*`, plus `balance.read` et `account.read` en lecture seule. Tout ce qui sort de la liste renvoie `403`. Il n'existe pas de `balance.write`, mais `transfer.write` suffit pour envoyer des payouts avec `POST /transfers` : ne l'accordez qu'à une clé dont le rôle est de payer quelqu'un. **Une liste d'IP autorisées.** Chaque clé accepte une liste d'adresses IPv4 ou IPv6 exactes, ou de plages CIDR de l'une ou l'autre famille, comme `203.0.113.0/24` ou `2001:db8::/32`. Vous la saisissez à la création de la clé, et vous pouvez la modifier ensuite, quel que soit le type de clé. Une requête venant de n'importe où ailleurs est refusée avec `403 IP address not allowed for this API key`, quel que soit le type de clé. Une clé qui ne fonctionne que depuis vos serveurs de production ne vaut rien dans un dépôt divulgué. **Une date d'expiration.** Une clé peut porter `expires_at`. Passé ce moment, elle n'authentifie plus rien. Utilisez-la pour un sous-traitant, un script de migration ou toute intégration que vous savez temporaire. Vous la fixez à la création de la clé, vous la changez ou la retirez ensuite, quel que soit le type de clé, et elle s'affiche à côté de la clé dans la liste : **Expire le …**, ou **Expirée le …** une fois la date passée. Une clé sans expiration n'affiche aucune date. Modifier autre chose sur une clé laisse son expiration telle qu'elle était. Une clé créée en approuvant un appairage, `wajub login` ou une application comme le plugin WordPress, expire au bout de 90 jours, sauf si la personne qui approuve choisit **Durée indéterminée**, ce que la page d'approbation ne propose jamais pour la CLI. ## Variables d'environnement Trois noms suffisent pour une intégration serveur. Gardez-les dans l'environnement plutôt que dans le code, et nommez-les exactement ainsi : les SDKs cherchent ces noms et aucun autre. ```bash title=".env" WAJUB_API_KEY=sk_test.xxxxxxxxxxxxxxxx… WAJUB_WEBHOOK_SECRET=whsec_test_xxxxxxxxxxxxxxxx WAJUB_PUBLIC_KEY=pk_test.xxxxxxxxxxxxxxxx… ``` `WAJUB_API_KEY` est l'identifiant d'authentification. Les SDKs Python et Go la lisent eux-mêmes dans l'environnement, si bien qu'une configuration vide vous donne un client qui fonctionne. Les SDKs Node et PHP ne le font pas : ils lèvent une erreur sur une configuration vide et attendent que vous passiez la valeur. Consultez [Configurer votre compte](https://docs.wajub.com/fr/getting-started/dashboard-setup#5-point-the-sdk-at-the-key) pour la forme exacte dans chaque langage. `WAJUB_WEBHOOK_SECRET` est la seule que les quatre lisent automatiquement. Définissez-la et la vérification de signature fonctionne sans que vous ayez à passer le secret nulle part. `WAJUB_PUBLIC_KEY` n'est lue par aucun SDK. Elle sert à votre propre code frontend, et seulement si votre navigateur ou votre client mobile initialise lui-même les paiements. Les valeurs de production ont leur place dans votre gestionnaire de secrets, jamais dans un fichier commité. La configuration la plus sûre sépare les variables de sandbox et de production, pour que la mise en production de votre code n'oblige jamais à modifier une clé à la main. ## Passer en production 1. Finalisez la vérification de votre entreprise dans le Dashboard. Consultez [Activation du compte et KYC](https://docs.wajub.com/fr/getting-started/account-activation) pour les documents requis et les délais d'examen. 2. Créez des clés de production. Les clés sandbox ne peuvent pas être promues, ce sont des objets distincts. 3. Faites pointer vos endpoints de webhook vers leurs URLs de production et copiez le nouveau secret de signature : il diffère selon l'environnement. 4. Testez à nouveau les fonctionnalités marquées « Live uniquement » dans le tableau ci-dessus. C'est la première fois que votre code s'exécute avec elles. 5. Suivez le guide [Passer en live](https://docs.wajub.com/fr/getting-started/going-live) pour la checklist complète. --- # Passer en live URL: https://docs.wajub.com/fr/getting-started/going-live > La checklist à dérouler avant de changer de clés, et ce qui change en production. Passer en production tient en une ligne de configuration. Tout ce qui rend ce passage sûr se fait avant de modifier cette ligne, et c'est l'objet de cette page : une checklist que vous pouvez vraiment cocher, puis la liste de ce qui se comporte différemment en production et qui n'a pas pu être testé dans la sandbox. ## Avant tout, faites vérifier votre compte La production s'ouvre quand votre dossier de conformité est approuvé, et pas une minute plus tôt. D'ici là, votre équipe reste en sandbox : le Dashboard refuse de passer en live et `wajub login` refuse un profil live, si bien qu'aucune clé live ne peut être créée. [Activation du compte et KYC](https://docs.wajub.com/fr/getting-started/account-activation) détaille le dossier et l'examen. Soumettez-le tôt. L'examen prend jusqu'à 48 heures, et votre intégration sandbox continue de fonctionner pendant ce temps. L'ordre logique est donc de déposer le dossier d'abord, puis de dérouler le reste de cette page pendant qu'il est examiné. ## Puis activez un moyen d'encaissement L'approbation du dossier ouvre la production, mais ne branche aucun moyen de paiement. Tant qu'aucun fournisseur n'est actif en production, la page de paiement n'en propose aucun et vos payeurs ne peuvent pas payer, même avec une intégration parfaite. Deux voies, depuis **Orchestration** dans le Dashboard, en Production : - [connecter votre propre fournisseur](https://docs.wajub.com/dashboard/orchestration/connect-provider), avec vos identifiants de production : il encaisse dès qu'il est connecté ; - [demander le rail Wajub](https://docs.wajub.com/dashboard/orchestration/rail), si vous n'avez pas de contrat à vous, pour encaisser sur ceux de Wajub. C'est une demande signée, que Wajub examine : faites-la dès que la production s'ouvre. Tant que rien n'est actif, l'accueil du Dashboard affiche **Activez vos moyens de paiement**. ## La checklist Cochez ces points dans votre propre environnement. Chaque élément se vérifie en exécutant du code, pas en faisant confiance. Votre progression est conservée dans ce navigateur : vous pouvez y revenir. ## Ce qui change une fois en live C'est la partie qu'une sandbox ne peut pas vous apprendre : lisez-la avant de basculer, pas après. **Cinq fonctionnalités ne vous ont jamais été accessibles.** Les liens de paiement, les factures, les taxes, Shield et les identifiants fiscaux des clients refusent tous les clés sandbox avec `403 This feature is only available in live mode.` Si votre intégration utilise l'une d'elles, ce code s'exécute pour la première fois en production. Prévoyez une répétition ciblée sur ces parcours précisément. **Votre limite de requêtes dépend de votre offre, pas de votre environnement.** Pay as you go autorise 120 requêtes par minute, Growth 360, Scale 720, et Enterprise n'a pas de plafond. Sur une offre sans plafond, les en-têtes `X-RateLimit-*` sont totalement absents : tout code qui les lit doit traiter leur absence comme normale, et non comme un zéro. **Le secret de signature des webhooks est différent.** Il appartient à un endpoint, et un endpoint appartient à un seul environnement. Enregistrer la même URL en production vous donne une nouvelle valeur `whsec_`. Recopier celle de la sandbox est la raison la plus fréquente pour laquelle un premier webhook live échoue à la vérification de signature. **Les identifiants perdent leur segment `test_`.** Un paiement sandbox est `trx_test_…` et son équivalent en production est `trx_…`. Rien dans votre code ne doit dépendre de ce segment, et tout ce qui reconnaît des identifiants par motif doit être vérifié une fois avant de basculer. **L'argent peut vraiment manquer.** Un payout échoue sur un solde insuffisant, un portefeuille a son propre plafond journalier inférieur au vôtre, et un client peut tout simplement ne pas confirmer. Rien de tout cela n'arrive dans une sandbox, où le résultat dépend du numéro de test que vous avez composé. ## Faire la bascule Faites ces quatre étapes dans un seul déploiement plutôt que sur tout un après-midi. Une intégration à moitié basculée envoie des paiements live vers un webhook sandbox, et vous ne le remarquerez qu'au rapprochement. 1. Enregistrez vos endpoints de webhook de production et copiez chaque nouveau secret de signature. 2. Placez la clé de production et ces secrets dans votre environnement de production. 3. Déployez. Le SDK ne demande aucun autre changement, la clé seule détermine l'environnement. 4. Vérifiez dans Konsole que votre première requête de production a bien été authentifiée en live. > [!CAUTION] > **Ne mélangez jamais un environnement avec l'autre** > > Un identifiant sandbox n'existe pas en production, et l'inverse est tout aussi vrai. Gardez les deux > jeux de variables entièrement séparés, et ne laissez jamais un repli de votre configuration se > rabattre discrètement sur la clé de test quand la clé live manque. Dans ce cas, échouer bruyamment > est le bon comportement. ## Votre premier vrai paiement Payez-vous vous-même. Prenez le plus petit montant accepté par votre opérateur, en général 100 XAF, et déroulez tout le parcours avec votre propre téléphone. Quatre conditions doivent être réunies avant d'ouvrir les portes. La transaction atteint `succeeded`. Votre endpoint de production a reçu `payment.succeeded` et la signature a été vérifiée. Le montant apparaît dans votre solde. Et votre propre base de données a enregistré la commande comme payée, par le même chemin de code que celui qu'un client déclencherait. Ensuite, remboursez-le. Le remboursement est le seul parcours que personne ne teste avant d'en avoir besoin, et le jour où l'on en a besoin n'est jamais un jour calme. ## En cas de problème Revenir en arrière consiste à redéployer votre clé sandbox. Aucune donnée n'est perdue et rien n'est à annuler côté Wajub, car les deux environnements n'ont jamais rien partagé. Les paiements déjà encaissés restent où ils sont, et vous pouvez tous les inspecter dans Konsole pendant que vous réparez ce qui a cassé. - [Activation du compte et KYC](https://docs.wajub.com/fr/getting-started/account-activation): Le dossier qui ouvre la production. - [Vérifier les signatures de webhook](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification): Le contrôle qui doit réussir dès la première livraison live. - [Bonnes pratiques de sécurité](https://docs.wajub.com/fr/best-practices/security): Stocker, restreindre et renouveler vos clés et secrets. - [Supervision et observabilité](https://docs.wajub.com/fr/resources/monitoring): Ce qu'il faut surveiller une fois que de l'argent réel circule. --- # Introduction URL: https://docs.wajub.com/fr/getting-started > L'orchestrateur de paiement qui réunit Mobile Money, cartes et virements derrière une seule API. Wajub est une **plateforme d'orchestration de paiement** pensée pour l'Afrique. Au lieu d'intégrer séparément chaque opérateur Mobile Money, chaque banque ou chaque agrégateur, vous intégrez **une seule API** et un seul jeu de webhooks. > [!NOTE] > **Vous découvrez les paiements en Afrique ?** > > Des termes comme Mobile Money, USSD, MTN MoMo, Orange Money, canal ou règlement vous sont peut-être > inconnus. Lisez d'abord le [Glossaire](https://docs.wajub.com/fr/resources/glossary). Il définit chaque terme en langage simple, > avant que vous n'écriviez la moindre ligne de code. ## Avant de commencer Pour suivre les exemples de ce site, il vous faut trois choses. 1. **Un compte Wajub.** Créez-en un gratuitement sur [dashboard.wajub.com](https://dashboard.wajub.com). 2. **Une API key.** Une fois connecté, ouvrez **Paramètres → Développeurs → Clés API** et créez-en une. 3. **Un client HTTP**, curl, ou un SDK serveur (Node.js, Python, PHP, Go, Ruby, Java, C#). Un nouveau compte ne possède aucune clé. Vous créez celles dont vous avez besoin, une par une, dans l'environnement affiché par le Dashboard. Les clés de production ne peuvent être créées qu'une fois votre compte vérifié. | Clé | Environnement | Où l'utiliser | | ----------- | ------------- | ------------------------------------------------------------------------------- | | `pk_test.…` | Sandbox | Publique. Sans risque dans un navigateur, initialise les paiements côté client. | | `sk_test.…` | Sandbox | Privée. Côté serveur uniquement, aucun argent réel ne circule. | | `rk_test.…` | Sandbox | Restreinte. Côté serveur uniquement, limitée aux scopes que vous lui accordez. | | `pk.…` | Production | Publique. Même rôle côté client, sur des fonds réels. | | `sk.…` | Production | Privée. Côté serveur uniquement, déplace de l'argent réel. | | `rk.…` | Production | Restreinte. Côté serveur uniquement, sur des fonds réels. | Consultez [Configurer votre compte](https://docs.wajub.com/fr/getting-started/dashboard-setup) pour une visite guidée du Dashboard, étape par étape. ## Ce que vous pouvez construire - **Encaissez** des paiements par Mobile Money (MTN MoMo, Orange Money, Wave, Airtel), carte et virement bancaire. - **Versez** des fonds sur des portefeuilles Mobile Money via l'[API des transferts](https://docs.wajub.com/fr/payouts/transfers) ou gérez vos [bénéficiaires](https://docs.wajub.com/fr/api/beneficiaries). - **Intégrez le checkout** directement dans votre application avec [Wajub Components](https://docs.wajub.com/fr/libraries/components), en React, Vue, Svelte, Angular ou JS natif. - **Orchestrez** intelligemment vos prestataires grâce au routage et au repli ([Orchestration](https://docs.wajub.com/fr/orchestration)). ## Comment fonctionne l'API L'API Wajub suit les principes REST. Elle utilise des URLs prévisibles, accepte des corps de requête encodés en JSON, renvoie des réponses JSON et s'appuie sur les codes HTTP standard. Toutes les requêtes passent par une seule URL de base : ```bash title="URL de base" https://api.wajub.com ``` ## Votre premier appel Un paiement commence par une requête. Vous envoyez le montant, la devise, la personne qui paie et la page vers laquelle la renvoyer une fois qu'elle a terminé. Wajub crée le paiement, le garde en `pending` et répond avec une page hébergée où le client choisit son opérateur et confirme. Personne n'est débité à ce stade. Décrivez le payeur dans l'objet `customer` : il porte `email`, `name`, `phone`, `address` et `metadata`. Le `callback` est l'adresse où Wajub renvoie le client une fois qu'il a terminé sur la page de paiement. Lancez cet appel depuis votre serveur ou votre terminal avec votre **clé privée sandbox** (`sk_test.…`). Ne mettez jamais cette clé dans un navigateur ou une application mobile. Wajub fournit aussi une clé publique (`pk_test.…`), destinée à créer un paiement depuis le navigateur. Consultez [Concepts clés → API keys](https://docs.wajub.com/fr/getting-started/concepts#api-keys) pour le détail complet. `POST /payments` **Créer un paiement** ```bash curl https://api.wajub.com/payments \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 25000, "currency": "XAF", "customer": { "email": "amina@example.com" }, "description": "Order #4172", "callback": "https://shop.example.com/order/complete" }' ``` ```javascript import { Wajub } from '@wajub/node'; const wajub = new Wajub({ apiKey: process.env.WAJUB_API_KEY }); const payment = await wajub.payments.create({ amount: 25000, currency: 'XAF', customer: { email: 'amina@example.com' }, description: 'Order #4172', callback: 'https://shop.example.com/order/complete', }); console.log('Payment page:', payment.authorization_url); ``` ```python import os from wajub import Wajub wajub = Wajub(api_key=os.environ["WAJUB_API_KEY"]) payment = wajub.payments.create({ "amount": 25000, "currency": "XAF", "customer": {"email": "amina@example.com"}, "description": "Order #4172", "callback": "https://shop.example.com/order/complete", }) print(payment.authorization_url) ``` ```php getenv('WAJUB_API_KEY')]); $payment = $wajub->payments->create([ 'amount' => 25000, 'currency' => 'XAF', 'customer' => [ 'email' => 'amina@example.com', ], 'description' => 'Order #4172', 'callback' => 'https://shop.example.com/order/complete', ]); echo $payment->authorization_url; ``` ```go client, err := wajub.New(wajub.Config{APIKey: os.Getenv("WAJUB_API_KEY")}) if err != nil { log.Fatal(err) } payment, err := client.Payments.Create(context.Background(), map[string]any{ "amount": 25000, "currency": "XAF", "customer": map[string]any{"email": "amina@example.com"}, "description": "Order #4172", "callback": "https://shop.example.com/order/complete", }, nil) if err != nil { log.Fatal(err) } log.Println(payment.AuthorizationURL) ``` Wajub répond `201 Created`. Le paiement existe désormais sur votre compte, il porte un id que vous utiliserez partout ailleurs, et il contient les deux valeurs qui pilotent le reste de votre intégration : ```json title="Réponse · 201 Created" { "code": 201, "status": "Created", "message": "Payment initiated", "authorization_url": "https://pay.wajub.com/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "authorization_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "transaction": { "id": "trx_test_CSUGajfv9xh0XQ5wu2lx", "amount": 25000, "amount_paid": 0, "currency": "XAF", "status": "pending", "description": "Order #4172", "customer": { "id": "cus_test_sAaim5apjocIgtlhzJY3wQ8s", "email": "amina@example.com" }, "callback": "https://shop.example.com/order/complete", "sandbox": true, "created_at": "2026-09-11T10:24:00+00:00" } } ``` Trois champs de cette réponse comptent dès maintenant : - **`authorization_url`** est la page de paiement hébergée de ce paiement, et de rien d'autre. Redirigez votre client vers elle. C'est la façon la plus simple d'intégrer Wajub, et celle que nous recommandons. - **`authorization_token`** est le jeton de session contenu dans cette URL. Il ne vaut que pour ce paiement et peut être transmis sans risque à un navigateur : c'est ce qu'utilisent les [Components](https://docs.wajub.com/fr/libraries/components) quand vous préférez garder le client sur votre propre page. - **`transaction.status`** démarre à `pending`. Il ne passe à `succeeded` qu'une fois que le client a confirmé sur son téléphone, ce qui arrive bien après le retour de cet appel. > [!WARNING] > **Les montants sont en unité principale, jamais en centimes** > > `"amount": 25000` signifie 25 000 XAF, pas 250 XAF. Contrairement à la plupart des prestataires de > paiement, Wajub n'utilise jamais de sous-unités. Envoyez `500` pour 500 NGN et `10.50` pour 10,50 USD. > Consultez [Concepts clés → Montants](https://docs.wajub.com/fr/getting-started/concepts#amounts). ### « Paiement » ou « transaction » Vous venez de voir les deux mots dans la même réponse, et ils désignent **le même objet**. « Paiement » est le concept métier, d'où l'endpoint `POST /payments`. « Transaction » est ce que l'API sérialise, d'où une réponse qui l'imbrique sous `"transaction"` et préfixe l'`id` par `trx_`. Les deux termes sont interchangeables dans toute cette documentation. L'explication complète se trouve dans [Concepts clés](https://docs.wajub.com/fr/getting-started/concepts#payment-vs-transaction). ### Ce qui se passe ensuite En ouvrant `authorization_url` dans votre navigateur, vous arrivez sur la page de paiement, où des numéros de téléphone sandbox permettent de simuler un succès, un refus ou un délai dépassé. Votre serveur confirme ensuite le résultat avec `GET /payments/{id}` avant de livrer quoi que ce soit, car le seul retour du navigateur peut être falsifié, ou ne jamais se produire. Le [Démarrage rapide](https://docs.wajub.com/fr/getting-started/quickstart) détaille ces deux étapes avec les numéros de test. > [!TIP] > **Déboguez en temps réel avec Konsole** > > Inspectez chaque requête API, rejouez vos webhooks et observez les décisions d'orchestration en direct > avec [Konsole →](https://docs.wajub.com/fr/developer-tools/konsole). C'est le moyen le plus rapide de comprendre ce qui se passe > pendant une intégration. ## Et maintenant ? ### Pour débuter - [Démarrage rapide](https://docs.wajub.com/fr/getting-started/quickstart) : traitez un premier paiement en 5 minutes. - [Démarrage rapide des SDKs](https://docs.wajub.com/fr/libraries/sdks/quickstart) : installez le SDK de votre langage (Node.js, Python, PHP, Go). - [Concepts clés](https://docs.wajub.com/fr/getting-started/concepts) : cycle de vie d'un paiement, sandbox ou live, jetons de session. - [Environnements et API keys](https://docs.wajub.com/fr/getting-started/environments) : test ou production. ### Prêt à intégrer - [Guides et tutoriels](https://docs.wajub.com/fr/guides) : des intégrations pas à pas pour chaque cas d'usage. - [Moyens de paiement et canaux](https://docs.wajub.com/fr/payments/payment-methods) : couverture complète pays × opérateur. - [Référence API](https://docs.wajub.com/fr/api) : chaque endpoint, avec des exemples de requête et de réponse. ### Pour aller plus loin - [Bonnes pratiques](https://docs.wajub.com/fr/best-practices) : idempotence, gestion des erreurs, sécurité. - [Passer en live](https://docs.wajub.com/fr/getting-started/going-live) : checklist de production et KYC. - [Tous les SDKs et bibliothèques](https://docs.wajub.com/fr/libraries/sdks) : Node.js, Python, PHP, Go, SDKs mobiles et navigateur. --- # Démarrage rapide URL: https://docs.wajub.com/fr/getting-started/quickstart > Votre premier paiement de bout en bout, de l'API key au webhook vérifié, en cinq minutes environ. Ce guide vous emmène d'un compte vide à un paiement vérifié, avec un webhook qui fonctionne. Il vous faut un compte Wajub (gratuit) et quelques minutes. ## 1. Créez votre compte et récupérez vos clés Créez un compte sur le [Dashboard](https://dashboard.wajub.com). Un nouveau compte ne possède aucune clé : une fois connecté, ouvrez **Paramètres → Développeurs → Clés API** et créez une clé **privée** pendant que le Dashboard affiche la sandbox. Elle commence par `sk_test.…`. | Clé | Environnement | Où l'utiliser | | ----------- | ------------- | ------------------------------------------------------------------------------- | | `pk_test.…` | Sandbox | Publique. Sans risque dans un navigateur, initialise les paiements côté client. | | `sk_test.…` | Sandbox | Privée. Côté serveur uniquement, aucun argent réel ne circule. | | `pk.…` | Production | Publique. Même rôle côté client, sur des fonds réels. | | `sk.…` | Production | Privée. Côté serveur uniquement, déplace de l'argent réel. | Les clés de production ne deviennent disponibles qu'une fois votre compte vérifié, et les clés restreintes `rk` sont présentées dans [Environnements et API keys](https://docs.wajub.com/fr/getting-started/environments). Tout ce guide s'exécute sur votre serveur, il utilise donc partout la clé privée sandbox. La clé publique existe pour le seul cas où du code s'exécute dans un navigateur : initialiser un paiement depuis la page elle-même. N'utilisez jamais une clé privée depuis un navigateur : lorsque Wajub en détecte une, il refuse la requête et vous prévient par e-mail, pour qu'une clé divulguée ne passe pas inaperçue. ## 2. Installez le SDK de votre langage Les SDKs enveloppent l'API HTTP avec des ressources typées et la vérification de signature des webhooks. Si vous préférez appeler l'API directement, chaque exemple ci-dessous a un onglet cURL. **Installation** ```javascript npm install @wajub/node ``` ```python pip install "wajub>=1.2.1" ``` ```php composer require wajub/wajub-php ``` ```go go get github.com/wajubhq/wajub-go ``` Ruby, Java, C#, Kotlin, Flutter, React Native et Swift ont leurs propres SDKs et leurs propres guides. Consultez [SDKs](https://docs.wajub.com/fr/libraries/sdks) pour la liste complète et la référence de configuration. ## 3. Créez un paiement Un paiement commence par une requête. Vous envoyez le montant, la devise, la personne qui paie et la page vers laquelle la renvoyer. Wajub crée le paiement, le garde en `pending` et répond avec une page hébergée où le client choisit son opérateur et confirme. Personne n'est encore débité. Décrivez le payeur dans l'objet `customer` : il porte `email`, `name`, `phone`, `address` et `metadata`. `POST /payments` **Créer un paiement** ```bash curl https://api.wajub.com/payments \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 5000, "currency": "XAF", "customer": { "email": "amina@example.com" }, "callback": "https://shop.example.com/order/complete" }' ``` ```javascript import { Wajub } from '@wajub/node'; const wajub = new Wajub({ apiKey: process.env.WAJUB_API_KEY }); const payment = await wajub.payments.create({ amount: 5000, currency: 'XAF', customer: { email: 'amina@example.com' }, callback: 'https://shop.example.com/order/complete', }); console.log('Payment page:', payment.authorization_url); ``` ```python import os from wajub import Wajub wajub = Wajub(api_key=os.environ["WAJUB_API_KEY"]) payment = wajub.payments.create({ "amount": 5000, "currency": "XAF", "customer": {"email": "amina@example.com"}, "callback": "https://shop.example.com/order/complete", }) print(payment.authorization_url) ``` ```php getenv('WAJUB_API_KEY')]); $payment = $wajub->payments->create([ 'amount' => 5000, 'currency' => 'XAF', 'customer' => [ 'email' => 'amina@example.com', ], 'callback' => 'https://shop.example.com/order/complete', ]); echo $payment->authorization_url; ``` ```go client, err := wajub.New(wajub.Config{APIKey: os.Getenv("WAJUB_API_KEY")}) if err != nil { log.Fatal(err) } payment, err := client.Payments.Create(context.Background(), map[string]any{ "amount": 5000, "currency": "XAF", "customer": map[string]any{"email": "amina@example.com"}, "callback": "https://shop.example.com/order/complete", }, nil) if err != nil { log.Fatal(err) } log.Println(payment.AuthorizationURL) ``` Wajub répond `201 Created` avec le paiement, son id et la page vers laquelle envoyer le client : ```json title="Réponse · 201 Created" { "code": 201, "status": "Created", "message": "Payment initiated", "authorization_url": "https://pay.wajub.com/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "authorization_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "transaction": { "id": "trx_test_CSUGajfv9xh0XQ5wu2lx", "amount": 5000, "amount_paid": 0, "currency": "XAF", "status": "pending", "customer": { "id": "cus_test_sAaim5apjocIgtlhzJY3wQ8s", "email": "amina@example.com" }, "callback": "https://shop.example.com/order/complete", "sandbox": true, "created_at": "2026-09-11T10:24:00+00:00" } } ``` Enregistrez `transaction.id` avec votre commande, puis redirigez le client vers `authorization_url`. > [!NOTE] > **Les montants sont en unité principale, jamais en centimes** > > `"amount": 5000` signifie 5 000 XAF, pas 50 XAF. Wajub n'utilise jamais de sous-unités. Envoyez `500` > pour 500 NGN et `10.50` pour 10,50 USD. Consultez [Concepts clés → Montants](https://docs.wajub.com/fr/getting-started/concepts#amounts). ## 4. Payez avec un numéro sandbox Ouvrez `authorization_url` dans votre navigateur. En mode test, la page de paiement accepte de faux numéros Mobile Money dont les **6 derniers chiffres** décident du résultat. Les mêmes suffixes fonctionnent pour tous les opérateurs et tous les pays : | Suffixe | Résultat | | -------- | ------------------------------------------------------ | | `000000` | Paiement réussi | | `000001` | Fonds insuffisants | | `000002` | Échec, refusé par l'opérateur | | `000003` | Délai dépassé | | `000004` | En attente → annulé | | `000009` | Le paiement réussit, un remboursement ultérieur échoue | Choisissez un numéro pour l'opérateur que vous voulez tester : La page de paiement sandbox ne demande aucun code PIN : le numéro de test décide seul du résultat. > [!WARNING] > **La sandbox propose des moyens de paiement que la production n'a pas forcément** > > La page de paiement sandbox propose toujours une carte de test, pour que vous puissiez tester ce > parcours de code. **La page de paiement live ne propose que les canaux couverts par vos prestataires > actifs.** Une carte n'y apparaît qu'une fois un prestataire qui accepte les cartes activé sur votre > compte. Développez et testez d'abord avec Mobile Money. ## 5. Vérifiez le paiement côté serveur Le client revient sur votre URL de `callback`, et ce retour ne prouve rien. N'importe qui peut ouvrir cette URL à la main, et un client qui ferme l'onglet ne l'ouvre jamais. Avant de livrer une commande, demandez à l'API ce qui s'est réellement passé, depuis votre serveur, avec l'id enregistré à l'étape 3. `GET /payments/{id}` **Récupérer un paiement** ```bash curl https://api.wajub.com/payments/trx_test_CSUGajfv9xh0XQ5wu2lx \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" ``` ```javascript const payment = await wajub.payments.retrieve('trx_test_CSUGajfv9xh0XQ5wu2lx'); console.log(payment.status, payment.amount, payment.currency); ``` ```python payment = wajub.payments.retrieve("trx_test_CSUGajfv9xh0XQ5wu2lx") print(payment.status, payment.amount, payment.currency) ``` ```php $payment = $wajub->payments->retrieve('trx_test_CSUGajfv9xh0XQ5wu2lx'); echo $payment->status; ``` ```go payment, err := client.Payments.Retrieve(context.Background(), "trx_test_CSUGajfv9xh0XQ5wu2lx") if err != nil { log.Fatal(err) } log.Println(payment.Status, payment.Amount, payment.Currency) ``` La réponse contient le paiement tel que Wajub le connaît, quoi qu'ait affiché votre navigateur : ```json title="Réponse · 200 OK" { "code": 200, "status": "OK", "message": "Payment retrieved", "transaction": { "id": "trx_test_CSUGajfv9xh0XQ5wu2lx", "amount": 5000, "amount_paid": 5000, "currency": "XAF", "status": "succeeded", "channel": "cm.mtn", "customer": { "id": "cus_test_sAaim5apjocIgtlhzJY3wQ8s", "email": "amina@example.com" }, "sandbox": true, "created_at": "2026-09-11T10:24:00+00:00" } } ``` Ne livrez la commande que lorsque `status` vaut `succeeded`, et seulement après avoir vérifié que `amount` et `currency` correspondent à ce que vous avez facturé. Un paiement encore en `pending` n'est pas un échec : c'est un client qui n'a pas encore terminé. Laissez donc la commande ouverte, et laissez le webhook de l'étape 6 vous prévenir quand le paiement aboutit. > [!TIP] > **Suivez la transaction dans Konsole** > > Ouvrez [Konsole → Journaux API](https://docs.wajub.com/fr/developer-tools/konsole/log-explorer) pour voir la requête et la réponse > exactes enregistrées par Wajub. Une fois en live, le [Journal de routage](https://docs.wajub.com/fr/developer-tools/konsole/routing-log) > montre quel prestataire a été choisi, et pourquoi. Il n'existe pas en sandbox. ## 6. Configurez un endpoint de webhook Interroger l'API après chaque redirection ne couvre que les clients qui reviennent. Les webhooks couvrent le reste : un paiement confirmé dix minutes plus tard côté opérateur, un remboursement émis depuis le Dashboard, un litige ouvert par le client. Configurez-en un maintenant, avant de construire quoi que ce soit par-dessus. ### Enregistrez l'endpoint Dans **Konsole → Webhooks → Points de terminaison** : 1. Cliquez sur **Ajouter un endpoint**. 2. Saisissez votre URL publique, par exemple `https://yourapp.com/webhooks/wajub`. 3. Sélectionnez les événements à recevoir. Commencez par tous les événements de paiement, avec **Tout sélectionner** à côté d'eux. Un abonnement ne reconnaît que des noms exacts : saisir `payment.*` ne recevrait rien. 4. Enregistrez, puis copiez le **Secret de signature** (`whsec_…`) dans votre environnement sous le nom `WAJUB_WEBHOOK_SECRET`. ### Donnez le secret de signature au SDK Le client que vous avez créé à l'étape 3 vérifie aussi les webhooks, dès qu'il connaît le secret de signature. Ajoutez-le au même constructeur, à côté de votre API key : **Configurer le client** ```javascript import { Wajub } from '@wajub/node'; export const wajub = new Wajub({ apiKey: process.env.WAJUB_API_KEY, webhookSecret: process.env.WAJUB_WEBHOOK_SECRET, }); ``` ```python import os from wajub import Wajub wajub = Wajub( api_key=os.environ["WAJUB_API_KEY"], webhook_secret=os.environ["WAJUB_WEBHOOK_SECRET"], ) ``` ```php getenv('WAJUB_API_KEY'), 'webhook_secret' => getenv('WAJUB_WEBHOOK_SECRET'), ]); ``` ```go client, err := wajub.New(wajub.Config{ APIKey: os.Getenv("WAJUB_API_KEY"), WebhookSecret: os.Getenv("WAJUB_WEBHOOK_SECRET"), }) ``` ### Écrivez l'endpoint Quatre règles rendent un endpoint de webhook correct, et le SDK ne gère que la première à votre place. **Vérifiez la signature, dans tous les environnements.** Un endpoint qui saute la vérification accepte tout ce que n'importe qui lui envoie, y compris un faux `payment.succeeded`. `constructEvent` vérifie la signature avant d'analyser le JSON. Il lui faut le corps **brut** : désactivez donc l'analyse du corps JSON sur cette route. **Accusez réception avant de travailler.** Wajub attend votre `2xx` pendant 30 secondes. Au-delà, la livraison compte comme échouée et fait l'objet d'une nouvelle tentative : répondez d'abord, et faites le travail lent ensuite, dans une file d'attente ou une goroutine. **Dédupliquez sur l'id de l'événement.** Une livraison échouée est retentée pendant 72 heures au plus, et chaque tentative porte le même `id` d'événement. C'est cet id qui empêche une nouvelle tentative de livrer deux fois la même commande. **Traitez ensuite l'événement.** Le type se trouve dans `event.event`, et `event.data` contient l'objet concerné par l'événement, avec la même forme que celle renvoyée par l'API. Pour `payment.succeeded`, `event.data.id` est l'id du paiement enregistré à l'étape 3. **Endpoint de webhook** ```javascript app.post('/webhooks/wajub', express.raw({ type: '*/*' }), async (req, res) => { const event = wajub.webhooks.constructEvent( req.body, req.headers['x-wajub-signature'], req.headers['x-wajub-timestamp'], ); res.sendStatus(200); if (await alreadyHandled(event.id)) return; await markHandled(event.id); if (event.event === 'payment.succeeded') { await fulfillOrder(event.data.id); } }); ``` ```python @app.post("/webhooks/wajub") def wajub_webhook(): event = wajub.webhooks.construct_event( request.get_data(as_text=True), request.headers["X-Wajub-Signature"], request.headers["X-Wajub-Timestamp"], ) if already_handled(event["id"]): return "", 200 mark_handled(event["id"]) queue.enqueue(handle_event, event) return "", 200 ``` ```php Route::post('/webhooks/wajub', function (Request $request) use ($wajub) { $event = $wajub->webhooks->constructEvent( $request->getContent(), $request->header('X-Wajub-Signature'), $request->header('X-Wajub-Timestamp'), ); if (AlreadyHandled::check($event['id'])) { return response()->noContent(); } AlreadyHandled::mark($event['id']); HandleWajubEvent::dispatch($event); return response()->noContent(); }); ``` ```go http.HandleFunc("/webhooks/wajub", func(w http.ResponseWriter, r *http.Request) { body, err := io.ReadAll(r.Body) if err != nil { w.WriteHeader(http.StatusBadRequest) return } event, err := client.Webhooks.ConstructEvent( body, r.Header.Get("X-Wajub-Signature"), r.Header.Get("X-Wajub-Timestamp"), 0, ) if err != nil { w.WriteHeader(http.StatusBadRequest) return } w.WriteHeader(http.StatusOK) id, _ := event["id"].(string) go handleEvent(id, event) }) ``` ### Recevez les événements sur votre machine Pas besoin d'URL publique, de déploiement ni d'endpoint enregistré pour commencer. La CLI transmet chaque événement sandbox à une adresse locale : ```bash npm install -g @wajub/cli wajub listen --forward-to http://localhost:3000/webhooks/wajub ``` Rien sur votre machine n'est exposé à Internet. `wajub listen` affiche le secret de signature des événements transférés : c'est ce secret que doit contenir votre `WAJUB_WEBHOOK_SECRET` local pendant que vous développez. Il reste le même d'une exécution à l'autre : placez-le une seule fois (`wajub listen --print-secret` l'affiche seul). Ce n'est pas le secret d'un endpoint enregistré : chaque endpoint garde le sien. Consultez la [commande CLI listen](https://docs.wajub.com/fr/developer-tools/cli/listen) pour toutes les options. > [!NOTE] > **Guide complet des webhooks** > > Vérification de signature, politique de nouvelles tentatives, catalogue d'événements et idempotence : > tout est traité dans la [section Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks). ## Et maintenant ? - [Concepts clés](https://docs.wajub.com/fr/getting-started/concepts): Cycle de vie d'un paiement, sandbox ou live, jetons de session, orchestration. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): Vérification de signature, catalogue d'événements, politique de nouvelles tentatives. - [Encaisser un paiement, guide complet](https://docs.wajub.com/fr/guides/accept-a-payment): Initialiser, rediriger, vérifier et livrer, de bout en bout. - [Passer en live](https://docs.wajub.com/fr/getting-started/going-live): La checklist complète avant de passer en production. - [Bonnes pratiques](https://docs.wajub.com/fr/best-practices): Idempotence, gestion des erreurs et sécurité pour la production. - [Référence API](https://docs.wajub.com/fr/api): Chaque endpoint, avec des exemples de requête et de réponse. --- # Solutions par activité URL: https://docs.wajub.com/fr/getting-started/solutions > Choisissez le parcours d'intégration adapté à votre activité, avec le plan et l'environnement dont il a besoin. L'API est la même pour tout le monde ; ce qui change d'une activité à l'autre, ce sont les produits que vous assemblez et leur ordre. Chaque parcours ci-dessous liste ses produits dans l'ordre de construction, avec le plan à partir duquel il est disponible et si vous pouvez le construire en sandbox ou uniquement en production. ## Quel est votre parcours Répondez à une seule question : où finit l'argent ? | Si | Votre parcours | | ------------------------------------------------------------ | ------------------------------------------------------------- | | Vous vendez vos propres produits et c'est vous qui êtes payé | [E-commerce](#e-commerce-and-online-sales) | | D'autres vendeurs sont payés par votre intermédiaire | [Marketplace](#marketplace-and-platform) | | Vous envoyez de l'argent plus souvent que vous n'en recevez | [Payouts en masse](#mass-payouts-and-gig-economy) | | Le même client vous paie à nouveau à chaque cycle | [Facturation récurrente](#subscription-and-recurring-billing) | Les parcours se recoupent, et c'est normal. Une marketplace vend et rembourse aussi : elle suit donc d'abord le parcours e-commerce et ajoute les sous-comptes par-dessus. ## Le socle de tous les parcours Les paiements, la page de checkout hébergée, les remboursements, les clients, les webhooks et les événements forment le cœur. Aucun plan ne les restreint, et ils se comportent de la même façon en sandbox et en production. Quoi que vous construisiez, c'est la base sur laquelle vous vous appuyez, et c'est ce qu'il faut faire fonctionner avant tout le reste. **Le socle** - [Encaisser un paiement](https://docs.wajub.com/fr/payments/hosted-checkout): Créez-le, redirigez vers la page hébergée ou intégrez la vôtre. - [Recevoir les webhooks](https://docs.wajub.com/fr/developer-tools/webhooks/quickstart): Le seul signal fiable qu'un paiement a réussi. ## E-commerce et vente en ligne Vous vendez des produits ou des services, et chaque client paie une fois. Avant d'écrire la moindre ligne de code, vérifiez sur quoi tourne déjà votre boutique. Si c'est WordPress, le plugin officiel couvre WooCommerce, GiveWP, Easy Digital Downloads, Tutor LMS, MemberPress et Gravity Forms, avec un shortcode `[wajub_pay]` pour tout le reste. Vous collez vos clés et c'est terminé, il n'y a aucune intégration à maintenir. Si vous construisez la boutique vous-même, trois étapes suffisent. Vous créez le paiement quand le panier est validé, vous envoyez le client vers l'`authorization_url` renvoyée, et vous livrez la commande quand le webhook `payment.succeeded` arrive. Ne livrez jamais sur la seule redirection : un client qui ferme l'onglet paie quand même. Les remboursements arrivent en dernier, et c'est voulu. Il vous faut des commandes avant d'avoir quoi que ce soit à rembourser, et l'endpoint de remboursement a besoin d'un identifiant de paiement que vous n'aurez qu'une fois la première étape fonctionnelle. Tout ceci fonctionne avec **Pay as you go**, en sandbox comme en production. Seule exception : les liens de paiement, disponibles uniquement en production et limités à 25 liens sur le plan gratuit, avant de devenir illimités avec Growth. **Votre parcours** - [Commencez ici si vous utilisez WordPress](https://docs.wajub.com/fr/libraries/plugins): WooCommerce, GiveWP, EDD, LMS, formulaires, sans aucun code d'API. - [1. Encaisser un paiement](https://docs.wajub.com/fr/payments/hosted-checkout): Page hébergée ou votre propre checkout. - [2. Livrer sur le webhook](https://docs.wajub.com/fr/developer-tools/webhooks/quickstart): Expédiez à l'arrivée de payment.succeeded, pas sur la redirection. - [3. Gérer les remboursements](https://docs.wajub.com/fr/payments/refunds): Retours, annulations, remboursements partiels. ## Marketplace et plateforme Vous mettez en relation des vendeurs et des acheteurs, et l'argent doit arriver au vendeur au lieu de s'arrêter chez vous. C'est le rôle de Sync. Chaque vendeur devient un sous-compte avec ses propres capacités, sa propre tarification et son propre historique de transactions. Vous agissez ensuite pour le compte d'un vendeur en ajoutant un en-tête à un appel que vous savez déjà faire, `X-Sync: acc_…`, sans deuxième API à apprendre. Inscrivez les vendeurs avant de faire passer le moindre paiement par eux, car un sous-compte doit être accepté et actif avant de pouvoir effectuer des transactions. Les payouts bouclent la boucle. Les bénéficiaires vous permettent d'enregistrer une fois le portefeuille d'un vendeur, au lieu de renvoyer le numéro et l'opérateur à chaque transfert. Sync est une fonctionnalité du plan **Scale** : les pages Sync du Dashboard, où vous créez et gérez vos connexions, s'ouvrent à partir de ce plan. Il fonctionne en sandbox, mais un sous-compte appartient à un seul environnement : appeler un sous-compte sandbox avec une clé de production, ou l'inverse, renvoie `404` `Sync account not found.`, la même réponse que pour un identifiant qui n'existe pas ou le sous-compte d'une autre plateforme. Les transferts et les bénéficiaires sont disponibles sur tous les plans. **Votre parcours** - [1. Encaisser les paiements](https://docs.wajub.com/fr/payments/hosted-checkout): Le même checkout que n'importe quelle boutique. - [2. Inscrire vos vendeurs](https://docs.wajub.com/fr/sync/quickstart): Créez des sous-comptes, définissez capacités et tarification. - [3. Payer les vendeurs](https://docs.wajub.com/fr/payouts/transfers): Transferts Mobile Money via l'API. - [4. Enregistrer les destinataires](https://docs.wajub.com/fr/api/beneficiaries): Enregistrez un portefeuille une fois, réutilisez-le à chaque payout. ## Payouts en masse et économie à la tâche Vous distribuez des fonds : salaires, gains de chauffeurs, commissions, primes. `POST /transfers/batch` accepte jusqu'à 500 payouts en un seul appel. Son en-tête `Idempotency-Key` est obligatoire et chaque ligne porte sa propre `reference` : un lot à moitié échoué se renvoie tel quel, et seules les lignes qui ne sont pas passées partent la deuxième fois. Chaque ligne passe les mêmes contrôles qu'un payout seul, et un destinataire refusé ne bloque pas les autres. Enregistrer d'abord vos destinataires comme bénéficiaires est ce qui raccourcit ce lot. Chaque ligne paie un identifiant `ben_…` au lieu de répéter le numéro de téléphone, l'opérateur et le pays, et une paie devient une liste d'identifiants que vous avez déjà. Surveillez le solde, pas la réponse de l'API. Un transfert est refusé quand le solde disponible est insuffisant : une série de payouts doit donc lire le solde avant de démarrer, au lieu de découvrir le problème au quarantième destinataire. Les transferts, les lots, les bénéficiaires et le solde sont disponibles sur tous les plans et fonctionnent en sandbox via l'API. Dans le Dashboard, le bouton qui crée un transfert à la main est réservé à la production. **Votre parcours** - [1. Envoyer un transfert](https://docs.wajub.com/fr/payouts/transfers): Un payout Mobile Money, un appel. - [2. Enregistrer vos destinataires](https://docs.wajub.com/fr/api/beneficiaries): Payez un bénéficiaire enregistré au lieu de répéter les coordonnées du portefeuille. - [3. Surveiller le solde](https://docs.wajub.com/fr/payouts/balance): Fonds disponibles, cycles de règlement, frais. - [4. Cadencer la boucle](https://docs.wajub.com/fr/api/rate-limits): Requêtes par minute autorisées sur votre plan. ## Abonnements et facturation récurrente Vous facturez le même client à chaque cycle. Sur Wajub, la facturation récurrente repose sur des factures, pas sur un mandat enregistré. Le Mobile Money ne permet pas de débiter un portefeuille plus tard sans que le client s'en aperçoive : chaque cycle produit donc une nouvelle facture avec son propre lien de paiement, et le client l'approuve. Vous créez la première facture avec `is_recurring` activé et une `recurring_frequency` parmi `daily`, `weekly`, `monthly`, `quarterly` ou `yearly`, et Wajub émet les suivantes selon le calendrier. Changer le montant ou le cycle revient à mettre à jour cette facture, et l'annuler arrête la facturation. Ce sont les relances qui font vraiment encaisser ce modèle. Comme chaque cycle demande une approbation humaine, une facture impayée le reste tant que personne n'est relancé : considérez le calendrier de relances comme une partie de l'intégration, pas comme un bonus. Il n'existe pas de ressource produits, prix ou coupons pour modéliser votre catalogue. Si vous avez besoin de plans par paliers, de prorata ou de facturation à l'usage, vous construisez cette logique de votre côté au-dessus de l'API Payments, et le guide de facturation récurrente vous accompagne. La facturation est disponible sur tous les plans, limitée à 10 factures avec Pay as you go et illimitée à partir de Growth. La génération récurrente elle-même nécessite **Growth** ou plus, et elle échoue sans bruit si vous repassez en dessous : la facture parente est conservée, mais aucun nouveau cycle n'est émis tant que le plan n'est pas rétabli. Les factures sont réservées à la production : construisez et testez d'abord la gestion des paiements et des webhooks en sandbox, puis changez de clé avant de toucher à la facturation. **Votre parcours** - [1. Émettre votre première facture](https://docs.wajub.com/fr/billing/invoice/quickstart): Lignes, taxes, date d'échéance, lien de paiement hébergé. - [2. La mettre sur un cycle](https://docs.wajub.com/fr/billing/invoice/recurring): is_recurring, fréquence, conditions de fin. - [3. Relancer les impayés](https://docs.wajub.com/fr/billing/invoice/reminders): Relances automatiques avant et après la date d'échéance. - [4. Construire des plans par-dessus](https://docs.wajub.com/fr/guides/subscription-billing): Paliers, prorata et facturation à l'usage, dans votre propre code. > [!TIP] > **Valable pour tous les parcours** > > Gardez [Konsole](https://docs.wajub.com/fr/developer-tools/konsole) ouvert pendant l'intégration : il affiche chaque > requête et chaque livraison de webhook en direct. Lisez les [Bonnes pratiques](https://docs.wajub.com/fr/best-practices) > avant de manipuler de l'argent réel, et déroulez la [checklist pour passer en > live](https://docs.wajub.com/fr/getting-started/going-live) avant de changer de clés. --- # Guide du tableau de bord URL: https://docs.wajub.com/fr/dashboard > Gérez votre activité depuis le tableau de bord Wajub, une tâche à la fois. Qui peut faire quoi, Test et Production, et le code de sécurité. Ce guide s'adresse aux personnes qui travaillent dans le tableau de bord [dashboard.wajub.com](https://dashboard.wajub.com) sans écrire de code : propriétaires, équipes finance, support et comptabilité. Chaque page décrit une tâche, étape par étape, avec ce que l'écran montre ensuite. Si vous connectez Wajub à votre site ou à votre application, commencez par les [Premiers pas](https://docs.wajub.com/fr/getting-started). Pour démarrer, [Recevoir un premier transfert](https://docs.wajub.com/dashboard/getting-started/first-payout) suit le chemin complet, de l'inscription au premier transfert vers votre compte. ## Comment se lit une page Avant les étapes, chaque page dit qui peut faire la tâche, le forfait qu'elle demande quand tous ne l'ont pas, si elle ne marche qu'en Production et si le tableau de bord demande un code de sécurité. Les règles ci-dessous valent partout : une page ne les répète que lorsqu'elle s'en écarte. ## Test et Production Le sélecteur en haut à droite du tableau de bord passe de **Test**, où les paiements sont simulés, à **Production**, où l'argent circule pour de vrai. Les deux ont des données séparées : un client ou un paiement créé en Test n'apparaît jamais en Production. [Environnements](https://docs.wajub.com/fr/getting-started/environments) explique ce que simule le mode test. ![L'accueil du tableau de bord en Production : volume du jour, solde total, volume brut, paiements réussis et échoués, puis les graphiques des tentatives de paiement et du volume crédité. Le sélecteur Test et Production est en haut à droite, sur Production.](https://docs.wajub.com/dashboard/fr/light/home.webp) *Le sélecteur en haut à droite indique l'environnement où vous êtes.* Une nouvelle organisation reste en Test tant que Wajub n'a pas validé son [activation](https://docs.wajub.com/fr/getting-started/account-activation). Ensuite, le propriétaire, un Administrateur, un Développeur, ou un rôle personnalisé qui a **Gérer les paramètres** ou **Gérer les paramètres développeur** peut basculer. Un Utilisateur de test reste toujours en Test. Six modules n'existent qu'en Production et quittent le menu en Test : **Factures**, **Liens de paiement**, **Revenus**, **Taxe**, **Shield** et **Orchestration**. Leur raccourci clavier indique alors qu'ils sont disponibles uniquement en production. Certaines actions demandent aussi la Production : envoyer un transfert, modifier, archiver ou supprimer un bénéficiaire, fusionner deux clients, et tous les exports sauf ceux de Konsole et l'export de vos données personnelles. Dans **Paramètres**, les sections **Liens de paiement**, **Factures**, **Transferts** et **Fusions de clients** restent dans la liste en Test, marquées **Production uniquement**. ## Rôles Une organisation a un propriétaire, la personne qui l'a créée, et les membres qu'il invite. Le propriétaire peut tout faire, et lui seul peut fermer l'organisation, la céder à quelqu'un d'autre ou lire les conversations des membres avec l'assistant. Chaque membre a l'un des sept rôles. | Rôle | Ce qu'il couvre | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Administrateur** | Tout ce que peut faire le propriétaire, sauf les trois actions ci-dessus. | | **Développeur** | Clés API, webhooks et Konsole, réglages techniques, et le passage entre Test et Production. Lit les paiements, les clients, les factures et les paramètres, et gère les liens de paiement. | | **Finance** | Les paiements, sans remboursements ni litiges. Transferts et bénéficiaires, factures, liens de paiement, abonnements, rapports, revenus et taxe. Lit les clients. | | **Analyste** | Lit les paiements, les clients, les transferts, les factures, les liens de paiement, les abonnements, les rapports, les revenus et la taxe. Ne modifie rien, sauf pour ouvrir un ticket de support. | | **Spécialiste support** | Paiements, remboursements, litiges et clients. Lit les factures. | | **Observateur** | Lit ce que lit un Analyste, plus les paramètres. Ne modifie rien, sauf pour ouvrir un ticket de support. | | **Utilisateur de test** | Test uniquement : paiements de test, clés API et webhooks. Lit les clients. | ![Paramètres › Membres : huit membres, chacun avec son nom, son e-mail et son rôle, d'Administrateur à Utilisateur de test, et le propriétaire marqué Vous.](https://docs.wajub.com/dashboard/fr/light/members.webp) *Paramètres › Membres liste chaque membre avec son rôle.* Shield est ouvert au propriétaire, aux Administrateurs et aux rôles personnalisés qui l'incluent. Quand aucun des sept rôles ne convient, le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les membres** en crée un dans **Paramètres › Membres › Rôles personnalisés**. Un rôle personnalisé ne peut contenir que des permissions que son créateur possède. ## Le code de sécurité Les modifications sensibles vous demandent d'abord de prouver que c'est bien vous : rembourser un paiement, envoyer un transfert, supprimer un lien de paiement, créer une clé API, accepter un litige ou modifier un rôle personnalisé, entre autres. Le tableau de bord ouvre **Vérification de sécurité** et demande un **Code de vérification**. Vous le recevez par e-mail, par SMS si le SMS est votre méthode de double authentification et que votre numéro est enregistré, ou dans votre application d'authentification si vous en avez activé une. Une fois le code saisi, le tableau de bord ne le redemande pas pendant 30 minutes. Votre mot de passe ne le remplace jamais. ## Modules hors de votre forfait Quand votre forfait n'inclut pas un module, son entrée reste dans le menu, marquée **Pas dans votre forfait**. En l'ouvrant, vous voyez la page du module : ce qu'il apporte, puis les façons de l'obtenir, côte à côte — le module seul quand il se vend à l'unité, et chaque forfait qui l'inclut, avec son prix et ce qu'il ajoute au vôtre. --- # Voir votre activité URL: https://docs.wajub.com/fr/dashboard/account/activity-and-data > Relire les connexions et les changements de sécurité de votre compte utilisateur, et exporter les données personnelles que Wajub garde sur vous. **Votre activité** liste les connexions et les changements de sécurité de votre compte utilisateur. **Vos données**, sur votre profil, exporte ce que Wajub garde sur vous. Chaque membre voit sa propre activité et exporte ses propres données, quel que soit son [rôle](https://docs.wajub.com/fr/dashboard#roles), [en Test comme en Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), sans [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Lire votre activité Ouvrez **Paramètres**, puis **Votre activité** dans le groupe **Personnel**. Chaque ligne donne une action et sa date : connexion, déconnexion, mot de passe changé ou réinitialisé, méthode de double authentification changée, clé d'accès ajoutée ou supprimée. **Date** choisit une période, sur 365 jours au plus, et **Action** garde une seule action. ![Paramètres › Votre activité : les filtres Date et Action, puis la liste des actions du compte, chacune avec son adresse IP, son appareil et sa date.](https://docs.wajub.com/dashboard/fr/light/account-activity.webp) *Seules les actions de votre compte utilisateur apparaissent ici.* Une connexion que vous ne reconnaissez pas : fermez la session et changez votre mot de passe, comme décrit dans [Sécuriser votre connexion](https://docs.wajub.com/dashboard/account/security#sessions). Ce que font les membres dans l'organisation figure dans le [journal d'audit](https://docs.wajub.com/dashboard/settings/audit-log). ## Exporter vos données Ouvrez **Profil** dans le groupe **Personnel**, puis, sous **Vos données**, **Exporter toutes mes données**. Le tableau de bord télécharge un fichier JSON avec votre profil (nom, e-mail, téléphone, langue), vos organisations et votre rôle dans chacune, vos sessions et les 500 dernières lignes de votre activité. --- # Supprimer votre compte URL: https://docs.wajub.com/fr/dashboard/account/delete > Supprimer votre compte utilisateur Wajub, ce qui ferme les organisations dont vous êtes propriétaire, et que faire si la suppression est refusée. Supprimer votre compte utilisateur retire votre accès à Wajub et ferme les organisations dont vous êtes propriétaire. C'est irréversible. Chaque membre peut supprimer son propre compte, quel que soit son [rôle](https://docs.wajub.com/fr/dashboard#roles), [en Test comme en Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). La suppression demande le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). Avant de commencer, pour chaque organisation dont vous êtes propriétaire, retirez son solde par un [transfert](https://docs.wajub.com/dashboard/transfers/send) et attendez la fin des litiges, remboursements et transferts en cours, ou [cédez-la à un autre membre](https://docs.wajub.com/dashboard/settings/organizations#transfer-ownership). ## Les étapes 1. **Ouvrez votre profil** Ouvrez **Paramètres**, puis **Profil** dans le groupe **Personnel**. **Zone dangereuse** est en bas de la page. 2. **Lancez la suppression** **Supprimer le compte** ouvre **Supprimer votre compte ?**. La fenêtre nomme les organisations que vous possédez et qui seront fermées : leurs clés API cessent de marcher, leurs membres perdent l'accès, et leurs enregistrements sont conservés. Les organisations dont vous êtes seulement membre continuent sans vous. Si une organisation ne peut pas encore être fermée, la fenêtre la liste sous **Réglez d'abord ces points, puis supprimez votre compte :** et ne propose pas la suppression : voir [Si la suppression est refusée](#if-deletion-is-refused). ![La fenêtre Supprimer votre compte ? : Cette action est irréversible, puis ce qui disparaît avec le compte, les organisations possédées qui seront fermées, le champ Saisissez votre adresse e-mail pour confirmer, avec les boutons Annuler et Supprimer le compte.](https://docs.wajub.com/dashboard/fr/light/account-delete-dialog.webp) *La fenêtre nomme chaque organisation qui sera fermée.* 3. **Confirmez la suppression** Saisissez votre adresse e-mail dans **Saisissez votre adresse e-mail pour confirmer**, puis choisissez **Supprimer le compte**, qui demande le code de sécurité. Le compte est supprimé, avec ses méthodes de connexion et ses sessions, et vous êtes déconnecté. ## Si la suppression est refusée Sous **Réglez d'abord ces points, puis supprimez votre compte :**, la fenêtre nomme chaque organisation qui ne peut pas encore être fermée et dit pourquoi : un solde à retirer, ou un litige, un remboursement ou un transfert en cours. Réglez ce point, ou cédez l'organisation, puis rouvrez la fenêtre. Si la suppression est refusée une fois confirmée, **Votre compte n'a pas été supprimé** donne la raison de la même façon. --- # Régler vos préférences URL: https://docs.wajub.com/fr/dashboard/account/preferences > Choisir la langue du tableau de bord, une devise d'affichage et les e-mails que vous recevez, et activer les raccourcis clavier. **Préférences**, dans le groupe **Personnel** des paramètres, règle la langue du tableau de bord, une devise d'affichage et vos e-mails. Ces choix ne valent que pour vous. Chaque membre règle ses propres préférences, quel que soit son [rôle](https://docs.wajub.com/fr/dashboard#roles), [en Test comme en Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), sans [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Langue et devise Ouvrez **Paramètres**, puis **Préférences** dans le groupe **Personnel**. **Langue d'interface** passe tout le tableau de bord en français ou en anglais. **Devise d'affichage** ajoute, à côté des principaux montants de l'[accueil](https://docs.wajub.com/dashboard/home/read), leur conversion au dernier taux de change ; les montants, le règlement et votre page de paiement ne changent pas. Le premier choix de la liste retire la conversion. ![Paramètres › Préférences : Langue et devise avec la Langue d'interface sur Français et la Devise d'affichage sans conversion, puis les Notifications par e-mail rangées en Transactions, Compte et Autre, un interrupteur par sujet, tous activés sauf Mises à jour produit.](https://docs.wajub.com/dashboard/fr/light/account-preferences.webp) *La langue et la devise s'enregistrent dès que vous les choisissez.* ## Les e-mails **Notifications par e-mail** a un interrupteur par sujet, rangés en **Transactions** (**Paiements**, **Transferts**, **Factures**, **Litiges**), **Compte** (**Conformité**, **Organisation**, **Sécurité**) et **Autre** (**Mises à jour produit**, désactivé au départ). Une barre apparaît en bas de l'écran dès la première modification : **Enregistrer les modifications** applique vos choix, **Abandonner** les annule. Wajub n'envoie à un membre que les e-mails qui concernent son rôle. ## Les raccourcis clavier Les raccourcis se règlent hors de cette page. **Raccourcis clavier**, dans le menu de votre compte en haut à droite, les liste, et **Utiliser les raccourcis à une touche** les active ou les coupe. Une fois activés, la touche ? ouvre aussi cette liste. --- # Modifier votre profil URL: https://docs.wajub.com/fr/dashboard/account/profile > Changer votre nom, l'adresse e-mail avec laquelle vous vous connectez et le numéro de téléphone où Wajub envoie vos codes. **Profil**, dans le groupe **Personnel** des paramètres, porte votre nom, l'adresse e-mail et le numéro de téléphone où Wajub envoie vos codes de connexion et de vérification. Ils suivent votre compte dans toutes vos organisations. Chaque membre modifie son propre profil, quel que soit son [rôle](https://docs.wajub.com/fr/dashboard#roles), [en Test comme en Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Changer d'adresse e-mail ne demande pas le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) mais un code envoyé à chaque adresse ; vérifier un numéro de téléphone le demande. ## Changer d'adresse e-mail 1. **Ouvrez votre profil** Ouvrez **Paramètres**, puis **Profil** dans le groupe **Personnel**. ![Paramètres › Profil : le champ Nom complet, puis la carte Coordonnées avec l'adresse e-mail marquée Vérifié et son bouton Modifier, et le numéro de téléphone, lui aussi marqué Vérifié avec son bouton Modifier, puis les cartes Vos données et Zone dangereuse.](https://docs.wajub.com/dashboard/fr/light/account-profile.webp) *Coordonnées réunit les deux adresses où arrivent vos codes.* 2. **Saisissez la nouvelle adresse** Dans **Coordonnées**, **Modifier** ouvre **Changer d'adresse e-mail**. Saisissez la **Nouvelle adresse e-mail**, puis **Envoyer le code**. Une adresse jetable est refusée : utilisez une adresse permanente. 3. **Vérifiez l'adresse actuelle** Saisissez le **Code de vérification** reçu à votre adresse actuelle, puis **Vérifier l'e-mail actuel**. 4. **Vérifiez la nouvelle adresse** Saisissez le code reçu à la nouvelle adresse, puis **Finaliser le changement d'e-mail**. Vous vous connectez désormais avec la nouvelle adresse. Tant que le changement n'est pas fini, **Coordonnées** affiche **Changement en attente vers** et la nouvelle adresse. **Continuer** reprend où vous en étiez, et **Annuler le changement d'e-mail** garde l'ancienne. ## Votre nom Remplacez votre **Nom complet** : une barre apparaît en bas de l'écran, et **Enregistrer le nom** l'applique. ## Votre numéro de téléphone Dans **Coordonnées**, **Ajouter un numéro de téléphone** ouvre une fenêtre du même nom. Saisissez le **Numéro de téléphone**, puis **Envoyer le code**, qui demande le code de sécurité. Saisissez le code à 6 chiffres reçu par SMS, puis **Vérifier le numéro de téléphone** : le numéro passe à **Vérifié**, et peut recevoir vos codes de connexion, comme décrit dans [Sécuriser votre connexion](https://docs.wajub.com/dashboard/account/security#other-methods). Un numéro pas encore vérifié a un bouton **Vérifier**, qui ouvre **Vérifier le numéro de téléphone**. Un numéro vérifié a un bouton **Modifier**, qui ouvre **Changer de numéro de téléphone**. Les deux fonctionnent de la même façon. **Vos données**, plus bas, exporte ce que Wajub garde sur vous : voir [Exporter vos données](https://docs.wajub.com/dashboard/account/activity-and-data#export-your-data). **Zone dangereuse** sert à [supprimer votre compte](https://docs.wajub.com/dashboard/account/delete). --- # Sécuriser votre connexion URL: https://docs.wajub.com/fr/dashboard/account/security > Configurer une application d'authentification, des clés d'accès ou des codes par e-mail ou SMS, changer votre mot de passe et fermer vos sessions. **Sécurité**, dans le groupe **Personnel** des paramètres, règle comment vous vous connectez : mot de passe, clés d'accès, double authentification et sessions. Les règles imposées à toute l'organisation se règlent dans [Sécuriser l'organisation](https://docs.wajub.com/dashboard/settings/security). Chaque membre sécurise son propre compte, quel que soit son [rôle](https://docs.wajub.com/fr/dashboard#roles), [en Test comme en Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Configurer une application d'authentification, ajouter ou supprimer une clé d'accès, désactiver une méthode, créer de nouveaux codes de récupération et fermer une session demandent le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Configurer une application d'authentification 1. **Ouvrez la page Sécurité** Ouvrez **Paramètres**, puis **Sécurité** dans le groupe **Personnel**. Tant que vous n'avez ni double authentification ni clé d'accès, l'entrée porte **L'authentification à deux facteurs est désactivée**. **Méthodes de connexion** liste chaque méthode avec son état, **Activé** ou **Désactivé**. ![Paramètres › Sécurité : Méthodes de connexion avec le mot de passe et Changer le mot de passe, puis les clés d'accès marquées Recommandé, l'application d'authentification, le code par e-mail et le code par SMS, tous marqués Désactivé avec leur bouton, puis les sessions, chacune avec son appareil, son adresse IP et sa dernière activité, la vôtre marquée Cet appareil.](https://docs.wajub.com/dashboard/fr/light/account-security.webp) *Sans double authentification ni clé d'accès, chaque méthode sauf le mot de passe est marquée Désactivé.* 2. **Lancez la configuration** Sur **Application d'authentification**, **Configurer** demande le code de sécurité, puis ouvre **Configurer l'application d'authentification**. 3. **Scannez le code QR** Scannez le code QR avec Google Authenticator, 1Password ou une application similaire. Si vous ne pouvez pas le scanner, saisissez la **Clé de configuration** dans l'application. 4. **Confirmez avec le code de l'application** Saisissez le code à 6 chiffres que montre l'application dans **Code de l'application**, puis **Activer l'application d'authentification**. 5. **Gardez vos codes de récupération** **Enregistrez vos codes de récupération** les affiche une seule fois. **Copier** ou **Télécharger** les garde : chacun vous connecte une fois si vous perdez votre téléphone. 6. **Terminez la configuration** Cochez **J'ai enregistré ces codes**, puis **Terminé**. L'application passe à **Activé**. ## Les autres méthodes **Clés d'accès**, marquées **Recommandé**, vous connectent avec votre empreinte, votre visage ou le verrouillage de l'écran. **Ajouter une clé d'accès** demande un nom, facultatif, puis votre navigateur prend le relais. Une clé d'accès compte comme deuxième étape. **Supprimer** retire une clé. **Code par e-mail** et **Code par SMS** envoient un code à chaque connexion. **Activer** vous envoie un premier code : saisissez-le, puis **Activer les codes par e-mail** ou **Activer les codes par SMS**. Le SMS demande un numéro vérifié dans votre [profil](https://docs.wajub.com/dashboard/account/profile#your-phone-number). **Désactiver** retire une méthode, après une confirmation. **Codes de récupération** propose **Créer de nouveaux codes** si vous avez perdu les vôtres : les anciens cessent aussitôt de marcher. ## Votre mot de passe **Changer le mot de passe** demande le **Mot de passe actuel**, le **Nouveau mot de passe** et **Confirmer le mot de passe**, puis **Mettre à jour le mot de passe**. Vos autres sessions restent connectées : fermez-les si vous l'avez changé par précaution. ## Vos sessions **Sessions** liste les appareils où votre compte est connecté, le vôtre marqué **Cet appareil**. **Se déconnecter** ferme une session, et **Déconnecter toutes les autres sessions** ferme toutes les autres. Déconnectez tout appareil que vous ne reconnaissez pas, puis changez votre mot de passe. --- # Ajouter un client URL: https://docs.wajub.com/fr/dashboard/customers/add > Créer la fiche d'un particulier ou d'une entreprise depuis le tableau de bord, et ce que fait l'alerte quand ce client existe déjà. La fiche d'un client garde ses coordonnées, ses préférences et vos étiquettes, et rassemble ensuite ses paiements, ses remboursements et ses litiges. Un client saisi avec un e-mail ou un téléphone sur une [facture](https://docs.wajub.com/dashboard/invoices/create) rejoint aussi votre répertoire. Le propriétaire, un Administrateur, un Spécialiste support ou un rôle personnalisé qui a **Gérer les clients** peut ajouter un client, avec tous les forfaits, en Test comme en Production. Aucun code de sécurité n'est demandé. ## Les étapes 1. **Ouvrez le formulaire** Ouvrez **Clients**, puis **Ajouter un client**. Le formulaire tient sur une seule page. 2. **Choisissez le type de client** Sous **Type de client**, choisissez **Particulier** ou **Entreprise**. Pour un particulier, **Informations personnelles** demande son **Nom complet**. Pour une entreprise, **Informations sur l'activité** demande le **Nom de l'entreprise**, seul champ obligatoire du formulaire, puis si besoin le **Numéro d'enregistrement**, le **Numéro d'identification fiscale** et le nom et le titre du représentant légal. ![Ajouter un client : le type Entreprise choisi, le nom de l'entreprise Boulangerie La Mie Dorée, le nom du représentant légal, puis l'e-mail et le téléphone sous Informations de contact.](https://docs.wajub.com/dashboard/fr/light/customers-add.webp) *Pour une entreprise, seul le nom de l'entreprise est obligatoire.* 3. **Saisissez ses coordonnées** Sous **Informations de contact**, saisissez son **E-mail** et son **Téléphone** : ses reçus et ses factures partent vers eux. Le tableau de bord vérifie aussitôt s'ils appartiennent déjà à un client, comme l'explique la section suivante. **Adresse** est facultative. 4. **Réglez ses préférences** Sous **Préférences**, la **Devise** est XAF par défaut. **Langue préférée** fixe la langue de ses factures, de ses reçus et de ses e-mails : l'anglais par défaut, ou le français. La **Description** n'est visible que de vos membres, et les **Étiquettes** s'ajoutent une à une avec la touche Entrée. 5. **Ajoutez le client** Choisissez **Ajouter un client**. Sa fiche s'ouvre avec **Client créé avec succès.** Si un champ est refusé, le formulaire le signale en rouge et rien n'est créé. ## Quand le client existe déjà Dans un même environnement, deux clients ne peuvent pas avoir le même e-mail. Si l'e-mail saisi est déjà pris, l'alerte **Cet e-mail est déjà utilisé** nomme le client qui l'a et propose de l'ouvrir : changez d'e-mail ou complétez plutôt sa fiche. Un téléphone déjà connu affiche **Ce client existe peut-être déjà**, sans bloquer : vous pouvez créer le client quand même, ou ouvrir la fiche existante. Si les deux fiches désignent la même personne, [fusionnez-les](https://docs.wajub.com/dashboard/customers/merge). ## Après la création La fiche du client s'ouvre. [Tenir à jour une fiche client](https://docs.wajub.com/dashboard/customers/profile) explique ce qu'elle montre et comment la modifier. --- # Bloquer, supprimer un client URL: https://docs.wajub.com/fr/dashboard/customers/block-disable-delete > Bloquer un client avec un motif et le débloquer, supprimer un client et ses données personnelles, puis retrouver ou restaurer une fiche supprimée. Ce que fait le blocage dépend de la version d'API de votre compte : à partir de `2026-11-02`, un client bloqué ne peut plus vous payer tant que vous ne le débloquez pas ; sur les versions antérieures, le blocage ne fait que le signaler à vos membres et à vos règles de routage. [Statut et blocage](https://docs.wajub.com/fr/payments/customers/manage#status-and-blocking) en dit plus. Supprimer un client efface ses données personnelles pour de bon et garde ses paiements. Le propriétaire, un Administrateur, un Spécialiste support ou un rôle personnalisé qui a **Gérer les clients** peut le faire, en Test comme en Production. Bloquer, débloquer et supprimer demandent le code de sécurité ; restaurer un client supprimé ne le demande pas. ## Les étapes 1. **Ouvrez le menu du client** Sur la fiche du client, ouvrez le menu à droite de **Modifier**, puis choisissez **Bloquer le client**. Dans **Clients**, le menu au bout de sa ligne propose la même action. 2. **Indiquez le motif** Un dialogue s'ouvre au nom du client, par exemple « Bloquer Restaurant Le Bastos ? ». **Motif (facultatif)** garde, en 500 caractères au plus, la raison du blocage pour vos membres : le client ne la voit pas. ![Le dialogue Bloquer Restaurant Le Bastos ? avec le champ Motif (facultatif) rempli et le bouton Bloquer le client.](https://docs.wajub.com/dashboard/fr/light/customers-block.webp) *Seuls vos membres voient le motif.* 3. **Bloquez le client** Choisissez **Bloquer le client**, puis saisissez le code de sécurité. Sa fiche affiche **Ce client est bloqué**, avec le motif et la date du blocage, et son statut passe à **Bloqué** dans la liste. Pour lever le blocage, choisissez **Débloquer le client** dans le même menu, puis saisissez le code : le client redevient **Actif**. Un client bloqué entre aussi dans le segment **Clients bloqués** des [règles de routage](https://docs.wajub.com/dashboard/orchestration/routing-rules). ## Supprimer un client Dans le menu de sa fiche, ou au bout de sa ligne dans **Clients**, choisissez **Supprimer le client**, confirmez, puis saisissez le code de sécurité. Le client quitte votre liste et ne peut plus être débité avec ses moyens de paiement enregistrés. Son nom, son e-mail et son numéro de téléphone sont effacés aussitôt, sans retour possible. Ses paiements restent dans votre historique. [Suppression et effacement](https://docs.wajub.com/fr/payments/customers/delete) détaille ce qui est retiré. ## Restaurer un client supprimé Dans **Clients**, le filtre **Clients supprimés** affiche les fiches supprimées. Le menu au bout d'une ligne propose **Restaurer le client** : la fiche revient dans la liste, sans les données personnelles déjà effacées. > [!NOTE] > **Plusieurs clients à la fois** > > Pour bloquer, débloquer ou supprimer jusqu'à 100 clients d'un coup, sélectionnez-les dans la > liste : [Agir sur plusieurs clients](https://docs.wajub.com/dashboard/customers/bulk-actions). --- # Agir sur plusieurs clients URL: https://docs.wajub.com/fr/dashboard/customers/bulk-actions > Sélectionner des clients dans la liste pour les bloquer, les débloquer, les supprimer ou les exporter d'un coup, et exporter toute la liste filtrée. Depuis la liste **Clients**, vous pouvez bloquer, débloquer, supprimer ou exporter jusqu'à 100 clients à la fois, ou exporter toute la liste avec ses filtres. Le propriétaire, un Administrateur, un Spécialiste support ou un rôle personnalisé qui a **Gérer les clients** voit les cases de sélection et le bouton **Exporter**. Bloquer, débloquer et supprimer demandent le code de sécurité. L'export n'existe qu'en Production : le forfait **Pay as you go** en compte 10 par mois, tous exports du tableau de bord confondus, et **Growth** et les forfaits au-dessus n'ont pas de limite. ## Les étapes 1. **Sélectionnez les clients** Dans **Clients**, filtrez la liste si besoin, puis cochez la case de chaque client. Une barre apparaît en bas de l'écran avec le nombre de clients choisis. Au-delà de 100, elle affiche « Jusqu'à 100 à la fois. » et ses actions restent grisées. Les clients supprimés ne se sélectionnent pas. ![La liste Clients avec trois clients cochés et, en bas de l'écran, la barre de sélection : 3 sélectionné(s), puis Exporter, Bloquer et Supprimer.](https://docs.wajub.com/dashboard/fr/light/customers-bulk.webp) *La barre ne propose que les actions qui s'appliquent aux clients choisis.* 2. **Choisissez l'action** **Bloquer** et **Débloquer** n'apparaissent que si la sélection contient des clients à bloquer ou à débloquer. Quand elle mélange les deux, le bouton donne le nombre concerné, par exemple « Bloquer 2 » : un client déjà bloqué garde son motif. **Bloquer** ouvre le dialogue du motif, comme pour [un seul client](https://docs.wajub.com/dashboard/customers/block-disable-delete), puis **Bloquer les clients**. **Supprimer** demande une confirmation : les noms, e-mails et numéros de téléphone sont effacés, les paiements restent. Confirmez avec **Supprimer les clients**. 3. **Saisissez le code de sécurité** Le code saisi, l'action s'applique et un message donne le nombre de clients traités, par exemple « 3 clients bloqués. ». La sélection se vide. ## Exporter les clients En Production, **Exporter**, en haut de la liste, ouvre **Exporter les clients** : le fichier contient les clients que la liste affiche avec ses filtres, rappelés sous **Filtres conservés**. Choisissez le **Format**, **CSV**, **Excel**, **PDF** ou **JSON**, et si besoin une période avec le bouton **Date** sous **Période** : une période prête comme **30 derniers jours**, ou une **Période personnalisée**. Sans période, toutes les dates sont exportées. Puis **Exporter en CSV**, **Exporter en Excel**, **Exporter en PDF** ou **Exporter JSON**, selon le format. Le fichier se télécharge, et « Votre export est prêt » donne son nom. L'export ne demande pas de code de sécurité. Pour n'exporter que certains clients, sélectionnez-les, puis **Exporter** dans la barre du bas : **Exporter les clients sélectionnés** reprend seulement ceux-là, sans période. > [!NOTE] > **En Test ou au bout de vos exports** > > En Test, le dialogue indique que les exports ne contiennent que des données de production. Une > fois les exports du mois utilisés, il l'indique : un membre qui a **Gérer le compte** voit > **Passer à un forfait supérieur**, les autres sont invités à s'adresser au propriétaire de > l'organisation. --- # Fusionner deux clients URL: https://docs.wajub.com/fr/dashboard/customers/merge > Réunir les deux fiches d'un même client en une seule, avec l'aperçu de ce qui passe d'une fiche à l'autre avant de confirmer. Quand un même client a deux fiches, la fusion réunit ses paiements, ses factures et ses notes sur celle que vous gardez, et archive l'autre. Le propriétaire, un Administrateur, un Spécialiste support ou un rôle personnalisé qui a **Gérer les clients** peut fusionner deux clients, avec tous les forfaits. La fusion n'existe qu'en Production et demande le code de sécurité. ## Les étapes 1. **Ouvrez l'outil de fusion** Ouvrez **Paramètres › Fusions de clients**. Depuis la fiche d'un client, **Fusionner avec un autre client**, dans le menu à droite de **Modifier**, ouvre l'outil avec ce client déjà choisi comme celui à garder. 2. **Choisissez le client à garder** Sous **Client à conserver**, cherchez-le par son nom, son e-mail, son téléphone ou son **ID client**. Cette fiche reste et reçoit tout ce que contient l'autre. ![L'étape Clients d'une fusion : Restaurant Le Bastos choisi comme client à conserver, le champ Client à fusionner avec lui encore vide, et le bouton Vérifier la fusion.](https://docs.wajub.com/dashboard/fr/light/customers-merge.webp) *La fiche à conserver reçoit tout ce que contient l'autre.* 3. **Choisissez le client à fusionner** Sous **Client à fusionner avec lui**, choisissez la fiche en double, qui sera archivée. Puis **Vérifier la fusion**. 4. **Relisez ce qui va passer** L'étape **Examiner** montre les deux fiches côte à côte, **Conservé** et **Fusionné, puis archivé**, avec leur e-mail, leur téléphone et leurs paiements réussis. Dessous, la liste de ce qui change de fiche compte les paiements de tous statuts, les litiges, les factures, les demandes de remboursement, les moyens de paiement enregistrés, les fiches des liens de paiement, les notes et les adresses. 5. **Fusionnez les clients** Choisissez **Fusionner les clients**, puis saisissez le code de sécurité. **Clients fusionnés** confirme que tout appartient désormais à la fiche gardée, avec un bouton pour l'ouvrir. ## Après la fusion La fiche gardée reçoit aussi les étiquettes de l'autre, ainsi que son e-mail, son téléphone, le nom de l'entreprise et la description quand elle n'en avait pas. Ses totaux de paiements s'additionnent, et son activité garde une note qui mentionne la fusion. La fiche fusionnée rejoint les **Clients supprimés** de la liste. > [!NOTE] > **Une fusion ne s'annule pas** > > Les données passées sur la fiche gardée y restent. Avant de confirmer, vérifiez à l'étape > **Examiner** que les deux fiches désignent bien la même personne. --- # Tenir à jour une fiche client URL: https://docs.wajub.com/fr/dashboard/customers/profile > Ce que montre la fiche d'un client, de ses paiements à ses adresses, et comment la modifier, gérer ses moyens de paiement et y laisser des notes pour l'équipe. La fiche d'un client réunit ce qu'il vous a payé, ses coordonnées, ses adresses, ses moyens de paiement enregistrés et les notes de votre équipe. Tous les rôles ouvrent les fiches clients. Les modifier, gérer les adresses et les moyens de paiement, écrire une note ou utiliser **Recalculer** est réservé au propriétaire, aux Administrateurs, aux Spécialistes support et aux rôles personnalisés qui ont **Gérer les clients**. La modification de la fiche demande le code de sécurité, tout comme [bloquer, débloquer ou supprimer](https://docs.wajub.com/dashboard/customers/block-disable-delete) le client et le [fusionner](https://docs.wajub.com/dashboard/customers/merge) avec un autre. ## Ce que montre la fiche Ouvrez **Clients**, puis le nom du client. L'en-tête donne son nom, son statut, son type et son **ID client**, à copier pour le support ou votre équipe technique. Les onglets **Paiements**, **Remboursements** et **Litiges** n'apparaissent que si le client en a ; **Chronologie** reprend toute son activité. Sur **Vue d'ensemble**, **Total dépensé** couvre les 12 derniers mois en Production et toute la relation en Test, à côté du nombre de **Paiements** et de la date **Client depuis**. En Production, **Analyses de paiement** résume les 30 derniers jours : **Volume réussi**, **Total des paiements**, **Taux de réussite** et paiements **Échoué**. **Recalculer** les met à jour. Suivent les **Coordonnées**, les **Détails de l'entreprise** pour une entreprise, et les **Préférences**. ![La fiche du client Restaurant Le Bastos : statut Actif, type Entreprise et ID client, puis Total dépensé, Paiements et Client depuis, les Analyses de paiement, et à droite les Moyens de paiement et les Adresses.](https://docs.wajub.com/dashboard/fr/light/customers-profile.webp) *Les moyens de paiement et les adresses sont à droite de la fiche.* ## Modifier la fiche **Modifier** ouvre **Modifier le client**, en cinq onglets : **Général** pour le nom, les coordonnées, la devise, la langue et la description, puis **Adresse**, **Entreprise**, **Préférences** et **Étiquettes**. **Enregistrer les modifications** demande le code de sécurité. Les changements valent pour les prochains paiements, factures et reçus du client, pas pour ceux déjà émis. ## Adresses et moyens de paiement Sous **Moyens de paiement**, la fiche liste ceux que le client a enregistrés en payant, avec le badge **Par défaut**. Leur menu propose **Définir par défaut** ou **Retirer le moyen de paiement** : il ne pourra plus être débité, et le client pourra l'enregistrer de nouveau à son prochain paiement. Le tableau de bord ne permet pas d'en ajouter un. Sous **Adresses**, **Ajouter une adresse** demande son **Type**, **Facturation** ou **Livraison**, puis au moins la **Ligne d'adresse 1**, la **Ville** et le **Pays**. Cochez **En faire l'adresse par défaut** pour qu'elle remplace l'adresse par défaut de ce type. Le menu d'une adresse propose **Modifier l'adresse** et **Supprimer l'adresse**. ## Activité et notes **Activité et notes** liste les paiements, les remboursements et les litiges du client, du plus récent au plus ancien, et **Voir toute l'activité** ouvre la **Chronologie**. Pour laisser une consigne à l'équipe, écrivez-la dans le champ du bas, puis **Ajouter une note** : seuls vos membres voient les notes. Le menu d'une note propose **Épingler la note**, qui la garde en haut sous **Notes épinglées**, et **Supprimer la note**. --- # Passer en compte entreprise URL: https://docs.wajub.com/fr/dashboard/activation/switch-to-business > Faire vérifier une entreprise quand l'organisation a été vérifiée comme particulier, sans interrompre les paiements. Une organisation vérifiée comme **Individuel (Auto-entrepreneur, Freelance)** peut devenir une entreprise, une association ou un autre type d'organisation. Il faut pour cela un nouveau dossier, examiné par l'équipe conformité. Pendant ce temps, votre vérification actuelle reste active : les paiements et les transferts continuent jusqu'à l'approbation du nouveau dossier. Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer le compte** lance et suit le passage (voir [Rôles](https://docs.wajub.com/fr/dashboard#roles)). Il est ouvert avec tous les forfaits, en [Test comme en Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Le lancer et l'abandonner demandent le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) si votre dernière vérification a expiré. ## Les étapes 1. **Ouvrez la page Conformité** Ouvrez **Paramètres › Conformité**. Sous **Vérification terminée**, choisissez **Passer à un compte entreprise**. Le bouton n'apparaît que si le dossier en vigueur est celui d'un particulier vérifié. 2. **Choisissez le type d'organisation** La fenêtre rappelle ce que le nouveau dossier demande. Dans **Type d'organisation**, choisissez par exemple **Entreprise** ou **Association / ONG**, puis **Commencer la mise à niveau**. Si votre dernière vérification de sécurité a expiré, le code de sécurité est demandé d'abord. Le dossier entreprise s'ouvre alors à sa première étape. ![La fenêtre Passer à un compte entreprise : le rappel que la vérification actuelle reste active, le champ Type d'organisation et le bouton Commencer la mise à niveau.](https://docs.wajub.com/dashboard/fr/light/activation-upgrade-modal.webp) *Le type choisi pourra encore changer dans l'étape Détails de l'entreprise.* 3. **Complétez le dossier entreprise** Le dossier reprend votre dossier de particulier : activité, adresse, présence en ligne, documents et votre fiche, dont vous devenez le représentant légal. Tout sera examiné à nouveau. Ajoutez ce que demande le nouveau type : les documents de l'entreprise, les bénéficiaires effectifs s'il y en a, et une nouvelle vidéo de vérification de présence, car l'ancienne n'est pas reprise. Chaque étape est décrite dans [Vérifier son entreprise](https://docs.wajub.com/dashboard/activation/verify-business). 4. **Envoyez-le pour vérification** À la dernière étape, **Vérifier et soumettre**, choisissez **Soumettre pour vérification**. ## Suivre le nouveau dossier Sur **Paramètres › Conformité**, la carte **Passage au compte entreprise** suit le nouveau dossier sous le statut de l'ancien, toujours **Vérifié**. Elle affiche son statut, la date d'envoi et **Continuer la mise à niveau** tant qu'il n'est pas envoyé. Ce que l'équipe conformité demande sur ce dossier apparaît dans **Actions requises sur votre dossier entreprise**, et se traite comme l'explique [Suivre sa vérification](https://docs.wajub.com/dashboard/activation/track-verification). Quand le dossier entreprise est approuvé, il remplace celui de particulier : l'organisation reste en Production et le nouveau type s'affiche sur la page. S'il est rejeté, votre vérification de particulier reste en vigueur ; **Corriger et soumettre à nouveau** le rouvre, avec sous **Motif** la raison donnée. ## Abandonner le passage Tant que le dossier entreprise n'est pas envoyé, ou après un rejet, la carte propose **Abandonner la mise à niveau**. Une fenêtre demande confirmation : le dossier entreprise est mis de côté et ne pourra plus être envoyé, mais l'organisation garde sa vérification actuelle. Vous pourrez lancer un nouveau passage plus tard. Pendant l'examen, le bouton n'apparaît plus : le dossier entreprise ne peut plus être abandonné. ## Si le bouton refuse de démarrer Si l'équipe conformité attend encore une réponse sur votre dossier actuel, la fenêtre affiche « Répondez d'abord aux demandes ouvertes sur votre dossier, puis commencez la mise à niveau. » Fournissez d'abord les éléments listés dans **Actions requises**, puis recommencez une fois que l'équipe conformité les a acceptés. --- # Suivre sa vérification URL: https://docs.wajub.com/fr/dashboard/activation/track-verification > Lire le statut du dossier, répondre aux actions requises et aux demandes de l'équipe conformité, et confirmer le dossier chaque année. Une fois le dossier envoyé, **Paramètres › Conformité** dit où il en est. L'onglet **Vue d'ensemble** affiche le statut et ce que Wajub attend de vous ; l'onglet **Demandes** rassemble les questions de l'équipe conformité. Le propriétaire de l'organisation reçoit un e-mail quand le dossier est validé ou rejeté, et quand Wajub attend quelque chose de vous. Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer le compte** voit cette page et y répond, en Test comme en Production, avec tous les forfaits. Un Développeur, un Observateur ou un autre [rôle](https://docs.wajub.com/fr/dashboard#roles) qui a **Voir les paramètres** voit **Paramètres › Statut du compte** : le statut, le **Mode production** et les **Restrictions actives**, sans le contenu du dossier. Répondre ne demande pas de [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les statuts du dossier | Statut | Ce qu'il veut dire | | --------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Non soumis** | Le dossier est commencé mais pas envoyé : **Continuer la vérification** reprend où vous en étiez. | | **En cours d'examen** | L'équipe conformité examine le dossier, qui ne se modifie plus. Rien à faire, la page indique le délai habituel. | | **Action requise** | L'équipe a besoin d'autre chose avant de décider. Le dossier repart en examen quand tout est fourni. | | **Vérifié** | La [Production](https://docs.wajub.com/dashboard/getting-started/test-and-live) est déverrouillée. La page affiche **Vérifié le** avec la date. | | **Rejeté** | Le dossier n'a pas été approuvé : voir [Si le dossier est rejeté](#if-the-file-is-rejected). | ![Paramètres › Conformité, onglet Vue d'ensemble : la bannière Mise à jour demandée, le statut Vérifié, puis Actions requises avec un élément à fournir, son échéance et le bouton qui permet d'y répondre.](https://docs.wajub.com/dashboard/fr/light/activation-requirements.webp) *Chaque élément demandé a son échéance et son propre bouton.* ## Répondre à une action requise 1. **Ouvrez la liste des actions requises** Sous le statut, **Actions requises** compte les éléments à fournir. Chacun indique ce qui est demandé, la personne concernée s'il y a lieu, et son échéance. 2. **Fournissez l'élément demandé** Un document se téléverse sur place avec **Téléverser le document**. Pour le reste, le bouton de l'élément ouvre l'étape du dossier concernée, qui ne montre que ce qui est demandé : par exemple **Mettre à jour les informations de la société**, ou **Commencer la vérification de présence** pour une nouvelle vidéo, décrite dans [Vérifier une identité](https://docs.wajub.com/dashboard/activation/verify-identity). 3. **Attendez l'examen de votre réponse** L'élément passe à **En cours d'examen**, puis disparaît de la liste quand l'équipe conformité l'a accepté. ## Répondre à une demande Quand l'équipe conformité pose une question, elle apparaît dans **Demandes**, avec la date limite « Répondre avant le » suivie de la date. Ouvrez-la, écrivez dans **Votre réponse**, joignez au besoin jusqu'à dix fichiers de 10 Mo au plus avec **Ajouter un fichier**, puis **Envoyer**. Une fois la demande traitée, elle affiche **Cette demande est fermée. Vous ne pouvez plus répondre.** ## Quand une échéance est dépassée Un élément en retard passe à **En retard**. Si l'organisation est déjà vérifiée, ses transferts se mettent aussi en pause : l'élément affiche **Les transferts sont en pause jusqu'à son acceptation.** et la pause apparaît dans **Restrictions actives**. Fournir l'élément ne suffit pas : les transferts reprennent quand l'équipe conformité l'a accepté. Les paiements, eux, continuent d'arriver. ## La confirmation annuelle Un an après la vérification, Wajub demande de confirmer que le dossier est toujours exact. Avant cette date, **Actions requises** affiche une **Revue périodique**. Cochez **Je confirme que les informations de mon dossier sont toujours exactes**, décrivez au besoin un changement d'activité, d'adresse ou de propriétaires dans **Qu'est-ce qui a changé ? (facultatif)**, puis **Envoyer ma confirmation**. L'organisation continue de fonctionner jusqu'à l'échéance. Une pièce d'identité ou une licence qui arrive à expiration est demandée de la même façon, dans **Actions requises** : l'élément indique **Ce document a expiré ou expire bientôt. Merci d'en envoyer un en cours de validité.** ## Si l'adresse du propriétaire est jetable Quand le propriétaire de l'organisation se connecte avec une adresse e-mail jetable, **Restrictions actives** affiche **Gel du compte (lecture seule)**, **Révocation de l'accès API** et **Désactivation des webhooks**, chacune avec « Le propriétaire de cette organisation utilise une adresse e-mail jetable (...). Cette restriction est levée dès qu'il utilise une adresse permanente dans les paramètres de son compte. » Les paiements, les transferts et les remboursements s'arrêtent, les clés API ne marchent plus et les webhooks ne sont plus envoyés. Le propriétaire peut toujours se connecter : dès qu'il [change d'adresse e-mail](https://docs.wajub.com/dashboard/account/profile#change-your-email) pour une adresse permanente, les restrictions sont levées. ## Si le dossier est rejeté La page affiche **Vérification rejetée** et, sous **Motif**, la raison donnée par l'équipe conformité. Choisissez **Corriger et soumettre à nouveau** : le dossier se rouvre, vous corrigez ce qui est indiqué, puis vous l'envoyez comme la première fois. Si l'organisation était déjà vérifiée, la Production se verrouille et tous les membres repassent en Test jusqu'à une nouvelle validation. Pour une question sur votre dossier, **Contacter le support** en haut de la page écrit à l'équipe conformité. --- # Vérifier son entreprise URL: https://docs.wajub.com/fr/dashboard/activation/verify-business > Remplir et envoyer le dossier d'activation depuis Paramètres › Conformité, étape par étape, pour déverrouiller la Production. Avant d'encaisser de l'argent réel, Wajub vérifie qui vous êtes et ce que vous vendez. Le dossier se remplit en ligne, en six étapes au plus, et la Production se déverrouille quand Wajub l'a validé. Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer le compte** remplit et envoie le dossier ; un Développeur, un Observateur ou un autre [rôle](https://docs.wajub.com/fr/dashboard#roles) qui a **Voir les paramètres** voit seulement où il en est, dans **Paramètres › Statut du compte**. Le dossier se remplit en [Test](https://docs.wajub.com/fr/dashboard#sandbox-and-live), avec tous les forfaits. L'e-mail et le téléphone de l'entreprise sont confirmés par un code qui leur est envoyé, mais le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est pas demandé. ## Les étapes 1. **Ouvrez le dossier** Ouvrez **Paramètres › Conformité**, puis **Commencer la vérification**. Un compteur indique l'étape en cours ; **Continuer** l'enregistre et passe à la suivante, **Précédent** revient en arrière. Vous pouvez vous arrêter à tout moment : le bouton devient **Continuer la vérification**. ![Paramètres › Conformité : le titre Commencer votre vérification, la liste des étapes du dossier avec leur avancement, puis le bouton Commencer la vérification.](https://docs.wajub.com/dashboard/fr/light/activation-compliance-start.webp) *Tant que le dossier n'est pas envoyé, la Production reste verrouillée.* 2. **Décrivez votre activité** Dans **Activité commerciale**, choisissez la **Catégorie d'entreprise** et l'**Activité précise**, puis rédigez la **Description de l'activité**, de 10 à 1 000 caractères : ce que vous vendez et à qui. Une activité réglementée affiche « Cette activité est réglementée : vous devrez fournir une licence. » 3. **Renseignez l'entreprise** Dans **Détails de l'entreprise**, choisissez le **Type d'organisation** et la **Structure juridique**, puis saisissez le **Nom légal** et l'**Identifiant fiscal ou numéro d'immatriculation** tels qu'ils figurent sur vos documents officiels, et l'**Adresse de l'entreprise**. Si personne ne détient 25 % ou plus de l'entreprise, cochez **Personne ne détient ni ne contrôle 25 % ou plus de l'entreprise** : ce choix ne peut plus changer une fois le dossier envoyé. 4. **Confirmez l'e-mail et le téléphone de l'entreprise** Sous **Contact de l'entreprise**, saisissez l'**E-mail professionnel** et le **Téléphone de l'entreprise**. Pour chacun, choisissez **Envoyer le code**, saisissez le code reçu dans **Code de vérification**, puis **Vérifier**. 5. **Ajoutez votre présence en ligne** Dans **Présence en ligne**, choisissez la **Plateforme** (site web, application, réseau social) et l'**Adresse (URL)**, puis **Ajouter ce canal**. Une présence au moins est obligatoire ; **Ajouter un canal** en ajoute une autre. 6. **Téléversez les documents de l'entreprise** **Documents d'entreprise** liste les pièces demandées pour votre type d'organisation, au format PDF, JPG ou PNG, jusqu'à 10 Mo chacune. Une société fournit par exemple le **Registre de commerce (RCCM)**, les **Statuts**, le **Plan de localisation** et l'**Attestation fiscale** ; une association, son **Récépissé, agrément ou autorisation** et l'**Acte de nomination du représentant légal**. Pour une activité réglementée, **Ajouter une licence** demande son type, son numéro, l'autorité qui l'a délivrée et le document. Avec le type **Individuel (Auto-entrepreneur, Freelance)** et sans activité réglementée, vous passez directement à l'étape suivante. ![Documents de votre entreprise : Registre de commerce (RCCM), Statuts, Plan de localisation et Attestation fiscale, chacun marqué obligatoire et Manquant, avec sa zone de téléversement.](https://docs.wajub.com/dashboard/fr/light/activation-documents.webp) *Chaque pièce est examinée par l'équipe conformité de Wajub.* 7. **Ajoutez les personnes** Dans **Personnes**, choisissez **Ajouter une personne** pour le représentant légal, puis pour chaque **Bénéficiaire effectif**, qui détient ou contrôle 25 % ou plus de l'entreprise. Cochez son **Rôle**, remplissez son identité, puis **Enregistrer la personne** ; téléversez ensuite sa pièce d'identité, carte d'identité ou passeport, sur sa fiche. Une personne qui a plusieurs rôles n'est saisie qu'une fois, avec tous ses rôles cochés : une deuxième fiche pour la même personne est refusée. Sur la fiche du représentant légal, téléversez aussi un **Justificatif de domicile** ou, si aucune facture n'est à son nom, un **Plan de localisation du domicile**. Avec le type **Individuel (Auto-entrepreneur, Freelance)**, l'étape s'appelle **Votre identité** : choisissez **Ajouter mon profil**, puis fournissez les mêmes documents pour vous-même. Le représentant légal (ou vous-même, avec le type Individuel) enregistre aussi une courte vidéo : [Vérifier une identité](https://docs.wajub.com/dashboard/activation/verify-identity) explique comment. 8. **Envoyez le dossier** **Vérifier et soumettre** récapitule tout le dossier. **Informations manquantes** liste ce qui reste à faire, chaque section ayant son bouton **Modifier** ; sinon, la page affiche **Tout est prêt**. Choisissez **Soumettre pour vérification**. ## Après l'envoi **Paramètres › Conformité** affiche **Votre dossier est en cours d'examen**, avec le délai habituel en jours ouvrés, et le dossier ne se modifie plus. Wajub écrit au propriétaire de l'organisation dès que la décision est prise ou s'il lui faut autre chose ; en attendant, vous pouvez continuer en Test. [Suivre sa vérification](https://docs.wajub.com/dashboard/activation/track-verification) explique chaque statut et comment répondre à une demande. --- # Vérifier une identité URL: https://docs.wajub.com/fr/dashboard/activation/verify-identity > Enregistrer la vérification de présence du représentant légal, depuis l'ordinateur ou en envoyant un lien sur son téléphone. La **Vérification de présence** est un court selfie vidéo : il prouve que la personne de la pièce d'identité existe et se tient devant la caméra. Le représentant légal l'enregistre pour une entreprise ; avec le type **Individuel (Auto-entrepreneur, Freelance)**, vous l'enregistrez pour vous-même. Une autre personne du dossier ne l'enregistre que si Wajub le lui demande. Comme le reste du dossier, elle se lance depuis **Paramètres › Conformité** par le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer le compte** (voir [Rôles](https://docs.wajub.com/fr/dashboard#roles)). Elle se fait en [Test](https://docs.wajub.com/fr/dashboard#sandbox-and-live), avec tous les forfaits, et ne demande pas de [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). La personne filmée, elle, n'a pas besoin de compte Wajub. ## Les étapes 1. **Ouvrez la fiche de la personne** Dans le dossier, ouvrez l'étape **Personnes**, ou **Votre identité** avec le type Individuel. Sous la fiche du représentant légal, le bloc **Vérification de présence** est marqué obligatoire et propose deux boutons. ![L'étape Personnes : la fiche du représentant légal avec sa pièce d'identité, puis le bloc Vérification de présence et les boutons Enregistrer maintenant et Continuer sur un téléphone.](https://docs.wajub.com/dashboard/fr/light/activation-liveness-card.webp) *Le bloc n'apparaît que pour la personne qui doit enregistrer la vidéo.* 2. **Enregistrez la vidéo sur cet ordinateur** Si la personne est devant votre écran, choisissez **Enregistrer maintenant**. Elle lit la notice **Avant de commencer**, coche la case qui donne son accord et autorise la caméra. Elle suit ensuite les consignes à l'écran, qui durent environ une minute, puis envoie la vidéo. Aucun son n'est enregistré. 3. **Ou envoyez-lui un lien** Si elle est ailleurs, ou si votre ordinateur n'a pas de caméra, choisissez **Continuer sur un téléphone**. La fenêtre affiche un QR code, le **Lien de vérification de vivacité** à copier et sa date d'expiration. Si la personne est à côté de vous, elle scanne le QR code ; sinon, **Envoyer par WhatsApp** prépare un message avec le lien, à adresser au bon contact. ![La fenêtre Continuer sur un téléphone : un QR code, le lien de vérification avec son bouton de copie, la date d'expiration, puis Envoyer par WhatsApp et Révoquer le lien.](https://docs.wajub.com/dashboard/fr/light/activation-liveness-link.webp) *Créer un nouveau lien désactive le précédent.* Sur son téléphone, elle arrive sur une page Wajub, dans la langue de son navigateur, qui nomme votre entreprise et la guide jusqu'à l'envoi de la vidéo. 4. **Suivez le résultat** Une fois la vidéo envoyée, le bloc affiche **En cours d'examen**, puis **Réussi** quand Wajub l'a validée. Vous n'avez pas besoin d'attendre : le dossier peut partir pour vérification dès que la vidéo est envoyée. ## Gérer le lien Tant qu'un lien peut servir, la fiche indique jusqu'à quelle date il est valable, et **Révoquer le lien** le désactive aussitôt, par exemple si vous l'avez envoyé au mauvais numéro. Le lien cesse aussi de fonctionner quand il expire, après quelques vidéos envoyées, quand une vidéo est validée ou refusée par l'équipe Wajub, ou quand le dossier est envoyé. La page dit alors à la personne de vous en demander un nouveau, ou qu'elle n'a plus rien à faire si sa vidéo a déjà été acceptée ou est en cours d'examen. Pour un nouveau lien, choisissez à nouveau **Continuer sur un téléphone**. ## Si la vidéo est refusée Le bloc passe à **Échoué** et affiche **Vérification de vivacité refusée** avec la raison donnée par Wajub. Les deux boutons reviennent : enregistrez une nouvelle vidéo de la même façon. Après plusieurs essais dans la journée, le tableau de bord répond « Trop de tentatives de vérification. Veuillez réessayer dans 24 heures. » Si Wajub demande une nouvelle vidéo après l'envoi du dossier, la demande apparaît dans **Paramètres › Conformité**, comme l'explique [Suivre sa vérification](https://docs.wajub.com/dashboard/activation/track-verification). ## Si la caméra ne s'ouvre pas La page dit ce qui bloque et comment le régler. Avec **L'accès à la caméra a été refusé**, autorisez la caméra pour ce site depuis l'icône à côté de la barre d'adresse, puis réessayez. Avec **Aucune caméra détectée**, passez par **Continuer sur un téléphone**. Un lien ouvert depuis WhatsApp, Instagram ou Facebook s'affiche parfois dans le navigateur de l'application, qui ne filme pas : la page demande alors de l'ouvrir dans Safari ou Chrome. --- # Trouver ses clés API URL: https://docs.wajub.com/fr/dashboard/developers/api-keys > Où sont les clés API dans le tableau de bord, qui les voit, et où lire comment les créer, les restreindre et les régénérer. Les clés API permettent à votre site ou à votre application d'appeler Wajub. Elles se trouvent dans **Paramètres › Développeurs › Clés API**. Leur création et leur usage sont décrits dans la documentation développeurs ; cette page dit seulement où les trouver. Le propriétaire, un Administrateur, un Développeur, un Utilisateur de test, en Test seulement, ou un rôle personnalisé qui a **Gérer les clés API** ouvre cette page ; pour les autres membres, l'entrée n'apparaît pas dans les paramètres. Tous les forfaits y ont accès. Créer, modifier, afficher, régénérer ou révoquer une clé demande le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Ce que montre la page Chaque [environnement](https://docs.wajub.com/fr/dashboard#sandbox-and-live) a ses propres clés : en Test, la page rappelle **Vous consultez des clés de test.**, et les clés de Production n'apparaissent qu'une fois passé en Production. La page range les clés en trois groupes. La **Clé publiable** identifie votre compte dans le code qui tourne chez le payeur et peut être partagée. Les **Clés secrètes** donnent un accès complet et ne servent que depuis votre serveur. Les **Clés restreintes** n'ouvrent que les permissions choisies, pour un outil tiers par exemple. **Créer une clé API** ouvre le formulaire de création. Sur une clé, **Afficher** montre de nouveau sa valeur, **Régénérer** la remplace, **Dans 24 heures** ou **Maintenant**, et **Révoquer la clé** la coupe pour de bon. **Copie rapide** donne la clé publiable et la première clé secrète, avec **Copier les lignes .env** pour les coller dans votre fichier d'environnement. ## Dans la documentation développeurs | Pour | Lire | | ------------------------------------------------ | --------------------------------------------------------------------------------------- | | Créer sa première clé et la placer dans son code | [Configurer votre compte](https://docs.wajub.com/fr/getting-started/dashboard-setup#3-create-your-first-api-key) | | Comprendre les types de clés | [Environnements et API keys](https://docs.wajub.com/fr/getting-started/environments#key-types) | | Limiter ce qu'une clé peut faire | [Environnements et API keys](https://docs.wajub.com/fr/getting-started/environments#narrowing-what-a-key-can-do) | | Régénérer une clé qui a fuité | [Configurer votre compte](https://docs.wajub.com/fr/getting-started/dashboard-setup#7-roll-a-key-that-leaked) | | Webhooks, Konsole et CLI | [Outils développeurs](https://docs.wajub.com/fr/developer-tools) | --- # Créer son compte URL: https://docs.wajub.com/fr/dashboard/getting-started/create-account > S'inscrire sur le tableau de bord Wajub, confirmer son e-mail, puis créer l'organisation qui encaissera les paiements. Votre compte vous connecte au tableau de bord ; l'organisation est l'entreprise pour laquelle vous encaissez, avec ses propres paiements, ses membres et ses réglages. Un même compte peut appartenir à plusieurs organisations. Tout le monde peut créer un compte et une organisation, sans carte bancaire. Vous devenez le propriétaire de l'organisation, avec tous les droits décrits dans [Rôles](https://docs.wajub.com/fr/dashboard#roles). L'organisation démarre en [Test](https://docs.wajub.com/fr/dashboard#sandbox-and-live), et aucun [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est demandé. ## Les étapes 1. **Remplissez le formulaire d'inscription** Sur **Créez votre compte**, saisissez votre **Nom complet**, votre **E-mail professionnel** et un **Mot de passe** : au moins 12 caractères, avec des majuscules, des minuscules et des chiffres, et absent des listes de mots de passe divulgués. Acceptez les conditions d'utilisation et la politique de confidentialité, puis choisissez **Créer un compte gratuit**. Une adresse déjà inscrite est refusée : connectez-vous plutôt. Une adresse jetable est refusée aussi : utilisez une adresse permanente. 2. **Confirmez votre e-mail** L'écran **Vérifiez votre e-mail** attend le code à six chiffres que Wajub vient de vous envoyer. Saisissez-le dans **Code de vérification**, puis choisissez **Vérifier l'e-mail**. Le code expire au bout de 10 minutes ; **Renvoyer le code** en envoie un nouveau après une minute d'attente, et **Modifier l'e-mail** corrige une adresse mal saisie. 3. **Nommez votre organisation** **Créez votre organisation** ne demande que le **Nom de l'organisation**. Vos clients le voient sur les reçus et les pages de paiement, et vous pourrez le changer plus tard. Choisissez **Créer une organisation** : l'accueil du tableau de bord s'ouvre. ![Créez votre organisation : le champ Nom de l'organisation rempli avec Kribi Coffee SARL, puis le bouton Créer une organisation.](https://docs.wajub.com/dashboard/fr/light/getting-started-create-organization.webp) *L'e-mail et le téléphone de l'entreprise sont demandés plus tard, dans le dossier d'activation.* 4. **Dites ce que vous voulez faire en premier** Une fenêtre demande **Que voulez-vous faire en premier ?** et ne se ferme qu'avec une réponse : **Intégrer via l'API**, **Accepter des paiements avec des liens**, **En personne ou au détail** ou **Envoyer des transferts**. Pour encaisser sans écrire de code, choisissez **Accepter des paiements avec des liens**, marqué **Recommandé**. Le bouton du bas vous laisse décider plus tard. Votre choix ne bloque rien : il range seulement les étapes de la liste que l'accueil affiche en Production, que vous pouvez faire dans n'importe quel ordre. ## Après la création L'accueil affiche **Préparez le passage en production**. Ses deux premières étapes, les clés API et le paiement de test, servent à ceux qui branchent Wajub sur un site ; la troisième, la vérification de votre entreprise, concerne tout le monde. Tant qu'elle n'est pas validée, l'organisation reste en Test : [Vérifier son entreprise](https://docs.wajub.com/dashboard/activation/verify-business) décrit le dossier, et [Passer en Production](https://docs.wajub.com/dashboard/getting-started/test-and-live) ce qui change ensuite. Pour ajouter une autre organisation, ouvrez le sélecteur d'organisation en haut du menu, puis **Créer une organisation**. Chaque organisation a ses propres membres, ses données et sa propre vérification. --- # Découvrir le tableau de bord URL: https://docs.wajub.com/fr/dashboard/getting-started/dashboard-tour > Le menu, la barre du haut, la recherche, les raccourcis clavier, la langue et le passage d'une organisation à l'autre. Le tableau de bord tient en trois zones : le menu à gauche, la barre du haut et la page ouverte. Chaque membre voit le menu de son [rôle](https://docs.wajub.com/fr/dashboard#roles) : une entrée que son rôle n'ouvre pas n'apparaît pas. En [Test](https://docs.wajub.com/fr/dashboard#sandbox-and-live), les modules réservés à la Production quittent aussi le menu. Changer de langue, de thème ou d'organisation ne demande ni forfait particulier ni [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Le menu En haut du menu, le sélecteur d'organisation affiche le nom de l'organisation ouverte, votre rôle et son statut. Viennent ensuite deux listes : la première avec **Tableau de bord**, **Paiements**, **Factures**, **Clients**, **Transferts**, **Liens de paiement** et **Sync**, puis la seconde, en bas, avec **Revenus**, **Taxe**, **Shield**, **Orchestration**, **Paramètres** et **Assistance**. ![Le menu du tableau de bord en Production : le sélecteur d'organisation Kribi Coffee SARL en haut, la première liste de Tableau de bord à Sync, puis la seconde, en bas, de Revenus à Assistance.](https://docs.wajub.com/dashboard/fr/light/getting-started-sidebar.webp) *Une entrée avec un cadenas ouvre la page de mise à niveau.* Un module que votre forfait n'inclut pas reste dans le menu, avec un cadenas : [Modules hors de votre forfait](https://docs.wajub.com/fr/dashboard#modules-outside-your-plan) dit ce qu'il affiche. Sur un téléphone ou une petite tablette, le menu devient une barre en bas de l'écran avec le tableau de bord et le module ouvert ; **Plus** ouvre les autres entrées. ## La barre du haut À gauche, la barre affiche le titre de la page. Le champ de recherche ouvre la palette de commandes. À droite, le sélecteur d'environnement passe de **Test** à **Production**, comme l'explique [Passer en Production](https://docs.wajub.com/dashboard/getting-started/test-and-live). Votre avatar ouvre le menu du compte. En Test, une bande en haut de chaque page rappelle « Données de test uniquement. Aucun argent réel ne circule ici. » ## La palette de commandes Ctrl + K, ou Cmd + K sur Mac, ouvre la palette depuis n'importe quelle page. Tapez le nom d'une page, d'une action ou d'un client : la palette propose les pages, les réglages et les données qui correspondent. Un premier caractère restreint la recherche : | Tapez | Pour chercher dans | | ----- | --------------------------------------------------------------------- | | `>` | **Actions** | | `@` | **Membres et organisations** | | `/` | **Rechercher des données** : paiements, clients, transferts, factures | | `?` | **Aide**, qui rappelle ces préfixes | Une entrée réservée à la Production ou absente de votre forfait reste visible avec la raison : **Production uniquement** ou **Pas dans votre forfait**. ## Les raccourcis clavier Les raccourcis s'enchaînent touche après touche. G puis une lettre ouvre un module : G puis P pour **Paiements**, G puis C pour **Clients**, G puis S pour **Paramètres**. C puis une lettre crée quelque chose : C puis L pour **Créer un lien de paiement**, C puis C pour **Ajouter un client**, C puis I pour **Créer une facture**, C puis T pour **Créer un transfert**. Dans le menu, une entrée montre son raccourci au survol, et toutes le montrent dès que vous appuyez sur G. La touche ? ouvre **Raccourcis clavier**, la liste complète. Les raccourcis ne se déclenchent jamais pendant que vous écrivez dans un champ. Si vous utilisez la saisie vocale, désactivez **Utiliser les raccourcis à une touche** dans cette même fenêtre : votre choix est gardé, et Ctrl + K reste actif. En Test, le raccourci d'un module réservé à la Production ne l'ouvre pas : un message indique « Disponible uniquement en production » et ce que vous pouvez faire. ## Langue, thème et devise Le menu du compte regroupe vos réglages personnels. **Langue** choisit le français ou l'anglais pour le tableau de bord et pour les e-mails que Wajub vous envoie ; la langue que vos clients voient au paiement ne change pas. Validez avec **Appliquer**. **Thème** propose **Système**, **Clair** ou **Sombre**. **Devise d'affichage** ajoute, pour vous seul, une conversion à côté des montants principaux de l'accueil ; les montants eux-mêmes ne changent pas. ## Changer d'organisation Si vous êtes membre de plusieurs organisations, cliquez sur le nom en haut du menu. **Vos organisations** les liste, chacune avec son identifiant et son statut ; au-delà de huit, un champ **Rechercher une organisation** apparaît. Choisissez-en une : le tableau de bord s'y ouvre, dans l'environnement où vous l'aviez laissée. Le même menu propose **Créer une organisation** et **Gérer les organisations**. --- # Recevoir un premier transfert URL: https://docs.wajub.com/fr/dashboard/getting-started/first-payout > Les huit étapes entre la création de votre compte Wajub et le premier transfert vers votre numéro Mobile Money ou votre compte bancaire. Cette page suit le chemin complet, de l'inscription au premier transfert vers votre propre compte. Chaque étape renvoie à la page qui la détaille. Tout le monde peut créer un compte et une organisation. Le dossier d'activation est envoyé par le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer le compte**. Les liens de paiement, les factures et les transferts ne marchent qu'en Production, donc après l'activation. Ajouter un compte de versement et envoyer un transfert demandent le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les étapes 1. **Créez votre compte** Sur **Créez votre compte**, saisissez votre **Nom complet**, votre **E-mail professionnel** et un **Mot de passe**, acceptez les conditions, puis choisissez **Créer un compte gratuit**. Wajub vous envoie un code à six chiffres : saisissez-le dans **Code de vérification**, sur l'écran **Vérifiez votre e-mail**. Le code expire au bout de 10 minutes, et **Renvoyer le code** en envoie un nouveau après une minute d'attente. [Créer son compte](https://docs.wajub.com/dashboard/getting-started/create-account) détaille chaque écran. 2. **Créez votre organisation** **Créez votre organisation** ne demande que le **Nom de l'organisation** : vos clients le voient sur les reçus et les pages de paiement, et vous pourrez le changer plus tard. Après **Créer une organisation**, vous en êtes le propriétaire. Le tableau de bord demande alors **Que voulez-vous faire en premier ?** : pour encaisser sans écrire de code, choisissez **Accepter des paiements avec des liens**. L'organisation démarre en **Test**, où les paiements sont simulés, et **Production** reste verrouillé. L'accueil affiche la liste **Préparez le passage en production**. Si vous avez choisi les liens, elle tient en une étape, la vérification du compte ; les clés API et le paiement de test ne sont demandés qu'à ceux qui branchent Wajub sur un site. [Passer en Production](https://docs.wajub.com/dashboard/getting-started/test-and-live) explique les deux environnements. 3. **Activez votre compte** Ouvrez **Paramètres › Conformité**, puis **Commencer la vérification**. Le dossier passe par votre **Activité commerciale**, les **Détails de l'entreprise**, votre **Présence en ligne**, les **Documents d'entreprise** et les **Personnes** qui dirigent l'entreprise (**Votre identité** avec le type **Individuel (Auto-entrepreneur, Freelance)**). Une fois le dossier envoyé, la page affiche **Votre dossier est en cours d'examen** avec le délai habituel. Quand Wajub valide le dossier, la Production se déverrouille et le sélecteur en haut à droite permet d'y passer. Si le dossier est refusé, la page indique ce qu'il faut corriger et propose **Corriger et soumettre à nouveau**. [Vérifier son entreprise](https://docs.wajub.com/dashboard/activation/verify-business) détaille chaque étape du dossier, et [Suivre sa vérification](https://docs.wajub.com/dashboard/activation/track-verification) chaque statut. Les pièces demandées sont listées dans [Activation du compte et KYC](https://docs.wajub.com/fr/getting-started/account-activation). 4. **Activez vos moyens de paiement** La validation du dossier ouvre la Production, mais ne branche aucun moyen de paiement. Tant qu'aucun n'est actif, l'accueil affiche **Activez vos moyens de paiement** : un lien ou une facture que vous partagez ne peut pas être payé. Passez en **Production**. Si vous avez déjà un compte chez un prestataire de paiement, choisissez **Connecter un fournisseur** et saisissez vos identifiants : il encaisse dès qu'il est connecté. Sinon, choisissez **Demander le rail Wajub** pour encaisser sur les contrats de Wajub (Mobile Money et plus) : vous choisissez vos pays et vos canaux, vous vérifiez les tarifs et vous signez. Wajub examine la demande, et l'accueil affiche **Vos moyens de paiement sont en cours d'examen** en attendant. [Connecter un fournisseur](https://docs.wajub.com/dashboard/orchestration/connect-provider) et [Demander le rail Wajub](https://docs.wajub.com/dashboard/orchestration/rail) détaillent les deux voies. 5. **Créez un lien de paiement ou une facture** En **Production**, ouvrez **Liens de paiement › Créer un lien** pour une page de paiement à partager, ou **Factures › Créer une facture** pour facturer un client précis. [Créer un lien de paiement](https://docs.wajub.com/dashboard/payment-links/create) et [Créer et envoyer une facture](https://docs.wajub.com/dashboard/invoices/create) détaillent chaque écran. 6. **Suivez le paiement** **Paiements** liste chaque paiement avec son statut. Un paiement **Réussi** est encaissé ; **En attente** et **En traitement** attendent encore le client ou l'opérateur. [Cycle de vie d'un paiement](https://docs.wajub.com/fr/payments/lifecycle) explique chaque statut. 7. **Ajoutez un compte de versement** Ouvrez **Paramètres › Transferts › Comptes de versement**, puis **Ajouter un compte de versement** : un numéro Mobile Money ou un compte bancaire. Le formulaire passe par **Pays**, **Méthode**, **Détails** et **Examiner**, et l'enregistrement demande le code de sécurité. Vous ne faites cette étape qu'une fois par compte. 8. **Envoyez votre premier transfert** **Transferts** affiche votre **Solde disponible**. Choisissez **Créer un transfert**, puis le **Compte de versement** et le **Montant**, et **Vérifier le transfert**. Le bouton suivant rappelle la somme, par exemple **Envoyer 150 000 FCFA**, et demande le code de sécurité. Un transfert envoyé ne peut plus être annulé, sauf tant que sa page affiche **En attente du moyen de paiement** : **Annuler le transfert** rend alors son montant à votre solde. Un transfert est traité sous 1 à 3 jours ouvrés selon le moyen de paiement. S'il est retenu pour vérification, sa page affiche **Ce transfert a été signalé et attend une vérification avant de pouvoir partir.** > [!NOTE] > **Quand un paiement devient disponible** > > Un paiement réussi ne rejoint pas tout de suite le **Solde disponible** : il est d'abord réglé, > et l'accueil indique la date à laquelle le montant en attente le sera. > [Solde et règlements](https://docs.wajub.com/fr/payouts/balance) explique ce délai. --- # Passer en Production URL: https://docs.wajub.com/fr/dashboard/getting-started/test-and-live > Quand la Production se déverrouille, comment passer de Test à Production et revenir, et pourquoi chaque membre a son propre environnement. Une nouvelle organisation travaille en **Test**, où les paiements sont simulés. La **Production**, où l'argent circule pour de vrai, se déverrouille quand Wajub a validé la vérification de votre entreprise. Les rôles qui peuvent basculer sont listés dans [Test et Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), avec les modules et les actions qui n'existent qu'en Production. Un Utilisateur de test, l'un des [rôles](https://docs.wajub.com/fr/dashboard#roles), reste toujours en Test. Les deux environnements existent avec tous les forfaits, et basculer ne demande pas de [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les étapes 1. **Vérifiez que la Production est déverrouillée** En haut à droite, le sélecteur d'environnement a deux boutons, **Test** et **Production**. Tant que l'organisation n'est pas activée, **Production** porte un cadenas. Cliquez dessus : **Mode production verrouillé** dit où en est la vérification et propose **Commencer la vérification**, **Voir où en est la vérification** pendant l'examen, ou **Examiner la vérification** si le dossier a été rejeté ou si Wajub attend une action de votre part. ![Le sélecteur d'environnement sur Test, le bouton Production avec un cadenas, et sous lui Mode production verrouillé, le message Complétez la vérification de votre compte pour débloquer les paiements en production, puis le bouton Commencer la vérification.](https://docs.wajub.com/dashboard/fr/light/getting-started-environment-locked.webp) *Le bouton mène à Paramètres › Conformité, où se trouve le dossier d'activation.* [Vérifier son entreprise](https://docs.wajub.com/dashboard/activation/verify-business) décrit ce dossier, et [Suivre sa vérification](https://docs.wajub.com/dashboard/activation/track-verification) ce qui se passe une fois envoyé. 2. **Passez en Production** Une fois l'organisation activée, le cadenas disparaît. Choisissez **Production** dans le sélecteur. Si un formulaire ouvert a des modifications non enregistrées, le tableau de bord demande d'abord **Quitter sans enregistrer ?** La page se recharge en Production : la bande de Test disparaît et les modules réservés à la Production reviennent dans le menu. 3. **Revenez en Test quand vous voulez** Choisissez **Test** dans le même sélecteur. La palette de commandes (Ctrl + K) propose aussi **Passer en production** ou **Passer en mode test**, selon l'environnement où vous êtes. ## Un environnement par membre L'environnement est un réglage personnel : passer en Production ne change rien pour les autres membres, qui restent là où ils étaient. Le tableau de bord le retient pour chaque organisation, et vous retrouvez la vôtre dans l'environnement où vous l'avez laissée. Une personne qui rejoint une organisation déjà activée arrive directement en Production. Celles qui étaient membres avant l'activation, vous compris, restent en Test jusqu'à ce qu'elles basculent. ## Quand une page n'existe qu'en Production En Test, un lien vers un module réservé à la Production vous ramène à la page précédente, ou à l'accueil, avec un message comme « Disponible uniquement en production : Factures. » Un raccourci clavier affiche le même message sans changer de page. La suite du message dit quoi faire selon votre situation : | Votre situation | Le message ajoute | | --------------------------------------- | --------------------------------------------------------------------------------------- | | Vous pouvez basculer | « Passez en production pour l'utiliser. » | | Votre rôle ne permet pas de basculer | « Demandez l'accès à la production à un administrateur de votre compte. » | | Vous êtes Utilisateur de test | « Votre rôle est limité à l'environnement de test. » | | L'organisation n'est pas encore activée | « Terminez la vérification de votre compte pour passer en production. » | | La vérification est en cours d'examen | « Votre vérification est en cours d'examen. Nous vous informerons une fois approuvée. » | Si votre dossier a été rejeté ou si Wajub attend une action de votre part, le message renvoie à **Conformité**, comme l'explique [Suivre sa vérification](https://docs.wajub.com/dashboard/activation/track-verification). --- # Retrouver un terme connu URL: https://docs.wajub.com/fr/dashboard/getting-started/vocabulary > Les mots que vous employiez sur une autre plateforme de paiement, ce qu'ils s'appellent dans Wajub et où les trouver dans le tableau de bord. Chaque plateforme de paiement a ses mots. Si vous arrivez d'une autre, cette page fait correspondre ceux que vous connaissez à ceux du tableau de bord, et dit où les trouver. Tout membre peut s'en servir, sur tous les forfaits. Chaque écran reste soumis à son [rôle](https://docs.wajub.com/fr/dashboard#roles), et plusieurs n'existent qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). ## Chercher avec votre mot La recherche connaît ces mots. Ouvrez-la avec Ctrl + K, ou Cmd + K sur Mac, et tapez le vôtre, par exemple `retrait` : la ligne trouvée indique **« retrait » se dit ici « Transferts »**, et Entrée ouvre la page. [Découvrir le tableau de bord](https://docs.wajub.com/dashboard/getting-started/dashboard-tour) présente la recherche. ## L'argent qui entre | Vous disiez | Dans Wajub | Où | | ----------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------- | | Transaction, encaissement, collecte, pay-in, cash-in, dépôt | Un **paiement** | **Paiements** | | Page de paiement, bouton de paiement, boutique, cagnotte | Un **lien de paiement** | **Liens de paiement** | | Demande de paiement, facture client | Une **facture** | **Factures** | | Chargeback, rétrofacturation, contestation | Un **litige** | **Paiements › Litiges** | | Agrégateur, passerelle, PSP, prestataire | Un **fournisseur** | **Orchestration › Fournisseurs** | | Moyens de paiement, opérateurs Mobile Money | Les **canaux**, ouverts par le rail Wajub ou par votre fournisseur | **Orchestration › Wajub Rail** | Un compte vérifié n'encaisse rien tant qu'aucun fournisseur n'est actif : [Connecter un fournisseur](https://docs.wajub.com/dashboard/orchestration/connect-provider) explique comment brancher le vôtre, et [Demander le rail Wajub](https://docs.wajub.com/dashboard/orchestration/rail) comment encaisser sur les contrats de Wajub si vous n'en avez pas. ## L'argent qui sort | Vous disiez | Dans Wajub | Où | | -------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------- | | Retrait, payout, reversement, décaissement, virement, cash-out | Un **transfert** | **Transferts** | | Compte de retrait, compte de règlement, RIB | Un **compte de versement** : le vôtre | **Paramètres › Transferts › Comptes de versement** | | Destinataire, recipient | Un **bénéficiaire** : le compte d'un tiers que vous payez | **Transferts › Bénéficiaires** | | Reversement automatique, auto-settlement | Les **versements automatiques**, à activer vous-même | **Paramètres › Transferts › Comptes de versement** | | Recharge, top-up, approvisionner le compte | Un **approvisionnement** | **Revenus › Approvisionnement** | Un transfert sert aux deux usages : retirer votre solde vers votre propre compte, ou payer quelqu'un. [Envoyer un transfert](https://docs.wajub.com/dashboard/transfers/send) détaille l'écran. ## Le solde | Vous disiez | Dans Wajub | Où | | --------------------------------- | ------------------------------------------------------------------- | ------------------------------------------ | | Portefeuille, wallet, float | Le **Solde total** | **Tableau de bord**, **Revenus › Soldes** | | Solde retirable | Le **Solde disponible** : ce qu'un transfert peut sortir maintenant | **Transferts**, **Revenus › Soldes** | | Settlement, en cours de règlement | Le solde **En attente** : des paiements réussis, pas encore réglés | **Revenus › Soldes** | | Commission, frais de transaction | Les **Frais** | **Revenus**, et la page de chaque paiement | | Relevé, rapport | Les **Revenus** et leur export | **Revenus** | À côté de ces chiffres, le bouton d'aide (un i dans un cercle) ouvre la définition du terme. [Lire l'accueil](https://docs.wajub.com/dashboard/home/read) explique chaque chiffre de la vue d'ensemble. ## Le compte et l'équipe | Vous disiez | Dans Wajub | Où | | ----------------------------------------------- | -------------------------- | ------------------------------- | | Marchand, compte marchand, entreprise, business | Une **organisation** | **Paramètres › Général** | | KYC, KYB, activation du compte | La **conformité** | **Paramètres › Conformité** | | Équipe, utilisateurs | Les **membres** | **Paramètres › Membres** | | Abonnement, plan, tarifs | Le **forfait** | **Paramètres › Facturation** | | Mode test, sandbox, mode live | **Test** et **Production** | Le sélecteur en haut de la page | | Service client, ticket | L'**assistance** | **Assistance** | ## Les modules au nom propre | Vous disiez | Dans Wajub | Où | | -------------------------------------------------------------- | ----------------- | ------------------------------ | | Routage, bascule entre prestataires | **Orchestration** | **Orchestration** | | Sous-comptes, comptes connectés, marketplace, paiement partagé | **Sync** | **Sync** | | Antifraude, liste noire | **Shield** | **Shield** | | Espace développeur, journaux, console | **Konsole** | **Konsole**, en bas de l'écran | | IPN, callback, URL de notification | Un **webhook** | **Konsole › Webhooks** | | Apikey, clé secrète, identifiants API | Les **clés API** | **Paramètres › Clés API** | Dans le menu, le nom de ces modules affiche au survol une ligne qui dit ce qu'ils font ; sur téléphone, elle est écrite sous le nom dans **Plus**. --- # Contacter l'assistance URL: https://docs.wajub.com/fr/dashboard/help/support > Envoyer une demande à l'équipe Wajub depuis le tableau de bord, suivre ses réponses, puis la clore et noter l'aide reçue. L'équipe Wajub répond dans le tableau de bord : chaque demande devient une conversation que vous suivez dans **Assistance**, en bas du menu (G puis H) et dans le menu du compte. **Centre d'aide**, en haut de la page, ouvre le centre d'aide dans un nouvel onglet. Tous les rôles sauf Utilisateur de test peuvent écrire à l'assistance ; un rôle personnalisé a besoin de **Voir ses propres demandes d'assistance** et de **Créer des demandes d'assistance**. Un membre voit ses propres demandes et celles des collègues qui ont le même rôle que lui ; le propriétaire, les Administrateurs et un rôle personnalisé qui a **Voir toutes les demandes d'assistance** les voient toutes. L'assistance est ouverte à tous les forfaits, et aucun code de sécurité n'est demandé. ## Les étapes 1. **Ouvrez une nouvelle demande** Ouvrez **Assistance** dans le menu, puis **Nouvelle demande**. Le formulaire s'ouvre sur la section **Votre demande**. ![Le formulaire Nouvelle demande : De quoi s'agit-il ? sur Intégration API, le Sujet, Décrivez votre problème, Joindre un fichier, puis la section Joindre le contexte technique.](https://docs.wajub.com/dashboard/fr/light/help-support-new.webp) *La section Joindre le contexte technique n'apparaît que pour les sujets techniques.* 2. **Choisissez le sujet** Dans **De quoi s'agit-il ?**, choisissez ce qui décrit le mieux votre demande, par exemple **Problème de paiement**, **Retard de versement**, **Intégration API** ou **Question générale**. Donnez ensuite un **Sujet**, jusqu'à 200 caractères. Pendant que vous le tapez, **Ceci répond peut-être déjà à votre question** propose des articles du centre d'aide. 3. **Décrivez le problème** Sous **Décrivez votre problème**, dites ce que vous faisiez, ce que vous attendiez et ce qui s'est passé. **Joindre un fichier**, facultatif, prend un PDF, une image, un CSV ou un fichier texte, jusqu'à 10 Mo. 4. **Joignez le contexte technique** Pour **Problème de paiement**, **Transaction échouée**, **Problème technique**, **Intégration API** et **Terminal de paiement**, la section **Joindre le contexte technique** apparaît. Cochez **Mes dernières erreurs API**, ou donnez l'identifiant d'une transaction ou d'une livraison de webhook. Seul ce que vous indiquez part : codes HTTP, horodatages, identifiants et messages d'erreur, jamais vos clés ni les données de vos clients. 5. **Envoyez la demande** **Envoyer la demande** ouvre la conversation, avec sa **Référence** et le délai de réponse attendu, en heures ouvrées. ## Suivre la conversation Les réponses arrivent dans la conversation, et **Assistance**, dans le menu, compte celles que vous n'avez pas lues. La liste des demandes a deux onglets, **Ouvert** et **Résolu**. Chaque demande affiche sa référence, la date de son dernier message, ses réponses non lues et son statut : **Ouvert**, **En attente de votre réponse** quand l'assistance attend votre réponse, ou **Résolu**. Une demande ouverte en Test porte **Test**, et la demande d'un collègue **Ouverte par** suivi de son nom. Dans la conversation, **Le support est en train d'écrire…** apparaît pendant qu'un agent écrit, et **Vu par le support le** suivi d'une date indique quand l'assistance l'a lue pour la dernière fois. Pour répondre, écrivez votre message sous la conversation, puis **Envoyer**, ou Ctrl+Entrée (⌘+Entrée sur un Mac). **Joindre un fichier** accepte les mêmes fichiers que le formulaire. Un fichier affiche **Analyse en cours…** jusqu'à ce qu'il ait été vérifié, et **Bloqué** s'il est refusé. Un message qui n'a pas pu partir affiche **Non envoyé** : **Renvoyer** l'envoie de nouveau. ## Les réponses par e-mail Une réponse que personne n'a lue dans le tableau de bord quelques minutes plus tard part aussi par e-mail. L'auteur reçoit « Le support a répondu à votre demande *référence* » ; chaque collègue qui a son rôle reçoit « Le support a répondu à la demande *référence* de *nom* », qui dit qui l'a ouverte. L'e-mail, dans votre langue, cite le début de la réponse avec le sujet et la référence de la demande, et **Lire la réponse** ouvre la conversation dans le tableau de bord, dans la bonne organisation. Vous répondez là : la conversation reste dans **Assistance**. Voir toutes les demandes n'apporte pas tous les e-mails : le propriétaire et les Administrateurs ne reçoivent que ceux de leurs propres demandes et des collègues qui partagent leur rôle. ## Suivre la demande d'un collègue Un collègue qui a le même rôle que l'auteur voit la demande, et peut y répondre, la marquer comme résolue ou la rouvrir, comme les siennes : une réponse n'attend pas une personne absente. Un rôle personnalisé sans **Créer des demandes d'assistance** peut lire une demande, mais pas y répondre. ## Clore et noter **Marquer comme résolue** clôt la demande, et **Rouvrir** la rouvre. Une demande résolue passe dans **Résolu** et affiche **Cette demande est résolue. Répondez pour la rouvrir.** : un nouveau message suffit aussi. Une fois la demande résolue, **Comment ça s'est passé ?** vous demande une note de 1 à 5, avec un commentaire facultatif. **Envoyer ma note** l'enregistre. --- # Adapter et exporter l'accueil URL: https://docs.wajub.com/fr/dashboard/home/customize > Choisir les blocs de votre accueil, partir d'un préréglage, et télécharger les chiffres de la période en CSV. Gardez sur l'accueil les blocs qui vous servent, puis téléchargez ses chiffres pour les reprendre ailleurs. Choisir ses blocs est réservé au propriétaire, aux Administrateurs et aux [rôles](https://docs.wajub.com/fr/dashboard#roles) personnalisés qui ont **Gérer les paramètres**, avec tous les forfaits. Chacun enregistre sa propre disposition : elle ne change pas l'accueil des autres membres. Tous les rôles peuvent exporter l'accueil, en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live) uniquement. Aucune des deux tâches ne demande le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les étapes 1. **Ouvrez Personnaliser** En haut de l'accueil, choisissez **Personnaliser**. **Personnaliser le tableau de bord** s'ouvre. La ligne du jour et les chiffres des paiements restent toujours affichés ; chaque autre bloc a son interrupteur. ![Le dialogue Personnaliser le tableau de bord : les préréglages Finance, Opérations et Développeur en haut, puis les interrupteurs des blocs rangés sous Chiffres clés, Graphiques et Autres sections, et les boutons Rétablir par défaut, Annuler et Enregistrer la disposition.](https://docs.wajub.com/dashboard/fr/light/home-customize.webp) *Un interrupteur par bloc, rangés en trois groupes.* 2. **Partez d'un préréglage** Sous **Préréglages**, **Finance** garde les soldes, les pays et la qualité du revenu. **Opérations** garde les tentatives, le volume crédité, les transferts, les fournisseurs, la qualité du revenu et les paiements récents. **Développeur** garde les tentatives, le volume crédité, les transferts, les fournisseurs et les paiements récents, avec **Santé API & webhook**, **Intelligence de routage** et **Métriques avancées**. Le compteur à droite indique combien de blocs sont actifs. 3. **Ajustez les blocs** Activez ou coupez un bloc avec son interrupteur. **Chiffres clés** contient **Solde Wajub**, qui affiche ou masque **Solde total**. **Graphiques** et **Autres sections** contiennent les blocs décrits dans [Lire l'accueil](https://docs.wajub.com/dashboard/home/read#the-blocks), dont **Soldes des fournisseurs**. 4. **Enregistrez** Choisissez **Enregistrer la disposition**. Le message « Préférences des métriques du tableau de bord mises à jour avec succès. » s'affiche, et l'accueil montre vos blocs. **Annuler** ferme le dialogue sans rien changer ; si vous avez changé un interrupteur, **Abandonner les modifications ?** vous demande d'abord de confirmer. Pour revenir plus tard à l'accueil d'origine, rouvrez **Personnaliser**, choisissez **Rétablir par défaut**, puis **Enregistrer la disposition**. ## Exporter l'accueil Choisissez la période dans **Période**, puis **Exporter** › **CSV**. Le fichier se télécharge, et « Votre export est prêt : » s'affiche avec son nom. Il reprend, pour la période choisie, le solde total, disponible et en attente, le volume, le volume net, le nombre de paiements, le taux de réussite, la croissance, le volume et le nombre de transferts, et les frais. Ses intitulés sont en anglais. En Test, **Exporter** n'apparaît pas. Chaque export compte dans la limite mensuelle de votre forfait : [Choisir ou changer de forfait](https://docs.wajub.com/dashboard/subscription/plans). Une fois la limite atteinte, le menu affiche « Vous avez atteint votre limite d'exportation mensuelle. Passez à un forfait supérieur. » et ses formats sont grisés. --- # Lire l'accueil URL: https://docs.wajub.com/fr/dashboard/home/read > Ce que disent les chiffres et les blocs de l'accueil, comment changer de période et ouvrir les paiements qu'un chiffre compte. L'accueil résume votre activité en Production : la journée en cours, votre solde, vos paiements réussis et échoués sur la période choisie, puis des graphiques et des listes. Tous les [rôles](https://docs.wajub.com/fr/dashboard#roles) ouvrent l'accueil. Choisir une période ne demande ni forfait particulier ni [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). En [Test](https://docs.wajub.com/fr/dashboard#sandbox-and-live), un accueil de test le remplace, décrit en bas de page. ## La période **Période**, en haut de l'accueil, propose **Aujourd'hui**, **7 derniers jours**, **30 derniers jours**, **90 derniers jours**, **12 derniers mois**, **Mois en cours**, **Mois dernier** et **Depuis le 1er janvier**, ou les jours de votre choix dans le calendrier, jusqu'à un an en arrière. L'accueil s'ouvre sur les 30 derniers jours. Les chiffres et les blocs suivent la période choisie, sauf la ligne du jour, les soldes, **Paiements récents** et **Activité des transferts**, qui couvre toujours les 30 derniers jours. ## La vue d'ensemble Sous **Vue d'ensemble**, à côté du nom de la période, une première ligne donne la journée en cours : **Volume aujourd'hui**, **Paiements aujourd'hui**, **Échoués aujourd'hui** et **Nouveaux clients aujourd'hui**. Elle se met à jour d'elle-même tant que la page reste ouverte. La ligne suivante couvre la période : - **Solde total** : votre solde, avec la part disponible, la part en attente et le prochain montant attendu avec sa date. Le libellé **mode direct** signale des fonds réglés sur vos propres comptes fournisseurs plutôt que chez Wajub. - **Volume brut** : les paiements crédités sur votre solde, avec le **Volume net** et l'écart en pourcentage « vs période précédente ». Il compte aussi vos approvisionnements, et le dit sous le montant quand il y en a. - **Paiements réussis** : leur nombre, et leur part des tentatives. - **Échoué** : les paiements qui ont échoué. ![L'accueil du tableau de bord en Production : volume du jour, solde total, volume brut, paiements réussis et échoués, puis les graphiques des tentatives de paiement et du volume crédité. Le sélecteur Test et Production est en haut à droite, sur Production.](https://docs.wajub.com/dashboard/fr/light/home.webp) *La ligne du jour, puis les chiffres de la période choisie.* ## Ouvrir ce qu'un chiffre compte Un chiffre de la vue d'ensemble s'ouvre d'un clic sur la liste qu'il compte, sur la même période. **Volume aujourd'hui**, **Paiements aujourd'hui**, **Volume brut** et **Paiements réussis** ouvrent **Paiements** filtrés sur **Crédités sur le solde**. **Échoués aujourd'hui** et **Échoué** ouvrent les paiements échoués, **Nouveaux clients aujourd'hui** les clients arrivés dans la journée. **Solde total** ouvre [Revenus](https://docs.wajub.com/dashboard/home/revenue). [Trouver un paiement](https://docs.wajub.com/dashboard/payments/find) explique ces filtres. ## Les blocs Sous la vue d'ensemble, l'accueil affiche ces blocs, du haut vers le bas : | Bloc | Ce qu'il montre | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Tentatives de paiement** | Les paiements réussis et échoués jour après jour, et **Où les paiements s'arrêtent** : les paiements non crédités, par statut. | | **Volume crédité** | Le volume crédité jour après jour, comparé à la période précédente, et sa répartition **Par moyen de paiement**. | | **Activité des transferts** | Le volume de vos transferts jour après jour, par statut, sur les 30 derniers jours. | | **Soldes et performances fournisseurs** | Où se trouvent vos fonds, et le volume, le taux de réussite et le coût de chaque fournisseur. | | **Meilleurs pays** | Les pays d'où viennent vos paiements, avec leur part du volume crédité. | | **Qualité du revenu** | La part du revenu des **Clients récurrents** et des **Nouveaux clients**, et le montant **Remboursé**. | | **Paiements récents** | Vos cinq derniers paiements, avec leur statut. **Tout voir** ouvre **Paiements**. | Trois blocs restent masqués tant que vous ne les ajoutez pas : **Métriques avancées**, **Santé API & webhook** et **Intelligence de routage**. [Adapter et exporter l'accueil](https://docs.wajub.com/dashboard/home/customize) dit comment choisir vos blocs. Au-dessus de la période, des avis signalent ce qui demande votre attention, par exemple un dossier d'activation à compléter, ou une baisse du taux de réussite ou du volume par rapport à la période précédente. ## L'accueil en Test En Test, l'accueil affiche **Solde de test**, le nombre de **Paiements**, de **Clients** et de **Webhooks envoyés**, le **Volume de paiements** des 7 derniers jours et des **Actions rapides** pour lancer une intégration. Une fois votre activation validée, **Passer en production** vous y emmène : [Passer en Production](https://docs.wajub.com/dashboard/getting-started/test-and-live). En Production, tant que votre organisation n'a encore ni paiement, ni client, ni transfert, l'accueil montre à la place les étapes pour démarrer. --- # Suivre ses revenus URL: https://docs.wajub.com/fr/dashboard/home/revenue > Revenu brut et net, frais et remboursements par période, détail de vos soldes et règlements à venir, évolution du solde, et export en Excel ou PDF. **Revenus** montre ce que vos paiements vous ont rapporté, où se trouve votre argent et comment votre solde a évolué. Les montants comptent l'argent encaissé, à la date où il l'a été. Le propriétaire, un Administrateur, un membre Finance, Analyste ou Observateur, ou un [rôle](https://docs.wajub.com/fr/dashboard#roles) personnalisé qui a **Voir les revenus** ouvre **Revenus**, avec tous les forfaits. Comme le rappelle [Test et Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), le module n'existe qu'en Production. Le lire ou l'exporter ne demande pas de [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Vue d'ensemble Ouvrez **Revenus** dans le menu : **Vue d'ensemble** s'affiche, sur les 30 derniers jours. **Période** propose les mêmes choix que l'accueil, ou les jours de votre choix. Quatre chiffres résument la période : - **Revenu brut** : les paiements crédités sur votre solde. - **Revenus nets** : ce qui reste après remboursements et frais, avec l'écart par rapport à la période précédente de même durée. - **Remboursements** : ce que vous avez rendu à vos clients. - **Frais** : les frais de traitement de la période. **Revenus par canal** répartit le volume entre Mobile Money, cartes et virements bancaires, avec le nombre de paiements et la part de chaque canal. **Revenus par devise** suit, avec le volume de chaque devise. Avec des abonnements actifs, **Revenu récurrent** donne leur nombre, le **Revenu récurrent mensuel (MRR)** et le **Revenu récurrent annuel (ARR)**. ![Revenus › Vue d'ensemble sur les 30 derniers jours : Revenu brut, Revenus nets avec l'écart par rapport à la période précédente, Remboursements et Frais, puis les tableaux Revenus par canal et Revenus par devise.](https://docs.wajub.com/dashboard/fr/light/home-revenue.webp) *Les quatre chiffres de la période, puis le volume par canal.* ## Soldes **Soldes** décrit votre argent à l'instant présent, sans période à choisir. **Résumé du solde** donne le **Solde total**, la part **Disponible** pour un transfert, la part **En attente** de règlement et la part **En transit** dans un transfert en cours. **Montants retenus** isole ce qui est **Réservé** pour des litiges, bloqué temporairement ou **Contesté**. Quand des litiges retiennent une partie du solde, **Litiges affectant le solde** le signale, avec **Voir les litiges**. **Frais par type** et **Frais par fournisseur** couvrent les 30 derniers jours. **Règlements estimés** liste, par fournisseur, les fonds crédités récemment qui ne sont pas encore réglés, avec le délai et la **Date estimée** de leur règlement. ## Progressions **Progressions** suit l'évolution de votre solde sur la période choisie. **Regrouper par** découpe le graphique **Progression du solde** par **Jour**, **Semaine** ou **Mois**. Le tableau **Par période** donne, pour chaque tranche, les paiements, les remboursements, les frais, les **Transferts sortants**, la **Variation nette** et le **Solde en fin de période**. ## Exporter un rapport Sur **Vue d'ensemble**, **Soldes** et **Progressions**, **Exporter** propose **Excel** ou **PDF**. Le fichier reprend la page ouverte, avec sa période et, pour **Progressions**, son regroupement. Chaque export compte dans la limite mensuelle de votre forfait : [Choisir ou changer de forfait](https://docs.wajub.com/dashboard/subscription/plans). Le quatrième onglet, **Approvisionnement**, sert à créditer votre solde : [Approvisionner son solde](https://docs.wajub.com/dashboard/home/top-up). --- # Approvisionner son solde URL: https://docs.wajub.com/fr/dashboard/home/top-up > Créditer votre solde Wajub par Mobile Money ou par virement bancaire, envoyer la preuve d'un virement et suivre chaque approvisionnement. Approvisionner votre solde y ajoute de l'argent sans passer par un paiement client, par exemple pour envoyer un transfert avant que vos encaissements soient réglés. Les rôles qui ouvrent [Revenus](https://docs.wajub.com/dashboard/home/revenue) peuvent approvisionner le solde, avec tous les forfaits. Comme **Revenus**, l'approvisionnement n'existe qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Il ne demande pas de [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les étapes 1. **Ouvrez l'approvisionnement** Ouvrez **Revenus › Approvisionnement**, puis choisissez **Ajouter des fonds**. La page affiche votre **Solde actuel** et trois étapes : **Méthode**, **Détails** et **Examiner**. 2. **Choisissez la méthode** Sous **Moyen de paiement**, choisissez **Mobile Money** ou **Virement bancaire**, marqué **Validation manuelle** : votre solde n'est crédité qu'après la vérification de votre preuve par Wajub. Le virement bancaire n'apparaît que lorsque Wajub l'accepte. Choisissez **Continuer**. ![Ajouter des fonds, étape Méthode : le solde actuel en haut, puis les deux cartes Mobile Money et Virement bancaire, ce dernier marqué Validation manuelle, et le bouton Continuer.](https://docs.wajub.com/dashboard/fr/light/home-top-up.webp) *Le virement bancaire n'est crédité qu'après vérification de la preuve.* 3. **Indiquez le montant** Pour Mobile Money, choisissez d'abord l'**Opérateur** du téléphone qui paie, rangé par pays. Saisissez le **Montant à ajouter** : 1 000 FCFA au moins, ou leur équivalent dans votre devise. En FCFA, des boutons proposent des montants tout faits. Pour Mobile Money, saisissez le **Numéro de téléphone** qui paie. La **Note**, facultative, reste attachée à l'approvisionnement. Choisissez **Examiner**. 4. **Vérifiez et envoyez** Le récapitulatif reprend la méthode et le montant ; **Modifier les informations** revient en arrière. Choisissez le bouton « Ajouter », suivi du montant. Pour Mobile Money, la page de l'approvisionnement s'ouvre et le téléphone reçoit une demande de paiement de l'opérateur : votre solde est crédité dès que le titulaire du numéro la confirme. Pour un virement, la page de l'approvisionnement s'ouvre sur les instructions de virement. ## Après un virement bancaire Sous **Instructions de virement bancaire**, la page donne le compte Wajub où envoyer le montant : **Motif du virement**, **Nom du compte**, **Banque**, **Numéro de compte**, puis **IBAN** et **SWIFT / BIC** quand le compte en a. Chaque ligne se copie, et **Tout copier** les copie toutes. Recopiez le motif tel quel dans votre virement : c'est lui qui rattache l'argent reçu à votre approvisionnement. Une fois le virement parti, remplissez **Justificatif de virement** sur la même page : **Votre banque**, **Votre numéro de compte ou IBAN** et le **Reçu** émis par votre banque, en PDF, JPG ou PNG de 10 Mo au plus. Choisissez **Envoyer la preuve et notifier Wajub** : l'équipe Wajub vérifie le virement, puis crédite votre solde. ## Suivre un approvisionnement **Revenus › Approvisionnement** liste vos approvisionnements avec leur montant, leur statut, leur méthode et leur date. Au-dessus, la page donne votre **Solde disponible**, le total **Crédité** et le nombre d'approvisionnements **En cours** et **Échoué**. Sur la page d'un approvisionnement, **Disponible à l'envoi** dit quand vous pourrez transférer l'argent. Quand un montant crédité reste bloqué un temps, **Fonds pas encore disponibles pour un transfert** l'indique, avec la date où il se libère. Une **Note de Wajub** s'affiche quand l'équipe en a laissé une. Une fois la preuve d'un virement envoyée, et tant que l'approvisionnement n'est ni crédité ni refusé, **Échanges avec Wajub** vous permet d'écrire à l'équipe et de joindre des fichiers. --- # Corriger ou annuler sa facture URL: https://docs.wajub.com/fr/dashboard/invoices/correct-cancel-refund > Modifier un brouillon, annuler et dupliquer une facture envoyée, réduire ce que doit le client avec un avoir, ou lui rembourser ce qu'il a payé. Un brouillon se modifie librement. Une facture envoyée garde son numéro : pour la corriger, annulez-la et dupliquez-la, ou réduisez ce que doit le client avec un avoir. Le propriétaire, un Administrateur, un membre Finance ou un rôle personnalisé qui a **Gérer les factures** peut le faire. Seul l'avoir demande le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Modifier un brouillon Sur la page d'un brouillon qui n'a reçu aucun paiement, **Modifier le brouillon** rouvre le formulaire. Une facture envoyée ne se modifie plus. Les brouillons inutiles se suppriment depuis la liste, avec [**Supprimer les brouillons**](https://docs.wajub.com/dashboard/invoices/export-and-bulk#bulk-actions). ## Corriger une facture envoyée 1. **Annulez la facture** Sur la page de la facture, choisissez **Annuler la facture** dans le menu à droite des boutons. Le dialogue **Annuler cette facture ?** rappelle que le client ne pourra plus la payer, qu'aucune relance ne partira et qu'elle garde son numéro. Ce qui a déjà été payé n'est pas remboursé. Confirmez avec **Annuler la facture** : elle passe à **Annulée**, et c'est définitif. 2. **Dupliquez-la** Dans le même menu, **Dupliquer en nouveau brouillon** crée un brouillon avec le même client et les mêmes lignes, et ouvre sa modification avec **Facture dupliquée avec succès**. 3. **Corrigez, puis envoyez le brouillon** Corrigez ce qui doit l'être, puis [envoyez la facture](https://docs.wajub.com/dashboard/invoices/create#after-creating-it) : elle reçoit un nouveau numéro. ## Émettre un avoir Un avoir réduit ce que doit le client sans annuler la facture, par exemple pour un article rendu ou une remise accordée après coup. Il porte un numéro de sa propre série, se télécharge en PDF et ne peut pas être annulé. 1. **Ouvrez Émettre un avoir** Sur la page d'une facture envoyée, choisissez **Émettre un avoir** dans le menu à droite des boutons. Le dialogue s'ouvre. 2. **Saisissez le montant et le motif** Le **Montant à créditer** va jusqu'à ce que la facture représente encore. Le **Motif**, obligatoire, est imprimé sur l'avoir. Sous les champs, le dialogue montre l'effet sur la facture : **Statut de la facture ensuite**, **Crédité au total** et **Montant dû ensuite**. ![Le dialogue Émettre un avoir, descendu jusqu'à son effet : le motif Remise commerciale, la case Envoyer au client cochée avec l'adresse du client, puis, pour un avoir de 10 000 FCFA, le montant demandé par la facture qui passe à 164 000 FCFA, le statut de la facture ensuite En retard, 0 FCFA payé, 10 000 FCFA crédités au total et 164 000 FCFA dus ensuite.](https://docs.wajub.com/dashboard/fr/light/invoices-credit-note.webp) *Le dialogue montre l'effet de l'avoir avant de l'émettre.* 3. **Choisissez de l'envoyer** **Envoyer au client** l'envoie par e-mail, avec le PDF en pièce jointe. Si la facture n'a pas d'adresse e-mail, remettez vous-même le PDF de l'avoir au client. 4. **Émettez l'avoir** Cliquez sur « Émettre un avoir de » suivi du montant, puis saisissez le code de sécurité. Un message confirme le numéro de l'avoir, qui apparaît sous **Avoirs** sur la page de la facture, avec son PDF. Ensuite, la facture affiche **Partiellement créditée** et ne demande plus que son montant dû. Si l'avoir couvre ce qui restait dû après un paiement partiel, elle passe à **Payée**. Créditée en totalité, elle passe à **Annulée** si rien n'avait été payé, à **Remboursé** sinon : rendez alors l'argent au client comme ci-dessous. ## Rembourser le client Un avoir ne rend pas d'argent. Pour rendre ce que le client a payé en ligne, ouvrez le paiement depuis **Historique** avec **Ouvrir le paiement**, puis [remboursez-le](https://docs.wajub.com/dashboard/payments/refund). Une fois ses paiements en ligne remboursés en totalité, la facture passe à **Remboursé**, sauf si un paiement y a été enregistré à la main. Un paiement reçu hors de Wajub se rend hors de Wajub. --- # Créer et envoyer une facture URL: https://docs.wajub.com/fr/dashboard/invoices/create > Facturer un client précis depuis le tableau de bord, du client aux lignes et aux conditions de paiement, puis l'envoyer par e-mail avec son PDF et son lien de paiement. Une facture s'adresse à un client précis : il la reçoit par e-mail, avec le PDF et un lien pour la payer en ligne. Le propriétaire, un Administrateur, un membre Finance ou un rôle personnalisé qui a **Gérer les factures** peut créer et envoyer une facture. Le forfait **Pay as you go** permet 10 factures en tout ; **Growth** et les forfaits au-dessus n'ont pas de limite. Aucun code de sécurité n'est demandé, sauf pour émettre un avoir. ## Les étapes 1. **Ouvrez le formulaire** En **Production**, ouvrez **Factures**, puis **Créer une facture**. Le formulaire passe par quatre étapes : **Client**, **Lignes**, **Paiement** et **Examiner**. **Continuer** vérifie chaque étape avant de passer à la suivante et signale le champ à corriger. 2. **Choisissez le client** Sous **Pour qui est-elle ?**, cherchez un client existant dans **Client de votre répertoire** par son nom ou son e-mail : le choisir remplit les champs. Sinon, saisissez son **Nom**, seul champ obligatoire, et si besoin son **E-mail**, le **Nom de l'entreprise**, son **Téléphone** et son **Adresse**. Sans e-mail, la facture ne peut pas lui être envoyée par Wajub. ![Créer une facture, étape Client : la recherche dans le répertoire, puis le nom Hôtel Les Cocotiers et l'e-mail compta@hotel-les-cocotiers.cm saisis, le nom de l'entreprise, le téléphone et l'adresse vides, et le bouton Continuer.](https://docs.wajub.com/dashboard/fr/light/invoice-customer.webp) *Un client saisi avec un e-mail ou un téléphone rejoint votre répertoire.* 3. **Ajoutez les lignes** Sous **Que facturez-vous ?**, choisissez la **Devise**, puis remplissez chaque ligne : **Nom de l'article**, **Quantité** et **Prix unitaire** sont obligatoires, **Description** et **Unité** facultatives. **Taxe et remise** règle la taxe et la remise de la ligne, et **Ajouter une ligne** en ajoute une autre. Sous les lignes, **Remise sur la facture** et **Livraison** s'appliquent à toute la facture. Le **Résumé**, à droite, suit le total. ![Créer une facture, étape Lignes : la devise XAF, une ligne Arabica Kribi 1 kg, quantité 20 à 9 500 FCFA, total de la ligne 190 000 FCFA, et le Résumé à droite avec un total de 190 000 FCFA.](https://docs.wajub.com/dashboard/fr/light/invoice-lines.webp) *Le Résumé se met à jour à chaque ligne.* 4. **Fixez les conditions de paiement** Sous **Quand et comment est-elle payée ?**, laissez **Numéro de facture** vide pour que la facture reçoive le numéro suivant de votre séquence à l'envoi. Les **Conditions de paiement**, de **Payable à réception** à 90 jours, calculent la **Date d'échéance** à partir de la **Date de facture**. Sous **Comment le client paie**, choisissez **En un seul paiement**, ou **En plusieurs échéances** pour [répartir le total sur 2 à 12 dates](https://docs.wajub.com/dashboard/invoices/installments). Plus bas, **Facture récurrente** [émet une copie de la facture](https://docs.wajub.com/dashboard/invoices/recurring) à chaque date choisie : seuls le propriétaire et les Administrateurs la voient, à partir du forfait **Growth**. Les **Notes**, les **Conditions générales** et le **Pied de page** sont imprimés sur la facture, et **Moyens de paiement** limite ceux que le client se voit proposer. ![Créer une facture, étape Paiement : le numéro de facture vide, la date de facture du jour, des conditions à 30 jours et l'échéance 30 jours plus tard, le choix entre En un seul paiement et En plusieurs échéances, puis l'interrupteur Facture récurrente.](https://docs.wajub.com/dashboard/fr/light/invoice-payment.webp) *La date d'échéance suit les conditions de paiement.* 5. **Vérifiez, puis créez la facture** **Vérifier la facture** reprend le client, les lignes, le paiement et le total. Sous **Ce qui va se passer**, choisissez **Enregistrer en brouillon** pour la garder modifiable, ou **La créer et l'envoyer par e-mail** pour l'envoyer tout de suite au client. Le bouton devient **Enregistrer le brouillon** ou **Créer et envoyer**. ![Créer une facture, étape Examiner : le récapitulatif des dates, le total de 190 000 FCFA, puis Ce qui va se passer avec La créer et l'envoyer par e-mail sélectionné, et le bouton Créer et envoyer.](https://docs.wajub.com/dashboard/fr/light/invoice-review.webp) *Une facture envoyée reçoit son numéro et ne peut plus être modifiée.* La page de la facture s'ouvre avec **Facture créée et envoyée avec succès**, ou **Facture créée avec succès** pour un brouillon. ## Ce que reçoit le client Le client reçoit un e-mail avec la facture en PDF et un bouton **Payer en ligne**, qui ouvre sa page de paiement sur invoice.wajub.com, ou sur votre domaine si vous en avez choisi un dans [**Paramètres › Factures › Adresse des factures**](https://docs.wajub.com/dashboard/invoices/settings#invoice-address). Quand la facture a une date d'échéance, il reçoit aussi des [rappels par e-mail](https://docs.wajub.com/dashboard/invoices/track-and-remind#automatic-reminders), qui s'arrêtent dès qu'elle est payée ou annulée. ## Après la création Sur la page d'un brouillon, **Envoyer la facture** l'envoie et **Modifier le brouillon** le reprend. Si le client n'a pas d'e-mail, **Envoyer la facture** n'apparaît pas : modifiez le brouillon pour en ajouter un, ou choisissez **Émettre sans e-mail** dans le menu à droite des boutons. La facture est alors numérotée sans rien envoyer, et vous transmettez vous-même le PDF ou le lien de paiement. Une facture envoyée ne se modifie plus. **Renvoyer** envoie à nouveau l'e-mail, et **Télécharger le PDF** ou **Copier le lien de paiement** permettent de la transmettre autrement. Pour [corriger une erreur](https://docs.wajub.com/dashboard/invoices/correct-cancel-refund#correct-a-sent-invoice), choisissez **Annuler la facture** dans le menu, puis **Dupliquer en nouveau brouillon** : une facture émise garde son numéro et ne peut pas être supprimée. > [!NOTE] > **Une facture commencée reste sur cet appareil** > > Tant que la facture n'est pas créée, ce que vous saisissez est gardé dans ce navigateur. Au > prochain **Créer une facture**, le formulaire vous propose **La reprendre** ou > **L'abandonner**. Un autre navigateur ou une navigation privée ne la retrouve pas. --- # Agir sur plusieurs factures URL: https://docs.wajub.com/fr/dashboard/invoices/export-and-bulk > Sélectionner des factures dans la liste pour les envoyer, les annuler, supprimer des brouillons ou les exporter d'un coup, et exporter toute la liste filtrée. Depuis la liste **Factures**, vous pouvez envoyer, annuler, supprimer ou exporter jusqu'à 100 factures à la fois, ou exporter toute la liste avec ses filtres. Le propriétaire, un Administrateur, un membre Finance ou un rôle personnalisé qui a **Gérer les factures** voit les cases de sélection et le bouton **Exporter**. Aucun code de sécurité n'est demandé. Le forfait **Pay as you go** compte 10 exports par mois, tous exports du tableau de bord confondus, et **Growth** et les forfaits au-dessus n'ont pas de limite. ## Les actions groupées 1. **Sélectionnez les factures** Dans **Factures**, filtrez la liste si besoin, puis cochez la case de chaque facture. Une barre apparaît en bas de l'écran avec le nombre de factures choisies. Au-delà de 100, elle affiche « Jusqu'à 100 à la fois. » et ses actions restent grisées. ![La liste Factures avec un brouillon et une facture envoyée cochés et, en bas de l'écran, la barre de sélection : 2 sélectionné(s), puis Exporter, Envoyer (1), Annuler les factures et Supprimer les brouillons (1).](https://docs.wajub.com/dashboard/fr/light/invoices-bulk.webp) *Entre parenthèses, le nombre de factures concernées par l'action.* 2. **Choisissez l'action** La barre ne propose que les actions qui s'appliquent à la sélection, avec entre parenthèses le nombre concerné quand ce ne sont pas toutes les factures choisies. **Envoyer** numérote les brouillons et les envoie par e-mail aux clients qui ont une adresse, comme [un envoi seul](https://docs.wajub.com/dashboard/invoices/create#after-creating-it). **Annuler les factures** porte sur celles qui ne sont ni payées, ni annulées, ni remboursées : ce qui a déjà été payé n'est pas remboursé, et c'est définitif. **Supprimer les brouillons** efface les brouillons qui n'ont reçu aucun paiement. 3. **Confirmez** Le dialogue rappelle ce que l'action va faire, puis confirmez avec **Envoyer les factures**, **Annuler les factures** ou **Supprimer les brouillons**. Un message donne le nombre de factures traitées, par exemple « 2 factures traitées. », et la sélection se vide. ## Exporter les factures **Exporter**, en haut de la liste, ouvre **Exporter les factures** : le fichier contient les factures que la liste affiche avec ses filtres, rappelés sous **Filtres conservés**. Choisissez le **Format**, **CSV**, **Excel**, **PDF** ou **JSON**, et si besoin une période de dates de facture avec le bouton **Date** sous **Période** : une période prête comme **30 derniers jours**, ou une **Période personnalisée**. Sans période, toutes les dates sont exportées. Puis **Exporter en CSV**, **Exporter en Excel**, **Exporter en PDF** ou **Exporter JSON**, selon le format. Le fichier se télécharge, et « Votre export est prêt » donne son nom. Les avoirs ne sont pas exportés. Pour n'exporter que certaines factures, sélectionnez-les, puis **Exporter** dans la barre du bas : **Exporter les factures sélectionnées** reprend seulement celles-là, sans période. Une fois les exports du mois utilisés, le dialogue l'indique. Un membre qui a **Gérer le compte** voit **Passer à un forfait supérieur** ; les autres sont invités à s'adresser au propriétaire de l'organisation, et seul **Fermer** s'affiche. --- # Faire payer en plusieurs fois URL: https://docs.wajub.com/fr/dashboard/invoices/installments > Répartir le total d'une facture sur 2 à 12 échéances, chacune avec sa date et son montant, puis suivre celles que le client a payées. Une facture en plusieurs échéances garde un seul total, réparti sur 2 à 12 dates : le client paie chaque échéance à sa date. Les échéances se fixent en [créant une facture](https://docs.wajub.com/dashboard/invoices/create), avec les mêmes droits : le propriétaire, un Administrateur, un membre Finance ou un rôle personnalisé qui a **Gérer les factures**. Tous les forfaits les proposent, et aucun code de sécurité n'est demandé. Une fois la facture envoyée, l'échéancier ne change plus. ## Les étapes 1. **Choisissez le paiement en plusieurs échéances** Dans le formulaire de facture, à l'étape **Paiement**, choisissez **En plusieurs échéances** sous **Comment le client paie**. Deux échéances apparaissent, chacune avec la moitié du total : la première à la **Date de facture**, la seconde 30 jours plus tard. 2. **Fixez le nombre d'échéances** Choisissez de 2 à 12 échéances dans **Nombre d'échéances**. Chaque échéance ajoutée tombe 30 jours après la précédente, et le total est de nouveau réparti à parts égales. 3. **Ajustez les dates et les montants** Modifiez la **Date d'échéance** et le **Montant** de chaque échéance. La dernière prend le reste du total : son montant se calcule seul, et **Répartir à parts égales** remet des montants égaux. Chaque échéance tombe à la date de facture ou après, et pas avant la précédente. Si les montants dépassent le total, un message vous demande d'en baisser un. ![Les échéances d'une facture : Nombre d'échéances sur 3 échéances, le bouton Répartir à parts égales, puis trois échéances avec leur date et leur montant, 63 333 FCFA pour les deux premières et 63 334 FCFA pour la dernière, calculée à partir du reste du total.](https://docs.wajub.com/dashboard/fr/light/invoices-installments.webp) *La dernière échéance prend le reste du total.* 4. **Créez la facture** La **Date d'échéance** de la facture devient celle de la dernière échéance : le statut **En retard** et les rappels suivent cette date. Continuez jusqu'à **Examiner**, puis enregistrez le brouillon ou envoyez la facture. ## Suivre les échéances Sur la page de la facture, la section **Échéances** indique combien sont payées, par exemple « 1 échéance payée sur 3 », puis chaque échéance avec sa date, son montant et son statut : **Payée**, **En attente** ou **En retard**. Dès qu'une échéance est réglée, la facture passe à **Partiellement payé**, puis à **Payée** avec la dernière. Un paiement reçu hors de Wajub, [enregistré à la main](https://docs.wajub.com/dashboard/invoices/record-payment), règle les échéances dans l'ordre. ## Ce que voit le client Sur sa page de paiement, le client règle une échéance à la fois, la première qui reste à payer. --- # Enregistrer un paiement reçu URL: https://docs.wajub.com/fr/dashboard/invoices/record-payment > Ajouter à une facture un paiement reçu hors de Wajub, en espèces ou par virement, pour tout le solde ou une partie, ou la marquer comme payée en un clic. Quand un client vous règle hors de Wajub, en espèces ou par virement, enregistrez ce paiement sur sa facture : le montant dû baisse, et rien n'est débité au client. Le propriétaire, un Administrateur, un membre Finance ou un rôle personnalisé qui a **Gérer les factures** peut enregistrer un paiement, sur tous les forfaits. Aucun code de sécurité n'est demandé. ## Les étapes 1. **Ouvrez la facture** Dans **Factures**, ouvrez la facture. **Enregistrer le paiement** apparaît en tête tant qu'il reste un montant dû, même sur un brouillon, pour un client qui paie avant l'envoi. 2. **Choisissez le montant reçu** Cliquez sur **Enregistrer le paiement** : le dialogue **Enregistrer un paiement** s'ouvre. Sous **Montant reçu**, choisissez **Tout le solde**, ou **Une partie** puis saisissez le **Montant**, jusqu'au montant dû. 3. **Datez le paiement** **Reçu le** propose la date du jour : changez-la si l'argent est arrivé plus tôt, sans remonter avant la création de la facture. **Moyen de paiement** et **Notes** sont facultatifs, et les notes ne sont visibles que de vos membres. ![Le dialogue Enregistrer un paiement : Tout le solde sélectionné avec 174 000 FCFA, la date de réception du jour, les champs Moyen de paiement et Notes vides, et le bouton Enregistrer 174 000 FCFA.](https://docs.wajub.com/dashboard/fr/light/invoices-record-payment.webp) *Le bouton reprend le montant enregistré.* 4. **Enregistrez le paiement** Le bouton reprend le montant, par exemple « Enregistrer 174 000 FCFA ». Pour tout le solde, la facture passe à **Payée** avec **Facture marquée comme payée**. Pour une partie, elle passe à **Partiellement payé** avec « Paiement enregistré. Le reste de la facture reste dû. ». Le paiement apparaît dans **Historique**, avec son moyen et ses notes. Sur une facture en plusieurs échéances, le paiement règle les [échéances](https://docs.wajub.com/dashboard/invoices/installments#track-the-installments) dans l'ordre. ## Marquer comme payée Sur une facture envoyée, **Marquer comme payée** enregistre d'un coup tout le montant dû, reçu hors de Wajub et daté d'aujourd'hui. Confirmez dans **Marquer cette facture comme payée ?** : la facture passe à **Payée**. ## Ce que voit le client Le client ne reçoit aucun message : sa page de paiement ne lui demande plus que ce qui reste dû. --- # Créer une facture récurrente URL: https://docs.wajub.com/fr/dashboard/invoices/recurring > Faire préparer une copie d'une facture chaque jour, semaine, mois, trimestre ou année, l'envoyer après vérification, et arrêter la série quand elle n'a plus lieu d'être. Une facture récurrente prépare une nouvelle facture pour le même client à chaque période, avec les mêmes lignes : vous la vérifiez, puis vous l'envoyez. Seuls le propriétaire et les Administrateurs rendent une facture récurrente, à partir du forfait **Growth** : pour les autres, l'option n'apparaît pas dans le formulaire. Arrêter une série est ouvert à tous ceux qui peuvent [créer une facture](https://docs.wajub.com/dashboard/invoices/create). Aucun code de sécurité n'est demandé. ## Les étapes 1. **Commencez une facture** Ouvrez **Factures**, puis **Créer une facture**, et remplissez le client et les lignes comme pour [une facture ponctuelle](https://docs.wajub.com/dashboard/invoices/create). Saisissez l'**E-mail** du client : sans lui, aucune copie ne pourra lui être envoyée. Saisi sans e-mail ni téléphone, le client n'entre pas dans votre répertoire et aucune copie n'est préparée. 2. **Activez Facture récurrente** À l'étape **Paiement**, plus bas, activez **Facture récurrente**. Trois champs apparaissent : **Fréquence**, **Première copie le** et **Dernière copie au plus tard le**. 3. **Choisissez le rythme** Choisissez la **Fréquence**, de **Chaque jour** à **Chaque année**. Sans **Première copie le**, la première copie arrive une période après la **Date de facture**. Sans **Dernière copie au plus tard le**, la série continue jusqu'à ce que vous l'arrêtiez. ![L'interrupteur Facture récurrente activé, la fréquence Chaque mois, puis les champs Première copie le et Dernière copie au plus tard le, marqués Facultatif et remplis chacun d'une date.](https://docs.wajub.com/dashboard/fr/light/invoices-recurring.webp) *Les deux dates sont facultatives.* 4. **Créez la facture** Terminez avec **Examiner**, puis créez la facture. Sur sa page, **Détails de la facture** affiche **Récurrent** avec la fréquence et la date de la prochaine copie. ## Chaque copie À chaque date, une nouvelle facture apparaît dans **Factures** en **Brouillon**, datée de ce jour, avec les lignes, la devise et les notes de la facture d'origine, et le client tel qu'il est alors dans votre répertoire. Rien ne part tout seul : filtrez la liste sur le **Statut** **Brouillon**, vérifiez chaque copie, puis **Envoyer la facture**. Si la préparation d'une copie échoue, une notification vous prévient. Si votre forfait ne comprend plus les factures récurrentes, les copies s'interrompent, et reprennent quand vous repassez à [**Growth** ou au-dessus](https://docs.wajub.com/dashboard/subscription/plans). ## Arrêter la série Sur la page de la facture d'origine, choisissez **Arrêter la récurrence** dans le menu à droite des boutons, puis confirmez. Plus aucune copie n'est préparée, celles déjà créées restent telles quelles, et **Récurrent** disparaît de **Détails de la facture**. L'option n'existe que sur la facture d'origine, pas sur ses copies. [Annuler la facture d'origine](https://docs.wajub.com/dashboard/invoices/correct-cancel-refund) arrête aussi la série. --- # Paramétrer les factures URL: https://docs.wajub.com/fr/dashboard/invoices/settings > Choisir l'adresse où les clients ouvrent leurs factures, la numérotation, et le délai de paiement, la façon de payer et la devise de chaque nouvelle facture. **Paramètres › Factures** donne l'adresse de vos factures, leur numérotation, ce avec quoi commence chaque nouvelle facture et les rappels envoyés à vos clients. Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les paramètres** modifie ces réglages. Aucun code de sécurité n'est demandé. ## Adresse des factures Le **Domaine** est l'adresse où vos clients ouvrent et paient leurs factures : par défaut « L'adresse de Wajub (invoice.wajub.com) ». Pour utiliser la vôtre, [ajoutez et vérifiez un domaine](https://docs.wajub.com/dashboard/settings/custom-domains) pour les factures, puis choisissez-le dans la liste. ## Numérotation Une facture reçoit son numéro à l'envoi : les brouillons n'en ont pas. Choisissez le **Préfixe** (lettres, chiffres, tirets et tirets bas), le **Format**, avec ou sans l'année, et le **Prochain numéro**. **Prochain numéro de facture** montre le résultat, par exemple INV-2026-0001. Un numéro déjà donné est sauté. ![La section Numérotation : le préfixe INV-, le format avec l'année, le prochain numéro 1044, l'aperçu INV-2026-1044 sous Prochain numéro de facture et l'interrupteur Repartir de 1 chaque année activé.](https://docs.wajub.com/dashboard/fr/light/invoices-settings.webp) *L'aperçu suit le préfixe, le format et le prochain numéro.* Avec un format qui affiche l'année, **Repartir de 1 chaque année** donne le numéro 1 à la première facture envoyée dans une nouvelle année. Le préfixe ne peut pas être celui des avoirs, AV-, pour que factures et avoirs gardent chacun leur série. ## Paiement Ces valeurs remplissent chaque nouvelle facture, qui peut les changer. Le **Délai de paiement (jours)**, de 1 à 365, place la date d'échéance après la date de facture. **Comment les clients paient** choisit la façon de payer proposée, et **Devise** la devise de départ. ## Rappels **Envoyer les relances automatiquement** écrit à vos clients au sujet de leurs factures encore dues, pour les factures qui ont une échéance, jusqu'à ce qu'elles soient payées en entier ou annulées. Une fois l'interrupteur activé, cochez les jours sous **Avant l'échéance** et **Après l'échéance** : 1, 3, 7 ou 14 jours. Tant que vous n'avez pas enregistré votre choix, le formulaire montre l'interrupteur activé, avec 7, 3 et 1 jours avant l'échéance et 1 et 7 jours après. Chaque rappel apparaît dans l'[**Historique**](https://docs.wajub.com/dashboard/invoices/track-and-remind#automatic-reminders) de la facture. ## Enregistrer Une barre apparaît en bas dès qu'un réglage change : **Enregistrer les modifications** enregistre toutes les sections modifiées, **Abandonner** les remet comme avant. Si un champ est refusé, il s'affiche en rouge avec la raison. --- # Suivre et relancer une facture URL: https://docs.wajub.com/fr/dashboard/invoices/track-and-remind > Retrouver une facture, lire son statut et ce qu'il reste à payer, suivre les rappels envoyés au client et lui renvoyer la facture. La liste **Factures** et la page de chaque facture montrent ce que vos clients ont payé et ce qu'ils doivent encore. Le client est relancé par e-mail, et vous pouvez lui renvoyer la facture à tout moment. Tous les rôles qui lisent les factures ([Rôles](https://docs.wajub.com/fr/dashboard#roles)) suivent leur statut. **Renvoyer** demande **Gérer les factures**, comme [la création](https://docs.wajub.com/dashboard/invoices/create). Aucun code de sécurité n'est demandé. ## Trouver une facture En haut de **Factures**, quatre chiffres résument l'activité : **Factures**, **Facturé**, **Payée** et **En retard**. Cherchez une facture dans le champ **Numéro, client ou e-mail**, et filtrez par **Date de facture**, **Statut**, **Client**, **Date d'échéance**, **Montant** ou **Récurrent**. Les avoirs ne figurent pas dans la liste : ils sont sur la page de leur facture. | Statut | Ce qu'il veut dire | | ---------------------- | -------------------------------------------------------------------------------- | | **Brouillon** | Pas encore envoyée : sans numéro, encore modifiable. | | **Envoyée** | Numérotée et payable, pas encore ouverte par le client. | | **Vu** | Le client a ouvert sa page de paiement. | | **Partiellement payé** | Une partie est payée, le reste est dû. | | **Payée** | Réglée en totalité. | | **En retard** | La date d'échéance est passée et il reste un montant dû. | | **Annulée** | Le client ne peut plus la payer. | | **Remboursé** | Ce qui a été payé en ligne est remboursé en totalité, ou des avoirs le couvrent. | ## Lire la page d'une facture En tête, la page donne le client, la **Date d'échéance** et le **Montant dû**. Une facture en retard affiche **Cette facture est en retard**, avec le montant et la date où il était dû. À droite, **Paiement** répartit le total entre ce qui est payé, crédité et dû, et **Lien de paiement** donne le lien de paiement, avec **Copier**. ![L'en-tête de la facture INV-2026-1043 de 174 000 FCFA : le statut En retard, les boutons Télécharger le PDF, Renvoyer, Enregistrer le paiement et Marquer comme payée, puis l'encadré Cette facture est en retard.](https://docs.wajub.com/dashboard/fr/light/invoices-overdue.webp) *Une facture en retard le signale sous son en-tête.* **Historique** retrace les paiements, les rappels et chaque version de la facture, du plus ancien au plus récent. **Télécharger en CSV** en exporte les paiements. ## Les rappels automatiques Quand une facture envoyée a une date d'échéance, le client reçoit des rappels par e-mail aux jours réglés sous [**Rappels**](https://docs.wajub.com/dashboard/invoices/settings#reminders) dans **Paramètres › Factures**, jusqu'à ce qu'elle soit payée en entier ou annulée. Après un paiement partiel, ils continuent pour ce qu'il reste à payer. Chaque rappel, prévu ou parti, apparaît dans **Historique** avec son type et son statut. Pour une facture en plusieurs échéances, les rappels suivent la [dernière échéance](https://docs.wajub.com/dashboard/invoices/installments). ## Renvoyer la facture Sur la page d'une facture envoyée et pas encore réglée, **Renvoyer** envoie de nouveau l'e-mail de la facture au client. Le dialogue rappelle son adresse ; confirmez avec **Renvoyer**, et **E-mail de facture renvoyé avec succès** s'affiche. Rien d'autre ne change sur la facture. Pour la transmettre autrement, **Télécharger le PDF**, en tête de page, ou **Copier le lien de paiement**, dans le menu à droite des boutons. --- # Créer une alerte URL: https://docs.wajub.com/fr/dashboard/orchestration/alerts > Prévenir vos membres par e-mail quand le taux de réussite, le volume ou les webhooks de vos paiements franchissent un seuil, ou quand l'acceptation d'un fournisseur passe sous son niveau habituel, puis suivre les alertes déclenchées. Une alerte surveille un indicateur de vos paiements et prévient vos membres par e-mail quand il franchit un seuil, par exemple une baisse du taux de réussite sur MTN Mobile Money. Le propriétaire, un Administrateur, un Développeur ou un rôle personnalisé qui a **Gérer les paramètres** ou **Gérer les paramètres développeur** crée les alertes ; **Voir les paramètres** suffit pour les lire. Les alertes font partie de tous les forfaits, sauf **Acceptation sous son niveau habituel**, qui vient avec les forfaits **Growth**, **Scale** et **Enterprise**. Elles ne surveillent que la [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Aucun code de sécurité n'est demandé. ## Les étapes 1. **Ouvrez le dialogue** En **Production**, ouvrez **Orchestration**, l'onglet **Alertes**, puis **Créer l'alerte**. Le dialogue **Créer l'alerte** s'ouvre. 2. **Nommez l'alerte** Saisissez un **Nom** que vos membres reconnaîtront dans l'e-mail, par exemple « Taux de réussite de MTN Cameroun ». 3. **Choisissez l'indicateur** Sous **Métrique**, choisissez ce que l'alerte mesure, comme le **Taux de réussite**, le **Taux d'erreur**, le **Nombre de transactions**, le **Volume**, le **Taux de livraison des webhooks**, le **Nombre d'échecs de webhook**, le **Taux d'abandon du tunnel** ou l'**Acceptation sous son niveau habituel**, qui vous prévient quand un fournisseur accepte moins de paiements que d'habitude sur un canal. Sur un autre forfait, celle-ci affiche **Pas dans votre forfait**. 4. **Fixez le seuil** Réglez la **Condition**, par exemple « descend sous », le **Seuil**, puis la **Fenêtre** sur laquelle l'indicateur est calculé : 5 minutes, 15 minutes, 1 heure ou 24 heures. Pour **Acceptation sous son niveau habituel**, réglez à la place la **Baisse d'au moins**, en points sous le niveau habituel, et les **Tentatives minimum** en dessous desquelles rien n'est comparé. 5. **Choisissez ce qu'elle surveille** Sous **Ce qu'elle surveille**, gardez **Tous les paiements**, ou limitez l'alerte à **Un fournisseur**, **Un canal** ou **Une règle de routage**. Seuls le taux de réussite, le taux d'erreur, le nombre de transactions et le volume se limitent ainsi ; les alertes sur les webhooks et l'abandon couvrent tout votre compte. **Acceptation sous son niveau habituel** surveille **Tous les fournisseurs et canaux**, **Un fournisseur** ou **Un canal**. 6. **Choisissez les destinataires** Sous **Destinataires**, vous figurez déjà ; cliquez sur **En ajouter** pour choisir d'autres membres : seuls les membres de votre organisation peuvent recevoir l'e-mail. Sans destinataire, l'alerte est seulement enregistrée sur la page. Le **Délai de répit**, de 5 à 1 440 minutes, l'empêche de se déclencher de nouveau trop tôt ; pour **Acceptation sous son niveau habituel**, il compte pour chaque fournisseur et canal, une fois revenu à la normale. ![Le dialogue Créer l'alerte : le nom Taux de réussite de MTN Cameroun, la métrique Taux de réussite, la condition descend sous 90 % sur 15 minutes, Un canal avec MTN Mobile Money (Cameroun), puis deux membres destinataires.](https://docs.wajub.com/dashboard/fr/light/orchestration-alert-dialog.webp) *Seuls les membres de l'organisation peuvent recevoir une alerte.* 7. **Créez l'alerte** Laissez **Actif** activé, puis cliquez sur **Créer l'alerte**. Le message **Règle d'alerte créée.** s'affiche, et l'alerte rejoint les **Définitions d'alertes**. ## Après la création Une alerte active est vérifiée toutes les 5 minutes. Quand elle franchit son seuil, ses destinataires reçoivent un e-mail, puis elle reste silencieuse pendant son délai de répit. **Alertes récentes** liste les derniers déclenchements, et chaque alerte affiche son **Dernier déclenchement**. Si une alerte active ne prévient personne, un avertissement le signale en haut de la page. [Alertes](https://docs.wajub.com/fr/orchestration/analytics#alerts) détaille ce que compte chaque indicateur. Une alerte **Acceptation sous son niveau habituel** affiche aussi les fournisseurs et canaux sous leur niveau habituel, et sa **Dernière vérification**. Sur un forfait qui ne la comprend pas, elle est marquée **Pas dans votre forfait** et n'est pas vérifiée ; vous pouvez toujours la désactiver ou la supprimer. Le menu d'une alerte propose **Modifier l'alerte**, **Désactiver l'alerte**, qui la garde sans plus la vérifier, et **Supprimer l'alerte**, qui demande confirmation : ses déclenchements passés restent listés. --- # Définir une politique de canal URL: https://docs.wajub.com/fr/dashboard/orchestration/channel-policies > Choisir comment Wajub classe vos fournisseurs sur un canal d'opérateur, par acceptation, coût ou rapidité, avec un ordre fixe et des garde-fous, depuis la matrice de routage. Une politique de canal classe vos fournisseurs sur un canal d'opérateur, comme MTN Mobile Money au Cameroun, pour chaque paiement qu'aucune règle de routage ne capte. Sans politique, c'est la priorité de chaque connexion qui décide. Le propriétaire, un Administrateur, un Développeur ou un rôle personnalisé qui a **Gérer les paramètres** ou **Gérer les paramètres développeur** définit une politique ; **Voir les paramètres** suffit pour lire la matrice. Les politiques font partie de tous les forfaits et n'existent qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Aucun code de sécurité n'est demandé. ## Les étapes 1. **Ouvrez la matrice** En **Production**, ouvrez **Orchestration**, puis l'onglet **Matrice**. Sous **Canaux opérateurs**, chaque canal montre ses routes, une par fournisseur qui le sert. Les **Méthodes de paiement mondiales**, comme la carte, n'ont pas de politique. 2. **Ouvrez la politique du canal** Cliquez sur **Définir une politique** au bout de la ligne du canal, ou sur **Modifier la politique** s'il en a déjà une. Le dialogue **Politique du canal** s'ouvre, titré avec le nom du canal, par exemple MTN CM. 3. **Choisissez l'objectif** Dans **Objectif de routage**, **Acceptation maximale** place en tête le fournisseur qui réussit le plus de paiements sur cet opérateur, **Coût le plus bas** le moins cher, d'après les frais saisis sur chaque connexion, et **Le plus rapide** celui qui répond le plus vite. 4. **Fixez un ordre, si besoin** Avec au moins deux connexions sur le canal, activez **Ordre de cascade fixe** : la liste des connexions s'affiche, et **Monter** et **Descendre** règlent l'ordre dans lequel elles sont essayées, avant que l'objectif classe les autres. 5. **Posez des garde-fous** Sous **Garde-fous**, une connexion sous la **Santé minimale**, de 0 à 100 %, ou au-dessus du **Plafond de coût**, en frais par paiement dans la devise du paiement, passe après les autres. Elle n'est jamais écartée. ![Le dialogue Politique du canal sur MTN CM : l'objectif Acceptation maximale, un ordre de cascade fixe de deux connexions, la santé minimale à 80 % et l'interrupteur Actif activé.](https://docs.wajub.com/dashboard/fr/light/orchestration-policy-dialog.webp) *Une règle de routage qui correspond au paiement passe toujours avant la politique.* 6. **Enregistrez la politique** Laissez **Actif** activé, puis cliquez sur **Enregistrer la politique**. Un message confirme l'enregistrement, et la ligne du canal affiche un badge qui résume la politique. ## Ce que la politique décide La politique ne vaut que pour son canal, et seulement pour les paiements qu'aucune [règle de routage](https://docs.wajub.com/dashboard/orchestration/routing-rules) n'a captés. Elle y remplace la priorité de vos connexions. Une politique dont vous désactivez **Actif** est gardée, et la priorité reprend la main. [L'instruction la plus précise passe en premier](https://docs.wajub.com/fr/orchestration#the-most-specific-instruction-goes-first) détaille cet ordre. Pour revenir à la priorité des connexions, rouvrez la politique et cliquez sur **Retirer la politique**, puis confirmez. ## Lire la matrice Chaque ligne porte un diagnostic, comme **Opérationnel**, **Opérateur hors service**, **Problème d'agrégateur**, **Chemin unique** ou **Aucune donnée**, et chaque route son taux de réussite et l'état de son circuit. **Collecte** et **Transfert**, en haut, changent d'opération, et **Actualiser** recharge les chiffres. [La matrice et le diagnostic qu'elle permet](https://docs.wajub.com/fr/orchestration/analytics#the-matrix-and-the-diagnosis-it-enables) dit quoi faire d'une ligne ou d'une cellule rouge. --- # Connecter un fournisseur URL: https://docs.wajub.com/fr/dashboard/orchestration/connect-provider > Connecter votre propre compte chez un fournisseur de paiement, régler sa priorité et ses frais, coller son URL de webhook, puis le mettre en pause ou le déconnecter. Une connexion relie votre propre compte chez un fournisseur de paiement à Wajub. Avec deux connexions ou plus, un paiement refusé par l'une peut être repris par une autre. Le propriétaire, un Administrateur, un Développeur ou un rôle personnalisé qui a **Gérer les paramètres** ou **Gérer les paramètres développeur** connecte un fournisseur ; **Prévenez-moi quand disponible** demande **Gérer les paramètres**. Le forfait **Pay as you go** permet 2 fournisseurs, **Growth** 6, **Scale** et **Enterprise** n'ont pas de limite, et le rail Wajub ne compte pas. Les connexions n'existent qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est demandé que pour régénérer l'URL du webhook ou déconnecter un fournisseur. ## Les étapes 1. **Ouvrez le catalogue** En **Production**, ouvrez **Orchestration**, l'onglet **Fournisseurs**, puis **Ajouter un fournisseur**. La recherche et les filtres **Pays**, **Région**, **Type** et **Statut** réduisent le catalogue. Si votre forfait est plein, la page affiche **Limite de fournisseur atteinte** avec **Passer à un forfait supérieur**. 2. **Choisissez le fournisseur** Cliquez sur **Connecter** sous sa carte. Un fournisseur à venir propose **Prévenez-moi quand disponible** à la place. Le rail Wajub n'est pas dans le catalogue : [Demander le rail Wajub](https://docs.wajub.com/dashboard/orchestration/rail). 3. **Saisissez les identifiants** Sous **Identifiants API**, remplissez les champs que ce fournisseur demande, tels que votre tableau de bord chez lui les affiche. Certains fournisseurs ont des identifiants par pays : remplissez au moins un pays. Cliquez sur **Continuer**. 4. **Choisissez les canaux** Sous **Canaux de paiement**, cochez les canaux à confier à ce fournisseur, ou **Tout sélectionner** ; seuls les canaux des pays dont vous avez saisi les identifiants sont proposés. Il faut au moins un canal. 5. **Réglez le routage** Sous **Paramètres de routage**, la **Priorité** la plus haute est essayée en premier, et le **Poids (%)** répartit le trafic entre fournisseurs de même priorité. Désactivez **L'activer dès sa connexion** pour le connecter en pause. **Frais (pour le routage au moindre coût)** est facultatif : votre **Taux variable (%)**, vos **Frais fixes**, les **Devises** acceptées (vide pour toutes) et des **Personnalisations par canal**. ![L'étape Routage de la connexion d'un fournisseur : la section Paramètres de routage avec les champs Priorité et Poids (%) et l'interrupteur L'activer dès sa connexion activé, puis la section Frais (pour le routage au moindre coût).](https://docs.wajub.com/dashboard/fr/light/orchestration-provider-setup.webp) *Une règle de routage ou une politique de canal passe avant la priorité.* 6. **Connectez le fournisseur** L'étape **Examiner** résume vos choix et essaie vos identifiants sous **Vérification de la connexion**. Si l'essai échoue, le fournisseur sera connecté en pause, sauf si vous cochez **L'activer quand même**. Cliquez sur **Connecter le fournisseur** : sa page s'ouvre avec le message **Fournisseur activé avec succès.** Si vous quittez en cours de route, la page affiche à votre retour dans le même onglet, pendant 24 heures, **Nous avons restauré votre configuration inachevée** : vos choix reviennent, pas les identifiants. **Repartir de zéro** efface le tout. ## Après la connexion Sur la page du fournisseur, l'onglet **Paramètres** affiche l'**Endpoint de webhook** : copiez-le avec **Copier l'URL du webhook** et collez-le dans votre tableau de bord chez le fournisseur, pour que Wajub apprenne l'issue de vos paiements. **Tester la connexion**, sous **Diagnostics**, vérifie vos identifiants. ![L'onglet Paramètres de Campay : la carte Endpoint de webhook avec son URL, le bouton de copie et le bouton Régénérer l'URL, puis la carte Diagnostics avec le bouton Tester la connexion.](https://docs.wajub.com/dashboard/fr/light/orchestration-provider-settings.webp) *Sans cette URL chez le fournisseur, Wajub n'apprend pas l'issue des paiements.* Le même onglet règle le routage, les frais, les canaux et les devises, enregistrés avec **Enregistrer les modifications**. L'interrupteur sous **Statut** met le fournisseur en pause tout de suite, sans rien supprimer. L'onglet **Identifiants** remplace un identifiant avec **Mettre à jour les identifiants** ; les secrets enregistrés ne s'affichent jamais. **Régénérer l'URL** demande le code de sécurité. L'ancienne URL cesse aussitôt de fonctionner : collez la nouvelle chez le fournisseur. Si le fournisseur refuse vos identifiants, la liste affiche **Connexion refusée** et sa page propose **Corriger la connexion** : [Lorsqu'une connexion rencontre un problème](https://docs.wajub.com/fr/orchestration/providers#when-a-connection-goes-bad). ## Déconnecter un fournisseur Sous **Zone dangereuse**, cliquez sur **Déconnecter le fournisseur**, saisissez son nom, puis le code de sécurité. La connexion, ses identifiants et ses réglages sont supprimés, ainsi que les règles de routage qui lui envoient des paiements ; celles dont il était le fournisseur de repli le perdent. Le message « Campay déconnecté. » le confirme. Pour le reconnecter, il faudra saisir de nouveau ses identifiants. Le rail Wajub ne se déconnecte pas ici. --- # Suivre la santé du routage URL: https://docs.wajub.com/fr/dashboard/orchestration/overview > Lire la vue d'ensemble de l'orchestration, ses incidents et ses recommandations, le statut en temps réel de vos routes, les paiements de la période et la performance de vos fournisseurs et des opérateurs. L'orchestration répartit vos paiements entre les fournisseurs que vous connectez. Sa vue d'ensemble dit si vos routes de paiement marchent, ce qu'il faut corriger, et comment vos fournisseurs ont fonctionné sur la période choisie. Le propriétaire, un Administrateur, un Développeur, un Observateur ou un rôle personnalisé qui a **Voir les paramètres** ouvre l'orchestration. La modifier demande **Gérer les paramètres** ou **Gérer les paramètres développeur** : le propriétaire, un Administrateur ou un Développeur. L'orchestration fait partie de tous les forfaits et n'existe qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Aucun code de sécurité n'est demandé pour la lire. ## Les onglets En **Production**, ouvrez **Orchestration** dans le menu. Les onglets mènent aux autres tâches : **Wajub Rail** ([Demander le rail Wajub](https://docs.wajub.com/dashboard/orchestration/rail)), **Fournisseurs** ([Connecter un fournisseur](https://docs.wajub.com/dashboard/orchestration/connect-provider)), **Matrice** ([Définir une politique de canal](https://docs.wajub.com/dashboard/orchestration/channel-policies)), **Règles de routage** ([Créer une règle de routage](https://docs.wajub.com/dashboard/orchestration/routing-rules)) et **Alertes** ([Créer une alerte](https://docs.wajub.com/dashboard/orchestration/alerts)). **Canaux** compare vos fournisseurs canal par canal : le **Taux de réussite**, les **Tentatives**, le **Volume**, le **Meilleur fournisseur**, le **Moins bon fournisseur** et l'**Écart** entre eux, puis la même chose **Par pays**. Une ligne ouvre la page du canal, où ses fournisseurs sont côte à côte. L'onglet vient avec les forfaits **Growth**, **Scale** et **Enterprise** ; sur un autre forfait, il affiche **Non inclus dans votre forfait** avec **Voir les forfaits**. ## La période et les filtres En haut, **Période** choisit les jours que couvre la page, et **Comparer à** fixe ce à quoi chaque chiffre est comparé : **Période précédente**, **Même période l'an dernier** ou **Aucune comparaison**. **Fournisseur**, **Canal**, **Pays** et **Devise** restreignent les chiffres de la période, et **Effacer les filtres** les retire. ## Incidents et recommandations **Incidents et recommandations** liste ce qui demande une action, chaque ligne marquée **Critique**, **Avertissement** ou **Attention**. Un incident sur l'un de vos canaux propose **Examiner**, qui ouvre la matrice. Un incident chez un opérateur précise qu'il vient de l'opérateur, pas de votre configuration, et propose **Voir l'état des opérateurs**. Une recommandation propose son propre bouton ; vous pouvez la masquer, et elle reste masquée dans ce navigateur. ## Le statut en temps réel **Statut de routage en temps réel** affiche **Vos routes de paiement sont saines**, ou le nombre de canaux qui demandent votre attention, avec **Ouvrir la matrice de routage**. **Fournisseurs en ce moment** donne la santé de chaque fournisseur : **Sain**, **Dégradé**, **En échec**, **Trop peu de trafic** ou **En pause** ; un fournisseur ouvre sa page. En dessous viennent le nombre de canaux surveillés et de fournisseurs actifs, et **Dernière mise à jour**, qui dit de quand date le dernier relevé. Le statut se met à jour tout seul. ![Le statut de routage en temps réel : Vos routes de paiement sont saines avec le bouton Ouvrir la matrice de routage, la liste Fournisseurs en ce moment avec la santé de chaque fournisseur, puis les canaux surveillés, les fournisseurs actifs et la dernière mise à jour.](https://docs.wajub.com/dashboard/fr/light/orchestration-overview.webp) *Le statut en temps réel se met à jour tout seul.* ## Les paiements de la période **Paiements sur la période** donne le **Taux de réussite**, le **Volume crédité**, avec le délai médian de crédit, les **Paiements terminés**, réussis et échoués, sans ceux encore en attente, et les paiements **Sauvés par un repli** : ceux qu'un autre fournisseur a encaissés après l'échec du premier. Chaque chiffre montre son évolution par rapport à la comparaison. Le taux de réussite, le volume et les paiements terminés ouvrent les paiements correspondants. **Acceptation par fournisseur** trace, sur la période, la part des tentatives terminées de chaque fournisseur qu'il a acceptées. ## La performance des fournisseurs **Performance des fournisseurs** compare vos fournisseurs : **Acceptation**, **Tentatives**, **Échecs du fournisseur**, **Temps de réponse**, **Volume** et **Échec le plus fréquent**. Un fournisseur avec peu de tentatives est marqué **Échantillon faible**. Une ligne ouvre la page du fournisseur, et **Gérer les fournisseurs** ouvre l'onglet **Fournisseurs**. Sans tentative sur la période, le tableau affiche **Aucune tentative de fournisseur sur cette période**. **Fournisseurs par canal** montre l'acceptation de chaque fournisseur sur chaque canal par rapport à la moyenne du canal ; une case ouvre le canal. **Où les paiements échouent** répartit les tentatives échouées selon l'endroit où elles se sont arrêtées, **Côté fournisseur**, **Côté client**, **Abandonné** ou **Inconnu**, puis liste les motifs les plus fréquents ; un motif ouvre ses paiements. ## L'état des opérateurs **État des opérateurs** montre les opérateurs par lesquels vous routez, sur l'ensemble de Wajub : leur état en ce moment et leur disponibilité sur les 90 derniers jours. --- # Demander le rail Wajub URL: https://docs.wajub.com/fr/dashboard/orchestration/rail > Demander l'accès au rail de paiement de Wajub pour encaisser sur ses contrats partenaires, signer l'accord, suivre la demande puis ajouter des pays ou des canaux. Le rail Wajub encaisse vos paiements sur les contrats partenaires de Wajub, sans contrat à signer avec chaque opérateur. Il ne se connecte pas comme un autre fournisseur : vous envoyez une demande signée, et Wajub l'examine. Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les paramètres** fait la demande et la signe ; un Développeur, un Observateur ou un rôle qui a **Voir les paramètres** suit son statut. Le rail est ouvert à tous les forfaits et ne compte pas dans leur limite de fournisseurs. Il n'existe qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), et aucun code de sécurité n'est demandé. Votre compte doit être vérifié : [Vérifier son entreprise](https://docs.wajub.com/dashboard/activation/verify-business). ## Les étapes 1. **Ouvrez Wajub Rail** En **Production**, ouvrez **Orchestration**, puis l'onglet **Wajub Rail**. La page présente la **Couverture disponible**, pays par pays. Cliquez sur **Démarrer la demande** ; tant que le compte n'est pas vérifié, le bouton est **Terminez la vérification du compte**. ![La page Wajub Rail avant toute demande : le titre Un seul accord. Plusieurs rails de paiement locaux., le bouton Démarrer la demande et la couverture disponible, avec le Cameroun et ses opérateurs.](https://docs.wajub.com/dashboard/fr/light/orchestration-rail-status.webp) *La couverture affichée est celle que le rail propose aujourd'hui.* 2. **Présentez votre entreprise** À l'étape **Votre entreprise**, décrivez votre produit ou service en 50 caractères au moins, choisissez le **Type de produit** et le **Cas d'utilisation principal**, ajoutez les liens de votre site ou de vos réseaux, puis estimez votre activité mensuelle. Cliquez sur **Continuer**. 3. **Donnez ce que l'examen demande** À l'étape **Pour l'examen**, **Ce dont Wajub a besoin pour examiner votre demande**, choisissez sous **Où vos clients paient-ils ?** : **Sur un site web**, **Dans une application mobile** ou **Ailleurs**. Les champs qui suivent dépendent de cette réponse et de ce que vous vendez : sur un site web, la **Page des conditions de vente** et la **Page de la politique de remboursement** ; ailleurs, **Où vos clients vous trouvent** et **Comment un client achète et paie** ; pour une application qui n'est pas encore en boutique, une **Version de test de l'application**. Sous **Compte de test pour l'examen**, donnez l'identifiant et le mot de passe d'un compte créé pour l'examen, jamais votre propre accès administrateur. Il est facultatif, sauf si votre produit s'utilise avec une connexion, comme une application mobile ou un abonnement. Cliquez sur **Continuer**. 4. **Choisissez les pays** À l'étape **Pays**, cochez les pays où vous voulez encaisser. Seuls les pays que le rail couvre sont proposés. 5. **Choisissez les canaux** À l'étape **Canaux**, cochez les opérateurs à demander. Ceux que votre compte a déjà apparaissent sous **Déjà accordés**, inutile de les redemander. ![L'étape Canaux de la demande : MTN Mobile Money CM, Orange Money CM et Express Union Mobile Money CM cochés, Virement bancaire laissé décoché.](https://docs.wajub.com/dashboard/fr/light/orchestration-rail-channels.webp) *Wajub peut accorder une partie seulement des canaux demandés.* 6. **Vérifiez la tarification** L'étape **Tarification** donne, pour chaque canal, les **Frais de paiement de référence** et les **Frais de transfert de référence** de votre forfait actuel. Le taux final peut varier selon la route de traitement, et vous connaissez les frais avant de confirmer une transaction. 7. **Signez et envoyez la demande** À l'étape **Vérifier et signer**, lisez le contrat sous **Lire et signer l'accord**, saisissez votre **Nom légal complet** tel qu'il figure dans votre dossier de vérification, cochez la déclaration, puis cliquez sur **Signer et soumettre**. Le message **Votre demande a été soumise pour examen.** s'affiche. ## Suivre la demande **Votre demande** indique sa date d'envoi, et Wajub vous répond par e-mail. Une seule demande peut être en cours à la fois. **Vos demandes** liste chacune avec son statut : **En cours d'examen**, **Approuvé**, **Partiellement approuvé**, où les canaux cochés sont ceux accordés, ou **Rejeté**. Après un refus, la page affiche **Votre dernière demande a été refusée.**, avec le motif quand Wajub en a donné un, et propose **Faire une nouvelle demande**. Le contrat ne prend effet qu'une fois la demande acceptée. Si votre compte utilisait déjà le rail avant ces demandes, la page affiche **Signez votre contrat Wajub Rail** avec une date limite. Saisissez votre **Nom légal complet**, cochez la déclaration, puis cliquez sur **Signer l'accord** avant cette date : passé ce délai, Wajub suspend votre connexion au rail, et il faut envoyer une nouvelle demande. ## Après l'approbation **Votre rail Wajub** indique l'état de votre connexion, ses **Marchés** et ses **Canaux actifs**. **Gérer la connexion** ouvre la page du rail parmi vos fournisseurs : vous y réglez sa priorité, le mettez en pause ou désactivez un canal accordé, comme pour un [fournisseur connecté](https://docs.wajub.com/dashboard/orchestration/connect-provider#after-creating-it). En dessous, la page suit le rail sur la période choisie, par canal ou par pays si vous le souhaitez : **Performance**, **Acceptation dans le temps**, **Par canal et opérateur**, **Là où le rail fait mieux**, **Motifs d'échec** et **Temps de réponse et de confirmation**. **État des opérateurs** donne l'état des opérateurs que le rail dessert. **Tarification et frais** met le prix signé pour chaque canal à côté des frais facturés sur la période, et **Quand l'argent est disponible** indique quand l'argent de ses paiements a rejoint votre solde disponible. Pour encaisser dans d'autres pays, **Couverture** liste les pays et les opérateurs que le rail couvre : **Demander ce pays**, sur la ligne d'un pays, ou **Demander d'autres canaux** ouvre une nouvelle demande. **Contrat et demandes** donne le contrat signé, que **Télécharger l'accord** enregistre en PDF, et l'historique de vos demandes. --- # Créer une règle de routage URL: https://docs.wajub.com/fr/dashboard/orchestration/routing-rules > Envoyer certains paiements vers un fournisseur choisi, avec un fournisseur de repli, mesurer l'effet d'une règle sur vos derniers paiements, puis tester le routage. Une règle de routage envoie les paiements qui remplissent ses conditions vers le fournisseur de votre choix, par exemple Orange Money au Cameroun vers une connexion moins chère. Le propriétaire, un Administrateur, un Développeur ou un rôle personnalisé qui a **Gérer les paramètres** ou **Gérer les paramètres développeur** crée les règles ; **Voir les paramètres** suffit pour les lire, pas pour lancer l'aperçu ni le simulateur. Les règles font partie des forfaits **Growth**, **Scale** et **Enterprise** : avec **Pay as you go**, l'onglet n'apparaît pas. Elles n'existent qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), et aucun code de sécurité n'est demandé. Il faut au moins un [fournisseur connecté](https://docs.wajub.com/dashboard/orchestration/connect-provider). ## Les étapes 1. **Ouvrez le dialogue** En **Production**, ouvrez **Orchestration**, l'onglet **Règles de routage**, puis **Créer la règle**. Sans fournisseur connecté, la page affiche **Connectez d'abord un fournisseur**. 2. **Nommez la règle** Saisissez un **Nom de la règle** qui dit ce qu'elle fait : la liste et le simulateur l'affichent. 3. **Choisissez le fournisseur** Sous **Router vers le fournisseur**, choisissez la connexion qui prendra ces paiements. Le **Fournisseur de repli**, facultatif, est essayé juste après lui s'il échoue, et à sa place quand il ne peut pas prendre le paiement. 4. **Fixez les conditions** Sous **Conditions**, remplissez ce qui compte parmi **Pays**, **Canal**, **Devise**, **Montant minimum** et **Montant maximum**, ces deux derniers dans la devise du paiement. Une condition vide accepte toutes les valeurs, et la règle ne s'applique que si toutes sont remplies. **Conditions avancées** ajoute des **Fenêtres horaires**, des **Segments clients**, des **Filtres de métadonnées** et des **Plafonds de fréquence**, et des **Étiquettes** qui servent seulement à retrouver la règle. 5. **Mesurez l'impact** Sous **Aperçu de l'impact**, cliquez sur **Exécuter l'aperçu**. Vos paiements des 7 derniers jours sont rejoués : le panneau dit combien seraient allés vers un autre fournisseur, fournisseur par fournisseur. ![Le bas du dialogue Créer la règle : les conditions Cameroun et Orange Money, la section Place et part du trafic avec Actif activé, puis l'Aperçu de l'impact : « 4 paiements sur 4 seraient allés vers un autre fournisseur », d'Orange Money vers Campay.](https://docs.wajub.com/dashboard/fr/light/orchestration-rule-dialog.webp) *L'aperçu donne le maximum que la règle peut déplacer, pas une prévision.* 6. **Créez la règle** Laissez **Actif** activé, puis cliquez sur **Créer la règle**. Le message **Règle de routage créée avec succès.** s'affiche, et la règle prend sa place dans la liste. ## L'ordre des règles Un paiement va à la première règle de la liste qui lui correspond : la priorité la plus haute d'abord, puis à priorité égale celle qui a le plus de conditions. **Monter** et **Descendre** déplacent une règle, et toutes les priorités sont alors renumérotées depuis le haut. Des règles de même priorité et avec autant de conditions se partagent les paiements selon leur **Poids**. [Quelle règle l'emporte](https://docs.wajub.com/fr/orchestration/routing-rules#which-rule-wins) détaille le classement, et [L'instruction la plus précise passe en premier](https://docs.wajub.com/fr/orchestration#the-most-specific-instruction-goes-first) dit ce qui décide quand aucune règle ne correspond. Chaque ligne affiche les paiements correspondants sur 30 jours et leur taux d'acceptation. Son menu propose **Modifier la règle** et **Supprimer la règle** : les paiements qu'elle visait suivent alors vos autres règles, puis la politique du canal, puis la priorité de vos connexions. ## Tester le routage **Tester le routage** ouvre le **Simulateur de routage**. Choisissez l'un des **Scénarios rapides**, ou un **Canal de paiement** et un **Montant** avec sa devise, puis cliquez sur **Exécuter la simulation**. Le résultat donne le fournisseur essayé en premier, l'ordre des suivants, les connexions écartées sous **Écartés** avec leur motif, et le **Journal des décisions**. Rien n'est débité. [Le simulateur](https://docs.wajub.com/fr/orchestration/routing-rules#the-simulator-on-the-routing-rules-page) dit ce qu'il ne peut pas reproduire. --- # Créer un lien de paiement URL: https://docs.wajub.com/fr/dashboard/payment-links/create > Créer depuis le tableau de bord une page de paiement avec sa propre adresse, choisir son type, la décrire et la publier pour la partager par WhatsApp, SMS ou code QR. Un lien de paiement est une page de paiement avec sa propre adresse : vous la partagez par WhatsApp, par SMS ou avec un code QR, et toute personne qui a le lien peut payer. Le propriétaire et les [rôles](https://docs.wajub.com/fr/dashboard#roles) Administrateur, Développeur et Finance créent des liens, comme un rôle personnalisé qui a **Gérer les liens de paiement** ; un Analyste, un Observateur ou un rôle qui a seulement **Voir les liens de paiement** les consulte sans les modifier. Le forfait **Pay as you go** permet 25 liens, archivés compris ; **Growth** et les forfaits au-dessus n'ont pas de limite. Les liens n'existent qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Créer un lien ne demande pas de [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les quatre types de lien - [Vendre quelque chose](https://docs.wajub.com/dashboard/payment-links/sell-something) : un article, un contenu numérique ou un service, à prix fixe. - [Vendre des billets](https://docs.wajub.com/dashboard/payment-links/sell-tickets) : des places pour un concert, une formation ou un gala. - [Collecter des fonds](https://docs.wajub.com/dashboard/payment-links/raise-funds) : des contributions vers un objectif à atteindre. - [Recevoir des dons](https://docs.wajub.com/dashboard/payment-links/donations) : des dons du montant que choisit chaque donateur. ## Les étapes 1. **Ouvrez le formulaire** En **Production**, ouvrez **Liens de paiement**, puis **Créer un lien**. La page **Nouveau lien de paiement** montre le formulaire et, sur un grand écran, l'aperçu de la page de paiement telle que vos clients la verront, mis à jour à chaque modification. Sur un téléphone, le bouton **Aperçu** l'ouvre. 2. **Choisissez le type** Sous **Pour quoi voulez-vous encaisser ?**, choisissez l'un des quatre types. Pour **Vendre quelque chose**, choisissez aussi sous **De quel type ?** : **Article physique**, **Contenu numérique** ou **Service**. ![Nouveau lien de paiement : les quatre choix Vendre quelque chose (sélectionné), Vendre des billets, Collecter des fonds et Recevoir des dons, puis les types Article physique (sélectionné), Contenu numérique et Service, et les modèles Vêtement ou accessoire, Formation en ligne ou e-book et Consultation.](https://docs.wajub.com/dashboard/fr/light/link-type.webp) *Une fois le lien payé, son type ne peut plus changer.* 3. **Partez d'un modèle si besoin** Sous **Partir de :**, un modèle préremplit quelques réglages du type choisi, jamais le titre ni le prix. Les modèles disparaissent dès que le titre est rempli ; chaque page de type dit ce que préparent les siens. 4. **Décrivez l'offre** Dans **L'offre**, le **Titre** est obligatoire, de 3 à 120 caractères. Ajoutez si besoin une **Photo** et une **Description**. Les autres champs de la section dépendent du type. 5. **Remplissez les sections du type** Le prix, les montants ou les billets, puis la livraison ou l'accès, changent avec le type : suivez les étapes de sa page, [Vendre quelque chose](https://docs.wajub.com/dashboard/payment-links/sell-something#the-steps), [Vendre des billets](https://docs.wajub.com/dashboard/payment-links/sell-tickets#the-steps), [Collecter des fonds](https://docs.wajub.com/dashboard/payment-links/raise-funds#the-steps) ou [Recevoir des dons](https://docs.wajub.com/dashboard/payment-links/donations#the-steps). Les questions au client, les codes promo et les moyens de paiement valent pour les quatre : voir [Régler ce que remplit le client](https://docs.wajub.com/dashboard/payment-links/payer-fields). 6. **Choisissez l'adresse du lien** Dans **Adresse et accès**, **Adresse du lien** donne la fin de l'adresse, par exemple wajub.link/sac-adaora ; laissez-la vide pour une adresse courte générée automatiquement. Le formulaire dit tout de suite si elle est libre. Le mot de passe, la date de fermeture, **Fermer après le premier paiement** et les autres réglages d'accès sont décrits dans [Partager un lien](https://docs.wajub.com/dashboard/payment-links/share#address-and-access). 7. **Publiez le lien** **Publier le lien** crée le lien et le met en ligne ; le bouton devient **Créer le lien hors ligne** quand **Page en ligne** est désactivé. S'il reste des champs à corriger, le formulaire les liste, et un clic sur l'un d'eux y mène. Une fois la limite du forfait atteinte, la publication est bloquée et le brouillon reste enregistré. ## Les autres sections Les sections repliées résument leur réglage ; ouvrez-les au besoin. **Bouton et remerciement** change le **Texte du bouton**, que la page complète avec le montant, et affiche un **Message de remerciement** sur la confirmation. **Après le paiement, envoyer le client vers** l'envoie quelques secondes après le paiement vers une page de votre site, avec la référence du paiement dans l'adresse. **Votre organisation** range le lien avec une **Catégorie**, des **Étiquettes** pour filtrer la liste et une **Référence externe**, votre propre identifiant. Rien de cette section n'est montré aux clients. ## Ce que voit le client Le client ouvre la page à l'adresse du lien, remplit ce que le lien demande, paie avec l'un de vos moyens de paiement et reçoit son reçu par e-mail. ## Après la publication La fenêtre **Votre lien est en ligne** s'ouvre pour le partager : voir [Partager un lien](https://docs.wajub.com/dashboard/payment-links/share). Pour le changer, le mettre hors ligne ou le supprimer, voir [Modifier ou retirer un lien](https://docs.wajub.com/dashboard/payment-links/edit-offline-delete). > [!NOTE] > **Un lien commencé reste en brouillon** > > Tant que le lien n'est pas publié, le formulaire s'enregistre tout seul et l'en-tête affiche > **Brouillon enregistré**. Au prochain **Créer un lien**, le formulaire propose **Reprendre** ou > **Recommencer**. Le brouillon suit votre compte, pas l'appareil, et vous n'en avez qu'un à la > fois. --- # Recevoir des dons URL: https://docs.wajub.com/fr/dashboard/payment-links/donations > Créer un lien de dons avec des montants suggérés, des paliers qui disent ce que permet un don, un mur des donateurs et des dons anonymes. Le type **Recevoir des dons** accepte des dons du montant que choisit chaque donateur, sans objectif à atteindre : une offrande d'église, le soutien à une association. Pour viser un montant, créez plutôt un lien pour [collecter des fonds](https://docs.wajub.com/dashboard/payment-links/raise-funds). Il demande les mêmes droits qu'un [lien de paiement](https://docs.wajub.com/dashboard/payment-links/create) : **Gérer les liens de paiement**, la [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), et une place dans la limite de liens du forfait. Aucun [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est demandé. ## Les étapes 1. **Choisissez Recevoir des dons** Dans **Nouveau lien de paiement**, choisissez **Recevoir des dons**. Sous **Partir de :**, **Offrande ou dîme d'église** et **Association ou ONG** permettent les dons anonymes et proposent quatre montants courants, 1 000, 2 500, 5 000 et 10 000 FCFA ; seul le second affiche les derniers donateurs. 2. **Présentez la cause** Remplissez **L'offre** et **Organisé par** comme pour une [collecte de fonds](https://docs.wajub.com/dashboard/payment-links/raise-funds#the-steps). 3. **Proposez des montants** Dans **Montants**, choisissez la **Devise**, puis jusqu'à 6 **Montants suggérés** ; le donateur peut toujours donner un autre montant. **Don minimum** et **Don maximum** sont facultatifs et encadrent aussi les montants suggérés. ![Section Montants d'un lien de dons : la devise XAF, les montants suggérés 1 000, 2 500, 5 000 et 10 000 FCFA, les champs Don minimum et Don maximum, et un palier de 5 000 FCFA qui finance un kit scolaire.](https://docs.wajub.com/dashboard/fr/light/payment-links-donation-amounts.webp) *Chaque palier est un montant en un geste, avec ce qu'il finance.* 4. **Dites ce que permet un don** Sous **Ce que permet un don**, **Ajouter un palier** associe un **Montant** à **Ce que cela finance**, par exemple 5 000 FCFA pour un kit scolaire, avec des **Détails** facultatifs. Jusqu'à 6 paliers. 5. **Choisissez ce que montre la page** Dans **Ce que montre la page**, **Afficher les derniers donateurs et le total donné** montre les derniers dons ; désactivé, la page n'affiche ni montant ni donateur. **Permettre les dons anonymes** laisse le donateur cacher son nom. 6. **Publiez le lien** Choisissez l'adresse dans **Adresse et accès**, comme pour un [lien de paiement](https://docs.wajub.com/dashboard/payment-links/create#the-steps), puis **Publier le lien**. ## Les dons anonymes Un don anonyme cache le nom du donateur sur la page seulement. Dans l'onglet **Donateurs** du lien, la ligne garde son nom avec le badge **Anonyme sur la page**, et l'export aussi : voir [Suivre un lien](https://docs.wajub.com/dashboard/payment-links/track#people-and-export). ## Ce que voit le donateur Le donateur choisit un palier ou un montant suggéré, ou saisit le sien, puis paie. ## Après la publication Des **Actualités** se publient comme pour une [collecte de fonds](https://docs.wajub.com/dashboard/payment-links/raise-funds#after-publishing). Le total donné et les dons se suivent sur la page du lien : voir [Suivre un lien](https://docs.wajub.com/dashboard/payment-links/track#what-the-link-gathered). Un lien de dons reste ouvert tant que vous ne le mettez pas hors ligne, sauf si vous avez réglé **Fermer la page le** ou **Nombre maximum de paiements** dans [Adresse et accès](https://docs.wajub.com/dashboard/payment-links/share#address-and-access). --- # Modifier ou retirer un lien URL: https://docs.wajub.com/fr/dashboard/payment-links/edit-offline-delete > Modifier un lien de paiement publié, le mettre hors ligne, l'archiver, le dupliquer ou le supprimer, et rouvrir un lien expiré. Ces actions demandent **Gérer les liens de paiement**, comme pour [créer un lien](https://docs.wajub.com/dashboard/payment-links/create), et se font en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Seule la suppression demande le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Modifier un lien 1. **Ouvrez le formulaire du lien** Sur la page du lien, choisissez **Modifier**, ou dans la liste **Liens de paiement**, le même choix dans le menu de la ligne. 2. **Changez ce qu'il faut** Le formulaire est celui de la création, sans les modèles. L'en-tête affiche **Modifications non enregistrées** tant que vous n'avez pas enregistré. 3. **Enregistrez** **Enregistrer les modifications**, ou Ctrl+S (Cmd+S sur Mac). La page publiée change tout de suite. Une fois le lien payé, son type ne peut plus changer. Pour un événement, les types de billets se figent à la première vente : voir [Vendre des billets](https://docs.wajub.com/dashboard/payment-links/sell-tickets#after-the-first-sale). ## Mettre hors ligne ou archiver Le menu en haut de la page du lien, comme celui de chaque ligne de la liste, propose deux façons de fermer la page : - **Mettre hors ligne** : l'adresse répond « page introuvable » jusqu'à ce que vous choisissiez **Mettre en ligne**, dans le menu ou dans le bandeau **Cette page est hors ligne**. Rien n'est supprimé. - **Archiver** : la page dit aux clients que le lien n'est plus disponible, ses paiements restent, et la liste le cache sauf avec le filtre **Liens archivés**. **Désarchiver** lui rend son état d'avant. ![En-tête d'un lien de paiement avec Partager le lien, Ouvrir la page et Modifier, et son menu ouvert : Dupliquer, Mettre hors ligne et Archiver.](https://docs.wajub.com/dashboard/fr/light/payment-links-actions-menu.webp) *Supprimer n'apparaît que pour un lien qui n'a encore reçu aucun paiement.* ## Plusieurs liens à la fois Dans la liste, cochez jusqu'à 100 liens : la barre qui apparaît les met en ligne ou hors ligne, les archive ou les désarchive ensemble. ## Dupliquer un lien **Dupliquer**, dans le menu, ouvre le formulaire rempli avec les réglages du lien et le titre « Copie de » suivi du sien. L'adresse, les dates, le mot de passe, le fichier hébergé, les codes promo, les actualités et la référence externe ne sont pas copiés. La copie est en ligne par défaut et compte comme un nouveau lien dans la limite du forfait. ## Supprimer un lien Seul un lien qui n'a reçu aucun paiement se supprime : **Supprimer**, en bas du menu de la page du lien, puis **Supprimer le lien** et le code de sécurité. Le lien, sa page et ses réglages disparaissent pour de bon, et son adresse répond « page introuvable ». Un lien déjà payé s'archive à la place, pour garder ses paiements. ## Un lien expiré Passé sa date de fermeture, la page du lien affiche **Ce lien a expiré**. **Changer la date de fermeture** ouvre le formulaire pour en choisir une nouvelle ou la retirer. Un lien expiré ou archivé ne se remet pas en ligne tel quel : changez d'abord sa date, ou désarchivez-le. --- # Prévenir votre serveur URL: https://docs.wajub.com/fr/dashboard/payment-links/notify-server > Ajouter à un lien de paiement un endpoint webhook qui prévient votre serveur à chaque paiement, billet, don ou remboursement, et gérer son secret de signature. L'onglet **Webhooks** d'un lien envoie ses événements à une adresse de votre serveur, signés avec un secret propre à chaque endpoint. Toute personne qui voit les liens de paiement voit l'onglet ; ajouter, modifier ou supprimer un endpoint demande **Gérer les liens de paiement**. Ces actions, comme afficher ou régénérer le secret d'un endpoint, demandent le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). Les liens n'existent qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Le contenu des événements et la vérification de la signature sont décrits dans la documentation développeur : [Les webhooks d'un lien](https://docs.wajub.com/fr/payments/link/tracking#webhooks-of-one-link). ## Les étapes 1. **Ouvrez l'onglet Webhooks** Sur la page du lien, ouvrez l'onglet **Webhooks**, puis **Ajouter un endpoint**. 2. **Donnez l'adresse de votre serveur** Dans **URL de l'endpoint**, saisissez une adresse HTTPS publique de votre serveur. 3. **Choisissez les événements** Sous **Événements**, cochez ceux que l'endpoint doit recevoir : **Paiement terminé avec succès**, **Billet d'événement acheté**, **Don reçu**, **Commande passée**, **Paiement remboursé, ou perdu en litige** et **Lien expiré**. Il ne reçoit que ceux-là. ![Fenêtre Ajouter un endpoint : l'URL de l'endpoint en HTTPS et la liste des événements, avec Paiement terminé avec succès et Paiement remboursé, ou perdu en litige cochés.](https://docs.wajub.com/dashboard/fr/light/payment-links-webhook-endpoint.webp) *L'endpoint ne reçoit que les événements cochés.* 4. **Enregistrez l'endpoint** **Ajouter un endpoint**, en bas de la fenêtre, l'enregistre après le code de sécurité. Quand votre organisation a déjà autant d'endpoints que permis, la fenêtre le dit sous **URL de l'endpoint** : supprimez-en un dont vous ne vous servez plus pour en ajouter un autre. 5. **Copiez le secret de signature** Dans le menu de l'endpoint, **Afficher le secret de signature** donne, après le code de sécurité, le **Secret de signature** que votre serveur utilise pour vérifier chaque envoi. 6. **Envoyez un test** **Envoyer un test**, dans le menu de l'endpoint, envoie un événement d'essai et dit si votre serveur l'a accepté. Après trop de tests, le message dit quand réessayer. La **Dernière livraison**, sur la ligne de l'endpoint, ne compte que les vrais événements, avec le statut HTTP reçu. ## Gérer un endpoint Le menu de chaque endpoint propose aussi **Copier l'URL** et **Modifier l'endpoint**, où **Actif** désactivé garde ses réglages sans rien lui envoyer. **Régénérer le secret de signature** ouvre **Régénérer le secret de signature ?**, qui dit quand l'ancien secret cesse de marcher. **Régénérer le secret**, après le code de sécurité, signe les envois avec un nouveau secret et l'affiche sous **Secret de signature** : mettez-le sur votre serveur pour qu'il continue d'accepter les envois. **Supprimer l'endpoint** demande **Supprimer cet endpoint ?** : l'endpoint ne reçoit plus les événements du lien et son secret est perdu, sans retour possible. Pour recevoir les événements de tous vos liens à la fois, utilisez plutôt les [webhooks de la console développeur](https://docs.wajub.com/fr/developer-tools/webhooks) ; la liste de leurs événements est dans [Liens de paiement](https://docs.wajub.com/fr/developer-tools/webhooks/events#payment-links). --- # Régler ce que remplit le client URL: https://docs.wajub.com/fr/dashboard/payment-links/payer-fields > Ajouter des questions au client, des codes promo, limiter les moyens de paiement et proposer la page en plusieurs langues et devises, pour tous les types de lien. Ces réglages valent pour les quatre types de lien et se trouvent dans le formulaire du lien, à la création comme avec **Modifier**. Ils demandent les mêmes droits qu'un [lien de paiement](https://docs.wajub.com/dashboard/payment-links/create) : **Gérer les liens de paiement** et la [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Aucun [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est demandé. Chaque client donne son e-mail pour le reçu et peut ajouter son nom et son téléphone. Ajoutez seulement ce dont vous avez vraiment besoin. ## Les questions au client Dans **Ce que remplit le client**, **Ajouter une question** pose jusqu'à 10 questions. Chacune a un libellé, **Question**, et un type de **Réponse** : **Texte court**, **Texte long**, **E-mail**, **Téléphone**, **Liste déroulante** avec jusqu'à 20 **Choix**, ou **Case à cocher**. **Réponse obligatoire** empêche de payer sans répondre ; pour une case, l'interrupteur devient **Doit être cochée pour payer**, utile pour des conditions à accepter. Les réponses arrivent dans [l'export des clients](https://docs.wajub.com/dashboard/payment-links/track#people-and-export). Pour un événement, les informations demandées pour chaque billet se règlent à part : voir [Vendre des billets](https://docs.wajub.com/dashboard/payment-links/sell-tickets). ![Questions au client : une question Paroisse en Liste déroulante avec les choix Saint-Joseph, Sainte-Thérèse et Saint-Paul, et l'interrupteur Réponse obligatoire activé.](https://docs.wajub.com/dashboard/fr/light/payment-links-checkout-questions.webp) *Les réponses arrivent dans l'export des clients du lien.* ## Les codes promo Sous **Codes promo**, **Ajouter un code** crée jusqu'à 20 codes. Le **Code** tient en 32 caractères : lettres majuscules, chiffres, tirets et soulignés. Choisissez la **Remise**, en **Pourcentage** ou en **Montant fixe**, puis sa **Valeur**. **Nombre d'utilisations** et **Valable jusqu'au** sont facultatifs ; **Actif** suspend un code sans le supprimer. Le champ du code n'apparaît sur la page que tant qu'au moins un code est actif. ## Les moyens de paiement Par défaut, le client se voit proposer tous les moyens sur lesquels vous encaissez. Sous **Moyens de paiement**, réduisez le choix avec **Uniquement ces pays**, **Uniquement ces moyens de paiement** ou **Uniquement ces types de moyens de paiement** (**Mobile Money**, **Cartes**, **Banque**, **Crypto**), seuls ou ensemble. Les cartes et la crypto ne dépendent d'aucun pays. Sous **Devise**, **Tous les moyens** convertit le montant quand les devises diffèrent ; **Même devise uniquement** garde les moyens qui encaissent dans la devise du paiement. ## Les langues et les devises Dans **Langues et devises**, la **Langue principale** est celle dans laquelle vous écrivez la page, français ou anglais. Sous **Langues proposées aux visiteurs**, cochez les langues dans lesquelles le visiteur peut voir la page : chacune ouvre un bloc pour traduire le titre, la description, le texte du bouton et le message de remerciement ; un champ vide reprend le texte de la langue principale. **Autres devises de paiement proposées aux visiteurs** laisse payer dans une autre devise, au cours du jour. Seules les devises acceptées par l'un de vos moyens de paiement sont proposées. --- # Collecter des fonds URL: https://docs.wajub.com/fr/dashboard/payment-links/raise-funds > Créer un lien de collecte avec un objectif, des montants suggérés, une barre de progression, des étapes et une date de fin, puis publier des actualités. Le type **Collecter des fonds** réunit des contributions vers un objectif : un projet associatif, des frais médicaux, une cotisation. Chaque contributeur choisit son montant. Il demande les mêmes droits qu'un [lien de paiement](https://docs.wajub.com/dashboard/payment-links/create) : **Gérer les liens de paiement**, la [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), et une place dans la limite de liens du forfait. Aucun [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est demandé. ## Les étapes 1. **Choisissez Collecter des fonds** Dans **Nouveau lien de paiement**, choisissez **Collecter des fonds**. Sous **Partir de :**, **Projet associatif** affiche la progression et les contributeurs ; **Frais médicaux** affiche la progression et cache les contributeurs. 2. **Présentez la collecte** Remplissez **L'offre** comme pour tout [lien de paiement](https://docs.wajub.com/dashboard/payment-links/create#the-steps). **Organisé par** nomme la personne ou l'organisation derrière la collecte ; la page le montre comme vérifié quand votre compte Wajub l'est. 3. **Fixez l'objectif** Dans **Objectif et montants**, saisissez l'**Objectif** et choisissez sa devise dans le même champ. **Montants suggérés** propose jusqu'à 6 montants en un geste ; le contributeur peut toujours en saisir un autre. **Contribution minimale** est facultative et reste sous l'objectif. ![Section Objectif et montants : l'objectif 2 000 000 FCFA, les montants suggérés 5 000, 10 000 et 25 000 FCFA et la contribution minimale de 1 000 FCFA.](https://docs.wajub.com/dashboard/fr/light/payment-links-fundraising-goal.webp) *Le contributeur peut toujours saisir un autre montant que ceux suggérés.* 4. **Choisissez ce que montre la page** Dans **Ce que montre la page**, **Afficher le montant collecté et la barre de progression** montre où en est la collecte ; désactivé, la page n'affiche que l'objectif. **Afficher les contributeurs** montre leur nombre et le nom des huit derniers, jamais leurs coordonnées ; leurs montants n'apparaissent que tant que **Afficher le montant collecté et la barre de progression** est activé. 5. **Choisissez ce qui se passe à l'objectif** Avec **Continuer la collecte une fois l'objectif atteint** désactivé, la page n'accepte plus de contribution une fois l'objectif atteint et le dit ; un remboursement qui ramène le total sous l'objectif la rouvre. Activé, la collecte continue au-delà de son objectif. 6. **Fixez la fin de la campagne** **Fin de la campagne** est facultative : à cette date, la page se ferme d'elle-même, et elle affiche un compte à rebours pendant les 30 derniers jours. Elle remplace la date de fermeture des autres types. 7. **Ajoutez des étapes** **Ajouter une étape** marque un palier de l'objectif, jusqu'à 10, avec son **Montant**, un **Titre** facultatif et **Ce qu'elle permet**. Tant que le montant collecté est affiché, la page coche chaque étape atteinte. 8. **Publiez le lien** Choisissez l'adresse dans **Adresse et accès**, comme pour un [lien de paiement](https://docs.wajub.com/dashboard/payment-links/create#the-steps), puis **Publier le lien**. ## Ce que voit le contributeur Le contributeur voit l'objectif, la progression si vous l'affichez, choisit ou saisit un montant et paie. ## Après la publication Pour raconter à quoi sert l'argent, ouvrez **Modifier**, puis **Publier une actualité** dans **Actualités**, avec un **Titre**, une **Date** et le **Texte de l'actualité** ; la page montre les quatre dernières, sur 20 au plus. Le montant collecté et les contributions se suivent sur la page du lien : voir [Suivre un lien](https://docs.wajub.com/dashboard/payment-links/track#what-the-link-gathered). La collecte s'arrête à la **Fin de la campagne**, à l'objectif sauf si **Continuer la collecte une fois l'objectif atteint** est activé, au **Nombre maximum de paiements** si vous l'avez fixé dans **Adresse et accès**, ou quand vous mettez le lien hors ligne ou l'archivez : voir [Modifier ou retirer un lien](https://docs.wajub.com/dashboard/payment-links/edit-offline-delete#offline-or-archive). --- # Vendre quelque chose URL: https://docs.wajub.com/fr/dashboard/payment-links/sell-something > Vendre un article physique, un contenu numérique ou un service à prix fixe avec un lien de paiement, avec ses options, son stock, sa livraison ou son accès. Le type **Vendre quelque chose** vend à prix fixe un article livré ou retiré sur place, un fichier ou un lien à télécharger, ou un rendez-vous. Il demande les mêmes droits qu'un [lien de paiement](https://docs.wajub.com/dashboard/payment-links/create) : **Gérer les liens de paiement**, la [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), et une place dans la limite de liens du forfait. Aucun [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est demandé. ## Les étapes 1. **Choisissez le type de produit** Dans **Nouveau lien de paiement**, choisissez **Vendre quelque chose**, puis sous **De quel type ?** : **Article physique**, **Contenu numérique** ou **Service**. Sous **Partir de :**, **Vêtement ou accessoire** demande une adresse de livraison et ajoute l'option **Taille** de S à XL ; **Formation en ligne ou e-book** prépare un lien de téléchargement ; **Consultation** prépare un service en ligne de 60 minutes. 2. **Décrivez le produit** Remplissez **L'offre** comme pour tout [lien de paiement](https://docs.wajub.com/dashboard/payment-links/create#the-steps). **Autres photos** ajoute jusqu'à 10 images dans l'ordre de la page. Une **Vidéo** MP4 ou WebM remplace la photo en haut de la page. 3. **Fixez le prix** Dans **Prix et options**, saisissez le **Prix** et choisissez sa devise dans le même champ. Le prix est obligatoire et le client ne peut pas le changer. Pour laisser chacun choisir son montant, créez plutôt un lien pour [collecter des fonds](https://docs.wajub.com/dashboard/payment-links/raise-funds) ou [recevoir des dons](https://docs.wajub.com/dashboard/payment-links/donations). 4. **Ajoutez des options** **Ajouter une option** crée une taille, une couleur ou un format, jusqu'à 5 options de 20 choix chacune. **Affichage** les montre en **Boutons avec texte** ou en **Pastilles de couleur**, et un choix peut coûter plus que le prix de base. Le client choisit un élément de chaque option avant de payer. ![Section Prix et options d'un article physique : le prix 15 000 FCFA, l'option Taille avec les choix S, M, L et XL affichés en boutons avec texte, XL à 2 000 FCFA de plus, le stock à 40 et l'interrupteur Continuer à vendre en rupture de stock.](https://docs.wajub.com/dashboard/fr/light/payment-links-product-options.webp) *Un choix peut coûter plus que le prix de base.* 5. **Réglez la livraison ou l'accès** La section suivante dépend du type de produit : [un article physique](#a-physical-item), [un contenu numérique](#digital-content) ou [un service](#a-service). 6. **Publiez le lien** Choisissez l'adresse dans **Adresse et accès**, comme pour un [lien de paiement](https://docs.wajub.com/dashboard/payment-links/create#the-steps), puis **Publier le lien**. ## Un article physique Le **Stock**, sous le prix, ne s'affiche pas sur la page, mais le client ne peut pas commander plus qu'il n'en reste : une fois épuisé, la page n'accepte plus de commande, sauf si **Continuer à vendre en rupture de stock** est activé pour livrer plus tard. Laissez-le vide si vous ne suivez pas le stock. Dans **Livraison et retours**, **Demander une adresse de livraison** se désactive pour un article retiré sur place. Les **Frais de livraison** s'ajoutent une fois par commande ; vide ou 0, la livraison est gratuite. Les **Conditions de retour** s'affichent sur la page. Le choix d'option et l'adresse de chaque acheteur arrivent dans [l'export des clients](https://docs.wajub.com/dashboard/payment-links/track#people-and-export). ## Un contenu numérique Dans **Accès au contenu**, **Comment le client le reçoit** propose deux choix : - **Un lien de téléchargement** : l'adresse https de votre fichier, sur Drive, Dropbox ou votre site. - **Un fichier hébergé par Wajub** : jusqu'à 500 Mo, à partir du forfait **Growth**. Après le paiement, le client reçoit par e-mail un lien d'accès propre à son paiement, avec vos **Instructions d'accès**, qui s'affichent aussi sur la page. L'adresse du fichier n'apparaît jamais sur la page. **Accès valable** fixe en jours, à partir du paiement, la durée pendant laquelle ce lien marche, jusqu'à 365 : 30 jours sur un nouveau lien, sans limite si le champ est vide. Avec **Accès à usage unique**, le lien d'accès ne fonctionne plus après le premier téléchargement : chaque acheteur télécharge une fois, et le lien de paiement reste ouvert aux acheteurs suivants. Un client remboursé en totalité perd l'accès. Avec **Un lien de téléchargement**, le client arrive sur votre propre adresse et la garde : c'est à vous de la protéger. ## Un service Dans **Déroulement du service**, **Où cela se passe** propose **En ligne**, **En personne** ou **Les deux**. En ligne ou pour les deux, le **Lien de la réunion** est obligatoire : il part par e-mail après le paiement, avec **Ce que le client doit préparer**, qui s'affiche aussi sur la page, comme la **Durée** (de 5 minutes à 24 heures) et les **Conditions d'annulation**. Aucun créneau n'est réservé : convenez de l'heure avec le client. ## Ce que voit le client Le client choisit ses options et sa quantité, jusqu'à 100, donne son e-mail et son adresse si l'article est livré, puis paie le prix affiché. --- # Vendre des billets URL: https://docs.wajub.com/fr/dashboard/payment-links/sell-tickets > Vendre des places pour un concert, une formation ou un gala avec un lien de paiement, des types de billets, un billet avec code QR et la liste des participants. Un lien de billetterie est un lien de paiement de type **Vendre des billets** : l'acheteur choisit un type de billet et le nombre de places, paie, et reçoit par e-mail un billet avec un code QR. Il demande les mêmes droits qu'un [lien de paiement](https://docs.wajub.com/dashboard/payment-links/create) : **Gérer les liens de paiement**, la [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), et une place dans la limite de liens du forfait. Aucun [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est demandé. ## Les étapes 1. **Choisissez Vendre des billets** En **Production**, ouvrez **Liens de paiement**, puis **Créer un lien**, et choisissez **Vendre des billets** sous **Pour quoi voulez-vous encaisser ?**. Sous **Partir de :**, **Concert ou spectacle** crée deux billets, Standard et VIP, et **Formation ou conférence** un billet Participant qui demande le nom et l'entreprise de chaque participant. 2. **Décrivez l'événement** Dans **L'offre**, donnez un **Titre**, une **Affiche ou photo** et une **Description** : le programme, les artistes ou intervenants, ce que comprend le billet. Indiquez quand il commence dans **Débute**, et si besoin quand il finit dans **Se termine**, puis le **Fuseau horaire de l'événement** : les participants voient les horaires dans ce fuseau. Le **Lieu** est obligatoire, une salle ou « En ligne » ; **Adresse**, **Ville** et **Pays** sont facultatifs. 3. **Créez les types de billets** Dans **Billets**, choisissez la **Devise**, puis donnez à chaque billet un **Nom**, un **Prix** et une **Quantité**. Un prix de 0 rend le billet gratuit, et une quantité vide ne le limite pas. **Ajouter un type de billet** en ajoute un autre, jusqu'à 20, et **Capacité du lieu** plafonne le total, tous billets confondus. ![Section Billets : la devise XAF, un billet Standard à 5 000 FCFA sans limite de quantité, un billet VIP à 15 000 FCFA limité à 50, le bouton Ajouter un type de billet et une capacité du lieu de 300.](https://docs.wajub.com/dashboard/fr/light/link-tickets.webp) *Dès le premier billet vendu, les types de billets ne changent plus.* 4. **Réglez le billet envoyé** Dans **Billets et remboursements**, **Envoyer un billet avec QR code** est activé par défaut. Ajoutez vos **Conditions de remboursement** : elles figurent dans l'e-mail du billet. ![Section Billets et remboursements : l'interrupteur Envoyer un billet avec QR code activé, puis le champ Conditions de remboursement vide.](https://docs.wajub.com/dashboard/fr/light/link-ticket-delivery.webp) *Un seul e-mail part, vers l'acheteur, avec un code QR pour tout l'achat.* L'e-mail va à l'adresse de l'acheteur, pas à chaque participant : il contient un code QR qui vaut pour tout l'achat, avec le nombre de billets. 5. **Demandez les informations des participants** Dans **Ce que remplit le client**, **Informations demandées pour chaque participant** ajoute jusqu'à 10 champs remplis une fois par billet, par exemple **Nom complet** ou **Taille de t-shirt**. Les réponses arrivent dans l'onglet **Participants** du lien et dans son export, pas sur le billet. 6. **Publiez le lien** Choisissez l'adresse dans **Adresse et accès**, comme pour un [lien de paiement](https://docs.wajub.com/dashboard/payment-links/create#the-steps), puis **Publier le lien**. Il n'y a pas de date de fermeture à régler : la vente s'arrête d'elle-même à **Se termine**, ou au début de l'événement si **Se termine** est vide. ## Ce que fait l'acheteur L'acheteur choisit un type de billet et jusqu'à 100 places, remplit les informations de chaque participant et paie ; la page signale un billet épuisé et ferme la vente une fois l'événement terminé, ou une fois qu'il a commencé s'il n'a pas de fin. ## Le jour de l'événement Wajub ne scanne pas les billets et n'enregistre pas les entrées. Pour contrôler l'accès, servez-vous de l'onglet **Participants** : une ligne par achat, avec l'acheteur, le type et le nombre de billets, les participants et le montant. **Rechercher des participants** retrouve un nom, un e-mail, un téléphone ou un participant, et **Exporter** télécharge la liste en CSV. Comme un code QR vaut pour tout un achat, vérifiez dans la liste combien de billets il couvre. La page du lien suit les **Billets vendus**, les **Acheteurs** et les **Billets restants**. ## Après la première vente Dès le premier billet vendu, les types de billets ne changent plus : nom, prix, quantité et ordre restent figés. La **Capacité du lieu** et le reste du lien restent modifiables. Un type dont toutes les ventes ont été remboursées peut être renommé, pas retiré. Après l'événement, la page de paiement ferme la vente, mais le lien reste **En ligne** dans le tableau de bord : **Archiver**, dans le menu de la page du lien, le range. --- # Choisir le domaine des liens URL: https://docs.wajub.com/fr/dashboard/payment-links/settings > Servir vos liens de paiement sur votre propre domaine plutôt que sur wajub.link, depuis les paramètres des liens de paiement. Par défaut, l'adresse d'un lien commence par wajub.link. Avec un domaine à vous, vérifié, vos liens peuvent s'ouvrir sur votre propre adresse ; les domaines personnalisés font partie des forfaits **Scale** et **Enterprise**. Le propriétaire, un Administrateur, un Développeur ou un Observateur ouvre ce réglage, comme un rôle personnalisé qui a **Voir les paramètres** ; seuls le propriétaire, un Administrateur ou un rôle qui a **Gérer les paramètres** l'enregistrent (voir les [rôles](https://docs.wajub.com/fr/dashboard#roles)). Il n'existe qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), et aucun [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est demandé. ## Les étapes 1. **Vérifiez votre domaine** Le domaine doit d'abord être connecté et vérifié : voir [Connecter votre domaine](https://docs.wajub.com/dashboard/settings/custom-domains). 2. **Ouvrez les paramètres des liens** Dans **Paramètres**, sous **Produits**, ouvrez **Liens de paiement**. La page s'appelle **Liens**. 3. **Choisissez le domaine** Dans **Domaine du lien de paiement**, choisissez votre domaine sous **Domaine**, ou **Par défaut (wajub.link)** pour revenir à l'adresse Wajub. Sans domaine vérifié, la page le signale et propose **Ajouter un domaine**. ![Section Domaine du lien de paiement : le champ Domaine sur Par défaut (wajub.link) et l'avertissement Aucun domaine vérifié n'est encore configuré pour les liens de paiement, avec Ajouter un domaine.](https://docs.wajub.com/dashboard/fr/light/payment-links-settings.webp) *Seuls les domaines vérifiés sont proposés.* 4. **Enregistrez** La barre du bas propose **Enregistrer les modifications**, ou **Abandonner** pour revenir au réglage d'avant. ## Ce qui change Le domaine choisi sert à tous les liens qui n'ont pas leur propre domaine, y compris ceux déjà publiés, et il est proposé d'office pour chaque nouveau lien. Pour qu'un lien garde une autre adresse, choisissez son **Domaine** dans le formulaire du lien : voir [Partager un lien](https://docs.wajub.com/dashboard/payment-links/share#address-and-access). --- # Partager un lien URL: https://docs.wajub.com/fr/dashboard/payment-links/share > Envoyer l'adresse d'un lien de paiement par WhatsApp ou SMS, imprimer son code QR, mettre un bouton de paiement sur votre site et régler l'adresse et l'accès à la page. Toute personne qui voit les liens de paiement peut ouvrir la fenêtre de partage. Changer l'adresse ou l'accès d'un lien demande **Gérer les liens de paiement**, comme pour [créer un lien](https://docs.wajub.com/dashboard/payment-links/create). Les liens n'existent qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Aucun [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est demandé. ## Les étapes 1. **Ouvrez la fenêtre de partage** Elle s'ouvre seule après la publication, avec pour titre **Votre lien est en ligne**, ou **Votre lien est créé, hors ligne pour l'instant** si la page n'est pas encore en ligne. Plus tard, **Partager le lien** en haut de la page du lien la rouvre. 2. **Envoyez l'adresse** Copiez l'**Adresse du lien**, ou choisissez sous **Partager avec** : WhatsApp, SMS, Telegram, X, Facebook ou e-mail, qui préparent un message avec le lien. Sur un téléphone, un bouton ouvre aussi le partage de l'appareil. ![Fenêtre Partager le lien de paiement : l'adresse du lien à copier, les boutons WhatsApp, SMS, Telegram, X, Facebook et E-mail, puis le code QR avec Scanner pour payer et Télécharger le code QR.](https://docs.wajub.com/dashboard/fr/light/payment-links-share-dialog.webp) *Le code QR ouvre la page de paiement du lien.* 3. **Imprimez le code QR** **Télécharger le code QR** enregistre l'image à imprimer sur un flyer ou une carte de comptoir : scanné, il ouvre la page de paiement. ## Le bouton pour votre site L'onglet **Bouton pour votre site** prépare un bouton à coller dans votre site. **Par-dessus votre site** fait payer le client sans quitter votre page ; **Sur la page de paiement** est un simple lien qui marche partout, même là où les scripts sont interdits. Réglez le **Texte du bouton**, la **Couleur**, la **Forme** (**Carré**, **Arrondi** ou **Pilule**) et la **Taille** ; pour un lien simple, **Ouvrir la page dans** choisit **Nouvel onglet** ou **Même onglet**. L'**Aperçu** montre le bouton, puis **Copier** copie le **Code à coller** dans le bloc « Code », « HTML » ou « Intégrer » de Systeme.io, WordPress, Wix, Webflow ou Shopify. Si vous avez déclaré des sites dans [Les sites qui affichent la page](https://docs.wajub.com/dashboard/settings/checkout-page#embedding), la fenêtre par-dessus votre site ne s'ouvre que sur eux ; ailleurs, le bouton propose la page dans un nouvel onglet. Tant que la liste est vide, elle s'ouvre sur n'importe quel site. ![Onglet Bouton pour votre site : le choix Par-dessus votre site ou Sur la page de paiement, le texte, la couleur, la forme et la taille du bouton, son aperçu et le code à coller avec Copier.](https://docs.wajub.com/dashboard/fr/light/payment-links-button-builder.webp) *Le code se colle dans le bloc HTML de votre site.* ## L'adresse et l'accès Ces réglages se trouvent dans **Adresse et accès**, à la création ou avec **Modifier** : - **Adresse du lien** : la fin de l'adresse, de 3 à 100 lettres, chiffres, tirets ou tirets bas, libre sur tout Wajub. - **Domaine** : n'apparaît qu'avec un domaine vérifié ; voir [Choisir le domaine des liens](https://docs.wajub.com/dashboard/payment-links/settings). - **Page en ligne** : désactivée, la page répond « introuvable » jusqu'à sa mise en ligne. - **Fermer la page le** : une date de fermeture, sauf pour un événement ou une collecte de fonds, qui s'arrêtent seuls. - **Nombre maximum de ventes**, ou **Nombre maximum de paiements** pour un don ou une collecte : la page se ferme une fois le nombre atteint. - **Fermer après le premier paiement** : pour un seul payeur. Une fois le paiement réussi, la page indique aux visiteurs que le lien a déjà été utilisé, et pendant qu'un paiement est en cours, les autres visiteurs en sont avertis. Le lien se rouvre si ce paiement n'aboutit pas ; un remboursement ne le rouvre pas. Si un second paiement réussit malgré tout, le propriétaire, les Administrateurs et les membres Finance reçoivent un e-mail qui nomme le paiement à rembourser. - **Mot de passe pour ouvrir la page** : de 4 à 100 caractères, à donner avec le lien ; ensuite, **Changer le mot de passe** ou **Retirer le mot de passe**. - **Fermer après ce nombre de visites** : la page se ferme au-delà de ce nombre de visites. Les champs vides ne posent aucune limite. --- # Suivre un lien URL: https://docs.wajub.com/fr/dashboard/payment-links/track > Lire les visites, les ventes et le taux de conversion d'un lien de paiement, sa collecte ou ses billets, ses paiements et ses clients, et exporter ses clients en CSV. Toute personne qui voit les liens de paiement lit ces chiffres ; exporter demande **Gérer les liens de paiement**. Les liens n'existent qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Ouvrez **Liens de paiement**, puis le lien : sa page se lit par onglets, **Vue d'ensemble**, **Paiements**, l'onglet de ses clients et **Webhooks**. ## La performance Sous **Performance**, la **Période** vaut les 30 derniers jours par défaut. Quatre chiffres la résument : **Visites**, **Ventes**, **Revenus** et **Taux de conversion**, avec sous les trois premiers le total depuis la création du lien, et sous le taux, dès qu'il y a une vente, la vente moyenne de la période. **Visites et ventes** les trace jour par jour, et **Afficher sous forme de tableau** montre les mêmes chiffres en tableau. **Meilleurs pays** dit d'où viennent les visites, **Appareils** sur quoi la page a été ouverte. ## Ce que le lien a réuni Plus bas, un bloc dépend du type, depuis le début : - Collecte de fonds : **Progression de la collecte de fonds**, le montant collecté sur l'objectif, la **Progression de l'objectif** et le nombre de **Donateurs**. - Dons : **Dons**, avec le nombre de **Donateurs** et le **Total donné**. - Événement : **Billets**, avec les **Billets vendus**, les **Acheteurs** et les billets restants. Les montants reçus dans une autre devise que celle du lien s'affichent à part, sous le total. **Détails du lien** reprend ensuite ses réglages : devise, stock, livraison, durée ou lieu, fin de la campagne, mot de passe, catégorie et étiquettes. ## Les paiements L'onglet **Paiements** liste les paiements du lien avec leur montant, leur statut, le client, le moyen de paiement, l'identifiant du paiement et la date. ## Les clients et l'export L'onglet suivant s'appelle **Clients**, **Donateurs** pour un don ou une collecte, ou **Participants** pour un événement. Il montre une ligne par achat ou par don, avec les badges **Anonyme sur la page** ou **Litige perdu**. La recherche trouve un nom, un e-mail ou un téléphone, et le menu de chaque ligne mène à **Ouvrir le paiement** ou **Voir le client**. **Exporter** télécharge un CSV de 50 000 lignes au plus, avec la recherche et les dates de l'onglet. Il ajoute les réponses aux questions du lien et des colonnes selon le type : quantité, option choisie et adresse de livraison pour un produit ; type de billet et participants pour un événement ; don anonyme ou non pour un don ou une collecte. Chaque export compte dans la limite mensuelle d'exports de votre [forfait](https://docs.wajub.com/dashboard/subscription/plans). ![Onglet Clients d'un lien : la recherche, le bouton Exporter et la liste des achats avec le nom, l'e-mail, le montant et la date de chaque client.](https://docs.wajub.com/dashboard/fr/light/payment-links-people.webp) *Les réponses aux questions du lien n'apparaissent que dans l'export.* --- # Répondre à un litige URL: https://docs.wajub.com/fr/dashboard/payments/disputes > Lire un litige, envoyer vos preuves et écrire au client avant l'échéance, puis accepter le litige ou le marquer comme gagné. Un litige conteste un paiement : pour un paiement encaissé par Wajub, le montant contesté est retenu sur votre solde jusqu'à ce que le litige se termine, et vous avez jusqu'à une échéance pour répondre. Il vient d'un client qui conteste depuis son portail Pocket, après une demande de remboursement, ou de la banque du client, par le fournisseur qui a traité le paiement : c'est alors une rétrofacturation. Tous les [rôles](https://docs.wajub.com/fr/dashboard#roles) voient les litiges, avec tous les forfaits. Envoyer des preuves, écrire au client, écrire une note, accepter un litige ou le marquer comme gagné est réservé au propriétaire, aux Administrateurs, aux membres Spécialiste support et aux rôles personnalisés qui ont **Gérer les litiges**. Accepter et marquer comme gagné demandent le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). Les litiges de [Test](https://docs.wajub.com/fr/dashboard#sandbox-and-live) restent séparés de ceux de Production et n'envoient aucun e-mail. ## La liste des litiges Quand un litige s'ouvre en Production, le propriétaire, les Administrateurs et les membres Spécialiste support reçoivent un e-mail avec un lien vers le litige. Dans le tableau de bord, ouvrez **Paiements**, puis l'onglet **Litiges**. La liste réunit les litiges et les demandes de remboursement ; choisissez **Étape** › **Litige** pour ne garder que les litiges. Les demandes ont leur page : [Répondre à une demande](https://docs.wajub.com/dashboard/payments/refund-requests). Chaque ligne donne le **Montant**, l'**Étape**, le **Statut**, la date **Répondre avant le** avec le temps qui reste, le **Motif**, le **Client** et la date d'**Ouverture**. Un litige né d'une demande porte **Issu d'une demande de remboursement**. Choisissez l'en-tête **Répondre avant le** pour voir d'abord les échéances les plus proches. Un litige est **Ouvert** jusqu'à votre première preuve, puis **En cours d'examen**. Il se termine **Gagné**, **Perdu** ou **Résolu**. La barre de recherche trouve un litige par son identifiant, celui de son paiement ou son motif. **Date**, **Étape**, **Statut** et **Montant** filtrent la liste. Le menu au bout d'une ligne propose **Ouvrir le litige**, **Copier l'identifiant du litige**, **Voir le paiement** et, quand le litige a un client, **Voir le client**. ## Lire un litige Choisissez la ligne du litige, ou **Répondre au litige** sur la page du paiement. L'en-tête donne le montant contesté, le statut, l'**ID du litige** et la date d'ouverture. Dessous, un encadré rappelle l'échéance et le temps qui reste ; il devient rouge à moins de trois jours, puis annonce que le délai est dépassé. ![La page d'un litige ouvert : le montant contesté, le statut et l'ID du litige en haut, l'encadré qui rappelle l'échéance, les faits Répondre avant le, Motif et Paiement, puis les détails du litige, et à droite le paiement contesté.](https://docs.wajub.com/dashboard/fr/light/payments-dispute.webp) *L'échéance juste sous le montant contesté.* Les faits sous l'en-tête donnent la date **Répondre avant le**, le **Motif** du litige, et le **Paiement** contesté avec le nom du client. **Détails du litige** donne de quoi joindre le client, puis ses mots : l'**Explication du client** pour un litige ouvert depuis Pocket, ou les **Détails transmis par le fournisseur** pour une rétrofacturation. Pour un litige né d'une demande, la section **Demande de remboursement** reprend la date de la demande, le **Montant demandé**, puis votre réponse si vous l'aviez refusée, ou **Sans réponse dans le délai**, et la date à laquelle le client l'a transformée en litige. **Preuves** liste ce que vous avez envoyé, **Conversation** vos échanges avec le client, et l'historique déroule le litige depuis son ouverture. À droite, **Paiement contesté** donne la date du paiement et son **ID du paiement**. Le menu de l'en-tête propose **Voir le paiement** et **Voir le client**. Un litige ouvert depuis Pocket vous laisse sept jours pour répondre. Passé ce délai, il reste ouvert jusqu'à ce que vous ou l'équipe Wajub le régliez. ## Envoyer des preuves 1. **Choisissez Soumettre des preuves** En haut de la page du litige, choisissez **Soumettre des preuves**. La fenêtre du même nom s'ouvre. ![La fenêtre Soumettre des preuves : la liste Type de preuve, le champ Description, la zone Fichier (facultatif), puis les boutons Annuler et Soumettre des preuves.](https://docs.wajub.com/dashboard/fr/light/payments-dispute-evidence.webp) *Un type de preuve, une description et un fichier.* 2. **Choisissez le type de preuve** Sous **Type de preuve**, choisissez ce que la preuve montre, par exemple **Preuve de livraison**, **Échanges avec le client** ou **Reçu**. 3. **Décrivez la preuve** Sous **Description**, dites ce que la preuve établit, en 2 000 caractères au plus. 4. **Joignez le document** Sous **Fichier (facultatif)**, ajoutez un PDF, une image JPG ou PNG, un document Word ou un fichier texte, de 10 Mo au plus. 5. **Envoyez la preuve** Choisissez **Soumettre des preuves**. Le message « Preuves soumises avec succès. » s'affiche, la preuve apparaît sous **Preuves** et le litige passe à **En cours d'examen**. Le litige garde une preuve par type : une nouvelle preuve du même type remplace la précédente. ## Écrire au client 1. **Partez d'un modèle si besoin** Sous **Modèles de réponse**, choisissez un modèle, par exemple **Produit livré**, **Service rendu** ou **Paiement autorisé par le client**. Son texte remplit **Répondre au client**. 2. **Écrivez le message** Sous **Répondre au client**, écrivez ou adaptez le message, en 5 000 caractères au plus. 3. **Joignez des fichiers si besoin** Choisissez **Joindre un fichier** pour ajouter un PDF, une image JPG ou PNG, un document Word ou un fichier texte, de 10 Mo au plus chacun. 4. **Envoyez** Choisissez **Envoyer**. Le message « Message envoyé avec succès. » s'affiche et votre message rejoint **Conversation**. Le client suit le statut du litige et la conversation dans son portail Pocket, où il peut vous répondre ; il ne voit ni vos preuves ni vos notes. ## Accepter le litige Accepter un litige reconnaît que le client a raison : vous perdez le litige, sans retour possible. 1. **Choisissez Accepter le litige** En haut de la page du litige, choisissez **Accepter le litige**. **Accepter le litige ?** rappelle que le client sera remboursé et que vous perdrez le litige. 2. **Confirmez avec le code de sécurité** Choisissez **Accepter le litige**, puis saisissez le code de sécurité. Le message « Litige accepté. » s'affiche et le litige passe à **Perdu**. Pour un litige ouvert depuis Pocket sur un paiement réussi, le client est remboursé du montant contesté, dans la limite de ce qui reste à rembourser sur le paiement. Les frais de ce remboursement sont à votre charge, quel que soit votre [choix par défaut](https://docs.wajub.com/dashboard/payments/refund#the-default-fee-choice), et il apparaît dans [Suivre les remboursements](https://docs.wajub.com/dashboard/payments/track-refunds). Une rétrofacturation acceptée n'est pas remboursée : la banque du client lui a déjà rendu l'argent, et le montant contesté est retiré de votre solde. Tant qu'une rétrofacturation est en cours sur un paiement, un litige ouvert depuis Pocket sur ce même paiement ne peut pas être accepté ; la fenêtre en donne la raison. ## Marquer le litige comme gagné **Marquer comme gagné** enregistre qu'un litige ouvert depuis Pocket s'est terminé en votre faveur. 1. **Choisissez Marquer comme gagné** Dans le menu de l'en-tête, choisissez **Marquer comme gagné**. **Marquer le litige comme gagné ?** s'ouvre. 2. **Confirmez avec le code de sécurité** Choisissez **Marquer comme gagné**, puis saisissez le code de sécurité. Le message « Le litige a été marqué comme gagné. » s'affiche et le litige passe à **Gagné**. Le montant retenu revient sur votre solde disponible. Le menu ne propose pas **Marquer comme gagné** pour une rétrofacturation : seule la banque du client la tranche. ## Les notes Les notes d'un litige s'écrivent en bas de l'historique, sous « Que doivent savoir vos membres sur ce litige ? », et s'épinglent ou se suppriment comme celles d'un paiement : [Les notes](https://docs.wajub.com/dashboard/payments/read#notes). Elles existent aussi en Test. --- # Trouver un paiement URL: https://docs.wajub.com/fr/dashboard/payments/find > Chercher un paiement par référence ou par client, filtrer la liste par statut, montant, fournisseur ou métadonnée, et l'exporter en CSV, Excel, PDF ou JSON. **Paiements** liste les paiements de vos clients, avec leur montant, leur statut et le client qui a payé. La recherche et les filtres retrouvent un paiement précis ; l'export emporte la liste dans un fichier. Tous les [rôles](https://docs.wajub.com/fr/dashboard#roles) ouvrent **Paiements**, avec tous les forfaits. Exporter est réservé au propriétaire, aux Administrateurs, aux membres Finance et Spécialiste support, et aux rôles personnalisés qui ont **Gérer les paiements**, en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live) uniquement. Rien sur cette page ne demande le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## La liste Ouvrez **Paiements** dans le menu. Les onglets en haut mènent aussi à **Remboursements** et à **Litiges** ; le nombre affiché sur **Litiges** compte les demandes de remboursement qui attendent votre réponse. Chaque ligne donne le **Montant**, le **Statut**, la **Description** avec l'identifiant du paiement, le **Client**, le **Moyen de paiement** et la **Date**. La description n'apparaît que sur un écran large, et le moyen de paiement se masque sur un écran étroit. Un paiement réglé en plusieurs fois porte le nombre de ses échéances. **Client supprimé** remplace le nom d'un client effacé depuis, **Aucun client** signale un paiement sans client. Choisissez l'en-tête **Montant** ou **Date** pour trier la liste. ![Paiements en Production : la barre de recherche et les filtres, puis la liste avec le montant, le statut, le client, le moyen de paiement avec le fournisseur qui l'a traité et la date de chaque paiement.](https://docs.wajub.com/dashboard/fr/light/payments-list.webp) *La recherche et les filtres au-dessus, un paiement par ligne.* Le menu au bout d'une ligne propose **Ouvrir le paiement**, **Copier l'identifiant du paiement** et, quand le paiement a un client, **Voir le client**. Pour un paiement **Réussi**, **Partiellement remboursé** ou **Remboursé**, il ajoute **Télécharger le reçu**. Cochez des lignes, jusqu'à 100, pour **Copier les identifiants** de toutes à la fois ou les exporter. ## Chercher et filtrer La barre de recherche trouve un paiement par sa référence, sa description, ou le nom, l'e-mail ou le téléphone du client. **Date** limite la liste à une période toute prête ou aux jours de votre choix. Les autres filtres se combinent : - **Statut** : un ou plusieurs statuts, par exemple **Réussi**, **En attente** ou **Échoué**. - **Montant** : un minimum, un maximum, ou les deux. - **Fournisseur** : le fournisseur qui a traité le paiement. Ce filtre n'apparaît que si votre organisation a connecté un fournisseur : [Connecter un prestataire](https://docs.wajub.com/dashboard/orchestration/connect-provider). - **Canal** : le canal par lequel le client a payé, ou **Tous les canaux**. - **Motif de l'échec** : en Production, la raison de l'échec d'un paiement, rangée sous **Du côté du fournisseur**, **Du côté du client** et **Autre**, par exemple **Fonds insuffisants**. - **Intégration** : le SDK ou la page depuis lequel le paiement a été fait. **Paiement (page hébergée ou Wajub.js)** regroupe les paiements faits sur une page de paiement qui n'a pas dit laquelle des deux, et **Inconnu** ceux qui n'indiquent aucune intégration. - **Échéances** : **Avec échéances** ou **Sans échéances**. - **Métadonnées** : une **Clé** envoyée par votre intégration, et sa **Valeur (optionnelle)**. Choisissez **Appliquer**. Un chiffre de l'accueil ouvre cette liste avec deux filtres de plus : **Période**, la période exacte que comptait le chiffre, et **Crédités sur le solde**, ou **Statut** pour un chiffre d'échecs. Choisissez des jours dans **Date** pour remplacer la période. Chaque filtre se retire avec sa croix. ## Exporter Choisissez **Exporter** en haut de la page, ou dans la barre qui apparaît quand des lignes sont cochées. **Exporter les paiements** s'ouvre : le fichier reprend la liste avec ses filtres, ou les seules lignes cochées. Chaque paiement du fichier donne son **Intégration**. 1. **Choisissez le format** Sous **Format**, choisissez **CSV**, **Excel**, **PDF** ou **JSON**. 2. **Choisissez la période** Sans lignes cochées, sous **Période**, choisissez une période toute prête, ou remplissez **De** et **À** sous **Période personnalisée** puis choisissez **Appliquer**. Sans période, toutes les dates sont exportées. **Filtres conservés** rappelle la recherche et les filtres que le fichier appliquera. 3. **Exportez** Choisissez **Exporter en CSV**, **Exporter en Excel**, **Exporter en PDF** ou **Exporter JSON**, selon le format. Le fichier se télécharge, et « Votre export est prêt : » s'affiche avec son nom. En Test, la fenêtre explique que les exports ne contiennent que des données de production et ne propose pas d'exporter. Chaque export compte dans la limite mensuelle de votre forfait : [Choisir ou changer de forfait](https://docs.wajub.com/dashboard/subscription/plans). Une fois la limite atteinte, la fenêtre le dit et n'exporte plus. Le propriétaire, les Administrateurs et les rôles personnalisés qui ont **Gérer le compte** voient **Passer à un forfait supérieur** ; les autres membres sont invités à s'adresser au propriétaire. --- # Lire un paiement URL: https://docs.wajub.com/fr/dashboard/payments/read > Le statut, l'historique et la répartition d'un paiement, son reçu, les notes de l'équipe et le renvoi du lien de paiement au client. La page d'un paiement réunit ce qui lui est arrivé : son statut, chaque tentative, ce qu'il vous rapporte une fois les frais retirés, et les litiges ouverts dessus. Tous les [rôles](https://docs.wajub.com/fr/dashboard#roles) ouvrent un paiement, avec tous les forfaits. Écrire une note et renvoyer le lien de paiement demandent **Gérer les paiements**, qu'ont le propriétaire, les Administrateurs, les membres Finance et Spécialiste support, et l'Utilisateur de test en Test. L'onglet **Échéances** n'existe qu'à partir du forfait **Growth**, et les notes qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Hormis le remboursement, rien sur cette page ne demande le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## L'en-tête Ouvrez un paiement depuis **Paiements** : [Trouver un paiement](https://docs.wajub.com/dashboard/payments/find). L'en-tête donne le montant, le statut, l'**ID du paiement** et sa date. **Retenue pour risque** signale un paiement crédité sur votre solde dont l'argent est retenu un temps avant de pouvoir être transféré. Dessous, **Client** mène à la fiche du client, **Moyen de paiement** nomme le moyen et le fournisseur, et **Créé depuis** dit d'où vient le paiement, par exemple un lien de paiement, une facture, l'API ou le tableau de bord. **Retour aux paiements** revient à la liste. Les boutons de l'en-tête dépendent du statut. **Reçu** apparaît pour un paiement réussi, remboursé ou partiellement remboursé ; **Rembourser** est décrit dans [Rembourser un paiement](https://docs.wajub.com/dashboard/payments/refund). Le menu à côté propose, selon le paiement, **Voir le client**, **Télécharger le reçu (PDF)** et **Envoyer le lien de paiement**. ![La page d'un paiement remboursé : le montant, le statut et l'ID du paiement en haut, les faits Client et Moyen de paiement, l'onglet Vue d'ensemble avec les détails du paiement, et à droite la répartition des revenus avec le montant brut, les frais, le remboursé et le montant net.](https://docs.wajub.com/dashboard/fr/light/payments-detail.webp) *Le paiement à gauche, ce qu'il vous rapporte à droite.* Quand un client conteste le paiement, l'encadré **Ce paiement est contesté** donne le montant contesté, le motif et l'échéance de votre réponse. **Répondre au litige** ouvre le litige : [Répondre à un litige](https://docs.wajub.com/dashboard/payments/disputes). Une fois le litige terminé, l'encadré devient **Litige gagné** ou **Litige clos**, avec **Voir le litige**. ## Les onglets **Vue d'ensemble** s'ouvre en premier. **Remboursements** apparaît quand le paiement en a, avec le montant, le motif et le statut de chacun : [Suivre les remboursements](https://docs.wajub.com/dashboard/payments/track-refunds). **Échéances** apparaît pour un paiement réglé en plusieurs fois, avec le détail de chaque échéance. ## La vue d'ensemble Un paiement qui n'a pas abouti commence par un encadré. **Paiement échoué** donne le **Code d'erreur** et une **Action suggérée** à transmettre au client. **Paiement expiré** et **Paiement annulé** disent que le paiement s'est arrêté avant d'être terminé. **Détails du paiement** donne la date **Crédité le**. Pendant une retenue, **Fonds disponibles le** dit quand elle se lève ; une fois levée, **Fonds devenus disponibles le** dit depuis quand vous pouvez transférer l'argent. Suivent le **Taux de change** et **Payé en** quand le client a payé dans une autre devise, l'**Intégration**, le SDK ou la page depuis lequel le paiement a été fait, la **Description**, et le **Descripteur de relevé** que le client voit sur son relevé. Les sections suivantes n'apparaissent que si le paiement en a : **Articles de commande**, à titre d'information, **Taxe**, **Références** avec **Votre référence**, **Référence de traitement** et **Référence fournisseur**, **Adresses**, puis **Paiements liés**. **Historique** déroule les étapes du paiement et chacune de ses tentatives, avec le fournisseur qui l'a traitée ; **Tout développer** les ouvre toutes. Pour un paiement qui n'a pas réussi, **Réviser le routage** mène au choix de fournisseur qu'a fait Wajub. **Webhooks** liste les événements envoyés à votre serveur pour ce paiement, avec la réponse reçue et les nouvelles tentatives. **Métadonnées** montre les données ajoutées par votre intégration. ## La répartition des revenus À droite, **Répartition des revenus** part du **Montant brut**, retire chaque frais avec son taux, puis ce qui a été **Remboursé** et ce qui a été **Perdu dans un litige**. Le **Montant net** est ce qui vous reste ; « Sera versé le » donne, quand elle est connue, la date de son versement. Tant que le paiement n'a pas réussi, les frais sont **Facturé en cas de succès** et le montant net **Non réglé**. Dessous, **Moyen de paiement** détaille le moyen utilisé, et **Risque et sécurité** donne le score de risque et ce que le contrôle a relevé. ## Les notes Les notes s'écrivent en bas de **Historique**, pour les membres de votre équipe ; le client ne les voit jamais. Saisissez le texte sous « Que doivent savoir vos membres sur ce paiement ? », puis choisissez **Ajouter une note**. Le menu d'une note propose **Épingler la note**, qui la range sous **Notes épinglées** en tête de l'historique, et **Supprimer la note**. ## Le reçu **Reçu** ouvre le reçu tel que le client le voit : le montant payé, la date, le moyen de paiement et les coordonnées de votre organisation. **Télécharger le PDF** l'enregistre, **Imprimer le reçu** l'imprime. **Télécharger le reçu (PDF)**, dans le menu, l'enregistre sans l'ouvrir. ## Renvoyer le lien de paiement Un client qui n'a pas terminé son paiement peut le reprendre depuis un lien envoyé par e-mail. Il faut un paiement **En attente** ou **En traitement**, pas encore expiré, et rattaché à un client. 1. **Choisissez Envoyer le lien de paiement** Dans le menu de l'en-tête, choisissez **Envoyer le lien de paiement**. Si le client a une adresse e-mail, une fenêtre la rappelle et demande confirmation. 2. **Indiquez l'adresse si besoin** Si le client n'a pas d'adresse e-mail, saisissez-la dans **E-mail du client**. Elle n'est enregistrée sur sa fiche que si votre rôle peut gérer les clients. 3. **Envoyez le lien** Choisissez **Envoyer le lien**. Le client reçoit un e-mail avec le lien pour terminer son paiement. --- # Répondre à une demande URL: https://docs.wajub.com/fr/dashboard/payments/refund-requests > Approuver ou refuser la demande de remboursement qu'un client a faite depuis son portail Pocket, avant qu'il puisse la transformer en litige. Un client qui veut récupérer son argent commence par une demande de remboursement, depuis son portail Pocket. C'est l'étape à l'amiable, avant tout litige : votre réponse décide s'il récupère son argent ou s'il peut contester le paiement. Tous les [rôles](https://docs.wajub.com/fr/dashboard#roles) voient les demandes. Approuver est réservé au propriétaire, aux Administrateurs, aux membres Spécialiste support et aux rôles personnalisés qui ont **Rembourser les paiements**, et demande le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). Refuser est ouvert au propriétaire, aux Administrateurs, aux membres Finance et Spécialiste support et aux rôles personnalisés qui ont **Gérer les paiements**, sans code de sécurité. Les demandes n'existent qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), avec tous les forfaits. ## Ouvrir une demande Quand une demande arrive, le propriétaire et les membres qui peuvent l'approuver ou la refuser reçoivent un e-mail, puis, si elle attend toujours, un rappel deux jours avant que le client puisse ouvrir un litige. Ces e-mails suivent la préférence **Litiges** de chacun : [Préférences](https://docs.wajub.com/dashboard/account/preferences). Le lien de l'e-mail ouvre directement la demande. Dans le tableau de bord, ouvrez **Paiements**, puis l'onglet **Litiges** : le nombre affiché sur l'onglet compte les demandes qui attendent votre réponse. Choisissez **Étape** › **Demande** pour ne garder qu'elles, puis choisissez la ligne. **Examiner la demande de remboursement** s'ouvre. ![La fenêtre Examiner la demande de remboursement : le montant demandé, le paiement, ce qui reste à rembourser dessus, ce que le client reçoit avec la part des frais Wajub, le client, la date de la demande, la date limite de réponse et le motif du client, puis les boutons Approuver et rembourser 18 500 FCFA, Rejeter et Annuler.](https://docs.wajub.com/dashboard/fr/light/payments-refund-request.webp) *Le montant demandé, le motif du client et la date limite de votre réponse.* La fenêtre donne le **Montant demandé**, le **Paiement** et ce qui reste à rembourser dessus (**Reste à rembourser dessus**), ce que **Le client reçoit** une fois la part des frais Wajub réglée, et le **Motif du client**. **Répondre avant le** est la date après laquelle le client peut ouvrir un litige si vous n'avez pas répondu. ## Approuver 1. **Vérifiez ce que fait l'approbation** L'encadré **Ce que fait l'approbation** dit combien le client récupère, depuis votre solde. La part des frais suit votre choix par défaut : [Le choix par défaut des frais](https://docs.wajub.com/dashboard/payments/refund#the-default-fee-choice). 2. **Approuvez** Choisissez le bouton « Approuver et rembourser », suivi du montant demandé, puis saisissez le code de sécurité. Le message « Demande de remboursement approuvée. Le remboursement a été enregistré. » s'affiche. Le remboursement part comme tout autre remboursement : [Suivre les remboursements](https://docs.wajub.com/dashboard/payments/track-refunds). Dans la liste des litiges, le menu de la demande propose ensuite **Voir le remboursement**. ## Refuser 1. **Choisissez Rejeter** Dans la fenêtre de la demande, choisissez **Rejeter**. **Refuser la demande de remboursement** s'affiche : aucun argent ne bouge. 2. **Écrivez votre réponse** Sous **Votre réponse au client**, dites pourquoi vous refusez et ce que le client peut faire à la place, en 1 000 caractères au plus. La réponse est obligatoire. 3. **Refusez la demande** Choisissez **Refuser la demande**. Le message « Demande de remboursement refusée. » s'affiche. Le client lit votre réponse dans son portail Pocket. ## Quand l'approbation est bloquée Un encadré remplace **Ce que fait l'approbation** quand la demande ne peut pas être remboursée telle quelle : | Encadré | Ce qu'il faut faire | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **Ce paiement ne peut pas être remboursé** | Seul un paiement réussi et crédité sur votre solde se rembourse. Refusez en expliquant pourquoi. | | **Un litige est ouvert sur ce paiement** | Répondez au litige plutôt qu'à la demande, pour ne pas payer le client deux fois. **Ouvrir le litige** y mène. | | **Une rétrofacturation est en cours sur ce paiement** | La banque du client décide ; le paiement ne peut pas être remboursé avant sa décision. | | **Il ne reste rien à rembourser** | Le paiement a déjà été rendu en entier. Refusez et dites-le au client. | | **Plus que ce qui reste à rembourser** | Le client demande plus que ce qui reste. Si vous refusez, il peut ouvrir un litige pour ce qui reste. | | **Déjà approuvée** | La demande a été approuvée et le remboursement fait, mais la réponse s'est perdue. **Terminer l'approbation** la clôt, sans second remboursement. | ## Quand le client ouvre un litige Le client peut transformer sa demande en litige depuis Pocket sept jours après l'avoir faite si vous n'avez pas répondu, ou dans les 30 jours qui suivent votre refus. La demande passe alors à **Transformée en litige**, et le litige apparaît dans la même liste, marqué **Issu d'une demande de remboursement** : [Répondre à un litige](https://docs.wajub.com/dashboard/payments/disputes). --- # Rembourser un paiement URL: https://docs.wajub.com/fr/dashboard/payments/refund > Rendre tout ou partie d'un paiement à votre client, choisir qui supporte les frais Wajub, et régler ce choix par défaut dans Paramètres › Remboursements. Un remboursement renvoie au client tout ou partie de ce qu'il a payé. Il ne peut pas être annulé. Rembourser est réservé au propriétaire, aux Administrateurs, aux membres Spécialiste support et aux [rôles](https://docs.wajub.com/fr/dashboard#roles) personnalisés qui ont **Rembourser les paiements**, avec tous les forfaits : un membre Finance ne peut pas rembourser. Rembourser demande le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). En [Test](https://docs.wajub.com/fr/dashboard#sandbox-and-live), il se fait aussitôt, sans argent réel. ## Les étapes 1. **Ouvrez le paiement** Ouvrez le paiement depuis **Paiements** : [Trouver un paiement](https://docs.wajub.com/dashboard/payments/find). **Rembourser** apparaît en haut de la page pour un paiement **Réussi** ou **Partiellement remboursé** dont il reste un montant à rendre. 2. **Choisissez Rembourser** Choisissez **Rembourser**. **Rembourser ce paiement** s'ouvre sur le **Montant du paiement**, ce qui est **Déjà remboursé**, ce qui a été **Perdu dans un litige** s'il y en a, et le montant **Disponible pour remboursement**. ![La fenêtre Rembourser ce paiement : le montant du paiement, ce qui est déjà remboursé et le montant disponible pour remboursement en haut, le champ Montant du remboursement prérempli avec les choix 25 %, 50 % et Montant total, le champ Motif, la carte Vous sous Qui supporte les frais Wajub sur ce remboursement, puis le bouton Rembourser 15 000 FCFA.](https://docs.wajub.com/dashboard/fr/light/payments-refund.webp) *Le montant est prérempli avec tout ce qui reste à rembourser.* 3. **Indiquez le montant** **Montant du remboursement** est prérempli avec tout ce qui reste à rembourser. Pour un remboursement partiel, saisissez un montant plus petit, ou choisissez 25 % ou 50 % du montant restant ; **Montant total** revient à tout ce qui reste. 4. **Ajoutez un motif** Le **Motif**, facultatif et de 500 caractères au plus, reste attaché au remboursement. 5. **Choisissez qui supporte les frais** Si le paiement a coûté des frais Wajub, **Qui supporte les frais Wajub sur ce remboursement ?** propose deux cartes. **Vous** rend au client tout ce qu'il a payé, y compris des frais qu'il aurait payés en plus, pris sur votre solde. **Client** laisse la part des frais au client : elle est déduite de ce qu'il récupère. La carte choisie d'avance suit le réglage par défaut, décrit plus bas. 6. **Vérifiez ce que fait le remboursement** Une fois le montant valide, **Ce que fait ce remboursement** montre le **Montant du remboursement**, ce que **Le client reçoit**, la **Part des frais Wajub** s'il y en a une, ce qui est **Débité de votre solde** et ce qui **Reste à rembourser ensuite**. Pour un paiement encaissé sur votre propre compte chez un fournisseur, **Débité de votre solde** indique **Rien** et dit de le rembourser depuis ce compte. Le bouton de remboursement attend que ces chiffres s'affichent ; s'ils ne peuvent pas l'être, choisissez **Réessayer**. 7. **Confirmez avec le code de sécurité** Choisissez le bouton « Rembourser », suivi du montant, puis saisissez le code de sécurité. Le message de confirmation dit ce qui se passe ensuite, selon le cas décrit ci-dessous. ## Après le remboursement Pour un paiement encaissé par Wajub, Wajub envoie le remboursement au client. Pour un paiement encaissé sur votre propre compte chez un fournisseur, le remboursement est enregistré, mais c'est à vous de le faire depuis ce fournisseur ; il se met à jour dans Wajub une fois que le fournisseur le confirme. Dans les deux cas, l'onglet **Remboursements** du paiement le suit : [Suivre les remboursements](https://docs.wajub.com/dashboard/payments/track-refunds). Quand le remboursement est refusé, la raison s'affiche sous **Montant du remboursement** ; tout autre problème s'affiche sous **Le remboursement n'a pas été effectué**. Pendant une rétrofacturation, la banque du client décide seule et le paiement ne peut pas être remboursé : **Rembourser** disparaît jusqu'à sa décision. Un compte dont les remboursements sont restreints doit d'abord [contacter l'assistance](https://docs.wajub.com/dashboard/help/support). ## Le choix par défaut des frais **Paramètres › Remboursements** fixe qui supporte les frais quand vous remboursez, pour la part des frais qui correspond au montant rendu. Wajub garde ses frais dans tous les cas. Le tableau de bord préremplit ce choix dans chaque remboursement, et l'API l'applique quand un remboursement ne précise rien. Sous **Qui supporte les frais lors d'un remboursement**, choisissez : - **Celui qui les a payés au paiement** : vous continuez de supporter les frais que vous aviez payés, et un client qui les avait payés en plus ne les récupère pas. C'est le choix de départ. - **Vous** : le client récupère tout ce qu'il a payé, frais compris, pris sur votre solde. - **Le client** : la part des frais reste au client, déduite de ce qu'il récupère quand c'est vous qui les aviez payés. Choisissez **Enregistrer les modifications**. Changer ce réglage est réservé au propriétaire, aux Administrateurs et aux rôles personnalisés qui ont **Gérer les paramètres** ; un Développeur ou un Observateur le lit sans pouvoir le changer. --- # Suivre les remboursements URL: https://docs.wajub.com/fr/dashboard/payments/track-refunds > Retrouver un remboursement, savoir où il en est et ce que le client a reçu, et exporter la liste des remboursements. **Remboursements** liste l'argent rendu à vos clients, que le remboursement vienne du tableau de bord, de l'API ou d'une demande de remboursement approuvée, et dit où en est chacun. Tous les [rôles](https://docs.wajub.com/fr/dashboard#roles) ouvrent **Remboursements**, avec tous les forfaits. Exporter est réservé au propriétaire, aux Administrateurs, aux membres Finance et Spécialiste support, et aux rôles personnalisés qui ont **Gérer les paiements**, en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live) uniquement. Rien sur cette page ne demande le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## La liste Ouvrez **Paiements**, puis l'onglet **Remboursements**. Chaque ligne donne le **Montant**, le **Statut**, le **Client** et le **Paiement** remboursé, avec la **Date**. Un remboursement passe par **En attente** et **En traitement** avant d'être **Réussi** ; il peut aussi finir **Échoué** ou **Annulée**. ![L'onglet Remboursements de Paiements : la recherche et les filtres Date, Statut et Montant, puis la liste avec le montant, le statut, le client, le paiement remboursé et la date de chaque remboursement.](https://docs.wajub.com/dashboard/fr/light/payments-refunds.webp) *Un remboursement par ligne, avec le paiement qu'il rembourse.* La barre de recherche trouve un remboursement par son identifiant, celui de son paiement, son motif, ou le nom ou l'e-mail du client. **Date**, **Statut** et **Montant** filtrent la liste. Le menu au bout d'une ligne propose **Ouvrir le remboursement**, **Copier l'identifiant du remboursement**, **Voir le paiement** et, quand le remboursement a un client, **Voir le client**. Cochez des lignes pour **Copier les identifiants** de toutes à la fois ou les exporter. ## Le détail d'un remboursement La page d'un remboursement donne son montant, son statut et son **Identifiant du remboursement**. Dessous, **Paiement** mène au paiement remboursé, **Client** à la fiche du client, et **Le client reçoit** donne ce qu'il récupère, avec qui a supporté les frais. **Détails du remboursement** reprend le **Motif**, la **Description**, la date **Terminé le** et, quand le paiement en portait, la **Taxe** annulée en proportion du remboursement. L'historique suit le remboursement de **Remboursement demandé** à **Remboursement effectué**, ou à **Remboursement échoué** ou **Remboursement annulé** ; entre les deux, **En attente du fournisseur** montre qu'il est en cours. À droite, **Paiement d'origine** résume le paiement. Sur la page du paiement, l'onglet **Remboursements** liste aussi ses remboursements. Pour un remboursement en cours, il précise si l'équipe Wajub s'en charge, s'il est en route vers le client, ou s'il vous reste à le faire depuis votre compte chez le fournisseur. ## Exporter Choisissez **Exporter** en haut de l'onglet, ou dans la barre qui apparaît quand des lignes sont cochées. **Exporter les remboursements** fonctionne comme l'export des paiements, avec les mêmes formats et la même limite mensuelle : [Exporter des paiements](https://docs.wajub.com/dashboard/payments/find#export). --- # Consulter le journal d'audit URL: https://docs.wajub.com/fr/dashboard/settings/audit-log > Retrouver qui a changé quoi dans l'organisation, quand et depuis quelle adresse IP, et vérifier que le journal n'a pas été modifié. Le **Journal d'audit** garde les modifications faites sur l'organisation, chacune avec le membre qui l'a faite, son adresse IP, son appareil et l'heure : - le nom de l'organisation, les membres, les invitations, les rôles et les rôles personnalisés ; - les clés API et les secrets de signature des webhooks ; - les sites autorisés à intégrer la page de paiement, la sécurité des transferts et les domaines personnalisés ; - la vérification de l'entreprise, la facturation et l'abonnement ; - les remboursements, les litiges, les liens de paiement envoyés et les avoirs ; - les clients ; - les transferts, les transferts récurrents et les bénéficiaires ; - les fournisseurs de paiement et les règles de routage ; - les connexions Sync et les applications connectées ; - ce que fait le support Wajub dans l'organisation. Des réglages comme l'image de marque, les champs de la page de paiement, sa langue et ses devises ne sont pas enregistrés. Vos propres connexions, mot de passe, méthode de double authentification et clés d'accès sont dans [Votre activité](https://docs.wajub.com/dashboard/account/activity-and-data). Le propriétaire, un Administrateur, un Développeur, un Observateur ou un rôle personnalisé qui a **Voir les paramètres** ouvre le journal. Personne ne peut le modifier, et il n'a pas d'export. Le même journal s'affiche en Test et en Production. ## Ouvrir le journal Ouvrez **Paramètres**, puis **Journal d'audit** dans le groupe **Organisation**. Chaque ligne donne l'**Action**, le **Membre** qui l'a faite, l'**Adresse IP et appareil** et la **Date**. Une action faite par Wajub lui-même porte **Système** à la place du membre. Les entrées vont de la plus récente à la plus ancienne, 50 par page. Ce que fait le support Wajub porte **Support Wajub** à la place du membre, par exemple **Le support Wajub a ouvert l'organisation**, **Fin de la session du support Wajub** ou **Informations de l'organisation modifiées par le support Wajub**. Chaque fois que le support ouvre l'organisation, le propriétaire reçoit aussi un e-mail. ![Paramètres › Journal d'audit : la recherche, les filtres Date, Action et Membre, le bouton Vérifier l'intégrité, puis la liste des actions avec le membre, l'adresse IP et l'appareil, et la date.](https://docs.wajub.com/dashboard/fr/light/settings-audit-log.webp) *Chaque ligne dit qui a fait quoi, depuis où et quand.* La plupart des modifications du propriétaire ajoutent aussi une ligne **Le propriétaire a utilisé son accès complet**. Pour ne suivre qu'une sorte de modification, filtrez par **Action**. ## Chercher une action La recherche porte sur l'e-mail du membre, l'adresse IP ou l'action. Les filtres **Date**, jusqu'à 365 jours en arrière, **Action** et **Membre** se combinent ; un membre qui a quitté l'organisation reste proposé dans le filtre **Membre**, comme **Support Wajub** dès que le support y a agi. ## Vérifier l'intégrité Chaque entrée est liée à la précédente, ce qui rend visible toute entrée modifiée, supprimée ou déplacée. **Vérifier l'intégrité** contrôle tout le journal et affiche **Le journal d'audit est intact**, avec le nombre d'entrées vérifiées, ou **Le journal d'audit a été altéré**, avec la première entrée qui ne correspond pas. Dans ce cas, contactez le [support](https://docs.wajub.com/dashboard/help/support). --- # Personnaliser votre marque URL: https://docs.wajub.com/fr/dashboard/settings/branding > Mettre votre logo, vos couleurs et votre police sur la page de paiement, les factures, les reçus et les e-mails envoyés à vos clients, avec un aperçu en direct. **Paramètres › Image de marque** donne à ce que voient vos clients votre logo, vos couleurs et votre police : la page de paiement, les factures, les reçus et les e-mails. Le propriétaire, un Administrateur, un Développeur, un Observateur ou un rôle personnalisé qui a **Voir les paramètres** ouvre la page. Seuls le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les paramètres** enregistre une marque. Il faut le forfait **Growth** ou au-dessus ; sinon, voir [Modules hors de votre forfait](https://docs.wajub.com/fr/dashboard#modules-outside-your-plan). La marque vaut en Test comme en Production, et aucun code de sécurité n'est demandé. ## Les étapes 1. **Ouvrez le studio de marque** Ouvrez **Paramètres**, puis **Image de marque** dans le groupe **Produits**. Le **Studio de marque** montre les réglages à gauche et l'aperçu à droite. ![Paramètres › Image de marque : le Studio de marque avec les onglets Identité, Couleurs, Typographie et Avancé, ouvert sur Identité : sous Logos, les emplacements Icône (carré, 512 × 512 px) et Logo (large, PNG ou JPG).](https://docs.wajub.com/dashboard/fr/light/settings-branding.webp) *Les autres réglages sont dans les onglets Couleurs, Typographie et Avancé.* 2. **Importez vos logos** Dans l'onglet **Identité**, importez une **Icône** carrée de 512 × 512 px et un **Logo** large, en PNG ou JPG, jusqu'à 2 Mo chacun. 3. **Choisissez vos couleurs** Dans l'onglet **Couleurs**, partez d'un des **Préréglages**, puis ajustez au besoin les **Jetons de couleur** un par un, en saisissant un code comme #007492. 4. **Réglez la présentation** Dans l'onglet **Typographie**, choisissez l'**Apparence** (**Suivre l'appareil**, **Clair** ou **Sombre**), la **Densité**, le **Traitement des médias**, la **Famille de police** et le **Rayon des coins**. 5. **Vérifiez l'aperçu** Au-dessus de l'aperçu, passez de la page de paiement à la facture, au reçu ou à l'e-mail, en **Mobile**, **Tablette** ou **Bureau**. 6. **Enregistrez la marque** **Enregistrer les modifications**, dans la barre en bas de l'écran, applique tous les réglages d'un coup ; **Abandonner** les annule. ## Les réglages avancés L'onglet **Avancé** règle le **Domaine de paiement** de la page de paiement : **Par défaut (pay.wajub.com)** ou l'un de vos [domaines personnalisés](https://docs.wajub.com/dashboard/settings/custom-domains). Un domaine personnalisé qui sert la page de paiement y est choisi de lui-même une fois vérifié. Les liens de paiement et les factures choisissent le leur dans **Paramètres › Liens de paiement** et **Paramètres › Factures**. **Sauvegarde du thème** exporte vos réglages avec **Exporter JSON** et les reprend avec **Importer du JSON**, par exemple dans une autre organisation. **Tout réinitialiser** remet les couleurs, la police, les coins et la présentation par défaut ; rien ne change tant que vous n'enregistrez pas. Un logo retiré disparaît de la page de paiement, des factures et des e-mails au prochain enregistrement. La page avertit aussi quand aucun site n'est déclaré pour afficher votre page de paiement : voir [Régler la page de paiement](https://docs.wajub.com/dashboard/settings/checkout-page#embedding). --- # Régler la page de paiement URL: https://docs.wajub.com/fr/dashboard/settings/checkout-page > Ajouter des champs à remplir avant de payer, choisir la langue et les devises de la page de paiement, et déclarer les sites qui peuvent l'afficher dans un cadre. **Paramètres › Paiement** règle ce que la page de paiement Wajub demande au client, dans quelle langue et avec quelles devises elle s'affiche, et sur quels sites elle peut apparaître. Le propriétaire, un Administrateur, un Développeur, un Observateur ou un rôle personnalisé qui a **Voir les paramètres** ouvre ces réglages. Seuls le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les paramètres** les change ; la liste des sites, un Développeur ou un rôle qui a **Gérer les paramètres développeur** peut aussi la changer. Tous les forfaits ont ces réglages, valables en Test comme en Production. Seul l'enregistrement de la liste des sites demande le code de sécurité. ## Ajouter un champ 1. **Ouvrez les champs** Ouvrez **Paramètres › Paiement**. L'onglet **Champs** liste vos **Champs personnalisés**, à côté d'un aperçu de la page de paiement en **Mobile**, **Tablette** ou **Bureau**. ![Paramètres › Paiement, onglet Champs : les Champs personnalisés, 2 champs configurés, Nom de l'entreprise et Numéro de contribuable (NIU), chacun en Texte court, et le bouton Ajouter un champ personnalisé.](https://docs.wajub.com/dashboard/fr/light/settings-checkout-fields.webp) *Chaque champ affiche son type et son texte indicatif.* 2. **Ouvrez le formulaire du champ** **Ajouter un champ personnalisé** ouvre la fenêtre du même nom. 3. **Choisissez le type de champ** Sous **Type de champ**, choisissez **Texte court**, **Texte long**, **Numéro** pour un nombre, **E-mail**, **Téléphone**, **Menu déroulant** ou **Case à cocher**. Pour un menu déroulant, ajoutez ses choix sous **Options** avec **Ajouter l'option**. 4. **Rédigez la question** Saisissez le **Libellé (question)**, et si besoin un **Texte indicatif (optionnel)** qui s'affiche dans le champ vide. **Champ requis** oblige le client à le remplir pour payer. 5. **Ajoutez le champ** **Ajouter un champ personnalisé** enregistre le champ : la page de paiement le demande aussitôt. Le menu au bout d'un champ le modifie, le masque du paiement sans le supprimer ou le supprime définitivement ; les flèches à sa gauche changent sa place dans la liste. Le client remplit ces champs sur la page de paiement, avant de payer. ## Choisir la langue Dans l'onglet **Langue**, la **Langue par défaut** est **Détection automatique**, **Anglais** ou **Français**. **Enregistrer les modifications** applique le choix. ## Les devises Dans l'onglet **Devises**, la **Devise de base** est celle dans laquelle le tableau de bord présente vos chiffres et facture par défaut, la même pour tous les membres. Elle ne change pas la devise de règlement, celle de vos versements, affichée dans **Paramètres › Général**. **Activer la conversion automatique** montre les prix dans la devise du client, parmi les **Devises affichées** que vous choisissez ; le client paie toujours dans la devise du paiement. **Activer les paiements fractionnés manuels** permet à votre intégration de découper un paiement en deux, trois ou quatre échéances, selon le **Nombre de fractionnements autorisés** et au-dessus du **Montant minimum pour fractionnement manuel**. **Enregistrer les modifications** applique ces réglages. ## Les sites qui affichent la page Si votre site affiche la page de paiement dans un cadre, déclarez-le dans l'onglet **Intégration**, sous **Sites autorisés**, un par ligne : https\:// suivi du domaine, sans chemin, jusqu'à 20 sites. Seuls ces sites peuvent alors l'afficher, en Test comme en Production. Tant que la liste est vide, n'importe quel site le peut, et la page vous en avertit. **Enregistrer les modifications** demande le code de sécurité. ![Paramètres › Paiement, onglet Intégration : l'avertissement qu'aucun site n'est déclaré, puis le champ Sites autorisés, un site par ligne.](https://docs.wajub.com/dashboard/fr/light/settings-checkout-embedding.webp) *Une liste vide laisse n'importe quel site afficher votre page de paiement.* --- # Connecter votre domaine URL: https://docs.wajub.com/fr/dashboard/settings/custom-domains > Servir la page de paiement, les liens de paiement et les factures sur un sous-domaine à vous, comme pay.example.com, en publiant deux enregistrements DNS. Un domaine personnalisé remplace l'adresse Wajub par défaut par un sous-domaine qui vous appartient, comme pay.example.com, pour la page de paiement, les liens de paiement et les factures. Le propriétaire, un Administrateur, un Développeur ou un rôle personnalisé qui a **Gérer les paramètres** ou **Gérer les paramètres développeur** connecte et gère les domaines ; un Observateur ou un rôle qui n'a que **Voir les paramètres** les voit. Il faut le forfait **Scale** ou **Enterprise** ; sinon, voir [Modules hors de votre forfait](https://docs.wajub.com/fr/dashboard#modules-outside-your-plan). Seule la suppression d'un domaine demande le code de sécurité. ## Les étapes 1. **Ouvrez les domaines personnalisés** Ouvrez **Paramètres**, puis **Domaines personnalisés** dans le groupe **Produits**. 2. **Ajoutez le sous-domaine** Sous **Ajouter un domaine personnalisé**, saisissez le sous-domaine, par exemple pay.example.com, sans https\:// ni chemin, puis cliquez sur **Ajouter un domaine personnalisé**. Il apparaît sous **Domaines connectés**, marqué **En attente de vérification**, avec les deux enregistrements DNS à publier. ![Paramètres › Domaines personnalisés : le domaine pay.kribicoffee.cm en attente, avec le tableau des enregistrements TXT et CNAME à ajouter chez le fournisseur DNS (Type, Hôte, Valeur) et le bouton Vérifier le DNS.](https://docs.wajub.com/dashboard/fr/light/settings-domains.webp) *Chaque hôte et chaque valeur a son bouton pour le copier.* 3. **Publiez les enregistrements DNS** Chez votre fournisseur DNS, ajoutez l'enregistrement TXT, qui prouve que le domaine est à vous, et le CNAME, qui dirige les visiteurs vers Wajub. Gardez le CNAME tant que vous utilisez le domaine. Avec Cloudflare, réglez le CNAME sur « DNS only », le nuage gris. 4. **Vérifiez le DNS** **Vérifier le DNS** contrôle les deux enregistrements. Une modification DNS peut prendre jusqu'à 48 heures : si la vérification échoue, **Ce que nous voyons dans votre DNS** montre ce que Wajub a trouvé, et **Vérifier le DNS** relance le contrôle. Une fois le DNS confirmé, le domaine reste en **Sécurisation de la connexion** le temps que Wajub prépare son certificat, puis passe à **Vérifié** et sert vos pages, après quelques minutes. 5. **Choisissez ce qu'il sert** Sous **Utiliser ce domaine pour**, gardez **Tous les modules**, ou limitez-le à la page de paiement, aux liens de paiement ou aux factures. Un domaine qui sert la page de paiement y est utilisé dès qu'il est vérifié ; l'[image de marque](https://docs.wajub.com/dashboard/settings/branding#advanced-settings) peut le changer. 6. **Choisissez-le pour les liens et les factures** Les liens de paiement et les factures gardent l'adresse Wajub tant que vous n'y choisissez pas le domaine, sous **Domaine**, dans **Paramètres › Liens de paiement** pour les liens et **Paramètres › Factures** pour les factures. Ces deux pages ne s'ouvrent qu'en Production. ## Si le domaine ne pointe plus vers Wajub Si le CNAME disparaît ou change, le propriétaire, les Administrateurs et les Développeurs reçoivent un e-mail, et le domaine affiche **Ce domaine ne pointe plus vers Wajub**, avec le délai avant sa déconnexion. Corrigez l'enregistrement avant ce délai. Sinon, le domaine est déconnecté, un second e-mail le signale, et la page de paiement, les liens de paiement et les factures reprennent l'adresse Wajub par défaut. Une fois l'enregistrement corrigé, **Réessayer** sur le domaine le reconnecte. ## Supprimer un domaine **Supprimer le domaine** demande le code de sécurité, puis retire le domaine définitivement : les pages qui l'utilisaient passent aussitôt à l'adresse Wajub par défaut. Un domaine déjà connecté à une autre organisation Wajub ne peut pas être ajouté. > [!NOTE] > **Un sous-domaine plutôt que le domaine racine** > > La plupart des fournisseurs DNS refusent un CNAME sur le domaine lui-même, comme example.com. > Connectez un sous-domaine, ou utilisez un enregistrement ALIAS ou ANAME si votre fournisseur le > propose. --- # Renommer l'organisation URL: https://docs.wajub.com/fr/dashboard/settings/general > Changer le nom de l'organisation, et retrouver dans Paramètres › Général les détails de son entreprise, son numéro de compte, son ID de support et sa devise de règlement. **Paramètres › Général** porte le nom de l'organisation, les détails de son entreprise et les numéros à donner au support ou à une autre organisation Wajub. Le propriétaire, un Administrateur, un Développeur, un Observateur ou un rôle personnalisé qui a **Voir les paramètres** ouvre la page. Seuls le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les paramètres** peut renommer l'organisation. Le nom est le même en Test et en Production, et aucun code de sécurité n'est demandé. ## Les étapes 1. **Ouvrez la page Général** Ouvrez **Paramètres**, puis **Général** dans le groupe **Organisation**. ![Paramètres › Général : la carte Nom de l'organisation avec Kribi Coffee SARL, puis la carte Identifiants : le Numéro de compte et l'ID de support, chacun avec son bouton Copier, Paiements en production Activé et la Devise de règlement XAF.](https://docs.wajub.com/dashboard/fr/light/settings-general.webp) *Le numéro de compte et l'ID de support ont chacun un bouton Copier.* 2. **Saisissez le nouveau nom** Dans **Nom de l'organisation**, remplacez le nom actuel : il est obligatoire, jusqu'à 255 caractères. Une barre apparaît en bas de l'écran dès la première modification. 3. **Enregistrez le nom** **Enregistrer les modifications** applique le nouveau nom ; **Abandonner** remet l'ancien. Le nouveau nom apparaît aussitôt dans le tableau de bord et dans les e-mails de vos membres. ## Ce que montre la page **Détails de l'entreprise** reprend votre dossier de vérification, déposé depuis **Conformité** : nom légal, type de compte, site web, e-mail professionnel, téléphone, pays et propriétaire. Voir [Vérifier votre entreprise](https://docs.wajub.com/dashboard/activation/verify-business). **Identifiants** donne le **Numéro de compte**, qu'une autre organisation Wajub utilise pour vous envoyer un transfert, et l'**ID de support**, à donner au [support](https://docs.wajub.com/dashboard/help/support) pour qu'il retrouve votre compte. **Paiements en production** indique si l'organisation peut déjà encaisser en Production. La **Devise de règlement**, celle dans laquelle Wajub vous verse votre solde, est fixée à la création du compte et ne change plus. La devise de base se règle à part : voir [Régler la page de paiement](https://docs.wajub.com/dashboard/settings/checkout-page#currencies). Le propriétaire voit en bas de la page une **Zone dangereuse**, pour céder ou fermer l'organisation : voir [Gérer vos organisations](https://docs.wajub.com/dashboard/settings/organizations). --- # Inviter et gérer les membres URL: https://docs.wajub.com/fr/dashboard/settings/members > Inviter une personne dans l'organisation avec un rôle, suivre les invitations en attente, changer le rôle d'un membre, le retirer ou quitter l'organisation. Chaque personne qui travaille dans votre organisation y entre par une invitation, avec un [rôle](https://docs.wajub.com/fr/dashboard#roles) qui fixe ce qu'elle voit et ce qu'elle peut faire. Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les membres** et **Voir les paramètres** gère les membres. Le forfait limite leur nombre, propriétaire non compris : 3 avec **Pay as you go**, 5 avec **Growth**, sans limite avec **Scale** et **Enterprise**. Inviter, changer un rôle, retirer un membre et quitter l'organisation demandent le code de sécurité ; renvoyer ou annuler une invitation, non. ## Les étapes 1. **Ouvrez la liste des membres** Ouvrez **Paramètres › Membres**. Chaque membre y figure avec son e-mail et son rôle ; le propriétaire est marqué **Propriétaire**, et votre ligne **Vous**. ![Paramètres › Membres : huit membres, chacun avec son nom, son e-mail et son rôle, d'Administrateur à Utilisateur de test, et le propriétaire marqué Vous.](https://docs.wajub.com/dashboard/fr/light/members.webp) *Le menu au bout de chaque ligne change le rôle du membre ou le retire.* 2. **Ouvrez l'invitation** **Inviter un membre** ouvre la fenêtre du même nom. 3. **Saisissez l'adresse e-mail** Dans **Adresse e-mail**, saisissez l'adresse de la personne à inviter. Une adresse jetable est refusée : **Les adresses e-mail jetables ne sont pas acceptées sur Wajub. Utilisez une adresse permanente.** 4. **Choisissez son rôle** Sous **Rôle**, choisissez l'un des sept rôles ou un [rôle personnalisé](https://docs.wajub.com/dashboard/settings/roles). Un rôle qui comprend des permissions que vous ne détenez pas est grisé : seule une personne qui les détient peut le donner. ![La fenêtre Inviter un membre : l'Adresse e-mail comptabilite@example.cm, puis la liste des rôles, chacun avec ce qu'il permet, Analyste sélectionné, et le bouton Inviter un membre.](https://docs.wajub.com/dashboard/fr/light/settings-invite-member.webp) *Chaque rôle de la liste dit ce qu'il permet.* 5. **Envoyez l'invitation** **Inviter un membre** demande le code de sécurité, puis envoie l'e-mail. L'invitation apparaît dans la liste des invitations en attente. ## Ce que reçoit la personne invitée La personne reçoit un e-mail avec un lien pour rejoindre l'organisation, valable 7 jours. Pour accepter, elle se connecte à Wajub avec l'adresse invitée, ou crée son compte avec cette adresse si elle n'en a pas. Si l'organisation a atteint entre-temps la limite de son forfait, l'acceptation est refusée : les invitations en attente ne comptent pas dans la limite tant qu'elles ne sont pas acceptées. ## Les invitations en attente **Renvoyer l'invitation** envoie un nouvel e-mail et repart pour 7 jours. **Annuler l'invitation** coupe le lien de l'e-mail et prévient la personne ; **Garder l'invitation** referme la fenêtre sans rien changer. ## Changer un rôle ou retirer un membre Le menu au bout de la ligne d'un membre propose **Changer le rôle**, qui prend effet tout de suite, et **Supprimer le membre** : la personne perd aussitôt l'accès, et vous pourrez l'inviter à nouveau plus tard. Un membre qui détient des permissions que vous n'avez pas ne peut être changé ou retiré que par quelqu'un qui les détient. Le propriétaire ne se retire pas : il [cède l'organisation](https://docs.wajub.com/dashboard/settings/organizations#transfer-ownership) d'abord. Sur votre propre ligne, **Quitter l'organisation** vous en retire aussitôt ; seul un membre qui gère les membres pourra vous inviter à nouveau. > [!NOTE] > **Un membre sans « Gérer les membres » ne peut pas partir seul** > > **Quitter l'organisation** se trouve sur cette page, que seuls ouvrent les membres qui gèrent > les membres. Un Développeur, un membre Finance, un Analyste, un Spécialiste support, un > Observateur ou un Utilisateur de test demande au propriétaire ou à un Administrateur de le > retirer. ## Les e-mails de chaque rôle Wajub envoie les e-mails de chaque sujet aux rôles ci-dessous. Le propriétaire reçoit ce que reçoit un Administrateur. | Sujet | Rôles | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | Paiements, factures, transferts, ajustements de solde, vérification de l'entreprise | **Administrateur**, **Finance** | | Litiges | **Administrateur**, **Spécialiste support** | | Sync, alertes techniques comme un endpoint webhook en échec ou un domaine qui ne pointe plus vers Wajub | **Administrateur**, **Développeur** | | Sécurité, rail Wajub | **Administrateur** | --- # Gérer vos organisations URL: https://docs.wajub.com/fr/dashboard/settings/organizations > Créer une autre organisation, passer de l'une à l'autre, céder une organisation à un autre membre ou la fermer. Une organisation a ses propres paiements, membres et paramètres. Un même compte Wajub peut en créer plusieurs, par exemple une par activité, et être membre d'organisations créées par d'autres. Tout le monde peut créer une organisation et en devient le propriétaire. Céder ou fermer une organisation est réservé à son propriétaire, et demande le code de sécurité. ## Créer une organisation 1. **Ouvrez le sélecteur d'organisation** Cliquez sur le nom de l'organisation, en haut du menu, puis sur **Créer une organisation**. 2. **Nommez l'organisation** Saisissez le **Nom de l'organisation** : vos clients le voient sur les reçus et les pages de paiement, et vous pourrez le changer plus tard. 3. **Créez-la** **Créer une organisation** la crée et vous y fait passer. Elle commence en Test : pour encaisser en Production, [vérifiez son entreprise](https://docs.wajub.com/dashboard/activation/verify-business). La nouvelle organisation prend le pays de votre inscription, qui fixe sa devise de règlement. ## Passer d'une organisation à l'autre Le sélecteur en haut du menu liste **Vos organisations** ; un clic sur l'une d'elles vous y fait passer, et à partir de neuf, **Rechercher une organisation** les filtre. **Gérer les organisations** ouvre **Paramètres › Organisations**, qui liste toutes celles dont vous êtes membre, avec **Actuel** sur celle où vous êtes, **Propriétaire** sur les vôtres, et un bouton **Changer** sur les autres. ![Paramètres › Organisations : Atelier Sanaga SARL avec le rôle Finance, « Appartient à Hervé Ngono » et le bouton Changer, puis Kribi Coffee SARL marquée Actuel et Propriétaire.](https://docs.wajub.com/dashboard/fr/light/settings-organizations.webp) *Une organisation qui n'est pas la vôtre affiche votre rôle et son propriétaire.* Pour quitter une organisation dont vous êtes membre, voir [Inviter et gérer les membres](https://docs.wajub.com/dashboard/settings/members#change-a-role-or-remove-a-member). ## Céder l'organisation 1. **Ouvrez la zone dangereuse** Ouvrez **Paramètres › Général** et descendez jusqu'à la **Zone dangereuse**. ![Paramètres › Général, Zone dangereuse : les actions Transférer la propriété et Fermer l'organisation, chacune avec ce qu'elle entraîne.](https://docs.wajub.com/dashboard/fr/light/settings-danger-zone.webp) *Seul le propriétaire voit la Zone dangereuse.* 2. **Choisissez le nouveau propriétaire** **Transférer la propriété** ouvre une fenêtre : choisissez le membre dans **Nouveau propriétaire**. Seul un membre de l'organisation peut en devenir propriétaire ; s'il n'y a pas d'autre membre, [invitez-le](https://docs.wajub.com/dashboard/settings/members) d'abord. 3. **Envoyez l'invitation** **Envoyer l'invitation de transfert** demande le code de sécurité, puis envoie l'invitation par e-mail. Elle est valable 7 jours ; une nouvelle invitation remplace la précédente. Le membre invité ouvre **Transfert de propriété de l'organisation** et choisit **Accepter le transfert** ou **Refuser**. Jusque-là, vous restez propriétaire. S'il accepte, il devient propriétaire, avec le contrôle des paramètres et de la facturation, et vous devenez Administrateur. ## Fermer l'organisation Dans la **Zone dangereuse**, **Fermer l'organisation** ouvre une fenêtre. Tant que l'organisation a un solde, même en attente ou réservé, un litige ouvert, ou un remboursement ou un transfert en cours, la fenêtre les liste sous **Réglez d'abord ces points, puis fermez l'organisation** et ne permet pas de la fermer. Sinon, saisissez le nom de l'organisation dans **Saisissez le nom de l'organisation pour confirmer**, puis **Fermer l'organisation** demande le code de sécurité. Ses clés API cessent aussitôt de fonctionner, chaque membre perd l'accès et plus aucun paiement ne peut être encaissé. Les données sont conservées, mais seul le [support](https://docs.wajub.com/dashboard/help/support) peut la rouvrir. --- # Créer un rôle personnalisé URL: https://docs.wajub.com/fr/dashboard/settings/roles > Préparer un rôle avec les permissions de votre choix quand aucun des sept rôles ne convient, le donner à un membre, puis le modifier ou le supprimer. Quand aucun des [sept rôles](https://docs.wajub.com/fr/dashboard#roles) ne convient, un rôle personnalisé réunit exactement les permissions que vous choisissez, par exemple pour un comptable qui lit les paiements, les transferts et les rapports sans rien modifier. Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les membres** crée les rôles personnalisés, et ne peut y mettre que des permissions qu'il détient lui-même. Créer ou supprimer un rôle ne demande pas de code de sécurité ; le modifier, si, car le changement s'applique aussitôt aux membres qui l'ont. ## Les étapes 1. **Ouvrez les rôles personnalisés** Ouvrez **Paramètres › Membres › Rôles personnalisés**. Depuis la liste des membres, **Gérer les rôles personnalisés** y mène aussi. 2. **Ouvrez le formulaire** **Créer un rôle personnalisé** ouvre le formulaire sur la page. 3. **Nommez le rôle** Le **Nom du rôle** est obligatoire, jusqu'à 50 caractères, et doit être unique dans l'organisation. La **Description** est facultative, jusqu'à 255 caractères, et s'affiche à côté du rôle. 4. **Cochez ses permissions** Sous **Permissions**, cochez-en au moins une. Elles sont rangées par module, chacun avec **Tout sélectionner** ; une case grisée est une permission que vous ne détenez pas. ![Le formulaire Créer un rôle personnalisé : le Nom du rôle « Comptable », la Description, puis les permissions rangées par module (Tableau de bord, Paiements, Clients, Transferts), chacune avec une case à cocher, Voir les paiements et Voir les clients cochées.](https://docs.wajub.com/dashboard/fr/light/settings-custom-role.webp) *Les permissions sont rangées par module.* 5. **Créez le rôle** **Créer un rôle personnalisé** enregistre le rôle. Il apparaît dans la liste, marqué **Attribué à aucun membre**. 6. **Donnez le rôle à un membre** Dans **Paramètres › Membres**, choisissez-le en invitant quelqu'un ou avec **Changer le rôle** sur la ligne d'un membre : voir [Inviter et gérer les membres](https://docs.wajub.com/dashboard/settings/members). ## Les permissions des paramètres Cinq permissions ouvrent les paramètres de l'organisation. **Voir les paramètres** les ouvre sans rien changer. **Gérer les paramètres** change la sécurité, la page de paiement, l'image de marque, les domaines, les remboursements, les liens de paiement et les factures, les réglages des transferts (comptes de versement, transferts récurrents et sécurité des transferts), et bascule entre Test et Production. **Gérer les paramètres développeur** ne change que les réglages techniques : les domaines personnalisés, les sites qui intègrent la page de paiement et le routage des paiements ; elle bascule aussi entre Test et Production. **Gérer les membres** invite et retire des membres, change leur rôle et crée des rôles personnalisés. **Gérer le compte** s'occupe de la vérification de l'entreprise et de la facturation de l'abonnement. ## Modifier ou supprimer un rôle Le menu au bout d'un rôle propose **Modifier le rôle**, qui rouvre le formulaire : **Enregistrer le rôle** demande le code de sécurité, et un nouveau nom suit le rôle chez ses membres et dans les invitations en attente. **Supprimer le rôle** l'efface définitivement, mais seulement si aucun membre ne l'a et qu'aucune invitation en attente ne le donne : changez d'abord leur rôle ou annulez l'invitation. Un rôle qui accorde des permissions que vous ne détenez pas ne peut être modifié ou supprimé que par quelqu'un qui les détient. --- # Sécuriser l'organisation URL: https://docs.wajub.com/fr/dashboard/settings/security > Exiger la double authentification de tous les membres et limiter l'accès au tableau de bord à certaines adresses IP, dans Paramètres › Sécurité de l'organisation. Deux règles protègent l'organisation entière : chaque membre confirme ses connexions par une deuxième étape, et le tableau de bord ne s'ouvre que depuis les adresses IP que vous autorisez. La double authentification de votre propre compte se règle à part, dans [Sécuriser votre compte](https://docs.wajub.com/dashboard/account/security). Le propriétaire, un Administrateur, un Développeur, un Observateur ou un rôle personnalisé qui a **Voir les paramètres** lit ces règles. Seuls le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les paramètres** les change, et l'enregistrement demande le code de sécurité. Les règles valent en Test comme en Production. ## Exiger la double authentification 1. **Ouvrez la sécurité de l'organisation** Ouvrez **Paramètres**, puis **Sécurité de l'organisation** dans le groupe **Organisation**. ![Paramètres › Sécurité de l'organisation : l'interrupteur Exiger l'authentification à deux facteurs pour tous les membres, puis la Liste blanche IP du tableau de bord avec l'adresse IP actuelle, le bouton Ajouter mon adresse IP et le champ Adresse IP ou plage.](https://docs.wajub.com/dashboard/fr/light/settings-org-security.webp) *Les deux règles s'enregistrent ensemble, avec le code de sécurité.* 2. **Activez la règle** Sous **Politique d'authentification à deux facteurs**, activez **Exiger l'authentification à deux facteurs pour tous les membres**. 3. **Enregistrez** **Enregistrer les modifications**, dans la barre en bas de l'écran, demande le code de sécurité puis applique la règle. La règle s'applique dès l'enregistrement. Un membre qui n'a pas encore de double authentification arrive, à sa prochaine action, sur **Configurer l'authentification à deux facteurs**, et n'ouvre plus rien dans l'organisation tant qu'il n'a pas choisi une méthode : **Application d'authentification**, **Code par e-mail**, **Clé d'accès** ou, s'il a un numéro de téléphone vérifié, **Code par SMS**. Un membre déjà connecté sans avoir passé sa deuxième étape est déconnecté et se reconnecte avec elle. **Faire confiance à cet appareil pour 30 jours**, qu'un membre peut cocher en saisissant son code à la connexion, dispense ce navigateur de la deuxième étape pendant 30 jours. Une organisation qui exige la double authentification ne l'accepte pas : ses membres passent la deuxième étape à chaque connexion. ## Limiter les adresses IP 1. **Ajoutez votre propre adresse** Sous **Liste blanche IP du tableau de bord**, la page affiche votre adresse IP actuelle. **Ajouter mon adresse IP** la met dans la liste. Tant qu'elle n'y est pas, la page vous avertit que vous perdriez l'accès et refuse d'enregistrer. 2. **Ajoutez les autres adresses** Dans **Adresse IP ou plage**, saisissez une adresse IPv4 ou IPv6, ou une plage comme 10.0.0.0/24, puis cliquez sur **Ajouter**. Recommencez pour chaque bureau ou réseau. 3. **Enregistrez la liste** **Enregistrer les modifications** demande le code de sécurité puis applique la liste. Une liste vide, marquée **Aucune restriction d'adresse IP**, laisse ouvrir le tableau de bord de partout. Un membre qui se connecte depuis une autre adresse arrive sur **Accès refusé** : il peut **Passer à une autre organisation**, ouvrir ses **Paramètres personnels** ou **Se déconnecter**, et demande à un Administrateur d'ajouter son adresse. La liste ne concerne que le tableau de bord : elle ne limite pas les appels faits avec vos clés API. Une clé API a sa propre liste d'adresses autorisées, voir [Environnements et API keys](https://docs.wajub.com/fr/getting-started/environments#narrowing-what-a-key-can-do). --- # Activer Shield URL: https://docs.wajub.com/fr/dashboard/shield/enable > Activer Shield pour voir ses décisions sur vos paiements, régler sa sévérité et traiter les paiements qu'il signale. Shield évalue le risque de fraude de chaque paiement en Production. La protection par défaut de Wajub s'applique déjà à vos paiements : activer Shield vous montre ses décisions et vous permet de les ajuster. Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer Shield** peut activer Shield ; avec **Voir Shield** seul, un rôle personnalisé lit ses écrans sans rien changer. Les autres [rôles](https://docs.wajub.com/fr/dashboard#roles) ne voient pas Shield. Shield fait partie de tous les forfaits, et n'existe qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Aucun code de sécurité n'est demandé. ## Les étapes 1. **Ouvrez Shield** En **Production**, ouvrez **Shield** dans le menu. Tant que Shield n'est pas activé, la page présente la **Protection contre la fraude** sous le titre **Arrêtez la fraude avant qu'elle ne vous coûte.**, sans onglets. ![La page Shield avant l'activation : le badge Protection contre la fraude, le titre Arrêtez la fraude avant qu'elle ne vous coûte. et le bouton Activer Shield.](https://docs.wajub.com/dashboard/fr/light/shield-activate.webp) *Sans la permission Gérer Shield, un message remplace le bouton.* 2. **Activez Shield** Cliquez sur **Activer Shield**. Sans la permission, la page affiche à la place **Demandez à un administrateur de votre organisation d'activer Shield.** Le message **Shield est maintenant actif.** s'affiche, et la page devient la vue d'ensemble, avec les onglets **Vue d'ensemble**, **Examens**, **Règles**, **Listes** et **Contrôles de risque**. ## Ce que l'activation change Vos propres réglages s'appliquent à la place de ceux de Wajub : vos seuils, plus stricts que ceux de Wajub, jamais plus souples, et avec **Shield Advanced** vos règles, votre liste de blocage et le 3D Secure automatique. [Régler les contrôles de risque](https://docs.wajub.com/dashboard/shield/settings) les décrit. Un paiement que Shield signale est encaissé comme les autres, puis rejoint les **Examens**, où vous décidez quoi faire du client : [Examiner un paiement signalé](https://docs.wajub.com/dashboard/shield/reviews). Une tentative bloquée y figure aussi, sans rien encaisser. ## La vue d'ensemble En haut, **Analysées ce mois**, **Signalé** et **En attente de révision** comptent le mois en cours, comparé au mois précédent, et **Litiges ouverts** les litiges en cours. **Distribution des risques ce mois** montre la part des paiements signalés envoyés en examen et celle des paiements bloqués. **En attente de votre révision** liste les derniers paiements signalés, et **Tout réviser** ouvre les examens. **Performance des règles** classe vos règles personnalisées par nombre de déclenchements, avec **Gérer les règles**. Les litiges se traitent depuis les paiements : [Gérer un litige](https://docs.wajub.com/dashboard/payments/disputes). ![La vue d'ensemble de Shield : les chiffres Analysées ce mois, Signalé, En attente de révision et Litiges ouverts, puis Distribution des risques ce mois, En attente de votre révision et Performance des règles.](https://docs.wajub.com/dashboard/fr/light/shield-overview.webp) *Les trois premiers chiffres comptent le mois en cours.* ## Couper Shield Dans **Contrôles de risque**, désactivez **Utiliser mes réglages Shield**, puis cliquez sur **Enregistrer les modifications**. La protection par défaut de Wajub continue de s'appliquer, et Shield revient à sa page d'activation. Vos seuils sont gardés pour la prochaine activation. ## Ce que voit le client Un paiement autorisé ou signalé se déroule normalement pour le client, parfois avec une confirmation 3D Secure de sa banque ; un paiement bloqué est refusé, avec une référence à donner au support. --- # Gérer les listes Shield URL: https://docs.wajub.com/fr/dashboard/shield/lists > Ajouter une adresse e-mail, un numéro, une adresse IP, un pays ou un BIN de carte à la liste de blocage de Shield, et retirer un client autorisé. L'onglet **Listes** réunit les clients que vous laissez toujours passer et les valeurs que Shield refuse d'emblée. Les deux s'appliquent tout de suite aux paiements suivants. Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer Shield** modifie les listes ; **Voir Shield** suffit pour les lire. Les **Clients autorisés** existent avec tous les forfaits. La **Liste de blocage** fait partie de **Shield Advanced**, inclus dans les forfaits **Scale** et **Enterprise** et proposé en [option](https://docs.wajub.com/dashboard/subscription/add-ons) sur les autres ; sans lui, l'onglet affiche **Les listes font partie de Shield Advanced**. Shield doit être [activé](https://docs.wajub.com/dashboard/shield/enable). Aucun code de sécurité n'est demandé. ## Les étapes 1. **Ouvrez les listes** Dans **Shield**, ouvrez l'onglet **Listes**. Le formulaire **Ajouter à la liste de blocage** se trouve sous les **Clients autorisés**. 2. **Choisissez le type** Sous **Type**, choisissez **Adresse e-mail**, **Numéro de téléphone**, **Adresse IP**, **Pays** ou **BIN de carte**. Le champ suivant dit ce qu'il attend : l'adresse entière, le numéro avec son indicatif, une seule adresse IP, un pays dont les adresses IP sont refusées, ou les 6 à 8 premiers chiffres d'une carte. 3. **Saisissez la valeur** Remplissez le champ qui porte le nom du type choisi, **Adresse e-mail** par exemple, puis si besoin **Motif (facultatif)**, que seuls vos membres voient. 4. **Ajoutez l'entrée** Cliquez sur **Ajouter à la liste de blocage**. Le message **Entrée ajoutée à la liste de blocage.** s'affiche, et l'entrée apparaît en tête de la **Liste de blocage**. Chaque ajout active aussi **Appliquer la liste de blocage** dans les [contrôles de risque](https://docs.wajub.com/dashboard/shield/settings). ![L'onglet Listes : le formulaire Ajouter à la liste de blocage sur le type Adresse e-mail, puis la Liste de blocage avec cinq entrées, une par type.](https://docs.wajub.com/dashboard/fr/light/shield-lists.webp) *Chaque paiement qui correspond à une entrée est refusé.* ## La liste de blocage Au-delà de 10 entrées, une recherche au-dessus de la liste les filtre par valeur, type ou motif, et le bouton sous la liste charge les suivantes, 50 à la fois. Le menu d'une entrée propose **Copier la valeur** et **Supprimer l'entrée** : après confirmation, elle ne bloque plus rien. Une règle peut aussi s'appuyer sur la liste avec la condition **Correspond à une entrée de la liste de blocage** : [Créer une règle Shield](https://docs.wajub.com/dashboard/shield/rules). ## Les clients autorisés Un client entre dans **Clients autorisés** quand vous choisissez **Toujours autoriser ce client** sur l'un de ses paiements, dans les [examens](https://docs.wajub.com/dashboard/shield/reviews). Ses paiements passent quel que soit leur score, sauf s'il figure sur votre liste de blocage ou sur une liste de sanctions. Le tableau montre le **Client**, **Identifié par** (son e-mail ou son téléphone) et **Autorisé depuis**. Le menu de sa ligne propose **Ne plus autoriser**. Après confirmation, Shield évalue ses paiements suivants comme ceux de tout le monde, et le message **Ce client n'est plus toujours autorisé.** s'affiche. --- # Examiner un paiement signalé URL: https://docs.wajub.com/fr/dashboard/shield/reviews > Vérifier un paiement que Shield juge suspect ou une tentative qu'il a bloquée, puis l'approuver, autoriser le client pour de bon ou le bloquer et rembourser. Un paiement que Shield juge suspect est encaissé comme les autres, puis il rejoint les **Examens** ; une tentative que Shield a bloquée y figure aussi, sans rien encaisser. Shield ne retient jamais l'argent : si c'est une fraude, vérifiez avant de livrer, puis bloquez le client et remboursez-le. Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer Shield** décide ; **Voir Shield** suffit pour lire la liste. Approuver et autoriser un client marchent avec tous les forfaits. Bloquer le client demande **Shield Advanced**, inclus dans les forfaits **Scale** et **Enterprise** et proposé en [option](https://docs.wajub.com/dashboard/subscription/add-ons) sur les autres. Rembourser en même temps demande aussi **Rembourser les paiements** et le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les étapes 1. **Ouvrez les examens** Dans **Shield**, ouvrez l'onglet **Examens**. Le tableau couvre les 90 derniers jours, avec le **Montant**, le **Score**, le **Client**, les **Motifs** du signalement, le **Moyen de paiement** et la date sous **Signalé**. Le filtre **Décision** garde les paiements signalés (**Examiner**) ou les tentatives bloquées (**Bloquer**). ![L'onglet Examens : trois paiements signalés avec leur montant, leur score, le client, les motifs, le moyen de paiement et la date, chacun avec le bouton Approuver.](https://docs.wajub.com/dashboard/fr/light/shield-reviews.webp) *Chaque paiement de la liste a déjà été encaissé, sauf les tentatives bloquées.* 2. **Vérifiez le paiement** Cliquez sur la ligne pour ouvrir la page du paiement : [Lire un paiement](https://docs.wajub.com/dashboard/payments/read). Le menu au bout de la ligne propose aussi **Copier l'identifiant du paiement** et **Voir le client**. 3. **Approuvez un paiement légitime** Cliquez sur **Approuver**. Le paiement quitte la liste sans autre changement, et le message **Revue clôturée.** s'affiche. Pour un client de confiance, choisissez plutôt **Toujours autoriser ce client** dans le menu de la ligne : ses paiements suivants passeront, et il rejoint les [clients autorisés](https://docs.wajub.com/dashboard/shield/lists#allowed-customers). Le menu ne le propose que si le client a un e-mail ou un téléphone. ## Bloquer le client Si c'est une fraude, choisissez **Bloquer le client** dans le menu de la ligne. Une fenêtre s'ouvre au nom du client, par exemple « Bloquer Moussa Diallo ? ». Pour un paiement encaissé, **Bloquer sans rembourser** bloque le client et laisse l'argent, et **Bloquer et rembourser** rend le montant total au client après le code de sécurité. Pour une tentative bloquée, rien n'a été encaissé : le bouton est **Bloquer le client**. ![La fenêtre Bloquer Moussa Diallo ? sur un paiement encaissé, avec les boutons Bloquer sans rembourser et Bloquer et rembourser.](https://docs.wajub.com/dashboard/fr/light/shield-block-dialog.webp) *Bloquer seul ne rend pas l'argent au client.* L'e-mail et le téléphone du client rejoignent la [liste de blocage](https://docs.wajub.com/dashboard/shield/lists), qui s'applique désormais : ses paiements suivants sont refusés. Le remboursement se suit sur la page du paiement : [Rembourser un paiement](https://docs.wajub.com/dashboard/payments/refund). > [!NOTE] > **Avant l'activation de Shield** > > Tant que Shield n'est pas activé, les **Examens** ne listent que les paiements dont le payeur > porte un nom proche d'une personne sous sanctions, et la page **Shield** les signale avec **Les > examiner**. Ces paiements ont été encaissés : vérifiez-les avant de livrer, puis cliquez sur > **Marquer comme vérifié**. --- # Créer une règle Shield URL: https://docs.wajub.com/fr/dashboard/shield/rules > Créer une règle Shield qui bloque, envoie en examen, exige le 3D Secure ou autorise un paiement selon vos conditions, puis la classer, la couper ou la supprimer. Une règle personnalisée décide d'un paiement selon vos propres conditions : son montant, sa devise, son moyen de paiement, l'e-mail ou le téléphone du client, le pays de son adresse IP. Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer Shield** crée et modifie les règles ; **Voir Shield** suffit pour les lire. Les règles personnalisées font partie de **Shield Advanced**, inclus dans les forfaits **Scale** et **Enterprise** et proposé en [option](https://docs.wajub.com/dashboard/subscription/add-ons) sur les autres. Sans lui, l'onglet affiche **Les règles personnalisées font partie de Shield Advanced**. Shield doit être [activé](https://docs.wajub.com/dashboard/shield/enable). Aucun code de sécurité n'est demandé. ## Les étapes 1. **Ouvrez le dialogue** Dans **Shield**, ouvrez l'onglet **Règles**, puis cliquez sur **Créer la règle**. Le dialogue **Créer la règle** s'ouvre. 2. **Nommez la règle** Le **Nom** est obligatoire, en 120 caractères au plus. La **Description (optionnelle)** dit à vos membres à quoi sert la règle. 3. **Choisissez l'action** Sous **Action**, **Bloquer** refuse le paiement. **Envoyer pour examen** le laisse passer et l'ajoute aux **Examens**, sauf si Shield le bloque déjà. **Exiger le 3D Secure** fait confirmer un paiement par carte auprès de la banque du client, là où le prestataire de la carte le permet. **Autoriser (contourne les autres règles)** laisse passer le paiement, sauf s'il correspond à votre liste de blocage ou exactement à un nom sous sanctions. 4. **Choisissez le mode** Sous **Mode**, **Appliquée** agit sur les paiements. **Observation** compte les paiements qui correspondent sans rien décider : la règle porte le badge **Observation**, et ses déclenchements s'affichent comme les autres, de quoi la juger avant de l'appliquer. 5. **Ajoutez les conditions** Sous **Quand toutes ces conditions sont vraies**, choisissez un **Champ**, un **Opérateur** et une **Valeur**. **Ajouter une condition** en ajoute une autre, jusqu'à 10 : la règle ne s'applique que si toutes sont vraies. Les champs sont **Montant de la transaction**, **Devise**, **Moyen de paiement**, **E-mail du client**, **Téléphone du client**, **Pays de l'IP**, **Première transaction de ce client** et **Correspond à une entrée de la liste de blocage**. ![Le dialogue Créer la règle : le nom Grosses commandes depuis l'étranger, l'action Envoyer pour examen, le mode Observation et deux conditions sur le montant de la transaction et le pays de l'IP.](https://docs.wajub.com/dashboard/fr/light/shield-rule-dialog.webp) *La règle ne s'applique que si toutes ses conditions sont vraies.* 6. **Créez la règle** Laissez **Actif** activé pour qu'elle s'applique tout de suite, puis cliquez sur **Créer la règle**. Le message **Règle créée.** s'affiche, et la règle s'ajoute en bas de **Vos règles personnalisées**. ## L'ordre des règles Shield lit vos règles de haut en bas, et la première règle appliquée qui correspond au paiement décide ; une règle en **Observation** ne décide jamais. Les flèches de chaque ligne la montent ou la descendent d'une place. Un client autorisé depuis les examens devient une règle **Autoriser** placée en tête de liste. [Les règles](https://docs.wajub.com/fr/risk/shield/rules#which-one-wins) de la documentation développeur détaillent ce qui l'emporte. ## Modifier, couper ou supprimer une règle L'interrupteur de chaque ligne coupe la règle ou la rallume : une règle inactive est gardée, et jamais évaluée. Le menu de la ligne propose **Modifier la règle**, qui rouvre le dialogue, et **Supprimer la règle**, qui demande confirmation : les paiements qu'elle aurait visés passent alors sans changement. Si votre forfait perd **Shield Advanced**, vos règles sont gardées mais ne s'appliquent plus ; elles reprennent si vous retrouvez l'option. Les clients autorisés depuis les examens restent autorisés avec tous les forfaits. ## Les protections intégrées Sous vos règles, **Protections intégrées** résume les contrôles que Shield applique à chaque paiement, sans configuration. **Shield Advanced** en ajoute d'autres. --- # Régler les contrôles de risque URL: https://docs.wajub.com/fr/dashboard/shield/settings > Régler les seuils d'examen et de blocage de Shield, le 3D Secure automatique, la liste de blocage et ce qui arrive à un payeur proche d'un nom sous sanctions. **Contrôles de risque** règle la sévérité de Shield : à partir de quel score un paiement est envoyé en examen ou refusé, et ce que Shield fait de plus. Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer Shield** voit cet onglet ; **Voir Shield** ne suffit pas. Les seuils et le criblage sanctions marchent avec tous les forfaits. Le 3D Secure automatique et la liste de blocage font partie de **Shield Advanced**, inclus dans les forfaits **Scale** et **Enterprise** et proposé en [option](https://docs.wajub.com/dashboard/subscription/add-ons) sur les autres. Aucun code de sécurité n'est demandé. ## Les étapes 1. **Ouvrez les contrôles de risque** Dans **Shield**, ouvrez l'onglet **Contrôles de risque**. La page réunit les sections **Scoring** et **Criblage sanctions**, et avec **Shield Advanced** les sections **3D Secure** et **Liste de blocage**. 2. **Appliquez vos réglages** Sous **Scoring**, activez **Utiliser mes réglages Shield** : vos seuils, et avec **Shield Advanced** votre liste de blocage et vos règles, s'appliquent à chaque paiement en Production. Désactivé, la protection par défaut de Wajub s'applique seule, et Shield revient à sa page d'activation. 3. **Réglez les seuils** Un paiement dont le score atteint le **Seuil d'examen** passe, puis apparaît dans vos [examens](https://docs.wajub.com/dashboard/shield/reviews). À partir du **Seuil de blocage**, il est refusé. Un seuil plus bas est plus strict, et vous pouvez être plus strict que Wajub, jamais plus souple : la page indique les limites autorisées. ![Contrôles de risque, section Scoring : l'interrupteur Utiliser mes réglages Shield activé, la bande de score et les champs Seuil d'examen et Seuil de blocage.](https://docs.wajub.com/dashboard/fr/light/shield-settings.webp) *La bande de score montre ce qui s'applique en ce moment.* 4. **Choisissez le 3D Secure automatique** Avec **Shield Advanced**, **Auto 3D Secure** demande le 3D Secure aux paiements par carte dont le score atteint votre seuil d'examen, là où le prestataire de la carte le permet. Sans **Shield Advanced**, une carte **Auto 3D Secure** propose à la place **Mettre à niveau pour activer**. 5. **Appliquez la liste de blocage** Avec **Shield Advanced**, **Appliquer la liste de blocage** refuse les paiements qui correspondent à l'une de vos entrées. Il s'active tout seul dès qu'une entrée est ajoutée, et **Gérer la liste de blocage** ouvre l'onglet **Listes** : [Gérer les listes Shield](https://docs.wajub.com/dashboard/shield/lists). 6. **Choisissez la réponse aux sanctions** Wajub compare chaque payeur aux listes de sanctions, avec tous les forfaits, et refuse toujours une correspondance exacte. Sous **Un payeur proche d'un nom sous sanctions**, **Signaler en revue** laisse passer le paiement et l'ajoute à vos examens, et **Refuser le paiement** le refuse comme une correspondance exacte. 7. **Enregistrez** Dès la première modification, la barre du bas propose **Enregistrer les modifications** et **Abandonner**. Le message **Paramètres Shield mis à jour.** confirme l'enregistrement. --- # Activer un module URL: https://docs.wajub.com/fr/dashboard/subscription/add-ons > Ajouter à votre forfait un module complémentaire, comme Sync ou Shield Advanced, sans changer de forfait, puis le renouveler ou l'annuler. Un module complémentaire ajoute un module que votre forfait n'inclut pas, comme Sync ou Shield Advanced, sans changer de forfait. Son prix est mensuel, et il se renouvelle à la même date que le forfait. Le propriétaire, un Administrateur ou un [rôle](https://docs.wajub.com/fr/dashboard#roles) personnalisé qui a **Gérer le compte** active les modules. Un module activé vaut pour toute l'organisation, [en Test et en Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), et aucun [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est demandé. ## Les étapes 1. **Ouvrez la facturation** Ouvrez **Paramètres**, puis **Facturation** dans le groupe **Organisation**. Sur l'onglet **Abonnement**, la carte **Modules complémentaires** liste chaque module avec son prix par mois ; elle n'apparaît pas quand votre forfait les inclut tous. 2. **Choisissez le module** **Activer**, sur la ligne du module, ouvre la fenêtre d'activation. Elle indique le montant **Débité aujourd'hui**, calculé au prorata jusqu'au renouvellement de votre forfait, puis le **Prix mensuel**. Un module gratuit s'active tout de suite, sans fenêtre. ![La fenêtre d'activation du module Sync : le montant Débité aujourd'hui au prorata jusqu'au renouvellement du forfait, le Prix mensuel, puis le moyen de paiement de l'abonnement, Mobile Money, avec le lien Payer avec un autre moyen, et le bouton Payer avec le montant.](https://docs.wajub.com/dashboard/fr/light/subscription-addon-dialog.webp) *Le premier paiement couvre seulement les jours restants jusqu'au renouvellement du forfait.* 3. **Choisissez le moyen de paiement** Choisissez **Carte**, **Mobile Money**, **Crypto** ou **Virement bancaire**. Si votre abonnement a déjà un moyen de paiement, la fenêtre propose celui-là ; **Payer avec un autre moyen** affiche les autres. 4. **Payez le module** Le bouton **Payer**, suivi du montant, ouvre une page de paiement sécurisée pour une carte, Mobile Money ou Crypto ; le module s'active dès que le paiement est confirmé. Pour un virement, les instructions arrivent par e-mail, et le module s'active quand Wajub confirme le virement. Quand vous ouvrez un module que votre forfait n'inclut pas, sa page propose aussi **Activer le module complémentaire**, à côté des forfaits qui l'incluent : voir [Modules hors de votre forfait](https://docs.wajub.com/fr/dashboard#modules-outside-your-plan). ## Le renouvellement Chaque module se renouvelle à la date de votre forfait, et sa ligne dit comment. Soit il est facturé avec le forfait, soit il se paie à part, depuis l'onglet **Factures** avec **Payer maintenant**, avant cette date : voir [Payer une facture Wajub](https://docs.wajub.com/dashboard/subscription/wajub-invoices). Sans paiement, il s'arrête ce jour-là, et **Activer** le remet en route. ## Annuler un module **Annuler le module complémentaire**, sur sa ligne, ouvre une confirmation qui donne sa date de fin. Le même bouton confirme ; **Conserver le module complémentaire** referme sans rien changer. Le module reste actif jusqu'à cette date, puis se désactive. D'ici là, **Reprendre** le garde. --- # Demander l'offre Enterprise URL: https://docs.wajub.com/fr/dashboard/subscription/enterprise > Demander l'offre Enterprise à l'équipe commerciale de Wajub depuis la facturation, suivre la demande, puis payer la proforma par virement. L'offre **Enterprise** a des tarifs négociés, tout en illimité, un support dédié et un SLA. Vous la demandez à l'équipe commerciale de Wajub depuis la facturation, et vous la payez par virement. Le propriétaire, un Administrateur ou un [rôle](https://docs.wajub.com/fr/dashboard#roles) personnalisé qui a **Gérer le compte** envoie la demande, [en Test comme en Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), sans [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). L'organisation a une seule demande en cours : une nouvelle n'est possible qu'après un refus. ## Les étapes 1. **Ouvrez la demande** Ouvrez **Paramètres**, puis **Facturation** dans le groupe **Organisation**. Sur l'onglet **Abonnement**, **Contacter le service commercial**, dans l'encadré **Entreprise**, ouvre la fenêtre du même nom. Le même bouton figure dans la fenêtre **Changer de forfait**. 2. **Décrivez votre besoin** Le **Nom de l'entreprise** est obligatoire. Le **Volume mensuel de transactions**, le **Téléphone de contact** et les **Besoins** aident l'équipe à préparer son devis. ![La fenêtre Contacter le service commercial, remplie : Nom de l'entreprise, Volume mensuel de transactions en FCFA, Téléphone de contact en +237 et Besoins, puis les boutons Annuler et Envoyer la demande.](https://docs.wajub.com/dashboard/fr/light/subscription-enterprise-inquiry.webp) *Seul le nom de l'entreprise est obligatoire.* 3. **Envoyez la demande** **Envoyer la demande** la transmet à l'équipe commerciale. L'encadré **Entreprise** affiche ensuite son statut et **Voir la demande**. ## Suivre la demande **Voir la demande** ouvre **Demande Enterprise** : le **Statut de la demande**, vos besoins et les **Notes de notre équipe**. L'équipe commerciale répond sous 1 à 2 jours ouvrés, avec un devis ou des questions. Une demande refusée affiche **Demande refusée**. ## Payer la proforma Quand l'équipe envoie son devis, la page affiche la **Référence proforma**, le **Montant dû** et les **Instructions de paiement**. 1. **Téléchargez la proforma** **Télécharger la proforma** enregistre la facture proforma, avec le compte bancaire à créditer. 2. **Faites le virement** Virez le **Montant dû** sur ce compte, avec la **Référence proforma** dans le libellé du virement. 3. **Téléversez le justificatif** Choisissez votre justificatif sous **Téléverser un justificatif de paiement**, puis **Téléverser**. L'équipe l'examine. **Paiement confirmé** s'affiche quand l'équipe a reçu le virement : l'activation prend en général moins d'un jour ouvré. La page affiche ensuite **Forfait Enterprise actif**. Les renouvellements se paient aussi par virement, depuis la facturation : voir [Payer par virement](https://docs.wajub.com/dashboard/subscription/manage#bank-transfer). --- # Gérer l'abonnement URL: https://docs.wajub.com/fr/dashboard/subscription/manage > Annuler ou reprendre l'abonnement Wajub de l'organisation, comprendre son renouvellement et payer un forfait réglé par virement. L'onglet **Abonnement** de la facturation montre votre forfait et sa période. Vous y annulez l'abonnement, le reprenez avant sa fin, et payez un forfait réglé par virement. Le propriétaire, un Administrateur ou un [rôle](https://docs.wajub.com/fr/dashboard#roles) personnalisé qui a **Gérer le compte** gère l'abonnement, [en Test comme en Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), sans [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Annuler l'abonnement 1. **Ouvrez la facturation** Ouvrez **Paramètres**, puis **Facturation** dans le groupe **Organisation**. Sur l'onglet **Abonnement**, **Annuler l'abonnement** se trouve dans la carte **Forfait actuel**, pour un forfait payant. 2. **Lancez l'annulation** **Annuler l'abonnement** ouvre **Annuler votre abonnement ?**, avec la date jusqu'à laquelle votre forfait reste actif. ![La fenêtre Annuler votre abonnement ? : le forfait reste actif jusqu'à sa date de fin, puis passe au forfait gratuit, avec les boutons Conserver l'abonnement et Annuler l'abonnement.](https://docs.wajub.com/dashboard/fr/light/subscription-cancel-dialog.webp) *Rien ne change avant la date de fin.* 3. **Confirmez l'annulation** **Annuler l'abonnement** confirme ; **Conserver l'abonnement** referme sans rien changer. La carte **Forfait actuel** affiche alors la date de fin. Votre forfait et ses modules restent actifs jusqu'à cette date, puis l'organisation passe au forfait **Pay as you go**. ## Reprendre l'abonnement Jusqu'à la date de fin, **Reprendre l'abonnement**, dans **Forfait actuel**, annule l'annulation : le forfait continue comme avant. ## Le renouvellement Payé par carte, le forfait se renouvelle tout seul à la fin de chaque période. Payé par Mobile Money ou Crypto, il ne se renouvelle pas tout seul : un rappel avec un lien de paiement arrive par e-mail avant la date de fin. À la date de fin, si le renouvellement n'est pas payé, les modules du forfait s'arrêtent et l'organisation passe au forfait **Pay as you go**. Pendant quelques jours encore, pour un forfait payé par Mobile Money ou Crypto, **Payer maintenant**, dans l'onglet **Factures**, règle le renouvellement et remet les modules en route : voir [Payer une facture Wajub](https://docs.wajub.com/dashboard/subscription/wajub-invoices). Passé ce délai, il faut choisir de nouveau un forfait. ## Payer par virement Un forfait réglé par virement, comme l'offre [Enterprise](https://docs.wajub.com/dashboard/subscription/enterprise), affiche la carte **Virement bancaire** quand un paiement est dû. Elle donne le **Montant dû** et la **Référence** à indiquer sur votre virement. Une fois le virement fait, choisissez votre justificatif sous **Téléverser un justificatif de paiement** (PDF, PNG ou JPG, 5 Mo au plus), ajoutez si vous voulez la **Référence du virement chez votre banque**, puis **Téléverser**. **Justificatif reçu** s'affiche alors : l'équipe Wajub le vérifie sous 1 jour ouvré, et votre forfait démarre ou se renouvelle dès que le virement est confirmé. **Envoyer un autre justificatif** en ajoute un. --- # Changer de forfait URL: https://docs.wajub.com/fr/dashboard/subscription/plans > Passer à un autre forfait Wajub depuis Paramètres › Facturation, choisir la période de facturation et le moyen de paiement, puis payer. Le forfait fixe les modules et les limites de votre organisation, comme le nombre de membres ou de liens de paiement. Vous en changez depuis la facturation, et le nouveau forfait vaut pour toute l'organisation. Le propriétaire, un Administrateur ou un [rôle](https://docs.wajub.com/fr/dashboard#roles) personnalisé qui a **Gérer le compte** gère l'abonnement ; les autres rôles n'ouvrent pas **Facturation**. Le forfait est le même [en Test et en Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), et aucun [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est demandé. ## Les étapes 1. **Ouvrez la facturation** Ouvrez **Paramètres**, puis **Facturation** dans le groupe **Organisation**. L'onglet **Abonnement** montre votre **Forfait actuel**, le tableau **Comparer les forfaits**, l'**Utilisation** de la période et l'**Historique des abonnements**. Le menu de votre organisation, en haut du menu latéral, y mène aussi : sa dernière ligne donne votre forfait. **Comparer les forfaits** met les forfaits côte à côte : les frais par paiement sur le rail Wajub, les limites (liens de paiement, factures, exports, membres, fournisseurs) et les modules inclus. Sous un forfait, **Choisir** ouvre la fenêtre sur ce forfait. ![Paramètres › Facturation, onglet Abonnement : la carte Forfait actuel avec le forfait Scale marqué Actif, son prix mensuel, la période en cours et ses jours restants, les boutons Changer de forfait et Annuler l'abonnement, puis la carte Utilisation avec les limites du forfait, dont les membres, les liens de paiement et les fournisseurs de paiement en Illimité, et les transactions et le volume BYOP du mois.](https://docs.wajub.com/dashboard/fr/light/subscription-billing.webp) *Changer de forfait se trouve dans la carte Forfait actuel.* 2. **Choisissez le forfait** **Changer de forfait** ouvre la fenêtre du même nom. Sous **Choisissez votre forfait**, chaque forfait donne son prix, ses frais par paiement, ses limites et ce qu'il ajoute au vôtre. Sélectionnez le forfait voulu : le vôtre est marqué **Actuel** et ne peut pas être choisi. Puis **Choisir la période de facturation**. ![La fenêtre Changer de forfait, à l'étape Forfait : le forfait gratuit, les forfaits payants avec leur prix par mois, le forfait actuel marqué Actuel et grisé, l'encadré Entreprise avec le bouton Contacter le service commercial, puis les boutons Annuler et Choisir la période de facturation.](https://docs.wajub.com/dashboard/fr/light/subscription-plan-dialog.webp) *Les quatre étapes de la fenêtre sont en haut : Forfait, Période de facturation, Moyen de paiement, Examiner.* Pour l'offre **Enterprise**, **Contacter le service commercial** ouvre une demande : voir [Demander l'offre Enterprise](https://docs.wajub.com/dashboard/subscription/enterprise). 3. **Choisissez la période** Sous **Période de facturation**, choisissez **Mensuel**, **3 mois**, **6 mois** ou **Annuel**. Une période plus longue affiche ce que vous économisez et le prix sans remise. Puis **Choisir le moyen de paiement**. 4. **Choisissez le moyen de paiement** Avec une **Carte**, le forfait se renouvelle tout seul à la fin de chaque période. Avec **Mobile Money** ou **Crypto**, vous recevez avant la fin de la période un rappel avec un lien de paiement. Le virement bancaire est réservé à l'offre Enterprise. Puis **Vérifier le changement**. 5. **Vérifiez et payez** **Examiner** reprend le forfait, la période, la **Remise**, le moyen de paiement et le **Renouvellement**. En dessous, le **Prix du forfait**, la remise et, si votre forfait payant actuel court encore, les **Jours non utilisés de votre forfait actuel** donnent le montant **À payer aujourd'hui**. Si le moyen de paiement choisi ne peut pas déduire ces jours, un avertissement le signale. **Payer**, suivi du montant, ouvre une page de paiement sécurisée. Quand rien n'est dû, le bouton devient **Changer de forfait** et le forfait change tout de suite. ## Essayer un forfait Une organisation qui n'a jamais payé de forfait peut en essayer un. Dans **Comparer les forfaits**, **Essayer 7 jours pour 1 000 FCFA** ouvre une fenêtre qui dit tout avant le paiement : - vous payez 1 000 FCFA sur la page de paiement Wajub, et le forfait s'ouvre pour 7 jours dès que le paiement est confirmé ; - pour le garder ensuite, vous payez son prix par mois ; un rappel avec un lien de paiement vous arrive avant la fin de l'essai ; - sans paiement, votre organisation revient au forfait gratuit, et rien d'autre n'est prélevé. Il y a un seul essai par organisation. Pendant l'essai, **Forfait actuel** porte la mention **Essai** et sa date de fin. Si vous changez de forfait pendant l'essai, les jours qui en restent sont déduits du prix du nouveau forfait pour ce qu'ils vous ont coûté, pas pour le prix du forfait. ## L'assistant selon le forfait Chaque forfait inclut l'assistant IA ; ce qui change est le nombre de questions que votre organisation peut poser par mois : | Forfait | Questions par mois | | ------------- | ------------------ | | Pay as you go | 30 | | Growth | 300 | | Scale | 2 000 | Sur le forfait gratuit, l'assistant s'ouvre quand votre organisation passe en production. Avant, le bouton **Assistant** de la barre du haut et les boutons qui l'interrogent sur un élément (**Analyser le paiement**, **Résumer la période**…) s'affichent avec un petit cadenas : un clic dit que l'assistant s'ouvre avec la production, et nomme le forfait qui l'inclut dès aujourd'hui. L'assistant du forfait gratuit répond dans son panneau ; ses e-mails (les alertes et le résumé du lundi) viennent avec un forfait payant. Le panneau affiche les questions qui restent ce mois-ci. Une fois épuisées, il le dit et nomme le forfait qui en inclut davantage ; le compte repart le 1er. Un membre qui ne peut pas changer de forfait est invité à demander au propriétaire. ## Quand un forfait se rembourse Les frais du rail Wajub baissent avec le forfait. Quand les frais qu'un forfait vous aurait fait économiser sur les 30 derniers jours dépassent son prix, **Facturation** et **Revenus** affichent **Le forfait … se rembourserait**, avec vos frais payés, l'économie estimée et le prix du forfait. C'est une estimation faite sur ce que vous avez encaissé par le rail Wajub : elle suit votre volume. Rien ne s'affiche tant qu'aucun forfait ne vous ferait gagner d'argent. ## Avant d'atteindre une limite À partir de 80 % d'une limite de votre forfait, la page concernée le dit : **Liens de paiement**, **Factures**, **Membres**, **Fournisseurs** et la fenêtre d'export affichent par exemple « 21 liens de paiement utilisés sur 25 », avec **Voir les forfaits**. ## Après le paiement Le nouveau forfait remplace l'ancien dès que le paiement est confirmé, et **Forfait actuel** l'affiche. Si vous quittez la page de paiement sans payer, l'onglet **Abonnement** affiche **Paiement en attente** avec le forfait demandé, et **Finaliser le paiement** rouvre la page de paiement. > [!NOTE] > **Revenir au forfait gratuit** > > Choisir **Pay as you go** dans cette fenêtre change le forfait tout de suite, avec > **Changer de forfait** comme dernier bouton, et les jours déjà payés de votre forfait actuel > sont perdus. Pour le garder jusqu'à sa date de fin, [annulez > l'abonnement](https://docs.wajub.com/dashboard/subscription/manage#cancel) à la place. --- # Payer une facture Wajub URL: https://docs.wajub.com/fr/dashboard/subscription/wajub-invoices > Payer ce que l'organisation doit à Wajub pour son forfait, ses modules et son usage, télécharger les factures et régler les détails qui y figurent. L'onglet **Factures** de la facturation regroupe ce que votre organisation doit à Wajub : forfait, modules complémentaires et dépassements d'usage. Vous y payez le montant dû et téléchargez vos factures. Le propriétaire, un Administrateur ou un [rôle](https://docs.wajub.com/fr/dashboard#roles) personnalisé qui a **Gérer le compte** paie les factures, [en Test comme en Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), sans [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les étapes 1. **Ouvrez les factures** Ouvrez **Paramètres**, puis **Facturation** dans le groupe **Organisation**, et l'onglet **Factures**. La carte **Montant dû** donne le total, son détail et son échéance : **En retard**, une échéance dans les 7 jours, la date du renouvellement ou **À venir**. ![Paramètres › Facturation, onglet Factures : la carte Montant dû avec le total, son échéance, le bouton Payer maintenant et le détail, soit le forfait, le module et l'usage BYOP, puis l'Historique des factures avec la description, le numéro, la date, le moyen de paiement, le montant et le statut de chaque facture, Payée ou Échoué.](https://docs.wajub.com/dashboard/fr/light/subscription-invoices.webp) *Payer maintenant n'apparaît que lorsqu'un montant est dû.* 2. **Lancez le paiement** **Payer maintenant** ouvre **Payer la facture**, avec le montant à payer. 3. **Choisissez le moyen de paiement** Le moyen de paiement de votre abonnement est déjà choisi ; vous pouvez en prendre un autre. 4. **Payez la facture** Par carte, Mobile Money ou Crypto, le bouton **Payer**, suivi du montant, ouvre une page de paiement sécurisée. Si le montant dû a changé entre-temps, rien n'est prélevé : la fenêtre affiche le nouveau montant, à payer à son tour. Si la facture a été payée ou remplacée entre-temps, la fenêtre indique **Plus rien n'est dû** et rien n'est prélevé. ## Télécharger une facture **Historique des factures** liste chaque facture avec sa date et son **Statut**, et le filtre **Statut** en garde une partie. Le bouton de téléchargement, sur la ligne, télécharge la facture. Une ligne dépliée montre ses **Tentatives de paiement**. Plus bas, **Tentatives de paiement échouées** liste les paiements qui n'ont pas abouti, avec leur raison. ## Les détails de facturation L'onglet **Paramètres de facturation** règle ce qui figure sur vos factures : l'**E-mail de facturation**, qui reçoit les factures et les avis de facturation, le **N° d'identification fiscale / TVA** et le **N° de bon de commande / référence**. **Enregistrer les modifications** les applique. **Prélèvement automatique des dépassements d'usage** débite chaque mois votre carte pour les dépassements d'usage BYOP, sans attendre que vous les payiez. Il ne s'active que pour un abonnement payé par carte. --- # Suivre l'activité Sync URL: https://docs.wajub.com/fr/dashboard/sync/activity > Lire le volume, les paiements et les commissions de vos marchands connectés, ensemble ou compte par compte. Les onglets de **Sync** suivent ce que vos marchands connectés encaissent par votre plateforme et ce que vous y gagnez. Le propriétaire, un Administrateur, un membre Finance, un Analyste, un Observateur, ou un rôle personnalisé qui a **Voir les transferts** ou **Gérer les transferts**, voit cette activité. Le forfait est celui de [Connecter un marchand](https://docs.wajub.com/dashboard/sync/connect-merchant) : **Scale**, **Enterprise** ou l'option **Sync**. Chaque environnement montre ses propres connexions et ses propres paiements : [Test et Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). ## Vue d'ensemble Sync s'ouvre sur **Vue d'ensemble**. **Comptes connectés** compte toutes vos connexions, dont vos marchands actifs et vos invitations en attente. Pour la **Période** choisie, **Volume**, **Paiements** et **Commissions** sont comparés à la période précédente, et le graphique **Volume et commissions** les suit par jour ou par mois. ![La vue d'ensemble Sync : le sélecteur de période, les chiffres Comptes connectés, Volume, Paiements et Commissions, puis le graphique Volume et commissions.](https://docs.wajub.com/dashboard/fr/light/sync-overview.webp) *Le volume, les paiements et les commissions sont comparés à la période précédente.* En dessous, **Derniers paiements** liste les paiements récents, **Top comptes** classe vos marchands par volume, **Canaux de paiement** répartit les paiements par moyen de paiement, et **Depuis le début** donne le volume, les paiements et les commissions cumulés. ## Les paiements L'onglet **Paiements** liste les paiements encaissés par tous vos comptes connectés. La recherche prend l'identifiant du paiement, sa référence, sa description, ou le nom ou l'e-mail du client ; **Compte** limite la liste à un marchand, et **Date de paiement** à une période. Un paiement ouvert affiche **Votre commission** sur ce paiement. ## Les revenus L'onglet **Revenus** affiche **Revenus de commission** pour la **Période** choisie : **Commissions sur la période**, comparées à la période précédente, **Commissions depuis le début** et **Marchands connectés**, puis un graphique des commissions dans le temps. **Revenus par marchand** classe vos marchands du plus gros montant au plus petit, avec une ligne par devise quand un marchand est payé en plusieurs devises. Si vous gagnez dans plusieurs devises, **Commissions par devise** les montre côte à côte, sans jamais les additionner. ## Les frais collectés Dans le menu **Paiements**, l'onglet **Frais collectés** liste votre commission sur chaque paiement encaissé pour un marchand connecté, avec le **Total collecté** en tête. La recherche prend l'identifiant, la référence ou la description du paiement, et les filtres la date et le montant des frais ; chaque frais mène au paiement d'où il vient. L'onglet demande aussi le forfait **Growth** ou un forfait au-dessus : avec l'option **Sync** sur **Pay as you go**, il n'apparaît pas. Un rôle personnalisé a besoin en plus de **Voir les paiements**. ## Le détail d'un compte La page d'un marchand, ouverte depuis **Sync › Comptes**, a ses propres onglets. [Gérer un compte connecté](https://docs.wajub.com/dashboard/sync/connected-account#open-an-account) décrit sa vue d'ensemble. Les autres onglets suivent les permissions que le marchand a accordées : | Onglet | Apparaît avec la permission | | ---------------------------- | ------------------------------------- | | **Paiements** et **Litiges** | **Paiements** ou **Accès en lecture** | | **Transferts** | **Transferts** | | **Remboursements** | **Remboursements** | | **Clients** | **Clients** | Ces onglets n'apparaissent qu'une fois le marchand connecté. **Chronologie**, toujours présent, affiche l'**Historique** : ce qui s'est passé sur la connexion, du plus récent au plus ancien. --- # Connecter un marchand URL: https://docs.wajub.com/fr/dashboard/sync/connect-merchant > Inviter un marchand à connecter son compte Wajub à votre plateforme, avec votre commission et les permissions demandées, puis lui partager le lien d'invitation. Sync sert aux plateformes qui encaissent pour les marchands qui vendent chez elles : vous prenez une commission sur chacun de leurs paiements. Vous préparez une connexion avec vos conditions, et le marchand l'accepte depuis un lien d'invitation. Le propriétaire, un Administrateur, un membre Finance ou un rôle personnalisé qui a **Gérer les transferts** peut connecter un marchand ; un Analyste, un Observateur ou un rôle personnalisé qui a **Voir les transferts** suit les comptes connectés sans pouvoir en créer. Sync demande le forfait **Scale** ou **Enterprise**, ou l'option **Sync**, qui s'ajoute à n'importe quel forfait : [Ajouter une option](https://docs.wajub.com/dashboard/subscription/add-ons). Sync marche en Test comme en Production, avec des connexions séparées dans chaque environnement. Aucun code de sécurité n'est demandé pour créer une connexion. ## Les étapes 1. **Ouvrez le formulaire** Ouvrez **Sync**, puis l'onglet **Créer**. La page **Connecter un marchand** passe par trois étapes : **Compte**, **Conditions** et **Examiner**. 2. **Choisissez le type de compte** Sous **Type de compte**, **Direct** convient à un marchand qui a un compte Wajub complet et le gère lui-même. **Lite** lui donne un espace simplifié, et il encaisse toujours via Wajub. Ce choix ne change plus ensuite : il fait partie de ce que le marchand accepte. ![Connecter un marchand, étape Compte : les types de compte Direct (sélectionné) et Lite, l'encadré Relay marqué Pas encore disponible, puis le champ E-mail du marchand.](https://docs.wajub.com/dashboard/fr/light/sync-create.webp) *Relay n'est pas encore disponible : pour payer quelqu'un sans compte Wajub, passez par un compte de versement.* **Relay** est marqué **Pas encore disponible**. Pour payer un bénéficiaire qui n'a pas de compte Wajub, [ajoutez un compte de versement](https://docs.wajub.com/dashboard/transfers/payout-accounts). 3. **Donnez l'e-mail du marchand** **E-mail du marchand** est facultatif : c'est l'adresse où vous pourrez envoyer l'invitation, et où partent des rappels avant son expiration. Sans adresse, vous partagez le lien vous-même. **Continuer** passe aux conditions. 4. **Fixez votre commission** Dans **Tarification**, la commission part de vos réglages par défaut, que vous changez ici pour ce marchand : un **Pourcentage** de chaque paiement, de 0 à 100, et des **Frais fixes** ajoutés au pourcentage, dans la **Devise des montants**. **Frais minimum** et **Frais maximum** sont facultatifs. Sans pourcentage ni frais fixes, le formulaire prévient que vous ne prendrez rien sur les paiements de ce marchand. 5. **Choisissez les permissions** **Permissions** dit ce que votre plateforme pourra faire sur le compte du marchand : **Accès en lecture**, **Paiements**, toujours demandé, **Transferts**, **Remboursements**, **Litiges**, **Clients** et **Factures**. Le marchand voit cette liste avant d'accepter et peut retirer votre accès à tout moment. **Continuer** ouvre l'examen. 6. **Créez la connexion** **Examiner** résume le compte et les conditions ; **Modifier** ramène à l'étape d'une section. **Créer une connexion** crée la connexion et ouvre sa page sur **En attente de la connexion du marchand**, avec le lien d'invitation. ## Partager le lien d'invitation La section **Lien d'invitation** donne le lien à copier, le bouton **Partager sur WhatsApp** et un code QR, que le marchand peut scanner avec son téléphone, à télécharger avec **Télécharger en PNG** ou **Télécharger en SVG**. Le lien ne sert qu'une fois, et toute personne qui l'ouvre peut connecter un compte à votre plateforme : envoyez-le au marchand seulement. ![La section Lien d'invitation d'une connexion en attente : le code QR et sa date d'expiration, le lien raccourci avec Copier, Partager sur WhatsApp, Télécharger en PNG et Télécharger en SVG, et en bas Renvoyer l'invitation.](https://docs.wajub.com/dashboard/fr/light/sync-invitation.webp) *Le lien n'apparaît qu'une fois, juste après la création.* Le lien expire au bout de 30 jours, à la date indiquée sous le code QR, et des rappels partent à l'adresse du marchand pendant ses 3 derniers jours. Il ne s'affiche qu'à la création : plus tard, **Régénérer le lien** en donne un nouveau, et l'ancien cesse de fonctionner. Avec une adresse e-mail, **Renvoyer l'invitation** envoie un nouveau lien au marchand, et celui que vous aviez partagé cesse aussi de fonctionner. Dans les deux cas, le nouveau lien a de nouveau 30 jours. ## Ce que voit le marchand Le marchand ouvre le lien, se connecte à Wajub ou crée son compte, choisit l'entreprise à connecter, termine sa vérification si elle manque, puis lit vos conditions et les accepte. ## Après l'acceptation La connexion passe au statut **Actif** dans **Sync › Comptes**. Jusque-là, vous pouvez encore changer la tarification et les permissions sur sa page ; ensuite, un changement doit être accepté par le marchand. [Gérer un compte connecté](https://docs.wajub.com/dashboard/sync/connected-account) décrit cette page, et [Paramétrer Sync](https://docs.wajub.com/dashboard/sync/settings) les réglages par défaut d'une nouvelle invitation. --- # Gérer un compte connecté URL: https://docs.wajub.com/fr/dashboard/sync/connected-account > Lire la page d'un marchand connecté, changer sa commission ou ses permissions, suspendre ses paiements, annuler une invitation ou déconnecter le marchand. Chaque marchand invité a sa page dans Sync : son activité, les conditions de la connexion et les actions pour la faire évoluer ou y mettre fin. Le propriétaire, un Administrateur, un membre Finance ou un rôle personnalisé qui a **Gérer les transferts** gère un compte connecté ; un Analyste, un Observateur ou un rôle personnalisé qui a **Voir les transferts** le consulte. Le forfait est celui de [Connecter un marchand](https://docs.wajub.com/dashboard/sync/connect-merchant) : **Scale**, **Enterprise** ou l'option **Sync**. Suspendre ou réactiver les paiements et déconnecter un marchand demandent le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) ; changer les conditions, régénérer le lien ou annuler une invitation, non. ## Ouvrir un compte Ouvrez **Sync**, puis l'onglet **Comptes**. **Comptes synchronisés** liste les marchands connectés et les invitations en attente, avec leur **Statut**, le montant **Collecté**, leurs **Paiements** et la date de création. Cliquez sur un compte pour ouvrir sa page. L'en-tête donne le nom du marchand, l'**ID de connexion** et le statut de la connexion : **En attente**, **Actif**, **Expiré** ou **Annulée**. Une fois le marchand connecté, un second badge dit s'il peut encaisser par votre plateforme : **Paiements activés**, **Paiements suspendus** ou **Paiements inactifs**. En Production, une nouvelle connexion reste **Paiements inactifs** jusqu'à ce que Wajub accepte la vérification du marchand, et pour un compte Lite son contrat Wajub Rail, puis passe d'elle-même à **Paiements activés** ; en Test, elle encaisse tout de suite. ![La page d'un compte connecté actif : le nom du marchand, les badges Actif et Paiements activés, l'ID de connexion, le bouton Suspendre les paiements, puis la section Performance avec le volume, les paiements, les commissions et le taux de réussite.](https://docs.wajub.com/dashboard/fr/light/sync-account.webp) *Le second badge dit si le marchand peut encaisser par votre plateforme.* **Performance** montre le **Volume**, les **Commissions**, les **Paiements** et le **Taux de réussite** sur la période choisie, avec les **Derniers paiements** en dessous. **Détails de la connexion** reprend le type de compte, l'e-mail du marchand et les dates. Les autres onglets du compte sont décrits dans [Suivre l'activité Sync](https://docs.wajub.com/dashboard/sync/activity#one-account). ## Changer les conditions 1. **Modifiez la tarification ou les permissions** Sur la page du compte, changez le **Pourcentage**, les **Frais fixes**, les **Frais minimum** ou les **Frais maximum** dans **Tarification**, ou cochez d'autres cases dans **Permissions**. La tarification affiche la commission prise sur un paiement d'exemple. 2. **Ajoutez un message** Quand le marchand est déjà connecté, **Message au marchand**, facultatif, accompagne votre proposition. Tant que l'invitation attend, il n'y a pas de message : le marchand découvrira les conditions en ouvrant le lien. 3. **Enregistrez ou proposez** Pour une invitation en attente, **Enregistrer la tarification** ou **Enregistrer les autorisations** applique le changement tout de suite. Pour un marchand connecté, le bouton devient **Proposer une nouvelle tarification** ou **Proposer de nouvelles autorisations** : le marchand reçoit la proposition par e-mail et l'accepte ou la refuse. En attendant sa réponse, un encadré en haut de la page rappelle la proposition et sa date, et la connexion garde ses conditions actuelles. ## Suspendre ou réactiver les paiements **Suspendre les paiements**, en haut de la page, empêche le marchand d'encaisser par votre plateforme ; les paiements déjà faits ne changent pas. Après la confirmation et le code de sécurité, le badge passe à **Paiements suspendus** et le marchand est prévenu par e-mail, sauf s'il a coupé cet e-mail. **Réactiver les paiements** fait l'inverse. ## Régénérer ou annuler une invitation Tant que le marchand ne s'est pas connecté, le menu **Actions sur la connexion**, à droite de l'en-tête, propose **Régénérer le lien** et **Annuler la connexion**. [Partager le lien d'invitation](https://docs.wajub.com/dashboard/sync/connect-merchant#share-the-invitation) dit ce que change un nouveau lien. Annuler la connexion rend le lien inutilisable, sans retour possible ; **Le garder** referme la fenêtre sans rien changer. Une invitation expirée ou annulée affiche **Cette invitation a expiré** ou **Cette connexion est terminée** : **Créer une connexion** en prépare une nouvelle. ## Déconnecter un marchand Dans le menu **Actions sur la connexion**, **Déconnecter** suivi du nom du marchand coupe tout de suite l'accès de votre plateforme à son compte : son accès API est révoqué et il ne peut plus encaisser par vous. Les paiements déjà faits restent dans les deux comptes. Après la confirmation et le code de sécurité, la page affiche **Cette connexion est terminée** et garde l'historique. C'est définitif : pour reconnecter ce marchand, créez une nouvelle connexion et envoyez-lui la nouvelle invitation. Le marchand peut aussi se déconnecter de son côté : [Répondre à une plateforme](https://docs.wajub.com/dashboard/sync/connected-to-a-platform#disconnect-from-a-platform). --- # Répondre à une plateforme URL: https://docs.wajub.com/fr/dashboard/sync/connected-to-a-platform > Quand votre organisation est connectée à une plateforme par Sync, voir ce qu'elle peut faire sur votre compte, accepter ou refuser ses nouvelles conditions, et vous en déconnecter. Une plateforme qui encaisse pour vous par Sync vous envoie un lien d'invitation. Une fois connectée, elle prend une commission sur vos paiements et agit sur votre compte selon les permissions que vous lui avez accordées. **Paramètres › Applications connectées**, dans le groupe **Organisation**, liste ces plateformes. Le propriétaire, un Administrateur, un Développeur, un Observateur ou un rôle personnalisé qui a **Voir les paramètres** voit cette page ; seuls le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les paramètres** acceptent une connexion, répondent à de nouvelles conditions ou déconnectent une plateforme. La page est ouverte à tous les forfaits. Elle montre les connexions de l'[environnement](https://docs.wajub.com/fr/dashboard#sandbox-and-live) en cours : une connexion faite en Test n'apparaît pas en Production. Se déconnecter demande le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Accepter une connexion Le lien d'invitation s'ouvre hors du tableau de bord : vous vous connectez à Wajub, choisissez l'organisation à connecter, puis lisez les conditions de la plateforme et les acceptez. Seul un membre qui peut gérer les paramètres de cette organisation peut l'accepter. La plateforme apparaît ensuite dans **Applications connectées**, avec la date de connexion et les **Permissions accordées**. ![Paramètres › Applications connectées : une plateforme avec sa date de connexion, l'encadré Nouvelle tarification proposée qui compare Aujourd'hui et Proposé, les boutons Accepter et Refuser, puis les Permissions accordées.](https://docs.wajub.com/dashboard/fr/light/sync-connected-apps.webp) *Une proposition de la plateforme ne change rien tant que vous ne l'acceptez pas.* ## Répondre à de nouvelles conditions Une plateforme connectée peut proposer une autre commission ou d'autres permissions. Vous recevez la proposition par e-mail, et rien ne change tant que vous ne l'acceptez pas. 1. **Ouvrez la proposition** Ouvrez **Paramètres › Applications connectées**. Sous le nom de la plateforme, l'encadré **Nouvelle tarification proposée** ou **Nouvelles autorisations proposées** met côte à côte la colonne **Aujourd'hui** et la colonne **Proposé**, avec le message de la plateforme si elle en a écrit un. 2. **Acceptez ou refusez** **Accepter** ouvre **Accepter les nouvelles conditions ?** : après **Accepter les nouvelles conditions**, elles s'appliquent à tout ce qui se passe ensuite, et les ventes déjà faites gardent les anciennes. **Refuser** ouvre **Refuser les nouvelles conditions ?** : après **Refuser les nouvelles conditions**, la connexion garde ses conditions actuelles, et la plateforme pourra en proposer d'autres plus tard. ## Se déconnecter d'une plateforme Ouvrez le menu de la plateforme, à droite de sa ligne, puis **Déconnecter**. Après la confirmation et le code de sécurité, la plateforme perd tout de suite tous ses accès à votre compte et la ligne disparaît. Les paiements déjà traités restent dans votre historique. Pour vous reconnecter, il faut une nouvelle invitation de la plateforme. La plateforme peut aussi vous déconnecter ou suspendre vos paiements ; les e-mails qui vous en préviennent se règlent dans [Les e-mails du compte connecté](https://docs.wajub.com/dashboard/sync/settings#connected-account-emails), avec le forfait **Scale** ou **Enterprise**, ou l'option **Sync**. --- # Paramétrer Sync URL: https://docs.wajub.com/fr/dashboard/sync/settings > Choisir les permissions et la commission par défaut d'une nouvelle invitation Sync, et les e-mails reçus quand une plateforme agit sur votre compte. **Paramètres › Sync** a deux onglets : **Plateforme**, les conditions par défaut de vos nouvelles invitations, et **Compte connecté**, les e-mails que vous recevez quand une plateforme à laquelle vous êtes connecté agit sur votre compte. Le propriétaire, un Administrateur, un Développeur, un Observateur ou un rôle personnalisé qui a **Voir les paramètres** ouvre ces réglages ; seuls le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les paramètres** les modifient. Les deux onglets demandent le forfait **Scale** ou **Enterprise**, ou l'option **Sync** : sans eux, l'entrée reste visible mais [verrouillée](https://docs.wajub.com/fr/dashboard#modules-outside-your-plan). Les réglages valent pour Test comme pour Production, et aucun code de sécurité n'est demandé. ## Les conditions par défaut 1. **Ouvrez les réglages Sync** Ouvrez **Paramètres › Sync**. La page s'ouvre sur l'onglet **Plateforme**. ![Paramètres › Sync, onglet Plateforme : les cases des Permissions par défaut, Paiements coché et grisé, puis la Commission par défaut avec Pourcentage (%), Frais fixes et Plafond de frais.](https://docs.wajub.com/dashboard/fr/light/sync-settings-platform.webp) *Ces conditions remplissent chaque nouvelle invitation, que vous pouvez encore changer.* 2. **Cochez les permissions par défaut** Sous **Permissions par défaut**, cochez ce qu'une nouvelle invitation demande au marchand. **Paiements** est toujours demandé. Dès le premier changement, la barre **Vous avez des modifications non enregistrées** apparaît en bas de la page. 3. **Fixez la commission par défaut** Sous **Commission par défaut**, saisissez le **Pourcentage (%)** et les **Frais fixes**, dans votre devise de règlement. Laissez **Plafond de frais** vide pour ne pas plafonner la commission. 4. **Enregistrez** **Enregistrer les modifications** applique les nouvelles valeurs ; **Abandonner** revient aux précédentes. Ces valeurs ne servent qu'aux invitations créées ensuite dans le tableau de bord, et vous pouvez encore les changer pour chaque marchand dans le formulaire. Une connexion existante garde ses conditions : elles se changent sur sa page, voir [Changer les conditions](https://docs.wajub.com/dashboard/sync/connected-account#change-the-terms). Une connexion créée par l'API prend les permissions et la commission que nomme sa requête, et aucune commission quand elle n'en nomme pas : [Capacités du compte](https://docs.wajub.com/fr/sync/account-types#pricing). ## Les e-mails du compte connecté L'onglet **Compte connecté** concerne votre organisation quand elle est elle-même connectée à une plateforme. Sous **Notifications par e-mail**, trois interrupteurs : | Interrupteur | L'e-mail part quand | | ------------------------------ | ------------------------------------------------------------------ | | **Capacités modifiées** | la plateforme active ou désactive des permissions sur votre compte | | **Statut du paiement modifié** | la plateforme suspend ou réactive vos paiements | | **Connexion terminée** | la plateforme vous déconnecte | Un interrupteur coupé arrête cet e-mail. Les nouvelles conditions qu'une plateforme propose arrivent toujours par e-mail, puisqu'elles attendent votre réponse : [Répondre à une plateforme](https://docs.wajub.com/dashboard/sync/connected-to-a-platform#answer-new-terms). Enregistrez avec **Enregistrer les modifications**. --- # Paramétrer la taxe URL: https://docs.wajub.com/fr/dashboard/tax/settings > Activer le calcul de la TVA ou de la GST sur vos paiements, dire si vos prix l'incluent, choisir le pays par défaut et enregistrer votre immatriculation fiscale. Une fois la collecte activée, Wajub calcule la taxe de chaque paiement crédité, d'après le pays du payeur, et la range dans [votre rapport](https://docs.wajub.com/dashboard/tax/track). Vos clients paient toujours le prix que vous avez fixé. Le propriétaire, un Administrateur, un membre Finance ou un rôle personnalisé qui a **Gérer les taxes** règle la taxe, à partir du forfait **Growth**. Comme le rappelle [Test et Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), le module n'existe qu'en Production. Aucun code de sécurité n'est demandé. ## Les étapes 1. **Ouvrez les paramètres fiscaux** Dans **Taxe**, cliquez sur **Configurer la taxe**, ou sur l'onglet **Paramètres** si la collecte est déjà activée. La page **Paramètres fiscaux** s'ouvre. 2. **Activez la collecte** Activez **Activer la collecte de taxes**. **Tarification taxe incluse**, **Pays par défaut** et **Immatriculation fiscale** apparaissent. L'encadré **Taux de taxe par pays** rappelle que le taux normal de chaque pays est déjà prêt. 3. **Dites si vos prix incluent la taxe** Activé, **Tarification taxe incluse** compte la taxe à l'intérieur de chaque prix. Désactivé, le rapport compte le taux en plus de chaque prix. Les paiements et les liens facturent toujours le prix fixé ; seules les factures peuvent ajouter la taxe en plus. 4. **Choisissez le pays par défaut** Le **Pays par défaut** sert quand le pays du payeur est inconnu. 5. **Saisissez votre immatriculation fiscale** Choisissez le **Type de numéro fiscal**, puis saisissez le **Numéro d'immatriculation fiscale** : les deux sont obligatoires pour activer la collecte, et le numéro doit suivre le format de son type. Il est gardé avec vos paramètres, sans être imprimé sur les factures ni les reçus pour l'instant. ![La section Immatriculation fiscale : le type de numéro fiscal CM NIU, puis le numéro d'immatriculation fiscale M123456789000L saisi.](https://docs.wajub.com/dashboard/fr/light/tax-settings.webp) *Le numéro d'immatriculation est obligatoire pour activer la collecte.* 6. **Enregistrez** Cliquez sur **Enregistrer les modifications** dans la barre du bas : **Paramètres fiscaux mis à jour.** s'affiche. **Taxe** montre désormais le rapport, avec les onglets **Vue d'ensemble** et **Paramètres**. ## Dans vos factures Tant que la collecte est activée, le formulaire de facture propose **Collecter la taxe automatiquement** à l'étape des lignes : il applique vos paramètres fiscaux et le pays du client. Désactivez-le pour fixer vous-même la taxe de chaque ligne, comme pour [toute facture](https://docs.wajub.com/dashboard/invoices/create#the-steps). ## Désactiver la collecte Désactivez **Activer la collecte de taxes**, puis enregistrez. Les nouveaux paiements ne sont plus taxés, et **Taxe** affiche de nouveau [sa présentation](https://docs.wajub.com/dashboard/tax/track#before-turning-it-on) à la place du rapport. Pour la réactiver, repassez par **Configurer la taxe**. --- # Suivre la taxe collectée URL: https://docs.wajub.com/fr/dashboard/tax/track > Lire la taxe calculée sur vos paiements pour une période, par pays et par devise, et l'exporter en CSV pour votre comptable. **Taxe** montre la TVA ou la GST que Wajub a calculée sur les paiements crédités, en ligne et au TPE, pour la période choisie. Le calcul ne change pas ce que paient vos clients. Le module est inclus à partir du forfait **Growth** ([Modules hors de votre forfait](https://docs.wajub.com/fr/dashboard#modules-outside-your-plan)) et n'existe qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Tous les rôles qui lisent la taxe voient le rapport ([Rôles](https://docs.wajub.com/fr/dashboard#roles)). L'export demande **Gérer les taxes** : le propriétaire, un Administrateur, un membre Finance ou un rôle personnalisé qui l'a. Aucun code de sécurité n'est demandé. ## Avant l'activation Tant que la collecte n'est pas activée, **Taxe** présente le module avec le badge **Collecte de taxes**. Ceux qui ont **Gérer les taxes** y trouvent **Configurer la taxe**, qui ouvre [les paramètres fiscaux](https://docs.wajub.com/dashboard/tax/settings). Les autres lisent « Demandez à un administrateur de votre organisation de configurer la collecte des taxes. ». Si la collecte est désactivée plus tard, cette présentation revient à la place du rapport. ## Lire le rapport Choisissez la **Période** en haut à droite : **30 derniers jours** par défaut, une autre période toute faite, ou le premier et le dernier jour dans le calendrier, puis **Appliquer**. Trois chiffres résument la période : **Taxe collectée** et **Montant taxable** (hors taxes), tous deux convertis dans la devise de votre compte, puis **Pays**, le nombre de pays où des paiements ont été taxés. ![La page Taxe sur les 30 derniers jours : la période et le bouton Exporter en haut, les chiffres Taxe collectée, Montant taxable et Pays, le tableau Taxe par pays avec le montant taxable, la taxe et le nombre de paiements du Cameroun et du Gabon, puis le tableau Taxe par devise.](https://docs.wajub.com/dashboard/fr/light/tax-overview.webp) *Les totaux et la taxe par pays sont convertis dans la devise du compte.* **Taxe par pays** détaille, pour chaque pays de payeur, le montant taxable, la taxe et le nombre de **Paiements**. **Taxe par devise** reprend les mêmes chiffres dans le montant propre à chaque devise. Une devise sans taux de change est laissée hors des totaux et de la taxe par pays : l'encadré **Certaines devises sont exclues des totaux** le signale. Un remboursement réussi retire sa part de taxe du rapport. Sans paiement taxé sur la période, le tableau affiche **Aucune taxe collectée pour cette période**. ## Exporter le rapport **Exporter**, à côté de la période, puis **CSV** sous **Télécharger en** : le fichier reprend les totaux, la taxe par pays et la taxe par devise de la période affichée, et « Votre export est prêt » donne son nom. --- # Gérer les bénéficiaires URL: https://docs.wajub.com/fr/dashboard/transfers/beneficiaries > Retrouver les bénéficiaires que votre intégration paie par l'API, lire leur page, les modifier, les archiver ou les supprimer, et les exporter. L'onglet **Bénéficiaires** de **Transferts** liste les destinataires que votre intégration crée et paie par l'API, comme l'explique [Créer un bénéficiaire](https://docs.wajub.com/fr/payouts/beneficiaries/create). Le tableau de bord n'en crée pas : pour retirer votre solde vers l'un de vos propres comptes, [liez un compte de versement](https://docs.wajub.com/dashboard/transfers/payout-accounts). Tant que votre intégration n'a créé aucun bénéficiaire, une page de présentation remplace la liste. Tous ceux qui ont **Voir les transferts** ouvrent la liste et les bénéficiaires, en Test comme en Production : chaque environnement a ses propres bénéficiaires. Le propriétaire, un Administrateur, un membre Finance ou un rôle personnalisé qui a **Gérer les bénéficiaires** modifie, archive, restaure, supprime et exporte, en Production. Toutes ces actions sauf l'export demandent le code de sécurité. ## La liste ![L'onglet Bénéficiaires en Production : des bénéficiaires API avec leur moyen de paiement, leur statut Actif ou Inactif, leur nombre de transferts et leur date de création.](https://docs.wajub.com/dashboard/fr/light/transfers-beneficiaries.webp) *La liste ne montre que les bénéficiaires créés par l'API.* Chaque ligne donne le **Bénéficiaire**, son **Moyen de paiement**, son **Statut**, ses **Transferts** avec le nombre de réussis, et la date **Créé**. Les filtres portent sur la **Date de création**, le **Statut**, **Actif** ou **Inactif**, et **Bénéficiaires archivés**, qui n'affiche que les bénéficiaires archivés. La recherche trouve un bénéficiaire par son nom, son e-mail, son téléphone ou son ID. Le menu au bout d'une ligne propose **Ouvrir le bénéficiaire**, **Copier l'ID du bénéficiaire** et, en Production, **Modifier**. ## La page d'un bénéficiaire L'en-tête donne le nom, le statut, le type **Bénéficiaire API** et l'**ID du bénéficiaire** à copier. Trois chiffres suivent : le nombre de **Transferts**, le montant **Reçu**, devise par devise, et le **Taux de réussite**. Viennent ensuite les **Détails du bénéficiaire**, l'**Activité des transferts** des 30 derniers jours et les **Transferts récents** : **Voir tous les transferts** ouvre la liste des transferts filtrée sur ce bénéficiaire. Sur le côté, **Moyen de paiement** et **Par statut** résument où il est payé et comment ses transferts ont fini. La même page s'ouvre pour un compte de versement, par exemple depuis **Voir le bénéficiaire** sur un transfert. Elle porte alors le type **Compte de versement** et, en Production, pour qui peut envoyer un transfert, le bouton **Envoyer le transfert** quand le compte est actif et non archivé : il ouvre le formulaire de transfert sur ce compte. ## Modifier un bénéficiaire 1. **Ouvrez le formulaire** Sur la page du bénéficiaire, ou dans le menu de sa ligne, choisissez **Modifier**. 2. **Corrigez le contact** Sous **Contact**, corrigez le **Nom**, obligatoire, l'**E-mail**, le **Téléphone** ou le **Pays**. 3. **Changez le moyen de paiement** Sous **Transferts**, le **Type** reste celui choisi à la création. Le **Moyen de paiement** propose les moyens déjà enregistrés pour vos bénéficiaires. 4. **Activez ou désactivez le bénéficiaire** Désactivé, **Actif** fait refuser tout transfert vers ce bénéficiaire, par l'API comme depuis le tableau de bord. 5. **Enregistrez** Choisissez **Enregistrer les modifications**, puis saisissez le code de sécurité. La page du bénéficiaire s'ouvre sur « Bénéficiaire mis à jour avec succès. ». La **Note**, en bas du formulaire, garde une information que seuls vos membres voient. ## Archiver, restaurer ou supprimer Le menu de la page du bénéficiaire propose **Archiver le bénéficiaire** : il quitte la liste et ne peut plus être payé, et ses transferts restent. Le filtre **Bénéficiaires archivés** le retrouve ; sa page affiche **Ce bénéficiaire est archivé** et son menu propose **Restaurer le bénéficiaire**. **Supprimer définitivement** efface le bénéficiaire et ses statistiques, sans retour possible. Un bénéficiaire dont un transfert est encore en cours ne peut pas être supprimé : archivez-le plutôt. Chacune de ces trois actions demande le code de sécurité. ## Exporter les bénéficiaires En Production, **Exporter**, en haut de la liste, ouvre **Exporter les bénéficiaires** : le fichier, en CSV, Excel, PDF ou JSON, reprend les bénéficiaires que la liste affiche avec ses filtres et son ordre. Chaque export compte dans la limite mensuelle du forfait **Paiement à l'usage**. --- # Lier un compte de versement URL: https://docs.wajub.com/fr/dashboard/transfers/payout-accounts > Ajouter le numéro Mobile Money ou le compte bancaire qui reçoit vos transferts, le faire vérifier, y activer les versements automatiques, puis le modifier ou l'archiver. Un transfert part de votre solde vers un compte de versement : un numéro Mobile Money, un compte bancaire ou un compte Wajub, le vôtre ou celui de quelqu'un que vous payez. Vous l'ajoutez une fois, puis vous le choisissez à chaque [transfert](https://docs.wajub.com/dashboard/transfers/send). Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les paramètres** ajoute, modifie et fait vérifier les comptes de versement, avec tous les forfaits. Un membre Finance envoie des transferts mais n'ouvre pas cette page. Elle n'existe qu'en Production, et ajouter, modifier ou faire vérifier un compte demande le code de sécurité. ## Les étapes 1. **Ouvrez le formulaire** Ouvrez **Paramètres › Transferts**, onglet **Comptes de versement**, puis **Ajouter un compte de versement**. Le formulaire passe par quatre étapes, **Pays**, **Méthode**, **Détails** et **Examiner**, et **Continuer** mène de l'une à l'autre. 2. **Choisissez le pays** Sous **Pays du compte**, choisissez le pays où le numéro ou le compte bancaire est enregistré. 3. **Choisissez le moyen de versement** **Moyen de versement** propose les moyens ouverts dans ce pays : Mobile Money, banque, virement bancaire ou compte Wajub selon le pays. Une carte ne peut pas recevoir de transfert. Si aucun moyen n'est encore ouvert pour votre organisation, le formulaire le dit et propose, selon le cas, **Demander l'accès**, **Signer le contrat** ou **Voir la demande**. 4. **Saisissez le numéro ou le compte** Pour Mobile Money, saisissez le **Numéro mobile**. Pour MTN, Orange Money et Express Union au Cameroun, le tableau de bord interroge l'opérateur et affiche « Nom enregistré : » suivi du nom du titulaire, avec **Utiliser ce nom**. Pour un compte bancaire, saisissez le **Numéro de compte** ; pour un virement bancaire, le **Nom de la banque**, la **Devise du compte**, l'IBAN ou le numéro de compte, le SWIFT/BIC ou le code bancaire local, et l'**Attestation de compte bancaire** quand elle est demandée. Pour un compte Wajub, le **Numéro de compte Wajub**. 5. **Indiquez le titulaire** **Nom du titulaire du compte** est le nom sous lequel le compte est enregistré, tel que la banque le connaît pour un virement. **E-mail de notification**, facultatif, reçoit les confirmations de versement. 6. **Ajoutez le compte** L'étape **Examiner** reprend **Où va l'argent** et **Titulaire du compte** : l'argent part vers ce compte exactement tel que saisi. Choisissez **Ajouter un compte de versement**, puis saisissez le code de sécurité. Si vous veniez du formulaire de transfert, vous y revenez avec ce compte déjà choisi. ## Faire vérifier le compte Un transfert ne part que vers un compte **Vérifié**. À l'ajout, un compte Mobile Money est vérifié quand le nom enregistré chez l'opérateur correspond au titulaire saisi, à la raison sociale de votre dossier d'activation ou à l'une des personnes qu'il déclare. Un compte Wajub l'est quand son titulaire correspond. Sinon, la liste l'affiche **Non vérifié**. Pour un compte Mobile Money **Non vérifié**, **Vérifier auprès de l'opérateur** relance la comparaison et demande le code de sécurité. Si les noms correspondent, le compte passe **Vérifié**. Sinon, le propriétaire de l'organisation reçoit par e-mail un code à six chiffres, valable 15 minutes : saisissez-le dans le champ qui apparaît sur la ligne du compte, puis **Vérifier**. Le tableau de bord ne permet pas de faire vérifier un compte bancaire. ## Versements automatiques Au-dessus de la liste, **Versements automatiques** verse vos ventes sur l'un de vos comptes de versement chaque nuit, sans transfert de votre part. Ils sont désactivés tant que vous ne les activez pas : sinon, votre argent reste sur votre solde jusqu'à ce que vous envoyiez un [transfert](https://docs.wajub.com/dashboard/transfers/send). 1. **Activer** Activez **Verser mon solde automatiquement**. 2. **Choisir le compte** Sous **Versé sur**, choisissez le compte de versement qui reçoit l'argent. Avec un seul compte, il est déjà choisi. Sans compte, ajoutez-en un d'abord : la section vous le dit. 3. **Enregistrer** Choisissez **Enregistrer**, puis saisissez le code de sécurité. Chaque nuit, Wajub verse les ventes pas encore versées, moins leurs remboursements, leurs frais et les litiges perdus, et jamais plus que ce qui est disponible sur votre solde avec les frais du payout en plus : ce que vous avez déjà envoyé vous-même n'est pas renvoyé, et les fonds que vous avez ajoutés à votre solde y restent. Le premier versement après l'activation comprend les ventes déjà sur votre solde, dans la limite de ce qui est disponible. Rien n'est envoyé sous 1 000. [Solde et règlements](https://docs.wajub.com/fr/payouts/balance#settlement-to-your-payout-account) donne le détail. Si le compte choisi est archivé ou désactivé, rien n'est versé et la section vous demande d'en choisir un autre. Désactivez l'interrupteur et enregistrez pour arrêter les versements automatiques à tout moment. ## Modifier ou archiver un compte Le menu au bout d'une ligne propose **Modifier** : **Modifier le compte de versement** change le contact, le **Moyen de paiement**, la case **Actif** et une **Note** que seuls vos membres voient. **Enregistrer les modifications** demande le code de sécurité. Changer le moyen de paiement remet le compte **Non vérifié** et envoie une alerte de sécurité par e-mail au propriétaire. **Archiver**, dans le même menu, retire le compte de la liste : plus aucun transfert ne peut lui être envoyé, et ses transferts restent. Archiver demande le code de sécurité et la permission **Gérer les bénéficiaires**. Pour le retrouver ensuite, ouvrez l'un de ses transferts, puis **Voir le bénéficiaire** : sa page propose **Restaurer le bénéficiaire**. > [!NOTE] > **Les bénéficiaires de votre intégration** > > Les destinataires que votre intégration paie par l'API sont aussi des bénéficiaires, mais pas > des comptes de versement : ils sont dans > [Gérer les bénéficiaires](https://docs.wajub.com/dashboard/transfers/beneficiaries). --- # Programmer des transferts URL: https://docs.wajub.com/fr/dashboard/transfers/recurring > Créer un calendrier qui envoie le même montant à un compte de versement chaque heure, chaque jour, chaque semaine ou chaque mois, puis le suspendre, le modifier ou le supprimer. Un transfert récurrent paie le même compte de versement selon un calendrier : un fournisseur chaque mois, votre propre compte chaque semaine. Chaque exécution est un vrai transfert, avec les mêmes limites, les mêmes contrôles et la même [vérification](https://docs.wajub.com/dashboard/transfers/under-review) qu'un transfert envoyé à la main. Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les paramètres** crée et gère les calendriers, en Production. Créer, modifier ou reprendre un calendrier demande le forfait **Growth** ou un forfait au-dessus. Créer, modifier et supprimer demandent le code de sécurité ; suspendre et reprendre ne le demandent pas. ## Les étapes 1. **Ouvrez le formulaire** Ouvrez **Paramètres › Transferts**, onglet **Transferts récurrents**, puis **Créer un transfert récurrent**. Si votre forfait ne les inclut pas, la page affiche **Non inclus dans votre forfait** et le bouton mène aux forfaits. 2. **Choisissez le compte et le montant** Sous **Destinataire et montant**, choisissez le **Compte de versement**, puis le **Montant de chaque exécution**, dans les limites rappelées au-dessus du champ. Le **Nom**, facultatif, aide à retrouver le calendrier dans la liste ; la **Description**, facultative, s'affiche sur chaque transfert. 3. **Réglez le calendrier** Sous **Planification**, choisissez la **Fréquence** : **Toutes les heures**, **Quotidien**, **Hebdomadaire** avec le **Jour de la semaine**, ou **Mensuel** avec le **Jour du mois**, de 1 à 31. Un mois plus court utilise son dernier jour. Sauf pour l'envoi horaire, réglez l'**Heure (UTC)**, 09:00 par défaut : le calendrier tourne en UTC, et 09:00 UTC correspond à 10:00 au Cameroun. ![Le formulaire d'un transfert récurrent : sous Destinataire et montant, le compte de versement Kribi Coffee SARL choisi, un montant de chaque exécution de 250 000 FCFA et le nom Paiement fournisseur mensuel, puis sous Planification, la fréquence Mensuel, le jour du mois 5 et l'heure 09:00 UTC.](https://docs.wajub.com/dashboard/fr/light/transfers-recurring.webp) *Les heures du calendrier sont en UTC.* 4. **Relisez le calendrier** Choisissez **Examiner**. L'étape reprend le destinataire, le montant de chaque exécution et le rythme, par exemple « Le 5 de chaque mois à 09:00 UTC ». **Modifier les informations** revient au formulaire. 5. **Créez le calendrier** Choisissez **Créer un transfert récurrent**, puis saisissez le code de sécurité. Le message de confirmation donne la date du premier envoi, et le calendrier rejoint la liste, **Actif**. ## Suivre et modifier un calendrier Chaque ligne de **Transferts récurrents** donne le compte, le montant, le rythme, la prochaine exécution et la dernière avec son statut. Les transferts qu'il envoie portent la source **Récurrent** dans [la liste des transferts](https://docs.wajub.com/dashboard/transfers/track#the-list). Le menu au bout d'une ligne propose **Modifier** : **Enregistrer les modifications** recalcule alors la prochaine exécution à partir de maintenant. **Mettre le calendrier en pause** arrête les envois. **Reprendre le calendrier** le relance à sa prochaine date, sans rattraper les envois manqués, et remet son compteur d'échecs à zéro ; sans le forfait, le menu affiche **Changer de forfait pour reprendre**. **Supprimer le calendrier** arrête définitivement les envois, et les transferts déjà envoyés restent. ## Quand une exécution échoue Une exécution échoue quand Wajub refuse le transfert, par exemple faute de solde, ou quand **Transferts autorisés depuis** est sur **API uniquement**, que **Arrêter tous les transferts** est activé ou que le montant sort des limites des [paramètres généraux](https://docs.wajub.com/dashboard/transfers/settings#general-settings). La ligne affiche alors le nombre d'échecs consécutifs et la dernière erreur, et le calendrier passe à sa date suivante. Après trois échecs de suite, il passe **En pause** et le propriétaire reçoit un e-mail. Reprenez-le une fois la cause réglée. Si votre forfait n'inclut plus les transferts récurrents, vos calendriers actifs passent en pause en quelques minutes et le propriétaire est prévenu. Vous pouvez toujours les voir et les supprimer. Ils repartent d'eux-mêmes quand votre forfait les inclut de nouveau, à leur prochaine date. > [!NOTE] > **Temporairement indisponible** > > Quand Wajub suspend les transferts récurrents, la page l'indique par cet encadré : aucun envoi ne > part, vos calendriers restent tels quels, et chaque transfert arrivé à échéance pendant ce temps > part une fois au retour du service. --- # Envoyer un transfert URL: https://docs.wajub.com/fr/dashboard/transfers/send > Envoyer de l'argent de votre solde vers l'un de vos comptes de versement, relire les frais avant l'envoi, et ce qui fait refuser un transfert. Un transfert envoie de l'argent de votre solde vers l'un de vos [comptes de versement](https://docs.wajub.com/dashboard/transfers/payout-accounts). Pour payer le même compte à date fixe, [programmez des transferts](https://docs.wajub.com/dashboard/transfers/recurring). Le propriétaire, un Administrateur, un membre Finance ou un rôle personnalisé qui a **Gérer les transferts** peut envoyer un transfert, avec tous les forfaits. Le formulaire n'existe qu'en Production, et l'envoi demande le code de sécurité. ## Les étapes 1. **Ouvrez le formulaire** Ouvrez **Transferts**, puis **Créer un transfert**. En haut, le formulaire donne le **Solde disponible**, ce que vous pouvez envoyer, et le montant **En attente**, pas encore disponible pour un envoi. [Solde et règlements](https://docs.wajub.com/fr/payouts/balance) explique ce délai. 2. **Choisissez le compte** Sous **Compte de versement**, choisissez le compte qui reçoit l'argent. Chacun porte son statut, **Vérifié** ou **Non vérifié** : un compte non vérifié affiche **Ce compte n'est pas encore vérifié** et ne peut pas recevoir le transfert. La liste reprend vos 100 comptes les plus récents. 3. **Saisissez le montant** Saisissez le **Montant** et, si besoin, changez de devise. Au-dessus du champ, le formulaire rappelle le minimum et les frais, qui s'ajoutent au montant : le compte reçoit tout le montant saisi, et votre solde paie le montant plus les frais. **Description**, facultative, s'affiche sur le transfert. ![Créer un transfert, étape Détails : le Solde disponible et le montant En attente, le compte MTN Mobile Money de Kribi Coffee SARL choisi, un montant de 150 000 FCFA avec les frais et le minimum, et le bouton Vérifier le transfert.](https://docs.wajub.com/dashboard/fr/light/transfers-send.webp) *Les frais s'ajoutent au montant que reçoit le compte.* 4. **Vérifiez le transfert** Choisissez **Vérifier le transfert** : le tableau de bord calcule les frais et passe à l'étape **Examiner**. **Destinataire** reprend le **Titulaire du compte**, le compte et sa **Vérification** ; **Montant** donne le montant, les frais et le total. **Modifier les informations** revient au formulaire. 5. **Envoyez le transfert** Le bouton rappelle la somme, par exemple « Envoyer 150 000 FCFA ». Choisissez-le, puis saisissez le code de sécurité. **Transferts** s'ouvre sur « Transfert lancé. ». Si le transfert est retenu pour vérification, sa page s'ouvre à la place : [Suivre un transfert retenu](https://docs.wajub.com/dashboard/transfers/under-review) explique la suite. ## Quand l'envoi est refusé Le formulaire affiche la raison sous le montant et rien ne part. Les réglages de [sécurité des transferts](https://docs.wajub.com/dashboard/transfers/settings#security-settings) refusent l'envoi quand **Transferts autorisés depuis** est sur **API uniquement** ou que **Arrêter tous les transferts** est activé, quand la double authentification est exigée et n'a pas été confirmée récemment, quand les transferts sont réservés aux adresses IP de la liste alors que la liste est vide, ou quand le nombre ou le montant maximum du jour est atteint. Le montant doit aussi rester dans les limites des [paramètres généraux](https://docs.wajub.com/dashboard/transfers/settings#general-settings). Wajub refuse aussi un transfert vers un compte non vérifié, et tout transfert tant que votre solde est négatif ou qu'une restriction bloque les transferts de votre organisation. > [!NOTE] > **Un transfert ne s'annule pas** > > Une fois envoyé, il part tel quel. Seule exception : un transfert dont la page affiche **En > attente du moyen de paiement**, que vous pouvez > [annuler tant qu'il attend](https://docs.wajub.com/dashboard/transfers/track#cancel-a-waiting-transfer). Si la page > semble ne pas répondre, n'en ouvrez pas une autre : renvoyé depuis le même formulaire, le > transfert n'est pas payé deux fois, et le formulaire affiche **Un transfert a déjà été envoyé > depuis ce formulaire**. --- # Régler les transferts URL: https://docs.wajub.com/fr/dashboard/transfers/settings > Les paramètres généraux des transferts, de la devise aux limites et aux e-mails, et les paramètres de sécurité qui décident d'où un transfert peut partir. **Paramètres › Transferts** réunit, dans les onglets **Général** et **Sécurité**, les règles que suivent tous vos transferts. Les deux autres onglets ont leur page : [Comptes de versement](https://docs.wajub.com/dashboard/transfers/payout-accounts) et [Transferts récurrents](https://docs.wajub.com/dashboard/transfers/recurring). Le propriétaire, un Administrateur ou un rôle personnalisé qui a **Gérer les paramètres** modifie ces réglages, avec tous les forfaits. Un membre Finance n'ouvre pas cette page. Elle n'existe qu'en Production. Enregistrer l'onglet **Sécurité** demande le code de sécurité, l'onglet **Général** non. ## Paramètres généraux ![Paramètres › Transferts, onglet Général : Limites de transfert avec les montants minimum et maximum, Vérification par Wajub et Devise par défaut.](https://docs.wajub.com/dashboard/fr/light/transfers-settings.webp) *L'onglet Général s'enregistre sans code de sécurité.* Sous **Limites de transfert**, **Montant minimum de transfert**, laissé vide, reprend le minimum de Wajub ; **Montant maximum de transfert**, laissé vide, ne fixe pas de plafond. Ces limites valent pour les transferts du tableau de bord, ponctuels et récurrents. Ceux de l'API ne sont comparés qu'au minimum de Wajub. Sous **Vérification par Wajub**, **Retenir chaque transfert pour vérification** fait attendre chaque transfert la décision de l'équipe Wajub avant son envoi. **Pas de vérification sous ce montant**, facultatif, en dispense les petits montants, qui peuvent rester retenus pour une autre raison : [Suivre un transfert retenu](https://docs.wajub.com/dashboard/transfers/under-review). **Devise par défaut** est la devise sur laquelle s'ouvrent les formulaires de transfert, de transfert récurrent et de compte de versement bancaire. Les transferts envoyés par l'API indiquent leur propre devise. **Transferts qui ne peuvent pas partir** vaut pour chaque transfert de Production, du tableau de bord ou de l'API, sauf les [versements automatiques](https://docs.wajub.com/dashboard/transfers/payout-accounts#automatic-payouts) vers votre propre compte : - **Annuler les transferts non envoyés après (heures)**, de 1 à 168, 24 par défaut : un transfert qu'aucun opérateur n'a reçu au bout de ce délai, parce qu'il attend encore votre confirmation ou sa place dans la file, est annulé et son montant revient au solde. - **Réessayer une fois un transfert refusé pour une raison passagère**, désactivé par défaut : quand tous les opérateurs refusent un transfert pour une raison de leur côté qui passe, indisponibilité ou fonds épuisés par exemple, il repart une fois 10 minutes plus tard. Un compte invalide, une limite ou votre solde ne sont jamais réessayés. Sous **E-mails**, **Envoyer les e-mails de transfert**, activé par défaut, prévient quand un transfert du tableau de bord part, et quand un transfert de Production échoue ou est annulé après le délai ci-dessus. L'e-mail va au propriétaire, aux Administrateurs et aux membres Finance, sauf à ceux qui ont coupé ces e-mails dans leurs préférences. Les e-mails de sécurité partent toujours. **Enregistrer les modifications** applique l'onglet. ## Paramètres de sécurité Sous **Qui peut envoyer des transferts**, **Transferts autorisés depuis** propose trois choix : | Choix | Effet | | ------------------------------ | ---------------------------------------------------------------------------------------------------------- | | **API et tableau de bord** | Votre intégration et le tableau de bord envoient des transferts. | | **API uniquement** | Le tableau de bord refuse tout envoi, ponctuel ou récurrent. | | **Tableau de bord uniquement** | Wajub refuse les transferts de Production créés par l'API, avec l'erreur transfers\_disabled\_for\_source. | **Arrêter tous les transferts** refuse chaque transfert de Production, du tableau de bord comme de l'API, ponctuel ou récurrent, jusqu'à ce que vous le désactiviez. Les [versements automatiques](https://docs.wajub.com/dashboard/transfers/payout-accounts#automatic-payouts) vers votre propre compte, si vous les avez activés, continuent. Le tableau de bord demande une confirmation avant d'enregistrer. Les autres réglages ajoutent des contrôles : - **Exiger l'authentification à deux facteurs pour les transferts** : un transfert du tableau de bord demande une double authentification récente. - **Vérifier les transferts à partir de ce montant** : à partir de ce montant, le transfert attend la vérification de Wajub. - **Nombre maximum de transferts par jour** et **Montant maximum par jour** : au-delà, Wajub refuse le transfert, qu'il vienne du tableau de bord, d'un calendrier ou de l'API. Le montant se saisit en XAF, et les autres devises sont converties au taux du moment. - **N'autoriser les transferts que depuis les adresses IP de la liste** : un transfert du tableau de bord doit venir d'une adresse de la liste de l'organisation, et il est refusé tant que la liste est vide. **Modifier la liste d'adresses IP autorisées** ouvre [Limiter les adresses IP](https://docs.wajub.com/dashboard/settings/security#restrict-ip-addresses). Sous **Détection de menaces**, **La détection d'anomalies est toujours active** rappelle que Wajub retient un premier transfert, ou un montant très au-dessus de l'habitude, sur tous les comptes. > [!NOTE] > **Un réglage sans effet** > > **Exiger la vérification du bénéficiaire** ne change rien : Wajub refuse déjà tout transfert vers > un compte non vérifié, que la case soit cochée ou non. --- # Suivre ses transferts URL: https://docs.wajub.com/fr/dashboard/transfers/track > Lire la liste des transferts, ses chiffres et ses filtres, ce que montre la page d'un transfert, y laisser des notes, annuler un transfert en attente et exporter les transferts. **Transferts** liste chaque transfert parti de votre solde : depuis le tableau de bord, par un calendrier de transferts récurrents ou par votre intégration. Le propriétaire, un Administrateur, un membre Finance, un Analyste, un Observateur ou un rôle personnalisé qui a **Voir les transferts** ouvre la liste et les transferts, en Test comme en Production. Exporter, écrire une note et annuler un transfert en attente demandent **Gérer les transferts** et la Production. L'annulation ne demande pas le code de sécurité. ## La liste En haut, quatre chiffres : le **Solde disponible**, les transferts **En cours**, avec le nombre retenus pour vérification quand il y en a, le montant **Terminé** et le nombre de transferts **Échoué**, échoués ou annulés. Les trois derniers comparent les 15 derniers jours aux 15 précédents, et un clic sur l'un d'eux filtre la liste. ![L'onglet Transferts en Production : Solde disponible avec le montant en attente, En cours avec un transfert en révision manuelle, Terminé et Échoué en haut, puis l'Activité des transferts des 30 derniers jours par statut.](https://docs.wajub.com/dashboard/fr/light/transfers-list.webp) *Un clic sur En cours, Terminé ou Échoué filtre la liste.* Les filtres portent sur la **Date du transfert**, le **Statut**, le **Montant**, la **Devise**, le **Fournisseur** et la **Source** : API, **Tableau de bord**, **Récurrent**, Webhook ou **Tiers**. Le menu au bout d'une ligne propose **Ouvrir le transfert**, **Copier l'ID du transfert** et **Voir le bénéficiaire**. | Statut | Ce qu'il veut dire | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **En attente** | Créé, pas encore remis à l'opérateur ou à la banque. | | **En cours d'examen** | Retenu pour vérification par Wajub : [Suivre un transfert retenu](https://docs.wajub.com/dashboard/transfers/under-review). | | **En traitement** | Remis à l'opérateur ou à la banque, qui ne l'a pas encore confirmé, ou [en attente de son moyen de paiement](#cancel-a-waiting-transfer). | | **Réussi** | L'opérateur ou la banque a confirmé l'envoi. | | **Échoué**, **Annulée** | Rien n'est parti, et le montant revient au solde disponible. | ## La page d'un transfert L'en-tête donne le montant, le statut, l'**ID du transfert** à copier pour le support, puis le bénéficiaire, son **Moyen de paiement** et la source, sous **Envoyé depuis**. Un transfert échoué affiche **Transfert échoué** avec sa raison. Pour un virement bancaire, l'encadré **Virement bancaire** donne la date limite d'envoi par Wajub, puis, une fois le virement parti, sa date et la référence bancaire. Suivent les **Détails du transfert**, la **Répartition du montant**, où les frais s'ajoutent au montant reçu, et l'**Historique**, qui suit chaque étape et chaque tentative auprès d'un opérateur. En Production, le champ **Note interne** de l'historique laisse une consigne à l'équipe, avec **Ajouter une note** : seuls vos membres voient les notes. Le menu d'une note propose **Épingler la note**, qui la garde sous **Notes épinglées**, et **Supprimer la note**. ## Annuler un transfert en attente Quand son moyen de paiement est temporairement indisponible, un transfert reste **En traitement** et sa page affiche **En attente du moyen de paiement**, comme son **Historique**. Il part de lui-même dès le retour du moyen de paiement, et son montant reste réservé d'ici là. En Production, pour l'arrêter entre-temps, cliquez sur **Annuler le transfert** dans cet encadré. **Annuler ce transfert ?** demande confirmation : **Annuler le transfert** l'annule, **Continuer d'attendre** le laisse tel quel. Le transfert passe **Annulée**, le bénéficiaire ne reçoit rien, et son montant est de nouveau disponible sur votre solde. S'il est parti entre-temps, l'annulation est refusée et le transfert suit son cours. ## Exporter les transferts En Production, **Exporter**, en haut de la liste, ouvre **Exporter les transferts** : le fichier reprend les transferts que la liste affiche avec ses filtres. Pour n'en exporter que certains, cochez-les, jusqu'à 100, puis **Exporter** dans la barre du bas, qui ouvre **Exporter les transferts sélectionnés**. La même barre propose **Copier les identifiants**. Chaque export compte dans la limite mensuelle du forfait **Pay as you go**. --- # Suivre un transfert retenu URL: https://docs.wajub.com/fr/dashboard/transfers/under-review > Pourquoi Wajub retient un transfert pour vérification, ce que vous voyez pendant ce temps, ce qui se passe quand il est accepté ou rejeté, et comment confirmer un ancien transfert en attente. Avant de partir, un transfert peut être retenu pour une vérification par l'équipe Wajub. Il reste alors **En cours d'examen** jusqu'à sa décision, que le tableau de bord ne permet pas de prendre : c'est ce qui vous protège si votre propre compte est compromis. Tous ceux qui voient les transferts suivent un transfert retenu. Confirmer ou rejeter un ancien transfert **En attente de confirmation** demande **Gérer les transferts** et la Production, et seule la confirmation demande le code de sécurité. ## Pourquoi un transfert est retenu Wajub retient un transfert en Production, qu'il vienne du tableau de bord, d'un calendrier ou de votre intégration. Un premier transfert, ou un transfert bien au-dessus de vos montants habituels, est retenu pour vérification par Wajub, sur tous les comptes. Un transfert est aussi retenu dans ces cas : - une restriction posée par Wajub sur votre organisation, qui soumet ses transferts à vérification ; - **Retenir chaque transfert pour vérification** activé dans vos [paramètres généraux](https://docs.wajub.com/dashboard/transfers/settings#general-settings), sauf sous le montant choisi dans **Pas de vérification sous ce montant** ; - un montant égal ou supérieur à **Vérifier les transferts à partir de ce montant**, dans vos [paramètres de sécurité](https://docs.wajub.com/dashboard/transfers/settings#security-settings). ## Pendant la vérification Juste après l'envoi, la page du transfert s'ouvre sur « Ce transfert a été signalé et attend une vérification avant de pouvoir partir. ». Dans **Transferts**, le chiffre **En cours** indique combien de transferts sont retenus, par exemple « 2 en révision manuelle », et le filtre **Statut** les retrouve. Son montant reste réservé sur votre solde. Un transfert en cours d'examen n'est jamais annulé par le délai de [Transferts qui ne peuvent pas partir](https://docs.wajub.com/dashboard/transfers/settings#general-settings) : ce délai ne compte qu'à partir de son acceptation. ## La décision de Wajub Accepté, le transfert part vers l'opérateur ou la banque et passe **En traitement**, puis **Réussi**. Rejeté, il passe **Échoué**, et son montant revient au solde disponible. ## Confirmer un ancien transfert Quand la page d'un transfert affiche l'encadré **En attente de confirmation**, le transfert reste **En attente** jusqu'à ce que vous le confirmiez ou le rejetiez. **Confirmer le transfert** ouvre une fenêtre titrée avec le montant et le bénéficiaire, par exemple « Envoyer 150 000 FCFA à Kribi Coffee SARL ? », puis demande le code de sécurité. Le transfert passe alors les mêmes contrôles qu'un nouveau : il part, il est retenu à son tour pour vérification, ou il est refusé et continue d'attendre. **Rejeter le transfert** demande un **Motif du rejet**, sans code : le transfert passe **Annulée** et son montant revient au solde disponible. Sans réponse, il est annulé au bout du délai de **Transferts qui ne peuvent pas partir**. --- # Automatiser ses transferts URL: https://docs.wajub.com/fr/dashboard/use-cases/automatic-payouts > Recevoir votre argent sans y penser, en liant votre compte de versement puis en programmant un transfert du même montant chaque jour, chaque semaine ou chaque mois. Un transfert récurrent envoie le même montant de votre solde vers votre compte à date fixe : vous n'avez plus à penser à vous payer. Chaque étape renvoie à la page qui la détaille. Le propriétaire, un Administrateur ou un [rôle](https://docs.wajub.com/fr/dashboard#roles) personnalisé qui a **Voir les paramètres** et **Gérer les paramètres** fait tout ce parcours ; un membre Finance envoie des transferts à la main, mais ne crée ni compte de versement ni calendrier. Les transferts récurrents demandent le forfait **Growth** ou un forfait au-dessus. Tout se fait en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), et ajouter ou faire vérifier le compte comme créer le calendrier demandent le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les étapes 1. **Ajoutez votre compte de versement** Liez le numéro Mobile Money ou le compte bancaire qui recevra l'argent : [Lier un compte de versement](https://docs.wajub.com/dashboard/transfers/payout-accounts#the-steps). 2. **Faites vérifier le compte** Un transfert, récurrent ou non, ne part que vers un compte **Vérifié** : [Faire vérifier le compte](https://docs.wajub.com/dashboard/transfers/payout-accounts#verify-the-account). 3. **Choisissez un montant que votre solde couvre** Chaque envoi transfère le même montant, quelles que soient vos ventes : choisissez-le pour que votre solde disponible le couvre à chaque date, sinon l'envoi échoue. Voir [Quand une exécution échoue](https://docs.wajub.com/dashboard/transfers/recurring#when-a-run-fails). 4. **Programmez le transfert** Créez le calendrier avec ce compte, ce montant et la fréquence de votre choix : [Programmer des transferts](https://docs.wajub.com/dashboard/transfers/recurring#the-steps). 5. **Surveillez les envois** La liste des calendriers donne la prochaine exécution et le statut de la dernière ; un calendrier qui échoue plusieurs fois de suite se met en pause : [Suivre et modifier un calendrier](https://docs.wajub.com/dashboard/transfers/recurring#manage-a-schedule). --- # Facturer un client URL: https://docs.wajub.com/fr/dashboard/use-cases/bill-a-customer > Facturer un client en une fois, en plusieurs échéances ou chaque mois, laisser partir les rappels par e-mail et noter un paiement reçu en espèces ou par virement. Une facture s'adresse à un client précis, qui la reçoit par e-mail avec un lien pour la payer en ligne. Chaque étape renvoie à la page qui la détaille. Le propriétaire, un Administrateur, un membre Finance ou un [rôle](https://docs.wajub.com/fr/dashboard#roles) personnalisé qui a **Gérer les factures** fait tout ce parcours, en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Un membre Finance ouvre **Clients** mais saisit le client sur la facture : y ajouter un client demande **Gérer les clients**. Seuls le propriétaire et les Administrateurs rendent une facture récurrente, à partir du forfait **Growth** ; le forfait **Pay as you go** permet 10 factures en tout. Aucun [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est demandé. ## Les étapes 1. **Ajoutez le client** Ajoutez-le dans **Clients** : [Ajouter un client](https://docs.wajub.com/dashboard/customers/add). Vous pouvez aussi le saisir directement sur la facture. 2. **Créez la facture** Ouvrez **Factures › Créer une facture**, puis choisissez le client et ajoutez les lignes : [Créer et envoyer une facture](https://docs.wajub.com/dashboard/invoices/create#the-steps). 3. **Choisissez le rythme de paiement** Sous **Comment le client paie**, gardez **En un seul paiement**, ou choisissez **En plusieurs échéances** pour [répartir le total](https://docs.wajub.com/dashboard/invoices/installments). Pour facturer chaque mois, rendez la facture [récurrente](https://docs.wajub.com/dashboard/invoices/recurring) : chaque copie attend en brouillon que vous l'envoyiez. 4. **Envoyez la facture** Créez et envoyez la facture : le client reçoit le PDF et un bouton pour payer. [Ce que reçoit le client](https://docs.wajub.com/dashboard/invoices/create#what-the-customer-receives). 5. **Suivez la facture** La page de la facture dit ce qui est payé et ce qui reste dû. Avec une date d'échéance, le client est relancé par e-mail sans que vous ayez rien à faire : [Suivre et relancer une facture](https://docs.wajub.com/dashboard/invoices/track-and-remind). 6. **Notez un paiement reçu hors de Wajub** Si le client paie en espèces ou par virement, enregistrez-le sur la facture : [Enregistrer un paiement reçu](https://docs.wajub.com/dashboard/invoices/record-payment). --- # Vendre un produit numérique URL: https://docs.wajub.com/fr/dashboard/use-cases/digital-products > Vendre une formation, un e-book ou un fichier avec un lien de paiement, et laisser Wajub envoyer l'accès au client après chaque paiement. Un lien **Vendre quelque chose** de type **Contenu numérique** encaisse le paiement, puis envoie lui-même au client l'accès à votre formation, votre e-book ou votre fichier. Chaque étape renvoie à la page qui la détaille. Comme tout lien de paiement, il demande **Gérer les liens de paiement** ([rôles](https://docs.wajub.com/fr/dashboard#roles)) et la [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), sans [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). Un lien de téléchargement vers votre propre adresse marche avec tous les forfaits ; un fichier hébergé par Wajub demande le forfait **Growth** ou un forfait au-dessus. ## Les étapes 1. **Choisissez Contenu numérique** Créez un lien **Vendre quelque chose** de type **Contenu numérique**, ou partez du modèle **Formation en ligne ou e-book** : [Vendre quelque chose](https://docs.wajub.com/dashboard/payment-links/sell-something#the-steps). 2. **Choisissez comment le client reçoit le contenu** Sous **Comment le client le reçoit**, choisissez **Un lien de téléchargement** ou **Un fichier hébergé par Wajub**, et réglez la durée de l'accès : [Un contenu numérique](https://docs.wajub.com/dashboard/payment-links/sell-something#digital-content). 3. **Partagez le lien** Envoyez l'adresse à vos abonnés ou mettez un bouton sur votre site : [Partager un lien](https://docs.wajub.com/dashboard/payment-links/share). 4. **Suivez les ventes** L'onglet **Paiements** du lien liste chaque vente, et l'onglet **Clients** chaque acheteur : [Suivre un lien](https://docs.wajub.com/dashboard/payment-links/track#payments). --- # Collecter pour une cause URL: https://docs.wajub.com/fr/dashboard/use-cases/fundraising > Recevoir des dons ou financer un projet pour une association, une église ou une cause avec un lien de paiement, montrer les donateurs et raconter à quoi sert l'argent. Un lien de dons ou de collecte laisse chacun donner le montant qu'il choisit, et sa page peut montrer qui a déjà donné. Chaque étape renvoie à la page qui la détaille. Créer le lien, publier une actualité et exporter les donateurs demandent **Gérer les liens de paiement** ; toute personne qui voit les liens de paiement suit la collecte ([rôles](https://docs.wajub.com/fr/dashboard#roles)). Le forfait **Pay as you go** permet 25 liens. Tout se fait en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), sans [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les étapes 1. **Choisissez le type de lien** **Recevoir des dons** accepte des dons sans objectif, comme une offrande ou le soutien à une association ; **Collecter des fonds** vise un montant, avec une barre de progression et une date de fin si vous le voulez. Voir [Les quatre types de lien](https://docs.wajub.com/dashboard/payment-links/create#the-four-types). 2. **Créez le lien** Suivez [Recevoir des dons](https://docs.wajub.com/dashboard/payment-links/donations#the-steps) ou [Collecter des fonds](https://docs.wajub.com/dashboard/payment-links/raise-funds#the-steps). 3. **Montrez les donateurs** À la création, choisissez sous **Ce que montre la page** si les derniers donateurs et le total apparaissent. Sur un lien de dons, chacun peut aussi donner sans montrer son nom : [Les dons anonymes](https://docs.wajub.com/dashboard/payment-links/donations#anonymous-gifts). 4. **Partagez le lien** Envoyez l'adresse dans vos groupes ou imprimez le code QR pour le lieu de culte ou l'événement : [Partager un lien](https://docs.wajub.com/dashboard/payment-links/share#the-steps). 5. **Publiez des actualités** Racontez sur la page à quoi sert l'argent reçu : [Après la publication](https://docs.wajub.com/dashboard/payment-links/raise-funds#after-publishing). 6. **Suivez la collecte** La page du lien donne le montant réuni et le nombre de donateurs : [Suivre un lien](https://docs.wajub.com/dashboard/payment-links/track#what-the-link-gathered). 7. **Remerciez les donateurs** Exportez l'onglet **Donateurs** pour avoir le nom et l'e-mail de chacun, même ceux qui ont donné anonymement : [Les clients et l'export](https://docs.wajub.com/dashboard/payment-links/track#people-and-export). --- # Préparer sa comptabilité URL: https://docs.wajub.com/fr/dashboard/use-cases/monthly-accounting > Exporter chaque mois les paiements, les remboursements, les transferts et les factures, le rapport des revenus et les factures Wajub à remettre à votre comptable. Une fois par mois, réunissez en quelques fichiers ce que votre comptable demande : ce que vous avez encaissé, remboursé, transféré et facturé, et ce que Wajub vous a facturé. Chaque étape renvoie à la page qui la détaille. Les exports n'existent qu'en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Le propriétaire, un Administrateur ou un membre Finance fait tous ceux de cette page ; un Analyste n'y fait que celui des revenus ([rôles](https://docs.wajub.com/fr/dashboard#roles)). Les factures Wajub demandent **Gérer le compte** : le propriétaire, un Administrateur ou un rôle personnalisé qui l'a. Avec le forfait **Pay as you go**, chaque export compte dans la limite de 10 par mois, tous exports du tableau de bord confondus, et ce parcours en utilise jusqu'à cinq. Aucun [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code) n'est demandé. ## Les étapes 1. **Exportez les paiements du mois** Exportez la liste **Paiements** avec pour période le premier et le dernier jour du mois : [Exporter des paiements](https://docs.wajub.com/dashboard/payments/find#export). 2. **Exportez les remboursements** Faites de même dans l'onglet **Remboursements** : [Exporter les remboursements](https://docs.wajub.com/dashboard/payments/track-refunds#export). 3. **Exportez les transferts** Filtrez **Transferts** sur la **Date du transfert** du mois, puis exportez : [Exporter les transferts](https://docs.wajub.com/dashboard/transfers/track#export-transfers). 4. **Exportez vos factures** Si vous facturez vos clients, exportez les factures du mois : [Exporter les factures](https://docs.wajub.com/dashboard/invoices/export-and-bulk#export-invoices). 5. **Exportez le rapport des revenus** Dans **Revenus**, réglez la **Période** sur le mois, puis exportez **Vue d'ensemble** en Excel ou en PDF : [Suivre ses revenus](https://docs.wajub.com/dashboard/home/revenue#export-a-report). 6. **Téléchargez vos factures Wajub** Récupérez les factures de votre forfait et de votre usage : [Télécharger une facture](https://docs.wajub.com/dashboard/subscription/wajub-invoices#download-an-invoice). --- # Organiser un événement URL: https://docs.wajub.com/fr/dashboard/use-cases/paid-event > Vendre les places d'un concert, d'une formation ou d'un gala avec un lien de paiement, suivre les ventes et contrôler les entrées avec la liste des participants. Un lien **Vendre des billets** vend vos places en ligne et garde la liste des participants pour le jour de l'événement. Chaque étape renvoie à la page qui la détaille. Créer, exporter et archiver le lien demandent **Gérer les liens de paiement** ; toute personne qui voit les liens de paiement suit les ventes ([rôles](https://docs.wajub.com/fr/dashboard#roles)). Le forfait **Pay as you go** permet 25 liens. Tout se fait en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), sans [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les étapes 1. **Créez le lien de billetterie** Créez un lien **Vendre des billets** avec vos types de places : [Vendre des billets](https://docs.wajub.com/dashboard/payment-links/sell-tickets#the-steps). 2. **Demandez le nom des participants** Pour contrôler les entrées par nom, demandez au moins le nom de chaque participant à la création du lien, à l'étape « Demandez les informations des participants » de [Vendre des billets](https://docs.wajub.com/dashboard/payment-links/sell-tickets#the-steps). 3. **Partagez le lien** Envoyez l'adresse par WhatsApp ou SMS, ou imprimez le code QR du lien sur vos affiches : [Partager un lien](https://docs.wajub.com/dashboard/payment-links/share#the-steps). 4. **Suivez les ventes** La page du lien compte les billets vendus et ceux qui restent : [Suivre un lien](https://docs.wajub.com/dashboard/payment-links/track#what-the-link-gathered). 5. **Exportez la liste des participants** La veille, exportez l'onglet **Participants** pour avoir la liste à l'entrée : [Le jour de l'événement](https://docs.wajub.com/dashboard/payment-links/sell-tickets#on-the-day). Wajub n'envoie pas de message groupé aux acheteurs ; pour leur écrire, servez-vous des e-mails de cet export. 6. **Contrôlez les entrées avec la liste** Wajub ne scanne pas les billets : à l'entrée, retrouvez chaque acheteur dans la liste. Un achat de plusieurs places reçoit un seul code QR, alors vérifiez dans la liste combien de places il couvre. Voir [Le jour de l'événement](https://docs.wajub.com/dashboard/payment-links/sell-tickets#on-the-day). 7. **Archivez le lien** Après l'événement, [archivez le lien](https://docs.wajub.com/dashboard/payment-links/edit-offline-delete#offline-or-archive) pour le retirer de la liste des liens. --- # Vendre sur les réseaux URL: https://docs.wajub.com/fr/dashboard/use-cases/social-selling > Vendre un article, un fichier ou un service dans une conversation WhatsApp ou une publication Facebook ou Instagram avec un lien de paiement, puis livrer et récupérer l'argent. Un lien de paiement donne à ce que vous vendez une page où payer : vous collez son adresse dans une conversation, une publication ou votre bio, et le client paie depuis son téléphone. Chaque étape renvoie à la page qui la détaille. Créer le lien et exporter ses clients demandent **Gérer les liens de paiement**, et le forfait **Pay as you go** permet 25 liens. Pour récupérer l'argent, un membre Finance envoie le transfert, mais seuls le propriétaire, un Administrateur ou un [rôle](https://docs.wajub.com/fr/dashboard#roles) personnalisé qui a **Voir les paramètres** et **Gérer les paramètres** ajoutent le compte de versement. Tout se fait en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live), et le compte comme le transfert demandent le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les étapes 1. **Créez le lien** Créez un lien **Vendre quelque chose**, en **Article physique**, **Contenu numérique** ou **Service** selon ce que vous vendez : [Vendre quelque chose](https://docs.wajub.com/dashboard/payment-links/sell-something). 2. **Partagez l'adresse** Envoyez l'adresse dans la conversation ou la publication depuis la fenêtre de partage : [Partager un lien](https://docs.wajub.com/dashboard/payment-links/share#the-steps). Instagram n'y figure pas : copiez l'adresse et collez-la dans votre bio, une story ou un message. 3. **Vérifiez le paiement avant de livrer** Livrez quand le paiement apparaît **Réussi** dans l'onglet **Paiements** du lien, jamais sur la foi d'une capture d'écran envoyée par le client : [Suivre un lien](https://docs.wajub.com/dashboard/payment-links/track#payments). 4. **Exportez les commandes** Pour un article livré, exportez l'onglet **Clients** du lien : le fichier donne l'adresse de livraison de chaque acheteur. Voir [Les clients et l'export](https://docs.wajub.com/dashboard/payment-links/track#people-and-export). 5. **Ajoutez un compte de versement** Liez le numéro Mobile Money ou le compte bancaire qui recevra l'argent : [Lier un compte de versement](https://docs.wajub.com/dashboard/transfers/payout-accounts). 6. **Envoyez-vous l'argent** Transférez votre solde vers ce compte : [Envoyer un transfert](https://docs.wajub.com/dashboard/transfers/send). Pour ne plus le faire à la main, [automatisez vos transferts](https://docs.wajub.com/dashboard/use-cases/automatic-payouts). --- # Travailler avec son équipe URL: https://docs.wajub.com/fr/dashboard/use-cases/team-and-accountant > Inviter vos collaborateurs et votre comptable avec le rôle qui correspond à leur travail, et savoir ce que chacun peut voir et exporter. Chaque personne qui travaille avec vous entre dans l'organisation par une invitation, avec un rôle qui fixe ce qu'elle voit et ce qu'elle peut faire. Chaque étape renvoie à la page qui la détaille. Le propriétaire, un Administrateur ou un [rôle](https://docs.wajub.com/fr/dashboard#roles) personnalisé qui a **Gérer les membres** et **Voir les paramètres** invite et gère les membres, en [Test comme en Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Le forfait limite le nombre de membres : voir [Inviter et gérer les membres](https://docs.wajub.com/dashboard/settings/members). Inviter, changer un rôle et retirer un membre demandent le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les étapes 1. **Choisissez le rôle de chacun** **Finance** convient à qui encaisse, facture et envoie les transferts, **Spécialiste support** à qui répond aux clients et rembourse, **Analyste** à qui lit les chiffres sans rien modifier : [Rôles](https://docs.wajub.com/fr/dashboard#roles). 2. **Créez un rôle sur mesure si besoin** Si aucun des sept rôles ne convient, réunissez les permissions voulues dans un rôle personnalisé : [Créer un rôle personnalisé](https://docs.wajub.com/dashboard/settings/roles). 3. **Invitez la personne** Envoyez l'invitation avec le rôle choisi : [Inviter et gérer les membres](https://docs.wajub.com/dashboard/settings/members#the-steps). 4. **Suivez l'invitation** Tant que la personne n'a pas accepté, l'invitation reste en attente : [Les invitations en attente](https://docs.wajub.com/dashboard/settings/members#pending-invitations). 5. **Changez un rôle quand le travail change** Changez le rôle d'un membre ou retirez-le de l'organisation : [Changer un rôle ou retirer un membre](https://docs.wajub.com/dashboard/settings/members#change-a-role-or-remove-a-member). ## Le rôle de votre comptable Un **Analyste** lit les paiements, les transferts, les factures et les revenus, et exporte le rapport des [Revenus](https://docs.wajub.com/dashboard/home/revenue#export-a-report). Il n'exporte ni les paiements, ni les remboursements, ni les transferts, ni les factures : ces exports demandent **Gérer les paiements**, **Gérer les transferts** et **Gérer les factures**. Un membre **Finance** a les trois, mais **Gérer les transferts** lui permet aussi d'envoyer de l'argent. Pour un comptable qui ne doit rien envoyer, faites les exports vous-même : [Préparer sa comptabilité](https://docs.wajub.com/dashboard/use-cases/monthly-accounting). Les factures Wajub, celles de votre forfait, ne se téléchargent qu'avec **Gérer le compte**, qui permet aussi de [changer de forfait](https://docs.wajub.com/dashboard/subscription/plans) : ni Finance ni Analyste ne l'a, alors téléchargez-les vous-même. --- # Encaisser sur son site URL: https://docs.wajub.com/fr/dashboard/use-cases/website-button > Mettre un bouton de paiement sur votre site sans développeur, en copiant son code depuis un lien de paiement, puis lui donner votre marque et votre domaine. Un lien de paiement fournit le code d'un bouton à coller dans votre site, sur Systeme.io, WordPress, Wix, Webflow ou Shopify : le client paie sans que personne écrive de code. Chaque étape renvoie à la page qui la détaille. Créer le lien demande **Gérer les liens de paiement**, mais toute personne qui voit les liens de paiement copie le code du bouton, en [Production](https://docs.wajub.com/fr/dashboard#sandbox-and-live). Déclarer le site, régler la marque, connecter le domaine et le choisir pour vos liens (en Production) demandent **Gérer les paramètres**, qu'ont le propriétaire et les Administrateurs ; un Développeur peut aussi déclarer le site et connecter le domaine ([rôles](https://docs.wajub.com/fr/dashboard#roles)). La marque demande le forfait **Growth** ou un forfait au-dessus, le domaine **Scale** ou **Enterprise**. Seul l'enregistrement des sites déclarés demande le [code de sécurité](https://docs.wajub.com/fr/dashboard#the-security-code). ## Les étapes 1. **Créez le lien** Créez le lien de ce que vous vendez : [Créer un lien de paiement](https://docs.wajub.com/dashboard/payment-links/create). 2. **Préparez le bouton** Sur la page du lien, ouvrez **Partager le lien**, puis l'onglet **Bouton pour votre site**, et choisissez **Par-dessus votre site** ou **Sur la page de paiement** : [Le bouton pour votre site](https://docs.wajub.com/dashboard/payment-links/share#button-for-your-site). 3. **Collez le code dans votre site** Choisissez **Copier**, puis collez le code dans un bloc HTML de votre site et publiez la page. Voir [Le bouton pour votre site](https://docs.wajub.com/dashboard/payment-links/share#button-for-your-site). 4. **Déclarez votre site** Ajoutez l'adresse de votre site dans [Les sites qui affichent la page](https://docs.wajub.com/dashboard/settings/checkout-page#embedding) : la fenêtre **Par-dessus votre site** s'ouvre alors sur vos sites, et sur aucun autre. 5. **Mettez votre marque** Donnez votre logo et vos couleurs à la page de paiement : [Personnaliser votre marque](https://docs.wajub.com/dashboard/settings/branding). 6. **Connectez votre domaine** Servez la page de paiement sur une adresse à vous, comme pay.example.com : [Connecter votre domaine](https://docs.wajub.com/dashboard/settings/custom-domains). 7. **Choisissez ce domaine pour vos liens** Une fois le domaine vérifié, choisissez-le pour vos liens de paiement : [Choisir le domaine des liens](https://docs.wajub.com/dashboard/payment-links/settings). --- # API directe URL: https://docs.wajub.com/fr/payments/direct-api > Débitez un paiement depuis votre serveur, sur le canal choisi, sans page Wajub. Avec l'API directe, c'est vous qui affichez chaque écran : votre serveur débite le paiement sur le canal choisi, et Wajub vous communique le résultat. Il faut deux appels, `POST /payments` pour enregistrer le paiement et `POST /payments/{id}` pour le débiter. > [!CAUTION] > **Cet appel a sa place sur votre serveur** > > Envoyez-le avec votre clé privée, depuis votre backend. N'utilisez jamais une clé `sk.…` depuis un > navigateur : Wajub la refuse avec un `403`. Si votre écran de paiement vit dans un > navigateur, utilisez plutôt les [Composants intégrés](https://docs.wajub.com/fr/libraries/components). ## 1. Créez le paiement Créez le paiement comme le montre le [guide de démarrage des paiements](https://docs.wajub.com/fr/payments/quickstart#1-create-the-payment). Conservez `transaction.id` dans la réponse. Vous n'utiliserez pas `authorization_url`, qui sert à la page hébergée. Conservez aussi `authorization_token` si vous débitez un canal dont le prestataire demande un code au payeur : c'est l'identifiant qui [confirme cette étape](#a-code-or-another-detail), et il n'est renvoyé qu'à la création. Le paiement est `pending`, et personne n'a encore été débité. ## 2. Débitez-le `POST /payments/{id}` - `channel` (string, required): Où débiter : un identifiant de canal renvoyé par `GET /channels`, comme `cm.mtn` ou `cm.orange`. Envoyez `mobile`, ou `cm.mobile` pour le Cameroun, pour laisser Wajub trouver l'opérateur à partir du numéro. Ce sont les deux seuls agrégats. - `data.phone` (string): Le numéro Mobile Money à débiter. Le format international est le plus sûr ; un numéro local est lu dans le pays du canal. - `data.operator` (string): Avec `cm.mobile` uniquement : l'opérateur choisi par le payeur, par exemple `orange`. Utilisé quand le numéro seul ne permet pas à Wajub de savoir à quel opérateur il appartient, un numéro porté par exemple. - `data.otp` (string): Le code que le payeur a généré dans le menu de son opérateur, pour un canal qui a répondu `payer_otp` : des chiffres uniquement. Voir [Un code que le payeur génère](#a-code-the-payer-generates). - `data.iban` (string): Pour un canal bancaire. `data.account_number` est accepté à la place. - `data.wallet_address` (string): Pour un canal crypto. - `data.save_payment_method` (boolean): Enregistre ce moyen de paiement sur le client, pour le lui proposer la prochaine fois. Uniquement avec l'accord du payeur. Vaut `false` par défaut. Chaque champ de `data` est aussi accepté à la racine du corps. Envoyez un en-tête `Idempotency-Key` propre à ce débit, pour qu'une nouvelle tentative après un délai dépassé ne débite jamais deux fois. **Débiter un paiement sur MTN Mobile Money** ```bash curl https://api.wajub.com/payments/trx_test_CSUGajfv9xh0XQ5wu2lx \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: charge-order-4172-1" \ -d '{ "channel": "cm.mtn", "data": { "phone": "+237670000000" } }' ``` ```javascript const payment = await wajub.payments.process( 'trx_test_CSUGajfv9xh0XQ5wu2lx', { channel: 'cm.mtn', data: { phone: '+237670000000' }, }, { idempotencyKey: 'charge-order-4172-1' }, ); console.log(payment.status); ``` ```python from wajub import RequestOptions payment = wajub.payments.process( "trx_test_CSUGajfv9xh0XQ5wu2lx", { "channel": "cm.mtn", "data": {"phone": "+237670000000"}, }, RequestOptions(idempotency_key="charge-order-4172-1"), ) print(payment.status) ``` ```php use Wajub\RequestOptions; $payment = $wajub->payments->process('trx_test_CSUGajfv9xh0XQ5wu2lx', [ 'channel' => 'cm.mtn', 'data' => [ 'phone' => '+237670000000', ], ], new RequestOptions(idempotencyKey: 'charge-order-4172-1')); echo $payment->status; ``` ```go payment, err := client.Payments.Process(context.Background(), "trx_test_CSUGajfv9xh0XQ5wu2lx", map[string]any{ "channel": "cm.mtn", "data": map[string]any{"phone": "+237670000000"}, }, &wajub.RequestOptions{IdempotencyKey: "charge-order-4172-1"}) if err != nil { log.Fatal(err) } log.Println(payment.Status) ``` ## La réponse Pour le Mobile Money, la réponse est presque toujours `202 Accepted`. La demande est sur le téléphone du payeur, le paiement est passé en `processing`, et `message` est la phrase à afficher pendant l'attente : ```json title="Réponse · 202 Accepted" { "code": 202, "status": "Accepted", "message": "Confirm the transaction on your phone.", "transaction": { "id": "trx_test_CSUGajfv9xh0XQ5wu2lx", "reference": "order-4172", "amount": 5000, "currency": "XAF", "status": "processing", "channel": "cm.mtn", "sandbox": true } } ``` Le résultat arrive plus tard, sous la forme d'un webhook `payment.succeeded` ou `payment.failed`. Avant de livrer la commande, [récupérez le paiement](https://docs.wajub.com/fr/payments/quickstart#3-verify-before-you-fulfil) et lisez son `status`, comme dans tous les autres modes. | Code | Ce qu'il signifie | Que faire | | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | Le canal a confirmé tout de suite. Le paiement est `succeeded` | Vérifiez, puis livrez | | `202` | En attente du payeur, ou d'une étape suivante indiquée dans `action` | Affichez `message`, terminez l'étape indiquée dans `action` s'il y en a une, attendez le webhook | | `400` | Le paiement ne peut plus être débité : il a déjà réussi, expiré ou été annulé, ou, en live, son `expires_at` est passé | Créez un nouveau paiement si besoin | | `402` | L'opérateur ou l'émetteur de la carte a refusé. Le paiement repasse en `pending`. Aussi `error_code: merchant_not_verified` tant que la vérification de votre compte est en cours, et `otp_attempts_exceeded` une fois que l'opérateur a refusé trois codes du payeur sur le canal | Laissez le payeur réessayer, voir plus bas. Pour `merchant_not_verified`, terminez votre vérification | | `403` | Refusé par une restriction sur votre compte, ou par [Shield](https://docs.wajub.com/fr/risk/shield). Un blocage Shield porte `error_code: shield_blocked` et sa référence `BLK-…` dans `block_reference` | Ne relancez pas la même tentative | | `404` | Aucun paiement avec cet id, dans cet environnement | Vérifiez l'id et la clé | | `409` | Un débit est déjà en cours sur ce paiement (`error_code: payment_in_progress`), un appel avec la même `Idempotency-Key` est encore en cours, ou le paiement a été préparé et sa commande n'est pas encore validée | Attendez l'issue de la tentative en cours, par webhook ou en relisant le paiement. Débitez de nouveau une fois qu'il est revenu à `pending`, ou `processing` sans plus aucun débit en cours | | `422` | Le canal n'est pas accepté, le numéro ne correspond pas à l'opérateur, le montant dépasse le plafond du canal, ou l'`Idempotency-Key` a déjà servi pour une autre requête | Corrigez la requête. Une clé réutilisée demande une nouvelle clé pour un nouveau débit | Un `402` porte `error_code`, un motif stable comme `insufficient_funds` que vous pouvez traduire pour le payeur, et `limit_exceeded` quand le paiement dépasserait l'un des plafonds de votre compte. ## Quand `action` est renseigné La plupart des débits Mobile Money n'attendent rien de plus de votre part : `action` est absent et vous attendez le webhook. Quand le prestataire derrière le canal veut d'abord que le payeur fasse quelque chose, la réponse reste un `202`, `action` nomme cette étape, et la réponse porte ce dont l'étape a besoin. | `action` | Ce que fait le payeur | Ce que porte la réponse | | --------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `redirect` | Il approuve le paiement sur la page du prestataire ou dans son application | `action_url`, l'adresse où envoyer le payeur | | `confirm_otp` | Il saisit le code que le prestataire lui a envoyé | `otp_id`, et `otp_masked_contact`, où le code est parti, masqué, ou vide quand le prestataire ne le dit pas | | `payer_otp` | Il génère un code dans le menu de son opérateur, puis vous le donne | `payer_otp`, comment obtenir le code. Débitez de nouveau avec lui dans `data.otp` | | `confirm_pin`, `confirm_phone`, `confirm_birthday`, `confirm_address` | Il donne une information de plus au prestataire | `pin_id` et `pin_instruction`, ou la même paire au nom de `phone`, `birthday` ou `address` | | `client_session` | Il paie dans une fenêtre que le prestataire gère lui-même | `client_session`, avec son `id` et, quand le prestataire a sa propre page, `hosted_url` | | `confirm` | Il suit la consigne donnée dans `message` | Rien de plus en live. En sandbox, un canal crypto ajoute `crypto.deposit` | | `confirm_3ds` | Il s'authentifie auprès de l'émetteur de la carte | Rien à gérer de votre côté : cette étape se passe dans la page de paiement ou les composants, une raison de plus d'y traiter les cartes | L'étape peut changer d'un paiement à l'autre sur un même canal : lisez donc `action` à chaque `202`, au lieu d'en supposer une par canal. ### Une redirection Wave fonctionne ainsi : le payeur approuve dans l'application Wave, pas sur une demande reçue sur son téléphone. Les canaux crypto aussi en live, où la page du prestataire affiche l'adresse et le montant à envoyer. ```json title="Réponse · 202 Accepted, avec une redirection" { "code": 202, "status": "Accepted", "message": "Open Wave to confirm your payment.", "action": "redirect", "transaction": { "id": "trx_CSUGajfv9xh0XQ5wu2lx", "amount": 5000, "currency": "XOF", "status": "processing", "channel": "ci.wave" }, "action_url": "https://pay.wave.com/c/cos-0example00" } ``` Envoyez le payeur vers `action_url` : une redirection dans un navigateur, un lien ou un bouton dans une application. Quand il a terminé, le prestataire le ramène vers le `callback` du paiement, si vous en avez défini un. Le résultat arrive toujours par webhook, et vous vérifiez toujours le paiement avant de livrer. ### Un code, ou une autre information Avec `confirm_otp`, le prestataire a envoyé un code au payeur. Recueillez-le sur votre propre écran, puis envoyez-le depuis votre serveur à [`POST /payments/{id}/confirm`](https://docs.wajub.com/fr/api/payments/confirm), avec votre clé secrète, l'`otp_id` de la réponse et le code. ```bash title="Confirmer le code reçu par le payeur" curl https://api.wajub.com/payments/trx_CSUGajfv9xh0XQ5wu2lx/confirm \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Idempotency-Key: confirm-order-1042" \ -H "Content-Type: application/json" \ -d '{ "otp_id": "prc_2b4l4EObTOnOa501JXNi", "code": "482913" }' ``` La réponse est celle du débit. `200` quand le paiement est payé. `202` quand le prestataire demande une étape de plus : `action` la nomme, avec ce qu'il lui faut, comme sur le débit. `402` quand le prestataire a refusé ce qui a été envoyé : `error_code` dit pourquoi (`invalid_otp`, ou `max_attempts_exceeded` une fois les trois essais de l'étape épuisés) et `attempts_remaining` compte les essais restants. Quand il n'en reste aucun, débitez le paiement à nouveau. Envoyez une `Idempotency-Key` : un appel rejoué répond alors ce qu'a répondu le premier, sans envoyer le code deux fois au prestataire. Les quatre autres étapes passent par le même appel, avec leurs propres champs. Chaque champ `…_instruction` de la réponse du débit est la formulation du prestataire lui-même pour ce qu'il demande. | `action` | Corps de `POST /payments/{id}/confirm` | | ------------------ | ---------------------------------------------------- | | `confirm_otp` | `otp_id`, `code` | | `confirm_pin` | `pin_id`, `pin` | | `confirm_phone` | `phone_id`, `phone` | | `confirm_birthday` | `birthday_id`, `birthday` au format `YYYY-MM-DD` | | `confirm_address` | `address_id`, `address`, `city`, `state`, `zip_code` | Chaque étape permet trois essais, qu'elle soit confirmée depuis votre intégration ou depuis la page de paiement. ### Un code que le payeur génère Quelques opérateurs, comme Orange Money au Burkina Faso, n'acceptent un paiement qu'avec un code que le payeur génère d'abord dans le menu de son opérateur. Sans lui, ou avec un code que l'opérateur refuse, rien n'est débité : la réponse est un `202` avec `action: payer_otp`, le paiement reste `pending`, et `payer_otp` indique comment obtenir le code : `ussd_code` à composer, `amount` et `currency`, le montant exact à saisir, `otp_length`, les étapes dans `steps.fr` et `steps.en`, `reason` (`required`, `invalid` ou `refused`) et `attempts_remaining`. `ussd_code` et `otp_length` peuvent valoir `null`, et chaque étape est un objet dont le `text` est ce qu'il faut afficher. Avec `invalid` ou `refused`, la réponse porte aussi `error_code: invalid_otp`. Affichez les étapes et `payer_message`, recueillez le code, puis débitez de nouveau le paiement sur le même canal avec le code dans `data.otp` et une nouvelle `Idempotency-Key`. Une fois que l'opérateur a refusé trois codes sur ce canal, le débit répond `402` avec `error_code: otp_attempts_exceeded` : le payeur paie avec un autre canal. ### La fenêtre du prestataire Avec `client_session`, le prestataire encaisse le paiement lui-même. Quand `client_session.hosted_url` est présent, envoyez-y le payeur comme pour une redirection. À son retour, appelez `POST /payments/{id}/confirm` avec `client_session_id` égal à `client_session.id`. Il répond comme le débit, `202` tant que le résultat n'est pas définitif. Un prestataire qui ne propose qu'un widget dans la page, sans `hosted_url`, est fait pour les [Composants intégrés](https://docs.wajub.com/fr/libraries/components), qui l'ouvrent pour vous. ## Laisser Wajub trouver l'opérateur Avec `channel` à `mobile`, ou à `cm.mobile` pour le Cameroun, Wajub lit l'opérateur à partir du numéro et débite dessus : `+23767…` part sur `cm.mtn`. Ce sont les deux seuls agrégats : un autre pays se débite sur le canal de son opérateur, comme `ci.orange`. Quand le numéro ne peut pas être attribué, un numéro porté par exemple, Wajub utilise `data.operator` si vous l'avez envoyé avec `cm.mobile`, et répond `422` sinon. Avec un canal précis comme `cm.mtn`, le numéro doit appartenir à cet opérateur. Un numéro Orange envoyé sur `cm.mtn` est refusé avec un `422` qui indique le bon canal, au lieu d'être débité sur le mauvais réseau. Certains canaux portent le nom d'un portefeuille, pas celui d'un opérateur. Wave (`ci.wave`, `sn.wave`), Express Union (`cm.eu`), Djamo (`ci.djamo`, `sn.djamo`), Capitec Pay (`za.capitec`), OPay (`ng.opay`) et PalmPay (`ng.palmpay`) se détiennent quel que soit l'opérateur du payeur : tout numéro y est accepté. Les autres portefeuilles appartiennent à un opérateur et prennent un numéro de cet opérateur : `ke.mpesa` un numéro Safaricom, `tz.mpesa` et `mz.mpesa` un numéro Vodacom, `tg.tmoney` un numéro Togocel, `gh.vodafone` un numéro Telecel. Un agrégat envoie un tel numéro sur le portefeuille. [Formats de numéros de téléphone](https://docs.wajub.com/fr/payments/payment-methods/phone-numbers#how-the-operator-is-identified) liste chaque portefeuille et l'opérateur derrière lui. Sur un paiement créé avec [`accept`](https://docs.wajub.com/fr/payments/payment-methods#choosing-what-a-payment-accepts), un agrégat est jugé d'après l'opérateur que donne le numéro : `cm.mobile` avec un numéro MTN est accepté partout où `cm.mtn` l'est. ## Réessayer après un refus Un `402` laisse le paiement en `pending` : le même paiement peut donc être débité de nouveau, avec un autre numéro, un autre opérateur, ou le même une fois que le payeur a rechargé son compte. Utilisez une **nouvelle** `Idempotency-Key` pour cette nouvelle tentative. Renvoyer la première clé renvoie la première réponse, le `402`, sans rien retenter. La même clé reste la bonne après un délai dépassé ou une erreur réseau, quand vous ne savez pas si le premier appel est passé. ## Cartes Le mode live refuse les données de carte brutes : un numéro de carte ou un code de sécurité dans le corps reçoit un `422` avec `error_code: raw_card_data_not_accepted`, avant tout débit. Les cartes se saisissent dans le [Checkout hébergé](https://docs.wajub.com/fr/payments/hosted-checkout), les [Composants intégrés](https://docs.wajub.com/fr/libraries/components) ou un SDK mobile, qui les collectent de façon sécurisée. La sandbox accepte `channel: card` avec les cartes de test publiées uniquement, pour que vous puissiez dérouler tout le parcours. Tout autre numéro de carte y est refusé aussi. Un débit par carte en sandbox prend quatre champs dans `data`, chacun refusé par un `422` à son nom s'il manque ou est mal formé : | Champ | Ce qu'il contient | | ------------- | ------------------------------------------------------------------------------------------------ | | `card.number` | Une [carte de test](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios#cards). Le numéro décide du résultat | | `card.holder` | Le nom sur la carte. `card_holder` est accepté aussi | | `exp` | L'expiration au format `MM/AA` ou `MM/AAAA`, une année de celle-ci à trente ans plus tard | | `cvc` | Trois ou quatre chiffres | Les deux clés `card.` sont des noms qui contiennent un point, pas un objet imbriqué : `"data": {"card.number": "4242424242424242", "card.holder": "Amina Diallo", "exp": "12/30", "cvc": "123"}`. ## En sandbox Les six derniers chiffres du numéro de téléphone décident du résultat, comme sur la page hébergée. `…000000` réussit ; `…000001` est refusé tout de suite comme le live refuse : un `402` avec `error_code: insufficient_funds`, et le paiement reste `pending`. Le tableau complet est dans [Scénarios de test](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios). La sandbox ne répond jamais `redirect`, `confirm_otp` ni `client_session` : ces étapes n'arrivent qu'en live. Elle répond sans `action` pour le Mobile Money et les canaux bancaires, `confirm_3ds` pour une carte de test 3-D Secure, et `confirm` avec `crypto.deposit`, l'adresse et le montant à envoyer, pour un canal crypto. Orange Money au Burkina Faso (`bf.orange`) demande le code du payeur avec `payer_otp`, comme en live, et accepte `123456`. L'API directe est disponible sur tous les plans, en sandbox comme en live. Le découpage d'un paiement en plusieurs versements, avec [`POST /payments/{id}/splits`](https://docs.wajub.com/fr/api/payments/splits), fonctionne dans les deux, sur les canaux Mobile Money en live : [Paiements fractionnés](https://docs.wajub.com/fr/sync/split-payments) le décrit. - [Choisir son intégration](https://docs.wajub.com/fr/payments/integration-paths): Les quatre modes comparés, et quand l'API directe est le bon choix. - [Numéros de téléphone](https://docs.wajub.com/fr/payments/payment-methods/phone-numbers): Les formats qu'un numéro peut prendre, et comment l'opérateur est trouvé. - [Cycle de vie d'un paiement](https://docs.wajub.com/fr/payments/lifecycle): Chaque statut que traverse un paiement, et le webhook de chacun. - [Référence API](https://docs.wajub.com/fr/api/payments/process): Chaque champ de POST /payments/{id}. --- # Checkout hébergé URL: https://docs.wajub.com/fr/payments/hosted-checkout > La page que Wajub affiche à votre client, ce qu'elle prend en charge et ce que vous contrôlez. Le checkout hébergé est le chemin le plus court vers un paiement qui fonctionne. Vous créez le paiement, vous envoyez le client vers la page affichée par Wajub, et vous vérifiez le résultat à son retour. > [!TIP] > **Le code d'intégration** > > Le code d'une redirection, d'une iframe intégrée ou d'une fenêtre superposée se trouve dans [Wajub > Components → Checkout hébergé](https://docs.wajub.com/fr/libraries/components/hosted-checkout). ## Créer le paiement Tout ce dont la page a besoin vient de l'appel de création. Envoyez-le depuis votre serveur avec la clé secrète : la clé publique crée aussi des paiements, mais elle existe pour le cas où l'appel est fait depuis un navigateur. `POST /payments` - `amount` (number, required): Montant dans l'unité principale de la devise. Les décimales sont acceptées, donc `10.50` vaut dix dollars cinquante. En XAF et XOF, le paiement doit être compris entre 25 et 2 000 000. - `currency` (string, required): Code ISO 4217 : XAF, XOF, NGN, GHS, KES et le reste de la liste prise en charge. - `customer` (object): Identité du payeur : `email`, `phone`, `name`, ainsi que `address` et `metadata`. Au moins un des champs `customer`, `email`, `phone` ou `customer_id` est obligatoire, et l'objet est la forme qui évolue avec vous. - `description` (string): Un libellé unique affiché au client sur la page. Vaut « Payment » par défaut. - `items` (array): Lignes de commande affichées sur la page, chacune avec un `name`, une `description` et une `quantity`. Elles sont affichées, jamais additionnées : `amount` reste le montant que vous débitez. - `callback` (string (url)): Où le client est envoyé ensuite, quelle que soit l'issue : succès, échec, annulation ou expiration, distinguées par `status` dans les paramètres de l'URL. Doit être en HTTPS ; `http://localhost` et `http://127.0.0.1` sont acceptés en sandbox. Toute autre adresse reçoit un `422`. Si vous l'omettez, il reste sur une page de confirmation Wajub, et le webhook est alors votre seul signal. - `reference` (string): Votre propre numéro de commande. Il revient à chaque lecture et dans l'URL de retour. Il n'est soumis à aucune contrainte d'unicité, ce n'est donc pas lui qui empêche un double débit. - `expires.in` (integer): Durée pendant laquelle la page reste utilisable, en minutes, de 5 à 43 200. Vaut 1 440 par défaut, soit 24 heures. - `bearer` (string): Qui paie les frais Wajub : `merchant` par défaut, ou `customer`, qui ajoute les frais au montant et affiche le détail sur la page. - `accept` (object): Réduit les moyens de paiement proposés, par `countries`, `channels`, `types` et `currencies`. Si vous l'omettez, tous les moyens sur lesquels vous pouvez encaisser sont affichés. Voir [Choisir ce qu'un paiement accepte](https://docs.wajub.com/fr/payments/payment-methods#choosing-what-a-payment-accepts). - `metadata` (object): Paires clé-valeur libres, renvoyées lors des lectures et dans les webhooks. Un appel de création qui utilise les champs propres à la page hébergée ressemble à ceci : **Créer un paiement pour la page hébergée** ```bash curl https://api.wajub.com/payments \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 25000, "currency": "XAF", "customer": { "email": "amina@example.com", "name": "Amina N." }, "description": "Order #4172", "reference": "order-4172", "items": [ { "name": "Wireless earbuds", "quantity": 1 }, { "name": "Delivery", "quantity": 1 } ], "expires": { "in": 60 }, "callback": "https://shop.example.com/order/complete" }' ``` ```javascript const payment = await wajub.payments.create({ amount: 25000, currency: 'XAF', customer: { email: 'amina@example.com', name: 'Amina N.' }, description: 'Order #4172', reference: 'order-4172', expires: { in: 60 }, callback: 'https://shop.example.com/order/complete', }); res.redirect(payment.authorization_url); ``` ```python payment = wajub.payments.create({ "amount": 25000, "currency": "XAF", "customer": {"email": "amina@example.com", "name": "Amina N."}, "description": "Order #4172", "reference": "order-4172", "expires": {"in": 60}, "callback": "https://shop.example.com/order/complete", }) return redirect(payment.authorization_url) ``` ```php $payment = $wajub->payments->create([ 'amount' => 25000, 'currency' => 'XAF', 'customer' => [ 'email' => 'amina@example.com', 'name' => 'Amina N.', ], 'description' => 'Order #4172', 'reference' => 'order-4172', 'expires' => ['in' => 60], 'callback' => 'https://shop.example.com/order/complete', ]); return redirect($payment->authorization_url); ``` ```go payment, err := client.Payments.Create(context.Background(), map[string]any{ "amount": 25000, "currency": "XAF", "customer": map[string]any{"email": "amina@example.com", "name": "Amina N."}, "description": "Order #4172", "reference": "order-4172", "expires": map[string]any{"in": 60}, "callback": "https://shop.example.com/order/complete", }, nil) if err != nil { log.Fatal(err) } http.Redirect(w, r, payment.AuthorizationURL, http.StatusSeeOther) ``` La réponse contient le paiement et la page vers laquelle envoyer le client. Enregistrez `transaction.id` avec votre commande avant de rediriger : ```json title="Réponse · 201 Created" { "code": 201, "status": "Created", "message": "Payment initiated", "authorization_url": "https://pay.wajub.com/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "authorization_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "transaction": { "id": "trx_test_CSUGajfv9xh0XQ5wu2lx", "reference": "order-4172", "amount": 25000, "currency": "XAF", "status": "pending", "sandbox": true, "created_at": "2026-09-11T10:24:00+00:00" } } ``` `authorization_url` contient un jeton de session opaque, pas l'id de la transaction. Redirigez vers cette URL exactement telle qu'elle est renvoyée : ne l'analysez jamais et n'en construisez jamais une vous-même. L'hôte n'est d'ailleurs pas toujours `pay.wajub.com`, car un compte sur le plan Scale peut servir son checkout depuis son propre domaine vérifié. ## Ce que la page décide seule Le client ne voit que les moyens qui peuvent prendre ce paiement, pas une liste figée. Le Mobile Money plafonne un débit unique à **500 000 XAF**, et au même montant en XOF. Un paiement au-dessus est refusé et la page propose au payeur un montant plus faible ou un autre moyen de paiement. Si vous définissez `bearer` à `customer`, la page affiche les frais ajoutés à votre montant et le total réellement débité. La langue est l'anglais ou le français. Elle suit le réglage [**Paiement — Langue**](https://dashboard.wajub.com/settings/regional/language), qui accepte `auto`, `en` ou `fr`. Sur `auto`, la page utilise le `preferred_language` du client, et s'ouvre en français quand le client n'en a pas. ## Gérer le retour Une fois la tentative terminée, le client revient sur votre `callback`, avec le paiement identifié dans les paramètres de l'URL : ```bash title="Redirection de retour" https://shop.example.com/order/complete?reference=trx_test_CSUGajfv9xh0XQ5wu2lx&status=succeeded&trxref=order-4172 ``` `reference` est l'id du paiement Wajub et `trxref` est la `reference` que vous avez envoyée, présente seulement si vous en avez défini une. Les deux reviennent quelle que soit l'issue. `status` vaut `succeeded`, `failed`, `cancelled` ou `expired`. Après un succès, la page renvoie le client d'elle-même ; après un échec ou une expiration, quand il choisit de revenir. Un client qui ferme la page sans terminer ne revient jamais. > [!CAUTION] > **Le retour ne prouve rien** > > N'importe qui peut ouvrir cette URL à la main et modifier `status`. Un client qui ferme l'onglet ne > l'ouvre jamais. Confirmez avec `GET /payments/{id}` depuis votre serveur, ou agissez sur le webhook > `payment.succeeded`, avant de livrer quoi que ce soit. L'appel de vérification prend l'id que vous avez enregistré avant la redirection : **Vérifier avant de livrer** ```bash curl https://api.wajub.com/payments/trx_test_CSUGajfv9xh0XQ5wu2lx \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" ``` ```javascript const payment = await wajub.payments.retrieve(req.query.reference); if (payment.status === 'succeeded' && payment.amount === order.total) { await fulfill(order); } ``` ```python payment = wajub.payments.retrieve(request.args["reference"]) if payment.status == "succeeded" and payment.amount == order.total: fulfill(order) ``` ```php $payment = $wajub->payments->retrieve($request->query('reference')); // Comparez des unités mineures entières. Utilisez 1000 au lieu de 100 pour une devise à trois décimales. $paid = (int) round((float) $payment->amount * 100); $due = (int) round((float) $order->total * 100); if ($payment->status === 'succeeded' && $paid === $due) { $order->fulfill(); } ``` ```go payment, err := client.Payments.Retrieve(context.Background(), r.URL.Query().Get("reference")) if err != nil { log.Fatal(err) } if payment.Status == "succeeded" && payment.Amount == order.Total { fulfill(order) } ``` Vérifiez le montant et la devise en plus du statut, et laissez le webhook clôturer les commandes dont le client n'est jamais revenu. ## Personnaliser la page L'apparence de la page se règle une fois pour tout le compte, dans **Paramètres → Image de marque**, et s'applique à chaque page de paiement que vous créerez, en sandbox comme en production. | Ce que vous réglez | Où cela apparaît | | ------------------------------------------------- | ---------------------------------------------------------- | | Logo rectangulaire, logo carré, favicon | L'en-tête de la page et l'onglet du navigateur | | Couleurs principale, secondaire et d'arrière-plan | Les boutons, les liens et le fond de la page | | Couleurs du texte et du texte des boutons | Le contraste avec votre propre palette | | Couleurs de succès et d'erreur | Les états de confirmation et d'échec | | Police et arrondi des bordures | Toute la page | | Mode d'apparence | `system`, `light` ou `dark` | | Densité et style de couverture | La compacité de la mise en page et le cadrage de l'en-tête | > [!NOTE] > **L'image de marque demande un plan payant** > > **Paramètres → Image de marque** dépend de la fonctionnalité Personnalisation du design, disponible à partir de **Growth**. > Sur Pay as you go, la page de paiement garde l'apparence par défaut. Servir le checkout depuis > votre propre domaine est une fonctionnalité distincte, Domaine personnalisé, disponible à partir de > **Scale**. Vous pouvez aussi collecter des informations que le paiement lui-même ne contient pas, une note de livraison ou un numéro de table, en ajoutant des champs dans **Paramètres → Collecter**. Chaque champ a un type parmi `text`, `textarea`, `select`, `checkbox`, `number`, `email` et `tel`, un libellé, un placeholder facultatif et un indicateur obligatoire. Les champs apparaissent sur la page hébergée dans l'ordre où vous les disposez. - [Démarrage rapide Paiements](https://docs.wajub.com/fr/payments/quickstart): Le même parcours de bout en bout, de la création au webhook vérifié. - [Afficher le checkout](https://docs.wajub.com/fr/libraries/components/hosted-checkout): Redirection, iframe intégrée ou fenêtre superposée, avec le code de chacune. - [Image de marque](https://docs.wajub.com/fr/libraries/components/branding): Chaque réglage d'apparence et la façon dont il atteint la page. - [Moyens de paiement et canaux](https://docs.wajub.com/fr/payments/payment-methods): Les opérateurs proposés, pays par pays. - [Cycle de vie d'un paiement](https://docs.wajub.com/fr/payments/lifecycle): Chaque état du paiement pendant que le client est sur la page. - [Tester la page de paiement](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios): Des numéros sandbox qui déclenchent chaque résultat à la demande. --- # Encaisser des paiements URL: https://docs.wajub.com/fr/payments > Les quatre façons d'encaisser un paiement, ce que chacune vous coûte en code, et la suite. Quatre façons d'encaisser un paiement, qui ne diffèrent que par qui affiche l'écran où le client confirme. Les opérateurs que vous atteignez, les webhooks que vous recevez et les remboursements que vous pouvez émettre sont les mêmes dans les quatre. ## Quatre points d'entrée Vous hésitez ? [Choisir une intégration](https://docs.wajub.com/fr/payments/integration-paths) compare les quatre sur le code, la personnalisation et les cas d'usage. Si vous préférez en voir un fonctionner avant de choisir, le [Démarrage rapide](https://docs.wajub.com/fr/payments/quickstart) mène un paiement sandbox de zéro jusqu'à un webhook vérifié. ## Moyens de paiement Le Mobile Money est la colonne vertébrale : MTN, Orange, Wave, Airtel, Moov et M-Pesa, dans une douzaine de pays. Les cartes et les virements bancaires domestiques sont disponibles là où l'opérateur les prend en charge. Les canaux sont nommés `country.operator` : `cm.mtn` est MTN Mobile Money au Cameroun et `sn.wave` est Wave au Sénégal. La matrice complète des pays et des opérateurs se trouve dans [Moyens de paiement et canaux](https://docs.wajub.com/fr/payments/payment-methods), et les formats de numéro acceptés par chaque opérateur dans [Formats de numéros de téléphone](https://docs.wajub.com/fr/payments/payment-methods/phone-numbers). Un mauvais format de numéro fait échouer le paiement avant même que le client voie une demande de confirmation : cette deuxième page mérite d'être lue une fois. ## Les deux appels Créer un paiement ne débite jamais personne. `POST /payments` enregistre l'intention, la garde en `pending`, et vous renvoie l'URL d'une page hébergée et un jeton de session utilisable dans le navigateur. Rien n'a encore atteint un opérateur. C'est le second appel qui débite. Le Checkout hébergé, les Composants intégrés et les liens de paiement le font pour vous. Seule l'[API directe](https://docs.wajub.com/fr/payments/direct-api) vous le laisse : vous collectez vous-même le numéro de téléphone, puis vous envoyez `POST /payments/{id}` avec un `channel` et les détails du paiement. > [!CAUTION] > **Une clé privée dans un navigateur est refusée** > > N'utilisez jamais `sk.…` depuis un navigateur. Lorsque Wajub le détecte, la requête est rejetée > avec un `403` et le propriétaire de la clé reçoit un e-mail. L'API directe a donc sa place sur > votre serveur. Le code front-end utilise la clé publique, ou le jeton de session que renvoie la réponse > de création. ## Ressources de l'API Les paiements partagent une seule API avec tous les autres produits. Voici les ressources qu'ils appellent ; les paramètres et les réponses complets se trouvent dans la [Référence API](https://docs.wajub.com/fr/api). | Endpoint | Méthodes | Utilisé pour | | --------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`/payments`](https://docs.wajub.com/fr/api/payments) | `GET` `POST` `DELETE` | Créer, lister, récupérer et annuler un paiement | | [`/payments/{id}`](https://docs.wajub.com/fr/api/payments/process) | `POST` | Le débiter sur un canal, et ses `/splits` pour les échéances, sur le Mobile Money en live | | [`/payments/{id}/activate`](https://docs.wajub.com/fr/api/payments/activate) | `POST` | Créer un paiement préparé avec `deferred: true` une fois la commande passée, pour des [champs de paiement affichés avant que la commande existe](https://docs.wajub.com/fr/libraries/components/payment-fields#before-the-order-exists). Avant cela, [`PATCH /payments/{id}`](https://docs.wajub.com/fr/api/payments/update) change son montant | | [`/refunds`](https://docs.wajub.com/fr/api/refunds) | `GET` `POST` | Émettre un remboursement et le suivre | | [`/customers`](https://docs.wajub.com/fr/api/customers) | `GET` `POST` `PUT` `DELETE` | Clients récurrents, plus blocage et désactivation | | [`/disputes`](https://docs.wajub.com/fr/api/disputes) | `GET` `POST` | Preuves, acceptation, clôture et messages | | [`/links`](https://docs.wajub.com/fr/api/payment-links) | `GET` `POST` `PUT` `DELETE` | Liens de paiement. Production uniquement | Les appels de paiement standard n'ont besoin d'aucun en-tête propre au produit. Une marketplace qui attribue le paiement à l'un de ses sous-comptes ajoute `X-Sync: acc_…` au même appel, comme décrit dans [Sync → Ressources de l'API](https://docs.wajub.com/fr/sync#the-resources). ## Après le paiement | Besoin | Où | | -------------------------------------------- | -------------------------------------------------------- | | Connaître le résultat au moment où il arrive | [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks) | | Comprendre chaque état et ses transitions | [Cycle de vie d'un paiement](https://docs.wajub.com/fr/payments/lifecycle) | | Rembourser un paiement | [Remboursements](https://docs.wajub.com/fr/payments/refunds) | | Traiter un litige ou une rétrofacturation | [Litiges](https://docs.wajub.com/fr/payments/disputes) | | Reconnaître un client récurrent | [Clients](https://docs.wajub.com/fr/payments/customers) | | Choisir entre webhooks et polling | [Webhooks ou polling](https://docs.wajub.com/fr/developer-tools/webhooks/polling) | - [Démarrage rapide Paiements](https://docs.wajub.com/fr/payments/quickstart): Un paiement sandbox, de zéro jusqu'à un webhook vérifié. - [Choisir une intégration](https://docs.wajub.com/fr/payments/integration-paths): Les quatre modes comparés sur le code, le contrôle et les cas d'usage. - [Moyens de paiement et canaux](https://docs.wajub.com/fr/payments/payment-methods): La couverture par pays et par opérateur, canal par canal. - [Accepter un paiement](https://docs.wajub.com/fr/guides/accept-a-payment): Le parcours de bout en bout : créer, rediriger, vérifier, livrer. --- # Choisir une intégration URL: https://docs.wajub.com/fr/payments/integration-paths > Les quatre façons d'encaisser un paiement, comparées sur le contrôle, le code et les contraintes. Les quatre modes d'intégration comparés : qui affiche l'écran où le client confirme, et ce que vous écrivez. Les opérateurs, les webhooks et les remboursements sont les mêmes dans les quatre. ## La décision en un tableau | Mode | Qui affiche l'écran de paiement | Ce que vous écrivez | Idéal pour | | ----------------------- | ------------------------------- | ---------------------------------------- | ---------------------------------------------------- | | **Checkout hébergé** | Wajub, sur sa propre page | Une redirection et un handler de retour | Aller vite en production, sur n'importe quelle stack | | **Composants intégrés** | Wajub, dans votre page | Une route serveur plus le SDK navigateur | Rester sur votre domaine, avec votre marque | | **Liens de paiement** | Wajub, sur sa propre page | Rien | Vendre sans site ni serveur | | **API directe** | Vous | Toute l'interface de paiement | Applications natives et parcours sur mesure | ## Ce que vous renvoie la réponse de création Créer un paiement ne débite personne. L'appel enregistre l'intention, la garde en `pending` et répond avec deux champs. Celui que vous utilisez dépend de votre mode d'intégration. - `authorization_url` (string): **Checkout hébergé.** L'URL complète de la page de paiement hébergée par Wajub. Redirigez-y votre client. C'est une URL de session opaque : ne l'analysez jamais et n'en construisez jamais une vous-même. - `authorization_token` (string): **Composants intégrés.** Un jeton de session utilisable dans le navigateur et limité à ce paiement. Passez-le en `sessionId` à `wajub.mount()`. Il n'est renvoyé qu'à la création, jamais lors d'une récupération ultérieure. Dans le code, toute la différence entre les deux modes tient en une ligne : ```js title="Le champ utilisé par chaque mode" // Hosted Checkout: send the customer to the page Wajub renders. res.redirect(payment.authorization_url); // Embedded Components: hand the token to the browser and mount in place. wajub.mount('#checkout', { sessionId: payment.authorization_token }); ``` L'API directe n'utilise ni l'un ni l'autre pour encaisser. Elle fait un second appel à la place, détaillé plus bas, et n'a besoin du jeton que lorsqu'un prestataire demande un code au payeur. ## Checkout hébergé Votre serveur crée le paiement et redirige vers `authorization_url`. Le client choisit un opérateur, saisit son numéro et confirme sur son téléphone, puis revient sur votre `callback`. Wajub envoie le webhook en parallèle : le résultat vous parvient même si le client ferme l'onglet en revenant. Vous écrivez deux choses : la route qui crée le paiement, et le handler qui le vérifie avant de livrer la commande. La page affiche votre logo et vos couleurs, réglés une fois dans le Dashboard sous Paramètres › Image de marque, à partir du plan Growth. C'est le mode que nous recommandons, et celui que parcourt le [Démarrage rapide Paiements](https://docs.wajub.com/fr/payments/quickstart). ## Composants intégrés Le même checkout, monté dans votre propre mise en page. Votre serveur crée le paiement et transmet `authorization_token` au navigateur, qui appelle `wajub.mount()` avec ce jeton en `sessionId`. Le client ne quitte jamais votre domaine. Vous écrivez une route serveur et quelques lignes de code front-end. Ce que vous n'écrivez pas, c'est l'interface de paiement elle-même : Mobile Money, cartes, OTP et 3DS viennent tous du composant monté, et vous fournissez l'habillage autour. Quand les composants s'affichent sur votre page de commande avant que la commande existe, alors que le panier peut encore changer, créez le paiement avec `deferred: true`. Il est seulement préparé : il reste hors de vos paiements et n'envoie aucun webhook `payment.*`. Votre serveur change son montant avec `PATCH /payments/{id}` quand le total bouge, puis l'active avec `POST /payments/{id}/activate` une fois la commande passée, depuis le `onBeforeSubmit` du composant. [Avant que la commande existe](https://docs.wajub.com/fr/libraries/components/payment-fields#before-the-order-exists) en détaille les étapes. Il existe un package JavaScript vanilla et des wrappers React, Vue, Svelte et Angular. La [vue d'ensemble des composants](https://docs.wajub.com/fr/libraries/components#four-ways-to-take-a-payment) compare ses quatre modes ; commencez par le [démarrage rapide des composants](https://docs.wajub.com/fr/libraries/components/quickstart), puis la page du framework qui correspond à votre stack. ## Liens de paiement Un lien à partager, sous forme d'URL ou de QR code. Vous le créez depuis le Dashboard ou avec un seul appel API, vous l'envoyez par WhatsApp, SMS ou e-mail, et le client paie sur une page Wajub. Il n'y a de code serveur à aucun moment. Deux limites sont à connaître avant de construire autour. Les liens de paiement fonctionnent **en production uniquement**, la sandbox n'a pas d'équivalent, et le plan Pay as you go autorise **25 liens**. Consultez [Liens de paiement](https://docs.wajub.com/fr/payments/link) pour savoir ce qu'un lien peut porter et comment suivre ce qu'il encaisse. ## API directe Vous collectez vous-même le numéro de téléphone, puis vous débitez avec un second appel, `POST /payments/{id}`, en passant un `channel` comme `cm.mtn` et les détails du paiement. La demande de confirmation de l'opérateur part vers le téléphone du client, et vous affichez chaque écran autour, y compris l'attente et le résultat. La page [API directe](https://docs.wajub.com/fr/payments/direct-api) détaille l'appel et chaque réponse possible. Les cartes font exception. Le mode live refuse les données de carte brutes sur cet appel : une carte se saisit dans le Checkout hébergé, les composants ou un SDK mobile, qui la collectent de façon sécurisée. C'est le seul mode où l'interface de paiement vous appartient entièrement, c'est pourquoi il existe pour les applications mobiles natives et pour les parcours qu'aucune page hébergée ne peut exprimer. C'est aussi le seul mode où c'est à vous de repérer les erreurs. > [!CAUTION] > **L'API directe a sa place sur votre serveur, jamais dans un navigateur** > > N'utilisez jamais une clé `sk.…` depuis un navigateur. Lorsque Wajub en détecte une, la requête est > rejetée avec un `403` et le propriétaire de la clé reçoit un e-mail. Le code front-end utilise la clé publique ou le jeton > de session de la réponse de création. Si votre interface de paiement vit dans un navigateur, ce sont > les Composants intégrés qu'il vous faut, pas ce mode. ## Toujours indécis Commencez par le Checkout hébergé. C'est le chemin le plus court vers un paiement qui fonctionne, et passer plus tard aux Composants intégrés ne change que votre front-end : l'appel de création, le traitement des webhooks et la vérification restent exactement tels quels. Optez plutôt pour les liens de paiement si vous n'avez pas de site où intégrer, et pour l'API directe seulement après avoir étudié les Composants intégrés et trouvé quelque chose qu'ils ne peuvent vraiment pas afficher. - [Démarrage rapide Paiements](https://docs.wajub.com/fr/payments/quickstart): Un paiement sandbox, de la création au webhook vérifié. - [Checkout hébergé](https://docs.wajub.com/fr/payments/hosted-checkout): Le parcours de redirection complet, personnalisation visuelle et gestion du retour compris. - [Wajub Components](https://docs.wajub.com/fr/libraries/components): Monter le checkout dans votre propre page, framework par framework. - [Liens de paiement](https://docs.wajub.com/fr/payments/link): Créer, partager et suivre un lien. - [Référence API des paiements](https://docs.wajub.com/fr/api/payments): Chaque paramètre des appels de création et de débit. - [Accepter un paiement, guide complet](https://docs.wajub.com/fr/guides/accept-a-payment): Le parcours de bout en bout, avec la logique de livraison autour. --- # Cycle de vie d'un paiement URL: https://docs.wajub.com/fr/payments/lifecycle > Chaque état d'un paiement, le webhook qui l'annonce, et ce qu'il faut faire dans chacun. Chaque état qu'un paiement peut prendre, le webhook qui l'annonce, et ce que fait votre intégration dans chacun. Deux d'entre eux signifient « attendez » : `pending`, avant tout contact avec un opérateur, et `processing`, pendant que le client reçoit la demande de confirmation, où une nouvelle tentative crée un deuxième débit. ## Les états > [!NOTE] > **Aiguillez sur `status`, jamais sur le message** > > Le champ `message` est rédigé pour des humains et peut changer sans préavis. La valeur `status` fait > partie du contrat de l'API, et c'est sur elle que votre code doit se baser. Aiguillez sur elle > plutôt que sur l'événement reçu, car plusieurs événements peuvent annoncer le même état. | `status` | Signification | Webhook | Que faire | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------- | | `pending` | Le paiement existe. Aucun opérateur n'a encore été contacté. | `payment.created` | Redirigez le client, ou faites l'appel de débit. Rien à livrer. | | `processing` | Envoyé à l'opérateur. Le client reçoit la demande de confirmation sur son téléphone. | `payment.processing` | **Attendez.** Ne faites pas de nouvelle tentative et ne créez pas de second paiement. | | `partial` | Certaines échéances d'un paiement fractionné sont réglées, d'autres non. | `payment.split.*` | Attendez. `amount_paid` sur le paiement indique ce qui est réglé jusqu'ici. | | `succeeded` | Fonds capturés. | `payment.succeeded` | Livrez la commande. | | `failed` | La tentative n'a pas abouti. | `payment.failed` | Lisez `failure_reason`, puis décidez si une nouvelle tentative a du sens. | | `cancelled` | Annulé par vous avec `DELETE /payments/{id}`, ou par le client avec le bouton Annuler de la page hébergée. Un refus sur le téléphone n'est pas une annulation. | `payment.cancelled` | Proposez de lancer un nouveau paiement. | | `expired` | Le délai de paiement s'est écoulé avant que le client agisse. | `payment.expired` | Créez un nouveau paiement. L'ancien ne pourra jamais aboutir. | **Paiement** `pending` (aucun opérateur contacté pour le moment) → [`payment.processing`] `processing` (demande envoyée au téléphone) → [`payment.succeeded`] `succeeded` (fonds capturés, livraison sans risque) Sorties anticipées, depuis pending ou processing: - `failed` (lire failure_reason) - `cancelled` (DELETE, ou Annuler sur la page hébergée) - `expired` (fenêtre fermée) Quatre de ces états mettent fin à la tentative : `succeeded`, `failed`, `cancelled` et `expired`. `succeeded` ne bouge plus jamais, sauf par les remboursements : un paiement remboursé se lit `refunded` ou `partially_refunded`. ## Un paiement préparé, avant son activation Un paiement créé avec `deferred: true`, pour des [champs de paiement affichés avant que la commande existe](https://docs.wajub.com/fr/libraries/components/payment-fields#before-the-order-exists), est seulement préparé jusqu'à ce que votre serveur l'active avec `POST /payments/{id}/activate`. D'ici là, il n'envoie aucun webhook `payment.*` et n'apparaît ni dans `GET /payments` ni dans le Dashboard. Lu par son `id`, il est `pending`, puis `expired` ou `cancelled`, et il ne peut pas être débité. L'activation envoie `payment.created`, puis le paiement suit les états ci-dessus, avec le même `id` et la même expiration. [Paiements préparés](https://docs.wajub.com/fr/api/payments#prepared-payments) résume les différences. ## Les transitions possibles Wajub ne fait évoluer un paiement que selon les chemins ci-dessous. | Depuis | Peut devenir | | ---------------------------------- | --------------------------------------------------------------------------- | | `pending` | `processing` · `partial` · `succeeded` · `failed` · `cancelled` · `expired` | | `processing` | `pending` · `partial` · `succeeded` · `failed` · `cancelled` · `expired` | | `partial` | `processing` · `succeeded` · `failed` | | `failed` · `cancelled` · `expired` | `succeeded` uniquement | Deux de ces chemins surprennent. `processing` revient à `pending` quand l'opérateur refuse un débit immédiatement, avec un `402`, pour que le même paiement puisse être débité de nouveau ; `payment.attempt_failed` en informe votre serveur. Et un paiement `failed`, `cancelled` ou `expired` peut encore devenir `succeeded` quand l'opérateur confirme l'argent en retard : livrez sur `payment.succeeded`, quel que soit le moment où il arrive. Quand une confirmation tardive ne peut pas être créditée, par exemple parce qu'une autre tentative avait déjà encaissé le paiement, le payeur est remboursé et le paiement reste tel quel. Rien d'autre ne fait sortir de ces trois états, donc une nouvelle tentative après eux passe par un nouveau paiement. ## Trois points qui surprennent ### `processing` signifie que le téléphone du client sonne C'est l'état dans lequel votre intégration passera le plus de temps, et celui qui a le plus de chances d'être mal géré. En Mobile Money, `processing` signifie que l'opérateur a envoyé une demande de confirmation sur le téléphone du client et attend qu'il saisisse son code PIN. Cela peut prendre quelques secondes, ou le temps qu'il faut à quelqu'un pour retrouver son téléphone. > [!WARNING] > **Ne retentez jamais un paiement en cours de traitement** > > Créer un second paiement parce que le premier « prend trop de temps » est la façon la plus courante > de débiter un client deux fois. Un paiement en `processing` est toujours actif. Attendez > `payment.succeeded`, `payment.failed` ou `payment.expired`. ### Un remboursement ne modifie le `status` du paiement qu'à travers ses remboursements Un paiement se lit `partially_refunded` dès que des remboursements réussis en couvrent une partie, et `refunded` quand ils le couvrent en entier. C'est une lecture des remboursements : le paiement lui-même ne change pas, et il n'existe pas d'événement `payment.refunded`. [Ce que dit le statut du paiement](https://docs.wajub.com/fr/payments/refunds#the-payments-status-never-changes) Les remboursements ont à la place leur propre famille d'événements : `refund.created`, `refund.processing` (en live uniquement), `refund.succeeded` et `refund.failed`, qui arrive aussi, avec `cancelled_by_wajub`, pour un remboursement que Wajub a arrêté avant de l'envoyer. Pour savoir quelle part d'un paiement a été restituée, listez ses remboursements avec [`GET /payments/{id}/refunds`](https://docs.wajub.com/fr/api/payments/refunds) et additionnez ceux qui ont réussi. ### `partial` ne concerne que les paiements fractionnés Un paiement peut être réglé en deux à quatre échéances, en sandbox et, sur le Mobile Money, en live ([Paiements fractionnés](https://docs.wajub.com/fr/sync/split-payments)). Tant que certaines sont payées et d'autres non, son statut est `partial`, `processing` pendant qu'une échéance attend le payeur, et chaque échéance rend compte d'elle-même via `payment.split.processing`, `payment.split.succeeded` et `payment.split.failed`. Il n'existe pas d'événement `payment.partial`, et un abonnement ne reconnaît que des noms exacts : `payment.*` ne correspond à rien. Listez les trois événements `payment.split` par leur nom, ou abonnez-vous à `*`. Le paiement ne porte pas la liste de ses échéances : `amount_paid` est la référence de ce qui a été réglé, et chaque événement `payment.split.*` indique quelle échéance a bougé. Un paiement `partial` reste ouvert jusqu'au paiement de sa dernière échéance : rien ne l'expire ni ne l'annule. Pour l'arrêter avant, clôturez-le avec [`POST /payments/{id}/close`](https://docs.wajub.com/fr/api/payments/close) : il devient `succeeded` pour ce qui a été encaissé, que vous gardez ou remboursez (`outcome`). `DELETE /payments/{id}` refuse un paiement dont des échéances sont déjà payées. ## Expiration Chaque paiement porte une date limite, fixée avec `expires.in` à la création, en **minutes**, et relue dans son `expires_at` : | | | | ---------- | ------------------------- | | Minimum | 5 minutes | | Par défaut | 1 440 minutes (24 heures) | | Maximum | 43 200 minutes (30 jours) | Le plancher est de cinq minutes, car une demande de confirmation Mobile Money a besoin de temps pour atteindre le téléphone et être confirmée. Des fenêtres plus courtes expirent avant que le client puisse payer. `payment.expired` peut arriver un peu après `expires_at`, et le paiement peut encore afficher `pending` entre les deux. Ne calculez pas l'expiration vous-même pour décider qu'une commande est morte : un opérateur peut encore confirmer un paiement dans les dernières secondes de sa fenêtre. Un paiement dont le débit est encore en cours quand `expires_at` passe, le payeur le validant sur son téléphone par exemple, n'expire pas à ce moment : il attend ce débit. Payé, il est `succeeded` ; refusé sur-le-champ, il revient à `pending` et peut expirer ; refusé plus tard, il est `failed`, sauf le code du payeur refusé plus tard par l'opérateur, qui le ramène à `pending`, où il peut aussi expirer. Un paiement dont une échéance est déjà payée n'expire jamais : il reste ouvert jusqu'à être soldé ou [clôturé](https://docs.wajub.com/fr/api/payments/close). ## Ce que vous recevez quand un paiement échoue Un paiement échoué porte un `failure_reason`, et `failure_message` le dit en une phrase. Voir [Motifs d'échec](https://docs.wajub.com/fr/api/failure-reasons#failed-payments). Aiguillez sur `status` pour le déroulement du code. Utilisez `failure_reason` pour expliquer à un humain ce qui s'est passé, et pour décider manuellement si une catégorie d'échec mérite une nouvelle tentative. ## Annuler un paiement Un paiement que personne n'est en train de payer peut être annulé depuis votre serveur, quand le client abandonne la commande de votre côté. `DELETE /payments/{id}` Le paiement passe en `cancelled`, `payment.cancelled` est envoyé, et sa page n'accepte plus de paiement. Un paiement qui ne peut pas être annulé maintenant répond `409`, avec sa raison dans `error_code` : | `error_code` | Quand | Que faire | | --------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `payment_in_progress` | Un débit est en cours : le payeur le valide sur son téléphone, ou paie sur la page du prestataire | Attendez son issue, par webhook ou `GET /payments/{id}`. Un paiement revenu à `pending` peut être annulé | | `payment_partly_paid` | Des échéances en ont été payées | Clôturez-le avec [`POST /payments/{id}/close`](https://docs.wajub.com/fr/api/payments/close), en gardant ou en remboursant ce qui a été encaissé | Tout autre paiement, déjà payé, échoué, annulé ou expiré, répond `400 This payment cannot be cancelled (already completed or expired).` Une confirmation que l'opérateur envoie après l'annulation fait quand même passer le paiement en `succeeded`, comme décrit plus haut. ## Lister les paiements par état `GET /payments` | Paramètre de requête | Valeurs acceptées | | -------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `status` | `pending`, `processing`, `partial`, `succeeded`, `failed`, `cancelled`, `expired` | | `reference` | Exactement la `reference` envoyée à la création. Elle n'est pas unique : chaque paiement qui la porte est renvoyé | | `search` | Texte libre sur l'id du paiement, votre `reference` et la description | | `date_from`, `date_to` | Dates, comparées à la date de création | | `amount_min`, `amount_max` | Montants dans l'unité principale de la devise | | `per_page` | De 1 à 100, 25 par défaut | | `cursor` | Passe à la pagination par curseur | `status` accepte aussi `refunded` et `partially_refunded` : ils listent les paiements remboursés en totalité ou en partie, que `succeeded` laisse alors de côté. [Ce que dit le statut du paiement](https://docs.wajub.com/fr/payments/refunds#the-payments-status-never-changes) Pour voir les paiements qui attendent encore un client, filtrez sur `pending` : **Lister les paiements en attente** ```bash curl -G https://api.wajub.com/payments \ -H "Authorization: $WAJUB_API_KEY" \ -d status=pending \ -d per_page=50 ``` ```javascript const page = await wajub.payments.list({ status: 'pending', per_page: 50 }); for (const payment of page.data) { console.log(payment.id, payment.created_at); } ``` ```python page = wajub.payments.list({"status": "pending", "per_page": 50}) for payment in page.data: print(payment["id"], payment["created_at"]) ``` ```php $page = $wajub->payments->list([ 'status' => 'pending', 'per_page' => 50, ]); foreach ($page->data as $payment) { echo $payment['id'], PHP_EOL; } ``` ```go page, err := client.Payments.List(context.Background(), map[string]any{ "status": "pending", "per_page": 50, }) if err != nil { log.Fatal(err) } for _, payment := range page.Data { log.Println(payment["id"], payment["created_at"]) } ``` ## Le reçu d'un paiement réussi Une fois le paiement réussi, il porte `receipt_url` : le reçu du payeur, une page hébergée sur votre domaine de factures, dans la langue du payeur. Le lien est signé : transmettez l'URL telle quelle. Le même document existe sous deux autres formes. Ajoutez `/pdf` au chemin pour un PDF, ou `/data` pour le reçu en JSON, en gardant la chaîne de requête. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): Recevoir ces événements de façon fiable : signatures, nouvelles tentatives, doublons. - [Mode test](https://docs.wajub.com/fr/developer-tools/testing/sandbox-mode): Amenez un paiement dans chaque état à la demande avec des numéros de test. - [Remboursements](https://docs.wajub.com/fr/payments/refunds): Le cycle de vie d'un remboursement et les événements qu'il émet. - [Récupérer un paiement](https://docs.wajub.com/fr/api/payments/retrieve): Faites le rapprochement côté serveur quand vous avez besoin de certitude. --- # Démarrage rapide URL: https://docs.wajub.com/fr/payments/quickstart > Un paiement sandbox, de la création au webhook vérifié, pour un compte qui a déjà ses clés. Un paiement sandbox en quatre étapes : le créer, envoyer le client vers une page, vérifier le résultat depuis votre serveur, et laisser les webhooks vous informer de ce qui arrive après le départ du client. > [!NOTE] > **Cette page commence après la configuration** > > Elle suppose un compte, des clés sandbox et un SDK installé. Si vous n'avez encore rien de tout > cela, le [démarrage rapide de la plateforme](https://docs.wajub.com/fr/getting-started/quickstart) couvre la création du > compte, les clés et l'installation, puis parcourt les mêmes quatre étapes depuis zéro. ## 1. Créez le paiement Une seule requête porte toute l'intention : combien, dans quelle devise, qui paie, et où cette personne revient. Wajub l'enregistre, la garde en `pending`, et répond avec une page vers laquelle envoyer le client. Rien n'a encore atteint un opérateur, et personne n'a été débité. Envoyez-la depuis votre serveur avec la clé secrète. La clé publique crée aussi des paiements, mais elle existe pour le seul cas où l'appel se fait dans un navigateur. Décrivez le payeur dans l'objet `customer`. Un `email` au premier niveau fonctionne aussi et aboutit sur la même fiche client, mais c'est l'objet qui grandit avec vous : il porte aussi `name`, `phone`, `address` et `metadata`. `POST /payments` **Créer un paiement** ```bash curl https://api.wajub.com/payments \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 5000, "currency": "XAF", "customer": { "email": "amina@example.com" }, "reference": "order-4172", "callback": "https://shop.example.com/order/complete" }' ``` ```javascript import { Wajub } from '@wajub/node'; const wajub = new Wajub({ apiKey: process.env.WAJUB_API_KEY }); const payment = await wajub.payments.create({ amount: 5000, currency: 'XAF', customer: { email: 'amina@example.com' }, reference: 'order-4172', callback: 'https://shop.example.com/order/complete', }); console.log(payment.id, payment.authorization_url); ``` ```python import os from wajub import Wajub wajub = Wajub(api_key=os.environ["WAJUB_API_KEY"]) payment = wajub.payments.create({ "amount": 5000, "currency": "XAF", "customer": {"email": "amina@example.com"}, "reference": "order-4172", "callback": "https://shop.example.com/order/complete", }) print(payment.id, payment.authorization_url) ``` ```php getenv('WAJUB_API_KEY')]); $payment = $wajub->payments->create([ 'amount' => 5000, 'currency' => 'XAF', 'customer' => [ 'email' => 'amina@example.com', ], 'reference' => 'order-4172', 'callback' => 'https://shop.example.com/order/complete', ]); echo $payment->authorization_url; ``` ```go client, err := wajub.New(wajub.Config{APIKey: os.Getenv("WAJUB_API_KEY")}) if err != nil { log.Fatal(err) } payment, err := client.Payments.Create(context.Background(), map[string]any{ "amount": 5000, "currency": "XAF", "customer": map[string]any{"email": "amina@example.com"}, "reference": "order-4172", "callback": "https://shop.example.com/order/complete", }, nil) if err != nil { log.Fatal(err) } log.Println(payment.ID, payment.AuthorizationURL) ``` Wajub répond `201 Created`. Deux champs comptent ici : `transaction.id`, que vous stockez avec votre commande, et `authorization_url`, où le client va ensuite. ```json title="Réponse · 201 Created" { "code": 201, "status": "Created", "message": "Payment initiated", "authorization_url": "https://pay.wajub.com/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "authorization_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "transaction": { "id": "trx_test_CSUGajfv9xh0XQ5wu2lx", "reference": "order-4172", "amount": 5000, "amount_paid": 0, "currency": "XAF", "status": "pending", "customer": { "id": "cus_test_sAaim5apjocIgtlhzJY3wQ8s", "email": "amina@example.com" }, "callback": "https://shop.example.com/order/complete", "sandbox": true, "created_at": "2026-09-11T10:24:00+00:00" } } ``` > [!NOTE] > **Les montants sont en unité principale, jamais en centimes** > > `"amount": 5000` vaut 5 000 XAF, pas 50. Wajub n'utilise pas de sous-unités. Un paiement en XAF ou > en XOF doit être compris entre 25 et 2 000 000 ; hors de cette plage, l'API répond `422` avec la > limite dans `errors.amount`. `reference` vous appartient : c'est votre numéro de commande, renvoyé à chaque lecture et consultable dans le Dashboard. Il n'a aucune contrainte d'unicité : l'envoyer deux fois crée deux paiements, et `GET /payments?reference=order-4172` liste chaque paiement qui le porte. Un paiement se lit par son `id`. Ce qui vous protège vraiment d'un double débit, c'est l'en-tête `Idempotency-Key`. Générez-le vous-même, stockez-le à côté de la commande, et renvoyez la même valeur à chaque nouvelle tentative : l'API renvoie alors le paiement d'origine au lieu d'en ouvrir un second. Passez vous-même cette clé à chaque appel. [Idempotence](https://docs.wajub.com/fr/best-practices/idempotency) présente les stratégies qui fonctionnent. ## 2. Envoyez le client vers la page Redirigez vers `authorization_url`. Le client choisit un opérateur, saisit son numéro, confirme sur son téléphone et revient sur votre `callback`. C'est le Checkout hébergé, et c'est le mode que nous recommandons : Wajub affiche l'écran, vous n'avez donc aucune interface de paiement à maintenir. La session reste valide 24 heures. Passez `expires.in` en minutes, de 5 à 43 200, pour fermer la fenêtre plus tôt. En sandbox, les six derniers chiffres du numéro décident du résultat, et `…000000` réussit. Le tableau complet des suffixes et un numéro par opérateur se trouvent dans le [démarrage rapide de la plateforme](https://docs.wajub.com/fr/getting-started/quickstart#4-pay-it-with-a-sandbox-number). La sandbox ne demande jamais de code PIN. ## 3. Vérifiez avant de livrer Le retour du client sur votre `callback` ne prouve rien. N'importe qui peut ouvrir cette URL à la main, et un client qui ferme l'onglet ne l'ouvre jamais. Demandez à l'API ce qui s'est passé, depuis votre serveur, avec l'id stocké à l'étape 1. `GET /payments/{id}` **Récupérer un paiement** ```bash curl https://api.wajub.com/payments/trx_test_CSUGajfv9xh0XQ5wu2lx \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" ``` ```javascript const payment = await wajub.payments.retrieve('trx_test_CSUGajfv9xh0XQ5wu2lx'); console.log(payment.status, payment.amount, payment.currency); ``` ```python payment = wajub.payments.retrieve("trx_test_CSUGajfv9xh0XQ5wu2lx") print(payment.status, payment.amount, payment.currency) ``` ```php $payment = $wajub->payments->retrieve('trx_test_CSUGajfv9xh0XQ5wu2lx'); echo $payment->status; ``` ```go payment, err := client.Payments.Retrieve(context.Background(), "trx_test_CSUGajfv9xh0XQ5wu2lx") if err != nil { log.Fatal(err) } log.Println(payment.Status, payment.Amount, payment.Currency) ``` La réponse est le paiement tel que Wajub le connaît, quoi qu'on ait dit au navigateur. `channel` indique l'opérateur réellement utilisé, et `amount_paid` ce qui a vraiment été encaissé : ```json title="Réponse · 200 OK" { "code": 200, "status": "OK", "message": "Payment retrieved", "transaction": { "id": "trx_test_CSUGajfv9xh0XQ5wu2lx", "reference": "order-4172", "amount": 5000, "amount_paid": 5000, "currency": "XAF", "status": "succeeded", "channel": "cm.mtn", "customer": { "id": "cus_test_sAaim5apjocIgtlhzJY3wQ8s", "email": "amina@example.com" }, "sandbox": true, "created_at": "2026-09-11T10:24:00+00:00" } } ``` Livrez la commande uniquement quand `status` vaut `succeeded`, et seulement si `amount` et `currency` correspondent à ce que vous avez facturé. Un paiement encore `pending` n'est pas un échec, c'est un client qui n'a pas encore terminé : laissez la commande ouverte et laissez l'étape suivante la clore. ## 4. Laissez le webhook boucler la boucle Vérifier au retour couvre les clients qui reviennent. Les webhooks couvrent tous les autres, ainsi que chaque événement sans aucun navigateur derrière : une confirmation que l'opérateur envoie avec dix minutes de retard, un remboursement émis depuis le Dashboard, une session qui expire sans avoir été ouverte. Abonnez-vous par leur nom aux sept événements qu'un paiement peut produire. Un abonnement ne reconnaît que des noms exacts : `payment.*` ne recevrait rien. | Événement | Se déclenche quand | | ------------------------ | ------------------------------------------------------------------------------------------------- | | `payment.created` | Le paiement a été enregistré et est `pending` | | `payment.processing` | La requête a atteint l'opérateur, le client reçoit la demande de confirmation | | `payment.succeeded` | Fonds capturés. C'est sur celui-ci que vous livrez la commande | | `payment.failed` | L'opérateur a signalé l'échec de la tentative après l'envoi de la demande | | `payment.attempt_failed` | Un refus renvoyé immédiatement : le paiement est de nouveau `pending` et le client peut réessayer | | `payment.expired` | La session a expiré avant que le client confirme | | `payment.cancelled` | Annulé avec `DELETE /payments/{id}`, ou avec le bouton Annuler de la page hébergée | > [!NOTE] > **Les webhooks sont documentés une seule fois, ailleurs** > > L'enregistrement de l'endpoint, la vérification de signature, les nouvelles tentatives et le > catalogue complet se trouvent dans [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks). Une règle a pourtant sa > place ici : dédoublonnez sur l'`id` de l'événement. Une livraison échouée est > [retentée](https://docs.wajub.com/fr/developer-tools/webhooks/retries), et chaque tentative porte ce même `id`, c'est ce qui > empêche une nouvelle tentative de livrer la commande deux fois. ## Choisissez ensuite le mode à mettre en production Ce que vous venez de construire, c'est le Checkout hébergé. Les trois autres modes changent une seule chose : qui affiche l'écran de l'étape 2. La création, la vérification et le traitement des webhooks restent mot pour mot ce qu'ils sont ci-dessus. **Modes d'intégration** - [Checkout hébergé](https://docs.wajub.com/fr/payments/hosted-checkout): Ce que vous venez de construire. Wajub affiche le choix de l'opérateur, la demande de confirmation et le résultat. - [Composants intégrés](https://docs.wajub.com/fr/libraries/components): Le même écran, monté dans votre page avec le jeton de session. - [Liens de paiement](https://docs.wajub.com/fr/payments/link/quickstart): Aucune intégration. Production uniquement, 25 liens sur l'offre gratuite. - [API directe](https://docs.wajub.com/fr/payments/direct-api): Vous collectez le numéro et le débitez vous-même avec un second appel. ## Et ensuite ? - [Cycle de vie d'un paiement](https://docs.wajub.com/fr/payments/lifecycle): Chaque statut qu'un paiement peut prendre, et les passages de l'un à l'autre. - [Moyens de paiement et canaux](https://docs.wajub.com/fr/payments/payment-methods): La couverture par pays et par opérateur, canal par canal. - [Formats de numéros de téléphone](https://docs.wajub.com/fr/payments/payment-methods/phone-numbers): Ce que chaque opérateur accepte, avant même qu'un paiement puisse démarrer. - [Remboursements](https://docs.wajub.com/fr/payments/refunds): Remboursements totaux ou partiels d'un paiement réussi. - [Accepter un paiement, guide complet](https://docs.wajub.com/fr/guides/accept-a-payment): Le même parcours de bout en bout, avec la logique de livraison autour. - [Passer en live](https://docs.wajub.com/fr/getting-started/going-live): La checklist avant de passer aux clés de production. --- # Suppression et effacement URL: https://docs.wajub.com/fr/payments/customers/delete > Supprimer un client efface aussitôt ses données personnelles. Ce que cela retire, ce qui reste, et ce qui ne peut pas être annulé. La suppression n'est pas l'archivage réversible qu'elle est sur la plupart des ressources. `DELETE /customers/{id}` La fiche est retirée de vos listes et ses données personnelles sont anonymisées immédiatement, dans la même requête, pour répondre à une demande de droit à l'effacement sans deuxième étape. La fiche anonymisée reste parmi les clients supprimés du Dashboard jusqu'à ce qu'un membre de votre équipe la supprime définitivement. Les paiements passés restent, car ce sont des écritures financières : leurs coordonnées client sont pseudonymisées, et ils conservent le numéro de portefeuille ou de compte avec lequel ils ont été réglés. L'événement `customer.deleted` porte la fiche anonymisée, et les coordonnées du client sont retirées des événements et des livraisons de webhook déjà enregistrés. Un appel répété répond le même `200`. Avec `X-Sync`, l'appel répond `403` : une plateforme n'efface pas les clients d'un marchand. [Supprimer un payeur](https://docs.wajub.com/fr/resources/compliance#deleting-a-payer) liste tout ce qu'il retire. > [!CAUTION] > **Aucune annulation possible via l'API** > > L'API n'a pas d'endpoint de restauration. Le Dashboard peut restaurer la fiche, mais les données > personnelles ne reviennent pas avec elle : elles ont été anonymisées dans la requête de > suppression. Désactivez plutôt que de supprimer quand vous voulez simplement écarter un client. - [Supprimer un payeur](https://docs.wajub.com/fr/resources/compliance#deleting-a-payer): Tout ce qu'un effacement retire, sur toute la plateforme. - [Pocket](https://docs.wajub.com/fr/payments/customers/pocket): Où un payeur peut supprimer lui-même ses données. --- # Clients URL: https://docs.wajub.com/fr/payments/customers > La fiche payeur que Wajub réutilise d'un paiement à l'autre, et ce qu'elle change sur la page de checkout. Chaque paiement est rattaché à un client, la fiche payeur que Wajub retrouve ou crée pour vous et réutilise d'un paiement à l'autre. Cinq pages vont plus loin : - [Payer en client connu](https://docs.wajub.com/fr/payments/customers/known-customer), par son id, et ce qu'un client connu change sur la page de checkout. - [Gérer les clients](https://docs.wajub.com/fr/payments/customers/manage) : en créer un en amont, le modifier, les lister, les bloquer, leurs numéros fiscaux et leurs webhooks. - [Suppression et effacement](https://docs.wajub.com/fr/payments/customers/delete), ce que supprimer un client efface et ce qui reste. - [Pocket](https://docs.wajub.com/fr/payments/customers/pocket), où vos payeurs retrouvent leurs paiements, tous marchands confondus. - Dans le guide du tableau de bord, [la fiche client](https://docs.wajub.com/dashboard/customers/profile), [la fusion de deux clients](https://docs.wajub.com/dashboard/customers/merge) et [l'export](https://docs.wajub.com/dashboard/customers/bulk-actions#export-customers). ## Chaque paiement en crée un ou en retrouve un Un paiement doit porter au moins un champ parmi `email`, `phone` et `customer_id`. Sans aucun des trois, l'API répond `422` et rien n'est enregistré. Dès qu'il en reçoit un, Wajub cherche un client correspondant sur votre compte, dans l'environnement que vous appelez. S'il en trouve un, le paiement lui est rattaché. Sinon, il crée le client et y rattache le paiement. Dans les deux cas, le paiement vous renvoie un objet `customer`, avec l'`id` que vous pourrez réutiliser ensuite. La sandbox et le live sont deux populations séparées. Un client créé par un paiement en sandbox est invisible pour un paiement live, et les ids diffèrent : `cus_test_…` en sandbox, `cus_…` en production. ## Comment Wajub décide que deux paiements viennent de la même personne La recherche suit un ordre fixe et s'arrête à la première correspondance. | Ordre | Champ | Méthode de comparaison | | ----- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | 1 | `customer_id` | Correspondance exacte sur l'`id` du client | | 2 | `email` | Espaces de début et de fin retirés, en minuscules : `Amina@Example.com` correspond à `amina@example.com` | | 3 | `phone` | Lu d'abord en E.164 : `+237 6 70 00 00 00`, `237670000000` et, pour un compte au Cameroun, `670000000` correspondent à `+237670000000` | Un compte a un seul client par email, quelle que soit sa casse, et par téléphone une fois en E.164. > [!NOTE] > **Les téléphones sont enregistrés en E.164** > > Tout téléphone de client est enregistré en E.164, quel que soit celui qui l'écrit : l'API, un > paiement, le payeur d'un lien de paiement ou d'une facture, le Dashboard. Un numéro écrit avec `+` > (ou `00`) est lu dans son propre pays ; un numéro écrit sans est lu dans `phone_country` quand > vous l'envoyez, sinon dans le pays de votre compte. Une valeur qui ne se lit pas comme un numéro > est gardée telle qu'envoyée, et ne correspond qu'à elle-même. Les formats sont dans > [Formats de numéros de téléphone](https://docs.wajub.com/fr/payments/payment-methods/phone-numbers). Quand un paiement porte à la fois un email et un téléphone, c'est l'email qui décide. Le téléphone n'est consulté que si aucun client ne correspond à l'email : un client existant peut donc être retrouvé par son email, puis recevoir discrètement un numéro de téléphone qu'il n'avait jamais eu. ## Un paiement n'écrase jamais un client Quand un paiement correspond à un client existant, les données que vous avez envoyées sont fusionnées, mais seulement dans les champs vides. Un champ qui a déjà une valeur n'est pas touché. | Envoyé sur le paiement | Le client a déjà une valeur | Le client n'en a pas | | ------------------------ | ------------------------------------------ | --------------------------------------------------------------------------------- | | `name`, `email`, `phone` | Ignoré | Renseigné, sauf si un autre client du compte porte déjà cet email ou ce téléphone | | `metadata` | Fusionné clé par clé, vos clés l'emportent | Renseigné | | `address` | Ignoré | Rattaché comme adresse de livraison principale | | `shipping` | Ignoré | Rattaché comme adresse de **facturation** principale | Envoyez l'adresse de livraison dans `customer.address`. Conséquence pratique : vous ne pouvez pas corriger un client via un paiement. Envoyez un paiement avec `"name": "Amina Diallo"` pour un client déjà nommé `Amina N.` et l'ancien nom est conservé. Utilisez [`PUT /customers/{id}`](https://docs.wajub.com/fr/payments/customers/manage#update-a-customer) pour les corrections. Un paiement envoyé avec `X-Sync` ne touche jamais aux `metadata` du marchand : ses `metadata` vont à celles de la plateforme, décrites dans [Pour le compte d'un sous-compte](https://docs.wajub.com/fr/payments/customers/manage#on-behalf-of-a-subaccount). > [!NOTE] > **Le premier paiement perd l'adresse** > > Les adresses ne sont rattachées que quand le client existait déjà. Un tout > nouveau client créé par un paiement est enregistré avec son email, son nom, son téléphone et ses > métadonnées seulement : une `address` envoyée sur ce premier paiement n'est donc pas conservée sur > la fiche client. [Créez le client en > amont](https://docs.wajub.com/fr/payments/customers/manage#create-a-customer-up-front) si l'adresse compte pour vous. - [Référence API des clients](https://docs.wajub.com/fr/api/customers): Tous les champs de la ressource, et ses endpoints. - [Formats de numéros de téléphone](https://docs.wajub.com/fr/payments/payment-methods/phone-numbers): Le format international dans lequel tout téléphone de client est enregistré. --- # Payer en client connu URL: https://docs.wajub.com/fr/payments/customers/known-customer > Débiter un client par son id, et ce qu'un client connu change sur la page de checkout. Une fois que vous détenez un `id`, issu de l'objet `customer` d'un paiement précédent ou de [`POST /customers`](https://docs.wajub.com/fr/payments/customers/manage#create-a-customer-up-front), passez-le et laissez complètement de côté les champs de contact. Le champ `customer` accepte l'id sous forme de simple chaîne, et `customer_id` accepte la même valeur ; ce sont deux écritures de la même chose. **Débiter un client existant** ```bash curl https://api.wajub.com/payments \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 5000, "currency": "XAF", "customer": "cus_test_sAaim5apjocIgtlhzJY3wQ8s", "reference": "order-4173" }' ``` ```javascript const payment = await wajub.payments.create({ amount: 5000, currency: 'XAF', customer: 'cus_test_sAaim5apjocIgtlhzJY3wQ8s', reference: 'order-4173', }); ``` ```python payment = wajub.payments.create({ "amount": 5000, "currency": "XAF", "customer": "cus_test_sAaim5apjocIgtlhzJY3wQ8s", "reference": "order-4173", }) ``` ```php $payment = $wajub->payments->create([ 'amount' => 5000, 'currency' => 'XAF', 'customer' => 'cus_test_sAaim5apjocIgtlhzJY3wQ8s', 'reference' => 'order-4173', ]); ``` ```go payment, err := client.Payments.Create(context.Background(), map[string]any{ "amount": 5000, "currency": "XAF", "customer": "cus_test_sAaim5apjocIgtlhzJY3wQ8s", "reference": "order-4173", }, nil) ``` L'identifiant n'est pas forcément un id. Si la valeur que vous passez ne correspond à aucun `id` de client, Wajub l'essaie comme numéro de téléphone, puis comme adresse email. `"customer": "amina@example.com"` et `"customer": "+237670000000"` sont donc tous deux résolus, ce qui est pratique quand votre propre base stocke l'email et non l'id Wajub. > [!CAUTION] > **Un identifiant qui ne correspond à rien donne un 422, pas un nouveau client** > > C'est le seul endroit où l'API refuse de créer. Passez `customer` ou `customer_id` et Wajub > trouvera ce client ou fera échouer l'appel avec un `422` sur le champ utilisé, `Customer not > found.` ; il ne se rabat jamais sur une création. Un id périmé, un client supprimé la semaine dernière ou un id live envoyé en > sandbox font tous échouer le paiement d'emblée. En cas de doute sur l'existence de la fiche, > envoyez plutôt `email` ou `phone`. ## Ce qu'un client change sur la page de checkout C'est ce qui rentabilise l'appel supplémentaire. Un paiement rattaché à un client connu affiche une page différente. | Ce que porte le client | Ce que le checkout en fait | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Cartes et numéros Mobile Money déjà utilisés | Les propose comme moyens enregistrés, utilisables en un geste, le moyen par défaut en premier, dix au maximum | | `preferred_language` | Définit la langue de la page, sauf si le réglage d'équipe ou de branding l'emporte | | `currency` | Devient la devise présélectionnée quand la conversion automatique est activée | Les moyens enregistrés sont le vrai gain pour les payeurs qui reviennent : le numéro est déjà là, masqué, et ils confirment sur leur téléphone sans le ressaisir. > [!NOTE] > **Enregistrer un moyen de paiement est la décision du payeur** > > Une carte ou un numéro Mobile Money n'est conservé que si le payeur coche la case sur la page de > checkout. Ce n'est jamais déduit ni coché par défaut : une fiche client sans moyen enregistré est > donc l'état normal tant que personne n'a donné son accord. Seuls les cartes et le Mobile Money sont > réutilisables ; les portefeuilles et les virements bancaires ne sont pas conservés. - [Gérer les clients](https://docs.wajub.com/fr/payments/customers/manage): En créer un en amont, pour que le premier paiement ait déjà un id à utiliser. - [Factures récurrentes](https://docs.wajub.com/fr/billing/invoice/recurring): Facturez un client connu selon un calendrier. --- # Gérer les clients URL: https://docs.wajub.com/fr/payments/customers/manage > Créer un client en amont, le modifier, le lister et le bloquer, conserver ses numéros fiscaux, et suivre ses webhooks. ## Créer un client en amont La création explicite en vaut la peine quand vous connaissez le payeur avant qu'il ne paie : une inscription, une base clients importée, un compte B2B avec un numéro fiscal et une adresse de facturation. `POST /customers` Au moins un champ parmi `email` et `phone` est obligatoire. Tout le reste est facultatif ; les champs ci-dessous sont ceux qu'il faut connaître, et la liste complète se trouve dans la [référence API](https://docs.wajub.com/fr/api/customers/create). - `email` (string): Obligatoire sauf si `phone` est fourni. Stocké tel qu'envoyé, et retrouvé quelle que soit la casse : un second `POST /customers` avec `Amina@Example.com` renvoie le client enregistré avec `amina@example.com`. - `phone` (string): Obligatoire sauf si `email` est fourni. Enregistré en E.164 : un numéro sans son préfixe international est lu dans `phone_country`, sinon dans le pays de votre compte. - `name` (string): Nom affiché, le seul champ de nom que vous pouvez définir. - `type` (enum, default `individual`): `individual` ou `business`. Envoyer `business_name` seul implique `business`. - `business_name` (string): Obligatoire quand `type` vaut `business`. Devient le `name` du client. - `currency` (string): Devise préférée, utilisée par défaut sur le checkout quand la conversion automatique est activée. - `preferred_language` (string): Langue du checkout hébergé, qui passe après les réglages d'équipe et de branding. - `address` (object): Adresse de livraison : `country`, `city`, `state`, `postal_code`, `address_line1`, `address_line2`. - `billing` (object): Adresse de facturation, même structure que `address`. - `customer_group` (string): Segment libre sur lequel vous pouvez filtrer la liste. - `tags` (array): Chaînes de 50 caractères maximum chacune. - `metadata` (object): Vos propres données clé-valeur, au format libre. Envoyez l'appel depuis votre serveur, avec la clé secrète. **Créer un client** ```bash curl https://api.wajub.com/customers \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: cus-signup-9182" \ -d '{ "email": "amina@example.com", "phone": "+237670000000", "name": "Amina Diallo", "metadata": { "user_id": "u_9182" } }' ``` ```javascript const customer = await wajub.customers.create({ email: 'amina@example.com', phone: '+237670000000', name: 'Amina Diallo', metadata: { user_id: 'u_9182' }, }); console.log(customer.id); ``` ```python customer = wajub.customers.create({ "email": "amina@example.com", "phone": "+237670000000", "name": "Amina Diallo", "metadata": {"user_id": "u_9182"}, }) print(customer.id) ``` ```php $customer = $wajub->customers->create([ 'email' => 'amina@example.com', 'phone' => '+237670000000', 'name' => 'Amina Diallo', 'metadata' => [ 'user_id' => 'u_9182', ], ]); echo $customer->id; ``` ```go customer, err := client.Customers.Create(context.Background(), map[string]any{ "email": "amina@example.com", "phone": "+237670000000", "name": "Amina Diallo", "metadata": map[string]any{"user_id": "u_9182"}, }, nil) ``` Un nouveau client est renvoyé en `201 Created`, avec l'`id` que vous passerez désormais sur vos paiements. ```json title="Réponse · 201 Created" { "code": 201, "status": "Created", "message": "Customer created", "customer": { "id": "cus_test_sAaim5apjocIgtlhzJY3wQ8s", "type": "individual", "name": "Amina Diallo", "email": "amina@example.com", "phone": "+237670000000", "status": "active", "blocked": false, "tags": [], "metadata": { "user_id": "u_9182" }, "sandbox": true, "created_at": "2026-09-11T10:24:00+00:00" } } ``` > [!WARNING] > **Un doublon répond 200, pas 201** > > Si vous créez un client dont l'email (quelle que soit sa casse) ou le téléphone existe déjà, l'API > renvoie la fiche existante avec `200 OK` et le message > `Customer already exists for this merchant`. Avec une clé publique, cette fiche ne contient que > son `id` et les champs envoyés par la requête. Rien n'est dupliqué, et rien n'est mis à jour non > plus. Testez `code === 201` pour distinguer une vraie création d'une > correspondance, et ne traitez jamais le `200` comme une erreur. `Idempotency-Key` fonctionne ici comme sur les paiements : la même clé rejoue la réponse d'origine pendant 24 heures au lieu d'ouvrir une deuxième fiche. C'est la façon sûre de retenter un hook d'inscription. ## Modifier un client Un paiement ne corrige jamais un client, il ne remplit que les champs encore vides : voir [Un paiement n'écrase jamais un client](https://docs.wajub.com/fr/payments/customers#a-payment-never-overwrites-a-customer). Les corrections passent par `PUT /customers/{id}`. `PUT /customers/{id}` `PUT /customers/{id}` ne change que les champs que vous envoyez. Le `name` ne change que si vous l'envoyez : `first_name` et `last_name` sont refusés, et envoyer `business_name` sur un particulier laisse son nom intact (sur une entreprise, un nouveau `business_name` devient son nom, sauf si vous envoyez aussi `name`). Un `email` (quelle que soit sa casse) ou un `phone` déjà porté par un autre client du compte répond `422` sur ce champ, `A customer with this email already exists.` ou `A customer with this phone already exists.` ## Récupérer et lister La récupération prend l'`id` du client et renvoie le même objet que l'appel de création. `GET /customers/{id}` La liste renvoie vos clients du plus récent au plus ancien, et accepte des filtres qui correspondent à votre façon de les segmenter. `GET /customers` | Paramètre de requête | Accepte | | -------------------- | ------------------------------------------------------------------------------ | | `per_page` | De 1 à 100, 25 par défaut | | `search` | Texte libre sur le nom, l'email, le téléphone et l'id | | `status` | `active`, `inactive`, `blocked` | | `type` | `individual`, `business` | | `country` | Code pays à deux lettres de l'adresse de livraison ou de facturation du client | | `customer_group` | La chaîne de groupe définie sur le client | | `cursor` | Un curseur opaque issu d'une réponse précédente | La pagination a deux modes, et le mode par numéro de page est celui par défaut. Sans `cursor`, `meta` contient `current_page`, `last_page`, `per_page` et `total`, ainsi que le `next_cursor` et le `has_more` qui permettent de continuer avec un curseur. Envoyez ce `next_cursor` comme `cursor` et l'endpoint passe en mode curseur, où `meta` contient à la place `per_page`, `next_cursor`, `prev_cursor` et `has_more`. Le mode curseur est celui qu'il vous faut pour un export complet, car il reste juste pendant que de nouveaux clients sont créés. [Pagination](https://docs.wajub.com/fr/api/pagination) détaille les deux. ## Pour le compte d'un sous-compte Une marketplace qui crée un client pour le compte d'un de ses sous-comptes ajoute l'en-tête `X-Sync` à `POST /customers`, et la règle des doublons ci-dessus s'applique : quand le marchand a déjà un client avec cet email ou ce téléphone, ce client est renvoyé avec `200`, et rien n'est dupliqué. L'appel de la plateforme ne remplit que les champs que le marchand a laissés vides ; il ne change jamais un champ qu'il a renseigné. Le client renvoyé, trouvé ou créé, est dès lors ouvert à la connexion : la plateforme peut le lire, le retrouver dans la liste et l'utiliser sur ses paiements et ses factures. Elle gère un client qu'elle a créé ; sur un client que le marchand avait déjà, ses modifications ne remplissent que les champs que le marchand a laissés vides, et elle ne peut pas le bloquer. Un paiement créé avec `X-Sync` et l'email ou le téléphone d'un client existant est rattaché à ce client de la même façon. Si le marchand a bloqué ce client, le paiement est refusé à partir de la version `2026-11-02`, comme pour tout [client bloqué](#status-and-blocking), même si la connexion n'a pas accès à ce client. Avec `X-Sync`, un client ne montre jamais les `notes`, le `block_reason` ni les `metadata` du marchand, et `notes` envoyé avec `X-Sync` est ignoré. Les `metadata` sont celles de la plateforme : elle les lit et les écrit comme sur tout client, chaque connexion a les siennes, et celles du marchand restent les siennes. 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}` remplace les `metadata` de la plateforme. [Types de compte](https://docs.wajub.com/fr/sync/account-types#customers-are-shared-with-the-merchant) donne le détail. ## Statut et blocage Un client est `active`, `inactive` ou `blocked`, et quatre endpoints le font passer d'un état à l'autre. | Appel | Effet | | --------------------------------- | -------------------------------------------------------------------------- | | `POST /customers/{id}/block` | Passe à `blocked`, enregistre votre `reason` et un horodatage `blocked_at` | | `POST /customers/{id}/unblock` | Remet le client à `active` | | `POST /customers/{id}/deactivate` | Passe à `inactive` | | `POST /customers/{id}/activate` | Passe à `active` | Bloquer un client déjà bloqué répond `400`, tout comme débloquer un client qui ne l'est pas. `inactive` est une étiquette sur la fiche client, quelle que soit la version d'API. Ce que fait `blocked` dépend de la version : - **À partir de `2026-11-02`**, un client bloqué ne peut plus payer, en sandbox comme en live. Un nouveau paiement pour lui, désigné par `customer_id` ou retrouvé par son email ou son téléphone, répond `403` avec `error_code: customer_blocked`, et rien n'est créé. Un paiement créé sur cette version ne peut plus être débité ni confirmé une fois son client bloqué. Vos liens de paiement et vos factures créent leurs paiements sur la version à laquelle votre compte est fixé. [Clients bloqués](https://docs.wajub.com/fr/api/errors#blocked-customers) - **Avant `2026-11-02`**, `blocked` ne fait que signaler le client, à votre équipe et à vos [règles de routage](https://docs.wajub.com/fr/orchestration/routing-rules) : il peut toujours payer. Le débloquer lui permet de payer à nouveau. [Gestion des versions](https://docs.wajub.com/fr/api/versioning) explique comment votre version est choisie. > [!NOTE] > **Pour refuser un payeur quelle que soit la version** > > Ajoutez son email ou son téléphone à la [liste de blocage](https://docs.wajub.com/fr/risk/shield/rules) de Shield, vérifiée > sur chaque transaction live, qui la rejette d'emblée. ## Numéros fiscaux Les numéros d'identification fiscale d'un client entreprise sont conservés dans leur propre liste, une entrée par numéro : un NIU camerounais, un NINEA sénégalais, un numéro de TVA européen. La liste est disponible en live uniquement. `POST /customers/{id}/tax_ids` - `type` (string, required): Le type de numéro : `cm.niu`, `sn.ninea`, `ci.ifu`, `ke.pin`, `ng.tin`, `gh.tin`, `gh.vat`, `eu.vat`, `gb.vat` ou `us.ein`. Un autre type est accepté aussi, et seule sa longueur est vérifiée. - `value` (string, required): Le numéro lui-même, avec ou sans les espaces et tirets que son format comporte. - `country_code` (string, required): ISO 3166-1 alpha-2, par exemple `CM`. Ajoutez le numéro depuis votre serveur, avec une clé privée live : **Ajouter un numéro fiscal** ```bash curl https://api.wajub.com/customers/cus_sAaim5apjocIgtlhzJY3wQ8s/tax_ids \ -H "Authorization: $WAJUB_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "cm.niu", "value": "M123456789000L", "country_code": "CM" }' ``` ```javascript const taxId = await wajub.customers.createTaxId('cus_sAaim5apjocIgtlhzJY3wQ8s', { type: 'cm.niu', value: 'M123456789000L', country_code: 'CM', }); console.log(taxId.verification_status); ``` ```python tax_id = wajub.customers.create_tax_id("cus_sAaim5apjocIgtlhzJY3wQ8s", { "type": "cm.niu", "value": "M123456789000L", "country_code": "CM", }) print(tax_id["verification_status"]) ``` ```php $taxId = $wajub->customers->createTaxId('cus_sAaim5apjocIgtlhzJY3wQ8s', [ 'type' => 'cm.niu', 'value' => 'M123456789000L', 'country_code' => 'CM', ]); echo $taxId['verification_status']; ``` ```go taxID, err := client.Customers.CreateTaxID(context.Background(), "cus_sAaim5apjocIgtlhzJY3wQ8s", map[string]any{ "type": "cm.niu", "value": "M123456789000L", "country_code": "CM", }, nil) if err != nil { log.Fatal(err) } log.Println(taxID["verification_status"]) ``` Le numéro revient `pending` pendant que Wajub le vérifie. `verification_status` passe ensuite à `verified` quand la valeur respecte le format de son type, à `failed` quand elle ne le respecte pas, et à `unavailable` quand la vérification n'a pas pu se faire. Les formats sont ceux qui servent à vérifier votre propre numéro d'immatriculation ([configuration de Tax](https://docs.wajub.com/fr/tax/configuration#customer-tax-ids) les liste) : un NIU camerounais compte une lettre, douze chiffres et une lettre. Pour un numéro `eu.vat`, la vérification confirme aussi que le numéro est enregistré. Ajouter de nouveau le même type et le même numéro ne crée pas de copie : l'appel répond `200` avec l'entrée existante, repassée à `pending` le temps d'une nouvelle vérification. C'est ainsi que l'on relance une vérification `unavailable`. `GET /customers/{id}/tax_ids` liste les numéros avec leur statut, et `DELETE /customers/{id}/tax_ids/{tax_id}` en retire un. ## Webhooks Trois événements suivent un client, et ils portent l'objet client complet comme payload. | Événement | Déclenché quand | | ------------------ | ----------------------------------------------------------------------------------- | | `customer.created` | Un client est créé, y compris implicitement par un paiement | | `customer.updated` | Un champ change, y compris un changement de statut ou une fusion depuis un paiement | | `customer.deleted` | Le client est supprimé et anonymisé | `customer.created` est plus bavard qu'il n'y paraît : il se déclenche pour chaque nouveau payeur que voit votre checkout, pas seulement pour ceux que vous créez vous-même. L'enregistrement, la vérification et les nouvelles tentatives sont traités dans [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks). - [Référence API des clients](https://docs.wajub.com/fr/api/customers): Tous les champs de la ressource, et ses endpoints. - [Règles Shield](https://docs.wajub.com/fr/risk/shield/rules): La liste de blocage qui refuse vraiment un payeur, par email, téléphone, IP ou BIN. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): Enregistrez un endpoint et vérifiez la signature des événements client. - [Pagination](https://docs.wajub.com/fr/api/pagination): Des numéros de page pour un écran, des curseurs pour un export. --- # Pocket URL: https://docs.wajub.com/fr/payments/customers/pocket > Le côté du payeur. Où vos clients retrouvent leurs paiements, demandent un remboursement, le font passer en litige ou suppriment leurs données. Vos clients ont leur propre espace, Pocket, sur `pocket.wajub.com`. Un payeur s'y connecte avec son adresse e-mail ou son numéro de téléphone et un code à usage unique, et y retrouve chaque paiement live fait avec cette adresse ou ce numéro, chez tous les marchands de Wajub. Depuis Pocket, il peut : - vous demander un remboursement, avec un montant et un motif. La demande arrive dans la liste **Litiges** de votre Dashboard, où vous l'acceptez ou la refusez ; - faire passer cette demande en [litige](https://docs.wajub.com/fr/payments/disputes) une fois que vous l'avez refusée, pendant 30 jours après votre réponse, ou quand elle attend depuis 7 jours sans réponse ; - suivre ses litiges, y compris les rétrofacturations ouvertes par sa banque, et vous y écrire ; - retirer un moyen de paiement enregistré, ou choisir celui par défaut ; - consulter et télécharger les factures qui lui ont été envoyées ; - supprimer ses données. Tant que la banque du payeur traite une rétrofacturation sur un paiement, le payeur ne peut ni envoyer de demande de remboursement sur ce paiement ni en faire passer une en litige, et ces délais attendent : ils reprennent là où ils en étaient une fois que la banque a tranché. Les détails sont dans [Demandes de remboursement](https://docs.wajub.com/fr/payments/refunds#refund-requests). Il n'y a rien à intégrer : Pocket lit les mêmes clients et paiements que votre intégration crée, une raison de plus d'envoyer la vraie adresse e-mail et le vrai numéro du payeur. - [Litiges](https://docs.wajub.com/fr/payments/disputes): Ce qui se passe une fois qu'un payeur fait passer une demande en litige depuis Pocket. - [Suppression et effacement](https://docs.wajub.com/fr/payments/customers/delete): Ce que supprimer un client efface, et ce qui reste. --- # Litiges URL: https://docs.wajub.com/fr/payments/disputes > Quand un payeur conteste un paiement, comment vous répondez, et ce qu'une perte vous coûte. Un litige, c'est un payeur, ou son réseau de carte, qui conteste l'un de vos paiements : vous y répondez, et il se termine soit avec l'argent conservé, soit avec votre solde débité. Vous ne pouvez pas en créer un par l'API. > [!CAUTION] > **Les endpoints de litige exigent la clé secrète** > > Chaque appel de cette section exige une clé secrète et répond `406 Not Acceptable` > avec `Private Key Required` à une clé publique. Ces appels ont leur place sur votre serveur. Deux pages vont plus loin : - [Répondre à un litige](https://docs.wajub.com/fr/payments/disputes/respond), avec des justificatifs, en concédant, ou en échangeant avec le payeur. - [Suivre les litiges](https://docs.wajub.com/fr/payments/disputes/track), les consulter et les webhooks qu'ils envoient. ## D'où vient un litige Un litige vous parvient de l'un de deux endroits. **Le payeur fait passer une demande de remboursement en litige depuis Pocket**, le portefeuille Wajub où il retrouve les paiements qu'il a effectués. Un problème y commence par une [demande de remboursement](https://docs.wajub.com/fr/payments/refunds#refund-requests) qui vous est adressée. Le payeur peut la transformer en litige une fois que vous l'avez refusée, pendant 30 jours après votre réponse, ou quand elle attend depuis 7 jours sans réponse. Il choisit un motif, et le texte de sa demande devient le premier message du fil de discussion du litige. | Motif choisi par le payeur | Ce qu'il affirme | | -------------------------- | -------------------------------------------------------- | | `product_not_received` | Il a payé et rien n'est arrivé | | `product_not_as_described` | Ce qui est arrivé ne correspond pas à ce qui était vendu | | `duplicate_charge` | Il a été débité deux fois pour la même chose | | `fraudulent` | Il n'a pas effectué ce paiement | | `other` | Tout autre cas, expliqué dans la description | Un litige ouvert depuis Pocket porte sur le montant demandé par le payeur, plafonné à ce qui reste sur le paiement une fois retirés ses remboursements et les rétrofacturations que vous avez perdues, et porte un `due_date` avant lequel répondre, sept jours après son ouverture. **Le prestataire signale une rétrofacturation.** Quand un réseau de carte ou un prestataire notifie une rétrofacturation sur l'un de vos paiements, Wajub ouvre un litige pour elle. Il porte la référence du prestataire dans `provider_reference`, son code de motif dans `reason`, et le montant que le prestataire conteste, qui peut être inférieur au paiement. Il porte aussi un `due_date` : l'échéance du prestataire quand il en envoie une, sept jours après l'ouverture sinon. Un avis ultérieur pour la même rétrofacturation, avec le même `provider_reference`, met à jour son litige au lieu d'en ouvrir un second, même une fois qu'il est tranché. Une rétrofacturation qui arrive pendant qu'un litige du payeur ouvert depuis Pocket est en cours sur le paiement ouvre son propre litige. Le payeur ne peut pas faire passer une demande en litige pendant qu'une rétrofacturation est en cours sur le paiement, ni ouvrir un second litige depuis Pocket sur ce paiement. > [!WARNING] > **Les litiges n'existent pas en sandbox** > > Les litiges viennent de vrais payeurs et de vrais prestataires : un paiement de test n'en produit > donc jamais. Ce parcours ne peut pas être répété de bout en bout avant de passer en live. > Construisez votre handler à partir des payloads de cette page, puis vérifiez-le sur le premier > vrai litige que vous recevez. > [!NOTE] > **Le montant est bloqué tant que le litige est ouvert** > > Un litige ouvert depuis Pocket, sur un paiement que Wajub a encaissé pour vous, fait > passer le montant contesté de votre solde disponible à votre solde en litige, dans la limite de > votre solde disponible. Gagner le rend disponible. Perdre le débite, comme décrit plus bas. ## Les états d'un litige **Litige** `open` (en attente de vos justificatifs) → `under_review` (justificatifs reçus, en cours d'examen) → [`dispute.won`] `won` (vous gardez l'argent) L'autre issue, depuis open ou under_review: - `lost` (montant débité de votre solde) Un litige arrive en `open`. L'envoi de justificatifs le fait passer de lui-même en `under_review`, vous ne réglez pas ce statut vous-même. Depuis l'un ou l'autre de ces deux états, il peut se terminer en `won` ou en `lost`. Sur un litige ouvert depuis Pocket, les deux sont définitifs. C'est Wajub qui tranche un litige ouvert depuis Pocket, et la banque du payeur une rétrofacturation. Aucun endpoint ne vous permet de vous déclarer gagnant ; ce que vous pouvez faire, c'est présenter les justificatifs à ceux qui décident, ou concéder. ### Comment une rétrofacturation est tranchée La banque du payeur tranche une rétrofacturation, par l'intermédiaire du prestataire, et le litige suit la décision que le prestataire signale. Une décision fixe `status` et `resolved_at`, avec `metadata.decided_by` à `provider` et `metadata.provider_stage`, le nom de l'étape du prestataire qui a tranché. | Ce que signale le prestataire | Ce que devient le litige | | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Un gain | `open` ou `under_review` passe en `won` | | Une perte | `open`, `under_review` ou `won` passe en `lost` : une rétrofacturation gagnée peut encore être perdue à une étape ultérieure | | Une nouvelle étape de rétrofacturation qui reprend les fonds, après un gain | `won` repasse en `open` : `resolved_at` est effacé, `due_date` est fixé de nouveau, à l'échéance du prestataire ou sept jours plus tard, et `metadata.reopened_at` en garde la date | `lost` est définitif : un gain signalé après une perte ne change rien. Chaque changement envoie `dispute.updated`, avec `dispute.won` pour un gain, ou `dispute.lost` et `dispute.closed` pour une perte. Un litige rouvert n'envoie que `dispute.updated`, et son rappel d'échéance est envoyé de nouveau. ## Ce que coûte une perte Sur un paiement que Wajub a encaissé pour vous, un litige perdu retire le montant contesté de votre solde, plafonné à ce qui n'est pas déjà sorti par un remboursement sur le même paiement, pour que l'argent ne puisse pas être pris deux fois. Sur un paiement encaissé par votre propre compte chez un prestataire, Wajub ne détient pas l'argent, et le prestataire règle la rétrofacturation directement avec vous. Des **frais de litige forfaitaires** s'ajoutent, 15 000 XAF par défaut dans la devise du litige, quand la perte vient de l'API, avec `accept` ou `close`, ou d'une rétrofacturation du prestataire. Accepter depuis le Dashboard ne les facture pas. Perdre un litige de 25 000 XAF par l'API coûte donc 40 000 XAF, et non 25 000. Les débits ont lieu au changement de statut lui-même, pas lors d'un appel que vous feriez ensuite, et une seule fois par litige : une rétrofacturation perdue après un gain ou une réouverture n'est débitée qu'une fois. Un litige ne change pas le statut du paiement d'origine. Quand vous acceptez, le remboursement que Wajub crée pour le payeur est un remboursement ordinaire, avec ses propres événements `refund.*`, et il apparaît sur le paiement comme n'importe quel autre. Il ne retire pas le montant contesté une seconde fois. Si le payeur a payé les frais Wajub en plus du prix (`bearer: customer`), ces frais vous sont débités aussi, puisque le payeur récupère tout ce qu'il a payé. Le mouvement d'argent apparaît sur votre solde, et c'est là que vous le rapprochez. ## Les remboursements attendent la fin d'une rétrofacturation Tant qu'une rétrofacturation est `open` ou `under_review` sur un paiement, aucun remboursement de ce paiement n'est effectué : la banque du payeur peut rendre l'argent elle-même. `POST /refunds` répond `422` avec ce message : `Transaction cannot be refunded while a chargeback is open: the payer's bank may return the funds itself. It can be refunded again once the dispute is decided.` Accepter un litige du payeur sur le même paiement échoue avec la même réponse, et le litige reste tel quel, puisque l'accepter rembourse le payeur. Clôturer un paiement en plusieurs fois avec `outcome: refund` répond `409` avec le code `chargeback_open`. Un litige ouvert depuis Pocket ne bloque aucun remboursement. Les détails sont dans [Remboursements](https://docs.wajub.com/fr/payments/refunds#what-can-be-refunded). ## Dans le Dashboard **Litiges** les liste avec leur statut et le paiement concerné. Ouvrir un litige vous donne la description du payeur, le fil de messages, et les trois mêmes actions que l'API, plus une qu'elle n'expose pas : vous pouvez marquer ici un litige ouvert depuis Pocket comme gagné quand Wajub a tranché en votre faveur. Une rétrofacturation ne peut pas être marquée gagnée : son prestataire la tranche. La même liste porte les [demandes de remboursement](https://docs.wajub.com/fr/payments/refunds#refund-requests) que les payeurs envoient depuis Pocket, comme une étape à part. La section exige la permission `manage_disputes`, distincte de `manage_payments`, pour qu'un coéquipier puisse gérer les commandes sans pouvoir concéder un litige à votre place. ## Moins de litiges coûte moins cher que d'en gagner Un litige vous coûte du temps quelle qu'en soit l'issue, et le travail le plus rentable se fait donc avant qu'il n'existe. Remboursez de bon gré quand un client se plaint et que vous n'avez pas d'argument : un [remboursement](https://docs.wajub.com/fr/payments/refunds) que vous choisissez vous coûte le montant, un litige perdu vous coûte le montant plus les frais de litige forfaitaires. Gardez vos preuves de livraison là où vous pouvez les joindre en un clic. Et laissez [Shield](https://docs.wajub.com/fr/risk/shield) refuser les paiements les plus susceptibles de se retourner contre vous, puisqu'un paiement refusé d'emblée ne peut pas du tout être contesté. - [Shield, détection de fraude](https://docs.wajub.com/fr/risk/shield): Refusez les paiements risqués avant qu'ils puissent être contestés. - [Remboursements](https://docs.wajub.com/fr/payments/refunds): Rendez l'argent selon vos conditions, pas selon les siennes. - [Solde et règlements](https://docs.wajub.com/fr/payouts/balance): Où atterrit le débit d'un litige perdu. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): Enregistrez un endpoint et vérifiez la signature des événements de litige. - [Bonnes pratiques de sécurité](https://docs.wajub.com/fr/best-practices/security): Limitez la fraude côté intégration. - [Référence API des litiges](https://docs.wajub.com/fr/api/disputes): Chaque champ de la ressource, et les six endpoints. --- # Répondre à un litige URL: https://docs.wajub.com/fr/payments/disputes/respond > Envoyer des justificatifs, concéder ou échanger avec le payeur. ## Répondre avec des justificatifs C'est cette étape qui décide de l'issue, et elle mérite d'être soignée. Chaque justificatif est classé sous un type, et vous pouvez faire plusieurs appels pour constituer votre dossier. `POST /disputes/{id}/submit-evidence` - `evidence_type` (enum, required): L'un de `customer_communication`, `proof_of_delivery`, `service_documentation`, `receipt`, `product_description`, `cancellation_policy`, `refund_policy`, `duplicate_charge_documentation`, `other`. - `evidence_text` (string): Votre argumentaire écrit pour ce justificatif, 2 000 caractères maximum. - `evidence_file` (file): Un seul fichier : PDF, JPG, JPEG, PNG, DOC, DOCX ou TXT, 10 Mo maximum. Envoyez l'appel en `multipart/form-data`. Le type est un emplacement, pas une étiquette. Envoyez deux appels avec `proof_of_delivery` et le second remplace le premier, il ne s'y ajoute pas. Utilisez un type différent pour chaque justificatif distinct, et mettez tout ce que vous voulez dire sur un justificatif dans cet unique appel. Envoyez un texte, un fichier, ou les deux : un appel sans l'un ni l'autre répond `422`, et le litige reste où il était. Sans fichier, le justificatif est enregistré sous la forme de votre seul texte : `evidence.proof_of_delivery` est alors une chaîne et non un objet. Le nom que vous aviez donné à un fichier revient dans `file_name`. Les fichiers sont privés : aucune adresse ne les ouvre d'elle-même. Chaque réponse de l'API qui renvoie le litige donne à chaque fichier, justificatifs comme pièces jointes des messages, une `url`, un lien signé valable 30 minutes. Passé ce délai, relisez le litige pour en obtenir un nouveau. Un webhook porte `file_path` sans lien. Comme un fichier est en jeu, il s'agit d'un envoi de formulaire et non d'un corps JSON. **Envoyer une preuve de livraison** ```bash curl https://api.wajub.com/disputes/dsp_hrgUOE225KMKULRQqYvlh/submit-evidence \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -F "evidence_type=proof_of_delivery" \ -F "evidence_text=Delivered 12 Sept, signed for by the customer." \ -F "evidence_file=@/path/to/delivery-note.pdf" ``` ```javascript import { readFile } from 'node:fs/promises'; // Text alone goes through the SDK, as JSON. const dispute = await wajub.disputes.submitEvidence('dsp_hrgUOE225KMKULRQqYvlh', { evidence_type: 'proof_of_delivery', evidence_text: 'Delivered 12 Sept, signed for by the customer.', }); console.log(dispute.status); // A file needs multipart/form-data, which the SDK does not send. // Post the form yourself instead of the call above. const form = new FormData(); form.set('evidence_type', 'proof_of_delivery'); form.set('evidence_text', 'Delivered 12 Sept, signed for by the customer.'); form.set( 'evidence_file', new Blob([await readFile('./delivery-note.pdf')], { type: 'application/pdf' }), 'delivery-note.pdf', ); const response = await fetch('https://api.wajub.com/disputes/dsp_hrgUOE225KMKULRQqYvlh/submit-evidence', { method: 'POST', headers: { Authorization: process.env.WAJUB_API_KEY, Accept: 'application/json' }, body: form, }); if (!response.ok) { throw new Error('Evidence refused: ' + response.status); } const body = await response.json(); console.log(body.dispute.status); ``` ```python import os import httpx # Text alone goes through the SDK, as JSON. dispute = wajub.disputes.submit_evidence( "dsp_hrgUOE225KMKULRQqYvlh", { "evidence_type": "proof_of_delivery", "evidence_text": "Delivered 12 Sept, signed for by the customer.", }, ) print(dispute["status"]) # A file needs multipart/form-data, which the SDK does not send. # Post the form yourself instead of the call above. with open("delivery-note.pdf", "rb") as f: response = httpx.post( "https://api.wajub.com/disputes/dsp_hrgUOE225KMKULRQqYvlh/submit-evidence", headers={"Authorization": os.environ["WAJUB_API_KEY"], "Accept": "application/json"}, data={ "evidence_type": "proof_of_delivery", "evidence_text": "Delivered 12 Sept, signed for by the customer.", }, files={"evidence_file": ("delivery-note.pdf", f, "application/pdf")}, ) response.raise_for_status() print(response.json()["dispute"]["status"]) ``` ```php use GuzzleHttp\Client; // Text alone goes through the SDK, as JSON. $dispute = $wajub->disputes->submitEvidence('dsp_hrgUOE225KMKULRQqYvlh', [ 'evidence_type' => 'proof_of_delivery', 'evidence_text' => 'Delivered 12 Sept, signed for by the customer.', ]); echo $dispute['status']; // A file needs multipart/form-data, which the SDK does not send. // Post the form yourself instead of the call above, with the Guzzle // client the SDK already installed. $response = (new Client())->post( 'https://api.wajub.com/disputes/dsp_hrgUOE225KMKULRQqYvlh/submit-evidence', [ 'headers' => [ 'Authorization' => getenv('WAJUB_API_KEY'), 'Accept' => 'application/json', ], 'multipart' => [ ['name' => 'evidence_type', 'contents' => 'proof_of_delivery'], ['name' => 'evidence_text', 'contents' => 'Delivered 12 Sept, signed for by the customer.'], [ 'name' => 'evidence_file', 'contents' => fopen('delivery-note.pdf', 'r'), 'filename' => 'delivery-note.pdf', ], ], ], ); $body = json_decode((string) $response->getBody(), true); echo $body['dispute']['status']; ``` ```go // Text alone goes through the SDK, as JSON. dispute, err := client.Disputes.SubmitEvidence(context.Background(), "dsp_hrgUOE225KMKULRQqYvlh", map[string]any{ "evidence_type": "proof_of_delivery", "evidence_text": "Delivered 12 Sept, signed for by the customer.", }, nil) if err != nil { log.Fatal(err) } log.Println(dispute["status"]) // A file needs multipart/form-data, which the SDK does not send. // Post the form yourself instead of the call above. file, err := os.Open("delivery-note.pdf") if err != nil { log.Fatal(err) } defer file.Close() var form bytes.Buffer writer := multipart.NewWriter(&form) writer.WriteField("evidence_type", "proof_of_delivery") writer.WriteField("evidence_text", "Delivered 12 Sept, signed for by the customer.") part, err := writer.CreateFormFile("evidence_file", "delivery-note.pdf") if err != nil { log.Fatal(err) } if _, err := io.Copy(part, file); err != nil { log.Fatal(err) } writer.Close() req, err := http.NewRequest( http.MethodPost, "https://api.wajub.com/disputes/dsp_hrgUOE225KMKULRQqYvlh/submit-evidence", &form, ) if err != nil { log.Fatal(err) } req.Header.Set("Authorization", os.Getenv("WAJUB_API_KEY")) req.Header.Set("Accept", "application/json") req.Header.Set("Content-Type", writer.FormDataContentType()) res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() log.Println(res.Status) ``` L'appel répond `200 OK` avec le litige dans son état actuel, déjà passé en `under_review`, et vos justificatifs regroupés sous `evidence`. ```json title="Réponse · 200 OK" { "code": 200, "status": "OK", "message": "Evidence submitted successfully", "dispute": { "id": "dsp_hrgUOE225KMKULRQqYvlh", "transaction": "trx_CSUGajfv9xh0XQ5wu2lx", "customer": "cus_sAaim5apjocIgtlhzJY3wQ8s", "amount": 25000, "currency": "XAF", "status": "under_review", "reason": "product_not_received", "evidence": { "proof_of_delivery": { "text": "Delivered 12 Sept, signed for by the customer.", "file_path": "…", "file_name": "delivery-note.pdf", "uploaded_at": "2026-09-11T12:04:00+00:00", "url": "https://…?signature=…" } }, "sandbox": false, "created_at": "2026-09-11T12:00:00+00:00" } } ``` Les justificatifs ne peuvent être déposés que tant que le litige est `open` ou `under_review`. Une fois en `won` ou `lost`, l'appel répond `422` et le dossier est clos. > [!WARNING] > **Les justificatifs restent chez Wajub** > > Quand le champ `evidence_reaches_provider` d'un litige vaut `false`, ce que > vous déposez est enregistré chez Wajub et lu par ceux qui tranchent un litige ouvert depuis Pocket. > Rien n'est transmis au prestataire ni au réseau de carte : pour une rétrofacturation, votre défense > doit passer par votre propre compte chez le prestataire. ## Concéder, et un appel qui ne fait pas ce que son nom laisse croire Si le payeur a raison, concédez tôt plutôt que de laisser traîner. `POST /disputes/{id}/accept` L'acceptation prend un `merchant_response` facultatif, 2 000 caractères maximum, enregistré sur le litige. Elle passe le litige en `lost` immédiatement, sans retour possible, et rend l'argent au payeur : Wajub crée un remboursement du montant contesté, plafonné à ce qui reste remboursable sur le paiement. Ce remboursement porte le motif `customer_complaint` et le motif du litige dans `metadata.dispute_reason`, et il rend au payeur tout ce qu'il a payé pour ce montant, y compris des frais qu'il aurait payés en plus. Si le remboursement ne peut pas être créé, l'appel échoue et le litige reste dans son état. Trois cas ne créent aucun remboursement, et le litige finit quand même `lost` : - **Une rétrofacturation.** La banque du payeur lui a déjà rendu l'argent : un remboursement paierait le payeur deux fois. - **Plus rien à rembourser.** Des remboursements antérieurs ont déjà rendu tout le paiement. - **Un litige dans une autre devise que son paiement.** Il n'y a pas de montant à rembourser dans la devise du paiement. > [!CAUTION] > **close, c'est accept sous un autre nom** > > `POST /disputes/{id}/close` n'est pas une façon neutre de ranger un litige. Il a exactement > le même effet que `accept` : le litige passe en `lost`, le payeur est remboursé sauf s'il s'agit > d'une rétrofacturation, et l'issue est définitive. Si vous cherchiez un appel qui classe un > litige en votre faveur, il n'en existe pas. Envoyez plutôt des justificatifs. ## Échanger avec le payeur Un litige porte un fil de messages, ouvert par la description du payeur lui-même. Vous pouvez y répondre. `POST /disputes/{id}/messages` Les messages prennent `content`, obligatoire et limité à 5 000 caractères, et un tableau `attachments` facultatif de fichiers soumis aux mêmes contraintes que les justificatifs. Chaque pièce jointe revient avec `file_name`, `file_path` et la même `url` valable 30 minutes. `POST /disputes/{id}/send-message` est un alias du même appel. Vos messages sont enregistrés avec un `sender_type` à `merchant`, ceux du payeur avec `customer`, et le fil complet est renvoyé lorsque vous récupérez le litige. Le fil reste ouvert après l'issue : un message sur un litige déjà `won` ou `lost` est accepté et enregistré, mais ne change rien au résultat. - [Suivre les litiges](https://docs.wajub.com/fr/payments/disputes/track): Les consulter, et leurs webhooks. - [Référence API des litiges](https://docs.wajub.com/fr/api/disputes): Tous les endpoints des litiges. --- # Suivre les litiges URL: https://docs.wajub.com/fr/payments/disputes/track > Consulter vos litiges et les suivre par leurs webhooks. ## Consulter les litiges Récupérer un litige le renvoie avec sa transaction, son client et son fil de messages complet. `GET /disputes/{id}` `GET /disputes` | Paramètre de requête | Valeurs acceptées | | ---------------------- | ---------------------------------------------------------- | | `per_page` | De 1 à 100, 25 par défaut | | `status` | `open`, `under_review`, `won`, `lost` | | `search` | Texte libre sur l'id, le motif et la description du litige | | `date_from`, `date_to` | Dates, `date_to` pas antérieure à `date_from` | | `cursor` | Passe à la pagination par curseur | Au-delà des champs évidents, un litige porte la `description` du payeur, votre `merchant_response`, les justificatifs que vous avez déposés dans `evidence`, `resolved_at` une fois tranché, et `metadata`. Sur une rétrofacturation, `metadata.source` vaut `provider_webhook`. Une fois qu'elle est tranchée par le prestataire, `metadata.decided_by` vaut `provider` et `metadata.provider_stage` donne le nom de l'étape du prestataire qui a tranché. Une rétrofacturation gagnée que le prestataire rouvre repasse en `open`, avec `resolved_at` effacé et `metadata.reopened_at` renseigné. Les règles sont dans [Litiges](https://docs.wajub.com/fr/payments/disputes#how-a-chargeback-is-decided). > [!NOTE] > **Comment due_date est fixé** > > Chaque litige porte `due_date`, l'échéance avant laquelle répondre. Sur un litige ouvert depuis > Pocket, c'est sept jours après l'ouverture. Sur une rétrofacturation, c'est l'échéance du > prestataire quand il en envoie une, sept jours après l'ouverture sinon. Passé son échéance, un > litige Pocket reste ouvert jusqu'à ce que Wajub tranche. ## Webhooks Sept événements, et ceux qui méritent une action sont les issues, plus le rappel. | Événement | Déclenché quand | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `dispute.created` | Un litige a été ouvert, par un payeur ou à partir d'une rétrofacturation. Lisez-le et décidez comment répondre | | `dispute.updated` | Un champ a changé, y compris à chaque changement de statut, et quand une rétrofacturation gagnée est rouverte (`status: open`) | | `dispute.won` | Résolu en votre faveur, rien ne quitte votre solde. Sur une rétrofacturation, le prestataire peut encore décider autrement plus tard | | `dispute.lost` | Résolu contre vous, le montant est débité. Sur une rétrofacturation, il peut suivre un `dispute.won` | | `dispute.closed` | Envoyé avec `dispute.lost`. Un litige gagné ne l'envoie pas | | `dispute.deadline_approaching` | L'échéance est dans deux jours et le litige est encore `open` ou `under_review`. Envoyé une seule fois, avec `metadata.reminded_at` renseigné, et de nouveau après la réouverture d'une rétrofacturation ; répondez maintenant | | `dispute.deleted` | L'enregistrement du litige a été supprimé | `dispute.deadline_approaching` est envoyé pour chaque litige qui a une `due_date` : litiges Pocket et rétrofacturations à l'identique. L'écriture de `metadata.reminded_at` sur le litige envoie aussi un `dispute.updated` à côté. > [!WARNING] > **Une perte vous envoie trois webhooks** > > Le passage en `lost` émet `dispute.updated`, `dispute.lost` et `dispute.closed`, dans cet ordre, > pour le même événement. Choisissez-en un pour agir, `dispute.lost`, et laissez passer les deux > autres. Agir aussi sur `dispute.closed` débitera deux fois votre propre comptabilité. > [!NOTE] > **Une rétrofacturation gagnée peut revenir** > > La banque du payeur peut trancher contre vous à une étape ultérieure d'une rétrofacturation que > vous aviez gagnée, ou reprendre les fonds : le litige passe alors en `lost`, ou repasse en `open`, > et envoie ses webhooks comme pour tout autre changement. Wajub ne débite une perte qu'une fois par > litige : continuez d'agir sur `dispute.lost` seul, même quand un `dispute.won` l'a précédé. **`dispute.created`**: Un payeur a ouvert un litige sur l'un de vos paiements. ```json title="dispute.created" { "id": "evt_Qp7Tz3Wk5Yb1NdLm2Xc94Rf8", "event": "dispute.created", "created": "2026-09-11T12:00:00+00:00", "livemode": true, "data": { "id": "dsp_hrgUOE225KMKULRQqYvlh", "transaction": "trx_CSUGajfv9xh0XQ5wu2lx", "customer": "cus_sAaim5apjocIgtlhzJY3wQ8s", "amount": 25000, "currency": "XAF", "status": "open", "reason": "product_not_received", "description": "Ordered on 2 Sept, nothing delivered." } } ``` Dédupliquez sur l'`id` de l'événement, comme partout ailleurs. L'enregistrement et la vérification de signature sont décrits dans [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks). - [Répondre à un litige](https://docs.wajub.com/fr/payments/disputes/respond): Justificatifs, concession, échange avec le payeur. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): Recevoir et vérifier les événements. --- # Personnalisation URL: https://docs.wajub.com/fr/payments/link/customization > Ce que chaque lien hérite de votre compte, et ce que chacun contrôle de son côté. Votre **marque**, réglée une fois pour le compte, donne à chaque lien son logo, ses couleurs, sa police et son arrondi. Chaque **lien** contrôle son propre contenu : images, texte, bouton, questions, langues et personnes autorisées à l'ouvrir. ## Ce qui vient du compte, une fois pour toutes Le logo, la palette, la police, l'arrondi des angles et le mode d'apparence se trouvent dans **Paramètres → Image de marque**. Modifiez-les là et tous vos liens sont mis à jour d'un coup, en même temps que votre checkout hébergé et vos factures. Le tableau complet est sur [Checkout hébergé](https://docs.wajub.com/fr/payments/hosted-checkout#make-the-page-yours), puisque c'est le même réglage qui sert les trois. > [!NOTE] > **L'image de marque nécessite un plan payant** > > **Paramètres → Image de marque** dépend de la fonctionnalité Personnalisation du design, incluse à partir de **Growth**. Avec > Pay as you go, chaque lien garde l'apparence par défaut. Servir vos liens depuis votre propre > domaine plutôt que `wajub.link` est une fonctionnalité distincte, Domaine personnalisé, incluse à partir > de **Scale**. ## Ce qui appartient au lien Tout ce qui suit se règle lien par lien, et deux liens d'un même compte peuvent différer sur chacun de ces points. ### Images Le `poster` est la bannière en haut de la page, et `gallery` en contient jusqu'à dix autres, affichées en dessous. Pour un produit, c'est la différence entre une page qui vend et une page qui annonce un prix. Les deux voies n'acceptent pas la même chose. Le Dashboard téléverse des fichiers, JPEG, PNG, GIF ou WebP jusqu'à 10 Mo chacun, et les héberge pour vous. L'API prend des **URLs que vous hébergez déjà**, jusqu'à 2 048 caractères chacune, et ne téléverse jamais rien. Faites-les pointer vers des images que vous servez vous-même. ### Le bouton, et ce qui suit le paiement `cta_type` fixe le texte du bouton parmi `buy_now`, `pay`, `donate`, `register`, ou `custom` associé à votre propre `custom_cta_text` de 50 caractères maximum. `thank_you_message` remplace la confirmation par défaut une fois le paiement réussi. C'est la dernière chose que lit le payeur, c'est donc le bon endroit pour un délai de livraison ou une prochaine étape. ### Questions au payeur `extra_fields` ajoute des champs à la page : un numéro de table, une taille, une note pour la cuisine. Un champ a un `name`, en lettres minuscules, chiffres et tirets bas, un `label`, un `type` parmi `text`, `email`, `tel`, `textarea`, `select` et `checkbox`, un indicateur `required`, un `placeholder` facultatif, et pour un `select` ses `options`. Un lien accepte jusqu'à dix champs. La page demande en plus l'e-mail du payeur, toujours : un paiement sur un lien ne peut pas se faire sans. ```json title="Deux questions sur la page" { "extra_fields": [ { "name": "size", "label": "Size", "type": "select", "required": true, "options": ["S", "M", "L"] }, { "name": "note", "label": "Note to the seller", "type": "textarea", "required": false } ] } ``` Donnez à chaque champ un `name` et un `type`. Les réponses accompagnent le paiement, imbriquées et non aplaties : lisez `metadata.extra_fields.size` dans votre handler de webhook, pas `metadata.size`. ### Codes promo Un lien porte jusqu'à vingt codes promo, réglés dans le Dashboard. Chacun a un `code`, de 3 à 32 lettres majuscules, chiffres, tirets ou tirets bas, unique parmi vos liens, une remise en pourcentage ou en montant fixe, et en option un nombre maximal d'utilisations et une date d'expiration. Le payeur saisit le code sur la page et voit la remise avant de payer. ### Produits numériques Un produit `digital` est livré par e-mail une fois le paiement réussi : le payeur doit donc donner une adresse e-mail. Dans le Dashboard, vous téléversez le fichier, à partir du plan Growth, ou vous donnez une URL `https` vers lui, sur tous les plans ; `file_url` sur `POST /links` prend une adresse à vous, pas un fichier téléversé dans le Dashboard. Le bouton **Télécharger maintenant** de l'e-mail est un lien propre à ce paiement, jamais l'adresse du fichier lui-même, et la page ne montre le fichier qu'après le paiement. Le téléchargement fonctionne pendant la durée d'accès que vous fixez dans le Dashboard, ou sans limite si vous n'en fixez pas, même une fois le lien fermé ou archivé, et s'arrête quand le paiement est remboursé en totalité ou perdu dans un litige. Avec `single_use_access: true`, l'acheteur télécharge le fichier une seule fois : la page de téléchargement lui demande de le conserver, et une visite suivante indique que le téléchargement a déjà servi. C'est l'accès de l'acheteur, pas celui du lien : l'acheteur suivant peut toujours acheter, sauf si le lien est un [lien à usage unique](https://docs.wajub.com/fr/payments/link/tracking#how-a-link-closes). Quand `file_url` est votre propre adresse, l'acheteur y est envoyé : protégez-la comme tout téléchargement. ### Langues Un lien peut être bilingue. `supported_locales` liste les langues que la page propose parmi `fr` et `en`, `default_locale` indique celle qui s'affiche en premier, et `translations` contient l'autre version, indexée par langue. ```json title="Le même lien, en deux langues" { "default_locale": "fr", "supported_locales": ["fr", "en"], "translations": { "en": { "title": "Amina Coffee, 250 g", "description": "Roasted in Douala, ground to order.", "custom_cta_text": "Order now", "thank_you_message": "Thank you, we ship within 48 hours." } } } ``` Seuls quatre champs se traduisent : `title`, `description`, `custom_cta_text` et `thank_you_message`. Les champs de base du lien sont ceux qu'affiche la langue par défaut, vous n'écrivez donc jamais que la seconde langue dans `translations`. ### Devises `supported_currencies` permet au payeur de changer de devise sur la page. La `currency` propre au lien est toujours proposée, et les devises que vous ajoutez viennent s'y joindre. ### Qui peut entrer Cinq verrous indépendants, et la page se ferme dès que l'un d'eux se déclenche. | Réglage | Réponse de la page | | ---------------------------------------- | ------------------------------------------------ | | `is_public` mis à `false` | `404`, le lien n'est pas publié | | `access_password` | Une demande de mot de passe avant tout affichage | | `max_views` atteint | `410`, le plafond de vues est épuisé | | `expiry_date` dépassée, ou `is_archived` | `410`, le lien est terminé | | `single_use_link`, une fois payé | Que le lien a déjà servi à payer | Une tentative bloquée n'est pas comptée comme une vue : le verrou du mot de passe n'entame donc pas `max_views`. ### Ce que chaque type ajoute Le type apporte ses propres réglages, qui n'existent que sur ce type. | Type | Ce que vous pouvez régler | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `product` | `product_variants`, stock, livraison, poids, et pour un service la durée, le lieu et l'URL de réunion | | `event` | Types de billets avec leur propre nom, prix et quantité, `event_capacity`, `generate_qr_tickets`, `attendee_info_fields`, `refund_policy` | | `fundraising` | `show_progress`, `show_contributors`, `allow_overflow`, `impact_tiers`, `campaign_deadline`, `fundraising_milestones` | | `donation` | `suggested_amounts`, `allow_custom_amount`, `min_amount`, `max_amount`, `allow_anonymous`, `show_donor_wall` | L'URL de réunion d'un service n'est jamais sur la page avant le paiement : le payeur la reçoit dans l'e-mail de confirmation de son paiement, avec ce qu'il faut préparer, et la page propose de la rejoindre une fois le paiement fait. ## Ce que l'API peut régler, et ce qu'elle ne peut pas C'est ce qu'il faut savoir avant d'automatiser quoi que ce soit. L'API et le Dashboard n'atteignent pas les mêmes champs, et `POST /links` en atteint davantage que `PUT /links/{id}`. | Champ | Création via l'API | Mise à jour via l'API | Dashboard | | -------------------------------------------------------------------- | ------------------ | --------------------- | ---------------------------- | | `title`, `description`, `price` | Oui | Oui | Oui | | `currency` | Oui | Non | Oui | | `target_amount`, `min_amount`, `max_amount` | Oui | Oui | Oui | | `callback_url` | Oui | Oui | Non | | `cta_type`, `custom_cta_text` | Oui | Oui | Oui | | `custom_url`, `tags` | Oui | Oui | Oui | | `category_id` | Non | Non | Oui | | `is_public`, `is_archived`, `expiry_date`, `sales_limit` | Oui | Oui | Oui | | `accept` (moyens de paiement proposés) | Oui | Oui | Oui | | `extra_fields`, `thank_you_message` | Oui | Non | Oui | | `poster`, `gallery` | Oui, en URLs | Non | Oui, en fichiers téléversés | | `allow_overflow`, sur une collecte | Oui | Oui | Oui | | Autres champs propres au type, événement et collecte de fonds | Oui | Non | Oui | | `supported_locales`, `default_locale`, `translations` | Non | Non | Oui | | `supported_currencies` | Non | Non | Oui | | `access_password`, `max_views` | Non | Non | Oui | | `single_use_link`, `single_use_access` | Oui | Non | Oui | | `file_url`, le fichier d'un produit numérique à votre propre adresse | Oui | Non | Oui, ou un fichier téléversé | | Codes promo | Non | Non | Oui | | Domaine personnalisé, types de billets | Non | Non | Oui | > [!WARNING] > **La mise à jour via l'API est plus restreinte que la création** > > `PUT /links/{id}` ignore les champs marqués Non dans la colonne Mise à jour via l'API, et répond > tout de même `200`. Modifiez-les dans le Dashboard. ## Dans le Dashboard Les langues, les devises, le mot de passe d'accès, le plafond de vues, le domaine personnalisé et les types de billets d'un événement ne se règlent que dans le Dashboard, dans le formulaire du lien. Le guide du tableau de bord montre [comment créer un lien](https://docs.wajub.com/dashboard/payment-links/create) et [comment le modifier](https://docs.wajub.com/dashboard/payment-links/edit-offline-delete#edit). Chaque lien a aussi ses propres endpoints de webhook, distincts de ceux de votre compte, avec leur propre secret, un envoi de test et une nouvelle tentative. Utilisez-les quand une campagne doit prévenir un système que le reste de votre compte ne prévient pas. Une livraison ne compte que si l'endpoint répond par un `2xx` : toute autre réponse, une redirection comprise, est enregistrée comme échouée et retentée, et une redirection n'est jamais suivie. L'envoi de test indique seulement si l'endpoint l'a accepté. Le guide du tableau de bord montre [où en ajouter un](https://docs.wajub.com/dashboard/payment-links/notify-server). - [Liens de paiement](https://docs.wajub.com/fr/payments/link): Ce qu'est le produit, et quand un lien vaut mieux qu'une intégration. - [Démarrage rapide](https://docs.wajub.com/fr/payments/link/quickstart): Créez un lien, publiez-le, partagez-le. - [Suivi et conversions](https://docs.wajub.com/fr/payments/link/tracking): Vues, taux de conversion et cycle de vie d'un lien. - [Image de marque du Checkout hébergé](https://docs.wajub.com/fr/payments/hosted-checkout): Les réglages du compte dont hérite chaque page de paiement. - [Référence API des liens de paiement](https://docs.wajub.com/fr/api/payment-links): Chaque champ accepté par l'API, endpoint par endpoint. --- # Liens de paiement URL: https://docs.wajub.com/fr/payments/link > Encaissez depuis une URL que vous partagez, sans intégration et sans page à vous. Un lien de paiement est une URL qui encaisse de l'argent : vous décrivez ce que vous vendez, Wajub héberge la page, et vous partagez l'adresse là où se trouvent vos clients. Ni code ni serveur à vous. ## Quand un lien vaut mieux qu'une intégration Optez pour un lien quand ce que vous vendez ne justifie pas un checkout, ou quand il n'existe aucun site où placer un checkout. Une boutique qui vend sur WhatsApp sans vitrine en ligne. Une facture ponctuelle pour un seul client. Des billets pour un événement le mois prochain. Une collecte de fonds qui a besoin d'une barre de progression et d'un mur des donateurs. Un consultant qui prend un acompte avant une réservation. Optez plutôt pour le [Checkout hébergé](https://docs.wajub.com/fr/payments/hosted-checkout) dès que le paiement conclut un parcours piloté par votre logiciel : un panier, une commande, un abonnement. Un lien ne sait rien de votre commande, et ne peut pas être créé au moment où un client en a besoin, sauf si vous appelez l'API. ## Quatre types de lien Le type n'est pas une étiquette, il change la page. Choisissez celui qui correspond à ce que vous encaissez. | Type | La page affiche | Choisissez-le quand | | ------------- | ---------------------------------------------------------------- | ---------------------------------------------- | | `product` | Un prix fixe et un bouton d'achat | Vous vendez une seule chose à un seul prix | | `event` | Une date, un lieu, un nombre de billets | Vous vendez l'accès à quelque chose qui a lieu | | `fundraising` | Un objectif, sa progression, et éventuellement les contributeurs | Vous collectez en vue d'un total | | `donation` | Un montant libre, dans des bornes que vous pouvez fixer | Le payeur décide de ce qu'il donne | Un lien `product` porte aussi un `product_type`, parmi `physical`, `digital` ou `service`, qui fait apparaître sur la page les champs de stock, de livraison ou de réservation. ## Deux façons d'en créer un **Le Dashboard** est la voie normale. **Liens → Créer un lien** parcourt les champs avec un aperçu en direct, génère le QR code, et publie quand vous êtes prêt. Rien sur cette page ne nécessite un développeur. **L'API** sert quand les liens sont produits par votre propre logiciel : un par client, un par campagne, un par commande. Même objet, même page. `POST /links` La liste complète des champs, ceux qui sont obligatoires selon le type, et les pièges à connaître sont dans le [Démarrage rapide](https://docs.wajub.com/fr/payments/link/quickstart). > [!CAUTION] > **Deux points qui vont vous piéger** > > Les liens sont **uniquement en production**. Il n'existe pas d'équivalent en sandbox, le premier > lien que vous créez encaisse donc de l'argent réel : une clé de test reçoit `403` sur tout appel > à `/links`, avec `This feature is only available in live mode.` Et un lien **est en ligne dès sa > création** : `is_public` vaut `true` par défaut, l'URL renvoyée est donc immédiatement ouverte aux > payeurs. Envoyez `is_public: false` pour préparer un lien et le publier quand vous êtes prêt. ## Ce que cela implique pour votre plan Les liens de paiement nécessitent la fonctionnalité Liens de paiement. **Pay as you go** les inclut, avec un plafond de 25 liens actifs ; Growth et les plans supérieurs suppriment ce plafond. Créer un lien au-delà de votre plafond répond `403` avec un message de mise à niveau, plutôt que d'échouer en silence. Les liens archivés comptent dans ce plafond : supprimez un lien, plutôt que de l'archiver, pour libérer sa place. Par défaut, un lien est servi depuis `wajub.link`. Sur Scale, un domaine personnalisé vérifié le sert à la place, et l'adresse que voit le payeur est la vôtre. ## Ce que vous obtenez en retour Un lien produit des paiements ordinaires, sur les mêmes canaux que tout le reste : MTN, Orange, Wave, Airtel, Moov, M-Pesa, et les cartes là où le pays les prend en charge. La matrice complète est dans [Moyens de paiement](https://docs.wajub.com/fr/payments/payment-methods). Il n'y a donc pas de rapprochement séparé. Le paiement arrive dans votre liste Payments, déclenche `payment.succeeded`, est réglé sur votre solde et peut être remboursé comme n'importe quel autre. Ce que le lien ajoute par-dessus, c'est la page, le partage, et des statistiques par lien. | Besoin | Où | | ------------------------------------------------ | ------------------------------------------------ | | Créer votre premier lien | [Démarrage rapide](https://docs.wajub.com/fr/payments/link/quickstart) | | Modifier l'apparence de la page | [Personnalisation](https://docs.wajub.com/fr/payments/link/customization) | | Voir les vues, les conversions et la vie du lien | [Suivi](https://docs.wajub.com/fr/payments/link/tracking) | | Chaque champ de la ressource | [Référence API](https://docs.wajub.com/fr/api/payment-links) | - [Démarrage rapide Liens de paiement](https://docs.wajub.com/fr/payments/link/quickstart): Créez un lien, publiez-le, partagez-le, soyez prévenu quand quelqu'un paie. - [Personnalisation](https://docs.wajub.com/fr/payments/link/customization): Couleurs de marque, logo, et champs de la page. - [Suivi et conversions](https://docs.wajub.com/fr/payments/link/tracking): Vues, taux de conversion, et vie d'un lien. - [Choisir une intégration](https://docs.wajub.com/fr/payments/integration-paths): Les quatre modes comparés, et quand un lien n'est pas le bon choix. - [Moyens de paiement](https://docs.wajub.com/fr/payments/payment-methods): Les opérateurs que voient vos payeurs, pays par pays. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): Écoutez payment.succeeded et livrez la commande automatiquement. --- # Démarrage rapide URL: https://docs.wajub.com/fr/payments/link/quickstart > Créez un lien de paiement, partagez-le, et encaissez sans écrire d'intégration. Créez un lien, partagez son adresse, et soyez prévenu par webhook quand quelqu'un paie, sans écrire d'intégration. > [!WARNING] > **Production uniquement, et soumis au plan** > > Les liens de paiement n'existent pas dans la sandbox. Chaque lien est actif et encaisse de > l'argent réel dès le premier partage : pour tester, vous payez un petit montant réel que vous > remboursez ensuite. La fonctionnalité Liens de paiement doit aussi figurer dans votre plan : **25 > liens avec Pay as you go**, illimités à partir de Growth. Au-delà du plafond, la création répond > `403` avec un message de mise à niveau. Une clé de test (`sk_test.`) reçoit `403` sur tout appel à > `/links`, avec `This feature is only available in live mode.` ## 1. Choisissez l'usage du lien Le `type` détermine la forme de la page et les champs qui deviennent obligatoires. Il en existe quatre, et le choix n'est pas cosmétique : un lien de collecte de fonds affiche une barre de progression, un lien d'événement affiche une date et un lieu. | Type | Ce que voit le payeur | Ce qu'il exige | | ------------- | ----------------------------------------------- | ------------------------------------------------------ | | `product` | Un prix fixe que vous définissez | `price` | | `event` | Une date, un lieu, un nombre de billets | `event_start_date`, `event_location`, `event_timezone` | | `fundraising` | Une campagne avec un objectif et sa progression | `target_amount` | | `donation` | Un montant libre, ou borné par vous | Rien de plus que l'essentiel | Au-delà du type, chaque lien a besoin d'un `title` d'au moins trois caractères, d'une `currency`, et d'un `cta_type` qui fixe le libellé du bouton : `buy_now`, `pay`, `donate`, `register`, ou `custom` avec votre propre `custom_cta_text`. Un lien `product` exige aussi un `product_type`, parmi `physical`, `digital` ou `service`, qui fait apparaître plus bas les champs de stock, de livraison ou de réservation. ## 2. Créez-le Le Dashboard est la voie la plus rapide : **Liens → Créer un lien** parcourt les mêmes champs avec un aperçu à côté. Ce qui suit est l'équivalent par l'API, pour le cas où les liens sont générés par votre propre logiciel. `POST /links` - `type` (enum, required): `product`, `event`, `fundraising` ou `donation`. - `product_type` (enum): Obligatoire pour un `product` : `physical`, `digital` ou `service`. - `title` (string, required): Affiché comme titre de la page. Trois caractères minimum. - `currency` (string, required): Code ISO 4217, la devise dans laquelle chaque paiement de ce lien est encaissé. - `cta_type` (enum, required): Libellé du bouton : `buy_now`, `pay`, `donate`, `register` ou `custom`. - `price` (number): Obligatoire pour un `product`. Le montant fixe débité au payeur. - `target_amount` (number): Obligatoire pour `fundraising`. L'objectif que remplit la barre de progression. - `min_amount` (number): Plancher du montant libre, sur une `donation`. - `max_amount` (number): Plafond du montant libre, sur une `donation`. - `custom_url` (string): Votre propre slug à la place de celui généré : lettres, chiffres, traits d'union et underscores. Unique sur tout Wajub, liens supprimés compris : un slug déjà pris par un autre marchand, ou par un lien que vous avez supprimé, répond `422` sur `custom_url`. - `external_reference` (string): Votre propre référence pour le lien, jusqu'à 255 caractères. Renvoyée telle quelle, jamais montrée aux payeurs. - `description` (string): Texte principal de la page, 5 000 caractères maximum. - `callback_url` (string (url)): Où le payeur est envoyé une fois le paiement terminé : après une réussite, et aussi quand il annule sur la page. Lisez `status` dans la chaîne de requête. - `expiry_date` (string (date)): Date à laquelle le lien cesse d'accepter des paiements. Doit être dans le futur. - `sales_limit` (integer): Le nombre d'unités que le lien peut vendre. Chaque paiement compte sa quantité, et un paiement encore en cours réserve ses unités jusqu'à ce qu'il réussisse ou expire. - `extra_fields` (array): Questions posées sur la page. Détaillé à l'étape suivante. - `is_public` (boolean, default `true`): Indique si la page s'ouvre à son URL. Envoyez `false` pour créer le lien hors ligne : il répond alors `404` aux payeurs jusqu'à sa publication. Envoyez-le avec la clé secrète. Les liens n'existent qu'en live, la clé est donc `sk.` et non `sk_test.`. **Créer un lien de type product** ```bash curl https://api.wajub.com/links \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: link-cafe-amina" \ -d '{ "type": "product", "product_type": "physical", "title": "Café Amina, 250 g", "currency": "XAF", "price": 3500, "cta_type": "buy_now", "custom_url": "cafe-amina", "is_public": true }' ``` ```javascript const link = await wajub.links.create({ type: 'product', product_type: 'physical', title: 'Café Amina, 250 g', currency: 'XAF', price: 3500, cta_type: 'buy_now', custom_url: 'cafe-amina', is_public: true, }); console.log(link.url); ``` ```python link = wajub.links.create({ "type": "product", "product_type": "physical", "title": "Café Amina, 250 g", "currency": "XAF", "price": 3500, "cta_type": "buy_now", "custom_url": "cafe-amina", "is_public": True, }) print(link.url) ``` ```php $link = $wajub->links->create([ 'type' => 'product', 'product_type' => 'physical', 'title' => 'Café Amina, 250 g', 'currency' => 'XAF', 'price' => 3500, 'cta_type' => 'buy_now', 'custom_url' => 'cafe-amina', 'is_public' => true, ]); echo $link->url; ``` ```go link, err := client.Links.Create(context.Background(), map[string]any{ "type": "product", "product_type": "physical", "title": "Café Amina, 250 g", "currency": "XAF", "price": 3500, "cta_type": "buy_now", "custom_url": "cafe-amina", "is_public": true, }, nil) ``` La réponse est `201 Created`, et `url` est ce que vous cherchiez : l'adresse que vous partagez, construite à partir de votre `custom_url` si vous en avez défini un, et de l'id généré sinon. ```json title="Réponse · 201 Created" { "code": 201, "status": "Created", "message": "Payment link created", "link": { "id": "8kD2xQpLm", "type": "product", "product_type": "physical", "title": "Café Amina, 250 g", "currency": "XAF", "price": 3500, "cta_type": "buy_now", "custom_url": "cafe-amina", "url": "https://wajub.link/cafe-amina", "qr_url": null, "is_public": true, "is_archived": false, "tags": [], "created_at": "2026-09-11T14:00:00+00:00" } } ``` > [!CAUTION] > **Un lien est en ligne dès sa création** > > `is_public` vaut `true` par défaut : l'URL renvoyée encaisse de l'argent réel dès que vous > l'avez. Envoyez `is_public: false` pour créer le lien hors ligne : il répond alors `404 This > payment link is not available` à tous ceux qui l'ouvrent, jusqu'à ce que vous le publiiez avec > `PUT /links/{id}` ou depuis la page du lien dans le Dashboard. Le Dashboard crée lui aussi les > liens en ligne, et expose le même indicateur sous le nom Status du lien. > [!WARNING] > **Le QR code vient du Dashboard** > > `qr_url` peut valoir `null` sur un lien créé par l'API. Téléchargez le QR code depuis la page du > lien dans le Dashboard, ou générez-le vous-même à partir de `url`. > [!NOTE] > **Un id de lien n'a pas de préfixe comme le reste de l'API** > > Les paiements sont `trx_…`, les clients `cus_…`, mais un id de lien est une chaîne nue de neuf > caractères comme `8kD2xQpLm`, parce qu'il sert aussi de slug dans l'URL. Définissez `custom_url` > et c'est votre slug qui apparaît dans l'adresse à la place ; l'id reste ce que vous passez à > `GET /links/{id}`. ## 3. Posez une question au payeur, si besoin Un numéro de table, une taille de T-shirt, une note de livraison : `extra_fields` ajoute des champs à la page et transmet les réponses jusqu'au paiement. ```json title="Deux questions sur la page" { "extra_fields": [ { "name": "table", "label": "Table number", "type": "text", "required": true }, { "name": "note", "label": "Note to the kitchen", "type": "textarea", "required": false } ] } ``` Un champ a besoin d'un `name` et d'un `type` : le `name` est la clé sous laquelle sa réponse revient, et le `type` est le champ de saisie que la page affiche. [Personnalisation](https://docs.wajub.com/fr/payments/link/customization#questions-for-the-payer) liste les types et les autres options. Ce que le payeur saisit revient sur le paiement, imbriqué sous ses métadonnées plutôt qu'étalé dessus : c'est donc dans `metadata.extra_fields.table` que se trouve le numéro de table. Lisez-le là dans votre handler de webhook, et vous avez la réponse à côté de l'argent. ## 4. Partagez-le L'`url` fonctionne partout où une URL fonctionne : un message WhatsApp, une bio, un SMS, une affiche imprimée. Rien à intégrer, et aucune page à vous n'intervient. Pour une affiche, le Dashboard vous donne le QR code sur la page du lien, prêt à télécharger. Par défaut, un lien est hébergé sur `wajub.link`. Avec le plan Scale, un domaine personnalisé vérifié le sert à la place, et l'adresse que voit le payeur est la vôtre. Sur la page, le payeur voit les opérateurs disponibles dans son pays, la même liste que propose le checkout hébergé : MTN, Orange, Wave, Airtel, Moov, M-Pesa et les cartes là où le pays les prend en charge. La matrice complète est dans [Moyens de paiement](https://docs.wajub.com/fr/payments/payment-methods). ## 5. Soyez prévenu quand quelqu'un paie Un lien produit des paiements ordinaires. Il n'existe pas d'événement `link.paid` : ce que vous écoutez, c'est `payment.succeeded`, exactement comme pour les autres modes. | Événement | Déclenché quand | | ------------------- | ------------------------------------------------------------- | | `payment.succeeded` | Quelqu'un a payé via le lien. Livrez la commande sur celui-ci | | `link.created` | Un lien a été créé | | `link.updated` | Un lien a été modifié, archivé ou désarchivé | | `link.deleted` | Un lien a été supprimé | | `link.expired` | L'`expiry_date` d'un lien est passée | Définir un `callback_url` renvoie ensuite le payeur vers votre page, mais c'est une attention pour lui, pas un signal pour vous. Considérez le webhook comme la source de vérité, comme toujours. [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks) couvre l'enregistrement et la vérification de signature. ## Fermer un lien Trois façons différentes, selon ce que vous entendez par fermer. | Vous voulez | Définissez | | ------------------------------------------------------------- | ----------------------- | | Qu'il s'arrête à une date | `expiry_date` | | Qu'il s'arrête après N ventes | `sales_limit` | | Qu'il s'arrête après une vente, avec un seul payeur à la fois | `single_use_link: true` | Un lien peut aussi être archivé avec `is_archived` via `PUT /links/{id}`, ce qui le retire de vos listes sans détruire ce qu'il a déjà encaissé. `DELETE /links/{id}` le supprime purement et simplement. ## Dans le Dashboard **Liens**, c'est tout le produit sans l'API, et il montre ce que l'API n'expose pas : les vues et la conversion de chaque lien, les paiements qu'il a produits et les personnes qui ont payé, exportables. Le guide du tableau de bord le couvre, de [la création d'un lien](https://docs.wajub.com/dashboard/payment-links/create) à [son suivi](https://docs.wajub.com/dashboard/payment-links/track). La section exige la fonctionnalité Liens de paiement dans le plan et la permission `view_links` ou `manage_links`, et elle est entièrement masquée tant que vous êtes en sandbox. - [Vue d'ensemble des liens de paiement](https://docs.wajub.com/fr/payments/link): Ce qu'est le produit, et quand un lien vaut mieux qu'une intégration. - [Personnalisation](https://docs.wajub.com/fr/payments/link/customization): Couleurs de marque, logo, et champs de la page. - [Suivi et conversions](https://docs.wajub.com/fr/payments/link/tracking): Vues, taux de conversion, et vie d'un lien. - [Moyens de paiement](https://docs.wajub.com/fr/payments/payment-methods): Les opérateurs que voient vos payeurs, pays par pays. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): Enregistrez un endpoint et vérifiez la signature. - [Référence API des liens de paiement](https://docs.wajub.com/fr/api/payment-links): Chaque champ de la ressource, et les cinq endpoints. --- # Suivi et conversions URL: https://docs.wajub.com/fr/payments/link/tracking > Ce qu'un lien mesure vraiment, où trouver ces chiffres, et comment il se ferme. L'API vous dit si un lien est toujours ouvert ; seul le Dashboard montre ses performances. ## L'API n'a pas de compteurs `GET /links/{id}` renvoie ce que le lien *est*, jamais ses *performances* : ni vues, ni conversions, ni revenus. `GET /links/{id}` **Récupérer un lien** ```bash curl https://api.wajub.com/links/8kD2xQpLm \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` ```javascript const link = await wajub.links.retrieve('8kD2xQpLm'); console.log(link.is_public, link.is_archived, link.expiry_date); ``` ```python link = wajub.links.retrieve("8kD2xQpLm") print(link.is_public, link.is_archived, link.expiry_date) ``` ```php $link = $wajub->links->retrieve('8kD2xQpLm'); echo $link->url; ``` ```go link, err := client.Links.Retrieve(context.Background(), "8kD2xQpLm") if err != nil { log.Fatal(err) } log.Println(link["url"], link["is_public"]) ``` La réponse est l'état du lien, et c'est ce que vous interrogez pour savoir s'il encaisse toujours. ```json title="Réponse · 200 OK" { "code": 200, "status": "OK", "message": "Payment link retrieved", "link": { "id": "8kD2xQpLm", "type": "product", "title": "Café Amina, 250 g", "url": "https://wajub.link/cafe-amina", "currency": "XAF", "price": 3500, "is_public": true, "is_archived": false, "expiry_date": null, "sales_limit": null, "created_at": "2026-09-11T14:00:00+00:00" } } ``` La liste fonctionne de la même façon. Elle accepte `per_page`, `search`, `archived` pour voir les liens archivés plutôt que les liens actifs, `only_public`, `type` (`product`, `event`, `fundraising` ou `donation`), et `sort_by` (`created_at`, `updated_at`, `title` ou `type`) avec `sort_dir` (`desc` ou `asc`). La liste suit le tri en premier, puis du plus récent au plus ancien entre liens à égalité. Pour les exports, un `cursor` parcourt la liste dans son ordre par défaut, du plus récent au plus ancien : avec un autre tri, la liste est paginée par numéro et ne porte pas de curseur. Un `type`, un `sort_by` ou un `sort_dir` hors de ces valeurs renvoie une `422` sur ce champ, comme un `per_page` hors limites. `GET /links` ## Ce qui est réellement mesuré Chaque visite qui passe les verrous d'accès est comptée, avec sa provenance (le referrer HTTP), le pays du visiteur et son type d'appareil. Les visiteurs uniques sont comptés **par jour** : la même personne qui visite deux jours différents compte donc pour deux visiteurs uniques. Lisez ce nombre comme « uniques par jour », pas comme un nombre de personnes. > [!NOTE] > **Une visite bloquée n'est pas une vue** > > Quand un lien est protégé par mot de passe, une tentative dont le mot de passe échoue n'est pas > comptée. Une visite sur un lien non publié, expiré ou dont le plafond de vues est atteint ne l'est > pas non plus. Le compteur n'avance que pour les visites qui ont réellement atteint la page, et c'est > ce qui fait de `max_views` un plafond fiable. ## Les chiffres, et où les lire **Liens → un lien → Vue d'ensemble** est le seul endroit où ils apparaissent. **Total des vues**, **Total des ventes** et **Revenu total** couvrent toute la vie du lien, et **Taux de conversion** rapporte ces ventes à ses visiteurs. La période choisie, les 7, 14, 30 ou 90 derniers jours, ne change que les graphiques : les barres sous chaque total et **Tendances des visites et des ventes**. La transaction moyenne, les vues par transaction, les principaux pays et les appareils couvrent toujours les 30 derniers jours. > [!WARNING] > **Le taux de conversion se calcule par visiteur, pas par vue** > > Le chiffre vaut `transactions ÷ unique visitors`, et non `transactions ÷ views`. Une page ouverte > quatre fois avant le paiement compte pour un visiteur et une conversion : le taux paraît donc plus > élevé qu'avec un calcul par vue. Comparez-le à lui-même dans le temps plutôt qu'à un chiffre venant > d'un autre outil. ## Attribuer un canal Aucun paramètre d'URL ne marque une visite. Un `?src=whatsapp` sur l'URL partagée n'est transmis nulle part : il n'atteint pas le paiement, il n'est pas enregistré sur la vue, et il n'apparaîtra dans aucun rapport. Vous disposez à la place de deux choses qui fonctionnent. Le **referrer** est capturé automatiquement : le trafic qui en porte un, depuis un lien dans une publication ou une page, affiche déjà son origine dans les statistiques. Le trafic venant de WhatsApp, d'un SMS ou d'un QR code n'a pas de referrer, et c'est en pratique l'essentiel du trafic. Donc, pour tout ce que vous devez vraiment attribuer, **créez un lien par canal**. Même produit, même prix, `custom_url` différente : `wajub.link/cafe-whatsapp`, `wajub.link/cafe-instagram`. Chacun garde ses propres vues, son propre taux de conversion et son propre chiffre d'affaires, et la comparaison est exacte plutôt que déduite. Un paiement fait sur un lien le désigne : son champ `link` est l'`id` du lien, dans l'API et dans les webhooks `payment.*`, si bien que votre handler sait de quel lien, donc de quel canal, vient l'argent. `GET /payments` n'a pas de filtre par lien : pour lister les paiements d'un lien, lisez **Liens → un lien → Transactions** dans le Dashboard, ou gardez le `link` de chaque paiement à son arrivée. ## Comment un lien se ferme Cinq réglages mettent fin à la vie d'un lien, et ils ne le ferment pas de la même façon. | Réglage | Ferme | Le payeur obtient | | ----------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `expiry_date` | La page, au moment que vous choisissez | `410`, avant tout affichage | | `is_archived` | La page, immédiatement | `410`, avant tout affichage | | `sales_limit` | Le paiement, pas la page | `422` au moment de payer, `This payment link has reached its sales limit.` | | `single_use_link` | La page, après son premier paiement réussi | Une page qui indique que le lien a déjà servi à payer | | `allow_overflow: false` | Les dons d'une collecte, une fois son objectif atteint | Une page qui indique que la collecte a atteint son objectif ; `410` avec `error_code: goal_reached` au moment de payer | La différence compte. Un lien expiré ou archivé ne s'ouvre jamais : le payeur voit une page fermée et tout s'arrête là. Un lien qui a atteint son plafond de ventes **s'ouvre toujours normalement**, affiche le produit et le bouton, et ne refuse qu'au moment du paiement. Si vous vendez une quantité fixe, attendez-vous à ce que des payeurs tombent sur ce message plutôt que sur une page fermée. Un lien à usage unique accepte un seul payeur à la fois. Pendant que quelqu'un paie par ce lien, un autre payeur apprend qu'un paiement par ce lien est en cours, et que le lien rouvre si ce paiement n'aboutit pas. Une fois un paiement réussi, le lien reste fermé, même si vous le remboursez. Aucun champ du lien n'indique qu'il est fermé : `payment.succeeded`, dont le `link` est l'`id` du lien, est votre signal. Si un second paiement aboutit malgré tout par ce lien, comme une tentative antérieure que l'opérateur confirme en retard, le propriétaire, les administrateurs et les membres finance de votre équipe reçoivent un e-mail qui nomme le paiement à rembourser : Wajub ne le rembourse pas de lui-même. Une collecte dont `allow_overflow` est désactivé n'accepte plus de dons une fois que ce qu'elle a gardé atteint `target_amount`. Le don qui franchit l'objectif passe ; le checkout suivant répond `410` avec `error_code: goal_reached`, et la page, qui s'ouvre toujours, indique que la collecte a atteint son objectif. Un remboursement qui ramène le total sous l'objectif la rouvre. Avec `allow_overflow` activé, la collecte continue au-delà de son objectif. `POST /links` crée une collecte avec `allow_overflow` désactivé, sauf si vous l'envoyez, et `PUT /links/{id}` le modifie. `link.expired` est envoyé une fois, dans la journée qui suit le passage de l'`expiry_date` d'un lien, sauf si le lien est archivé entre-temps, avec le lien dans `data`. L'archivage envoie `link.updated`, tout comme une vente ou un remboursement qui change le stock d'un produit. Atteindre le plafond de ventes, fermer un lien à usage unique et atteindre l'objectif d'une collecte n'envoient aucun événement propre. L'archivage est l'option réversible : remettez `is_archived` à `false` via `PUT /links/{id}` et le lien encaisse de nouveau, en conservant tout ce qu'il a déjà collecté. `expiry_date` est une condition plutôt qu'un état : la repousser rouvre un lien qui s'était fermé à cause d'elle. La dépublication avec `is_public: false` ferme aussi un lien, mais répond `404` au lieu de `410`, car un lien non publié doit donner l'impression de n'avoir jamais existé. Les verrous d'accès sont décrits dans [Personnalisation](https://docs.wajub.com/fr/payments/link/customization#who-is-allowed-in). ## Ce que rend un remboursement Un lien compte ce qu'il a gardé, pas ce qu'il a encaissé un jour. Un remboursement réussi, ou un litige que vous perdez, rend ce que le paiement avait pris : - Un billet ou une unité dont le prix entier est remboursé ne compte plus dans `event_capacity`, `sales_limit` ni dans la quantité de son type de billet, et revient dans le stock d'un produit physique. Le remboursement d'une partie du prix d'un billet garde le billet : trois billets à 3 000 XAF remboursés de 3 000 XAF laissent deux billets vendus. - Sur une collecte ou une page de dons, le total collecté, la progression vers l'objectif et le nombre de contributeurs baissent de ce qui a été remboursé. Un don remboursé en entier quitte le mur des donateurs, et une collecte fermée à son objectif se rouvre si le total repasse dessous. - Un paiement perdu dans un litige ne compte plus, comme un remboursement complet. Un litige encore ouvert, ou que vous avez gagné, ne change rien. Un remboursement qui échoue, ou qui est encore en cours, ne change rien non plus. ## Les webhooks d'un lien L'onglet **Webhooks** d'un lien, dans le Dashboard, envoie les événements propres à ce lien à une adresse à vous, avec un secret de signature qui lui est propre. Ils s'ajoutent aux webhooks de votre compte, qui couvrent tous les paiements. | Événement | Envoyé quand | | ------------------- | -------------------------------------------------------------------------------------------------------------------- | | `payment.success` | Un paiement par le lien a réussi, quel que soit son type | | `ticket_purchased` | Des billets ont été achetés sur un lien d'événement | | `donation.received` | Un don a été reçu sur un lien de don ou de collecte | | `order.placed` | Une commande a été payée sur un lien de produit | | `payment.refunded` | Un remboursement d'un de ses paiements a réussi, une fois par remboursement, ou un litige sur l'un d'eux a été perdu | | `link_expired` | L'`expiry_date` du lien est passée | Un paiement qui échoue n'envoie rien. Les paiements sandbox ne partent que vers les endpoints d'un lien sandbox, avec `sandbox: true`. En sandbox, un remboursement fait depuis le tableau de bord n'envoie pas de `payment.refunded`. Chaque envoi est un `POST` avec un corps JSON, signé dans `X-Webhook-Signature` et nommé dans `X-Webhook-Event`. Chaque événement porte en plus un `id` dans le corps, et la même valeur dans `X-Webhook-Id` : | En-tête | Ce que c'est | | --------------------- | ----------------------------------------------------------------------------------- | | `X-Webhook-Signature` | HMAC-SHA256 en hexadécimal du corps brut, avec le secret de signature de l'endpoint | | `X-Webhook-Event` | L'événement, comme dans le corps | | `X-Webhook-Id` | L'`id` de l'événement, comme dans le corps | **Vérifier un envoi d'un lien** ```javascript import crypto from 'node:crypto'; app.post('/webhooks/link', express.raw({ type: 'application/json' }), (req, res) => { const expected = crypto.createHmac('sha256', process.env.LINK_WEBHOOK_SECRET).update(req.body).digest('hex'); const received = String(req.headers['x-webhook-signature'] ?? ''); if (received.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) { return res.sendStatus(400); } const event = JSON.parse(req.body); // Ignorez un event.id déjà traité, puis livrez. res.sendStatus(200); }); ``` ```php $raw = file_get_contents('php://input'); $expected = hash_hmac('sha256', $raw, getenv('LINK_WEBHOOK_SECRET')); if (! hash_equals($expected, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '')) { http_response_code(400); exit; } $event = json_decode($raw, true); // Ignorez un $event['id'] déjà traité, puis livrez. ``` Répondez par un `2xx` une fois l'événement enregistré. Un envoi qui échoue est retenté, pendant 72 heures au plus, si bien qu'un même événement peut arriver plusieurs fois. Un événement garde son `id` à chaque fois : gardez ceux que vous avez traités et ignorez-les. Un envoi renvoyé depuis l'onglet a le même corps et le même `X-Webhook-Id`. `timestamp` est le moment où l'événement s'est produit, pas celui de l'envoi : une nouvelle tentative, ou un envoi renvoyé depuis l'onglet, le garde. Chaque événement de paiement porte le lien et le paiement. Le payeur n'est désigné que par `name` et `email` : un envoi ne contient jamais son numéro de téléphone ni sa carte. Ce qui a été saisi au paiement arrive avec toute suite de sept chiffres ou plus masquée, sous la forme `23••••89`, y compris au milieu d'une phrase ; `answers` ne contient que les questions du lien, chacune coupée à 500 caractères. ```json title="ticket_purchased" { "id": "lwe_5b3c2f1e-8d0a-5c4b-9e7f-2a1d6c0b9e84", "event": "ticket_purchased", "link_id": "9f3a1c52-6b1e-4f7d-a1c2-7e0d4b8f2a61", "link_uid": "8kD2xQpLm", "link": { "id": "9f3a1c52-6b1e-4f7d-a1c2-7e0d4b8f2a61", "uid": "8kD2xQpLm", "title": "Soirée Afrobeats", "type": "event" }, "sandbox": false, "timestamp": "2026-10-23T18:04:11+00:00", "payment": { "id": "trx_CSUGajfv9xh0XQ5wu2lx", "reference": "order-4172", "amount": 10000, "currency": "XAF", "status": "succeeded", "amount_refunded": 0, "dispute_lost": false, "quantity": 2, "quantity_kept": 2, "channel": "cm.mtn", "customer": { "id": "cus_Qe7Tb2Wn5Lr9Xc4Mv8Hk1Zs3", "name": "Ada Obi", "email": "ada@example.com" }, "answers": { "company": "Acme" }, "paid_at": "2026-10-23T18:04:09+00:00", "created_at": "2026-10-23T18:02:47+00:00" }, "ticket": { "ticket_type": { "id": "3e1b7a90-2c4d-4f6e-8a1b-5d9c0e2f7b13", "name": "VIP" }, "quantity": 2, "attendees": [{ "Nom complet": "Ada Obi", "Téléphone": "23••••33" }, { "Nom complet": "Ben Eko" }], "event_start_date": "2026-11-07T20:00:00+00:00" } } ``` `link_uid` est l'`id` du lien dans l'API, et `payment.id` celui du paiement. `quantity_kept` est ce que le paiement détient encore une fois ses remboursements et ses litiges comptés, comme plus haut. Chaque événement ajoute un objet à côté de `payment` : | Événement | Ajoute | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `payment.success` | Rien de plus | | `ticket_purchased` | `ticket` : `ticket_type` (`id`, `name`), `quantity`, `attendees`, `event_start_date` | | `donation.received` | `donation` : `amount`, `currency`, `anonymous`, `recurring_interval` | | `order.placed` | `order` : `product_type`, `quantity`, `variant`, `shipping_address` avec son `phone` masqué | | `payment.refunded` | `refund` : `id`, `amount`, `currency`, `reason`, `created_at`. `payment.status` vaut alors `partially_refunded` ou `refunded`. Pour un litige perdu, `dispute` à la place de `refund` : `id`, `amount`, `currency`, `reason`, `status`, `created_at`, avec `payment.dispute_lost` à true | `anonymous` signifie que le donateur a demandé à ne pas figurer sur le mur public des donateurs : vous recevez tout de même son nom. Un litige perdu envoie `payment.refunded` une fois ; si un remboursement le règle ensuite, ce remboursement envoie le sien, avec un autre `id`. `link_expired` porte `id`, `event`, `link_id`, `link_uid`, le lien avec son `expiry_date`, et `timestamp`. ## Le rapprochement des fonds Les paiements d'un lien sont des paiements ordinaires. Ils arrivent dans votre liste Payments, déclenchent `payment.succeeded`, sont réglés sur votre solde et se remboursent comme les autres : il n'y a donc rien de propre aux liens à rapprocher. Le webhook transporte ce que le payeur a saisi dans vos `extra_fields`, imbriqué sous `metadata.extra_fields`, ainsi que le `link` dont vient le paiement. - [Liens de paiement](https://docs.wajub.com/fr/payments/link): Ce qu'est le produit, et quand un lien vaut mieux qu'une intégration. - [Démarrage rapide](https://docs.wajub.com/fr/payments/link/quickstart): Créez un lien, publiez-le, partagez-le. - [Personnalisation](https://docs.wajub.com/fr/payments/link/customization): Images, langues, devises, et qui peut entrer. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): Écoutez payment.succeeded et livrez la commande automatiquement. - [Référence API des liens de paiement](https://docs.wajub.com/fr/api/payment-links): Chaque champ de la ressource, et les cinq endpoints. --- # Virements bancaires URL: https://docs.wajub.com/fr/payments/payment-methods/bank-transfers > Les virements nationaux sur le canal `bank`, réglés au rythme de la banque. Pour les gros montants, surtout entre entreprises. Le client reçoit des coordonnées bancaires, et le paiement passe à `succeeded` une fois les fonds arrivés. | Type | Canal | Pays | | --- | --- | --- | | Virement national | `bank` | CM, CI, SN, NG, GH | Un virement se règle au rythme de la banque, pas à celui du client. Attendez-vous à un délai entre le moment où il confirme et celui où le webhook est déclenché, et ne gardez jamais une commande ouverte dans le navigateur en l'attendant. - [Cycle de vie d'un paiement](https://docs.wajub.com/fr/payments/lifecycle): Ce que traverse le paiement jusqu'à l'arrivée des fonds. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): Être prévenu quand le virement est réglé. --- # Cartes bancaires URL: https://docs.wajub.com/fr/payments/payment-methods/cards > Visa et Mastercard sur le canal `card`, et quand Wajub demande le 3-D Secure. Visa et Mastercard, proposées sur la page hébergée partout où la devise de règlement le permet. | Réseau | Détecté comme | Remarques | | --- | --- | --- | | Visa | `visa` | 3-D Secure 2 sur demande | | Mastercard | `mastercard` | 3-D Secure 2 sur demande | Le canal est `card` pour les deux réseaux : vous ne nommez jamais la marque. American Express, Discover, Diners, JCB et Maestro sont acceptées là où votre prestataire les prend en charge. Wajub demande le 3-D Secure quand [Shield](https://docs.wajub.com/fr/risk/shield) l'exige : l'Auto 3DS de Shield Advanced à partir de votre seuil de revue, ou une règle `challenge_3ds`. Sinon, le prestataire et l'émetteur de la carte appliquent leur propre politique. - [Shield](https://docs.wajub.com/fr/risk/shield): Les règles qui demandent le 3-D Secure. - [Checkout hébergé](https://docs.wajub.com/fr/payments/hosted-checkout): La page où le payeur saisit sa carte. --- # Moyens de paiement et canaux URL: https://docs.wajub.com/fr/payments/payment-methods > Chaque moyen de paiement avec lequel Wajub encaisse, son identifiant de canal et où il fonctionne. Chaque moyen de paiement est désigné par un **canal** : une famille à part entière, `mobile`, `card`, `bank` ou `crypto`, ou un opérateur précis au format `country.operator`. La page hébergée propose tous les canaux sur lesquels votre compte peut encaisser ; réduisez cette liste paiement par paiement avec [`accept`](#choosing-what-a-payment-accepts), et ne nommez un canal que dans un débit par l'API directe. > [!NOTE] > **Comment lire un canal** > > `cm.mtn` correspond à MTN Mobile Money au Cameroun, `sn.wave` à Wave au Sénégal. Le préfixe est le > code pays ISO 3166-1 alpha-2 et le suffixe l'opérateur. Un nom de famille seul, comme `mobile`, > laisse Wajub déduire l'opérateur à partir du numéro de téléphone. Chaque famille a sa page : - [Mobile Money](https://docs.wajub.com/fr/payments/payment-methods/mobile-money), les opérateurs et leurs canaux, et les [formats de numéros](https://docs.wajub.com/fr/payments/payment-methods/phone-numbers) que chacun accepte. - [Cartes bancaires](https://docs.wajub.com/fr/payments/payment-methods/cards), Visa et Mastercard sur le canal `card`. - [Virements bancaires](https://docs.wajub.com/fr/payments/payment-methods/bank-transfers), sur le canal `bank`. - [Portefeuilles et cryptomonnaies](https://docs.wajub.com/fr/payments/payment-methods/wallets-and-crypto), Apple Pay, Google Pay et les canaux `crypto.{asset}`. ## Où en est chaque pays La devise décide des canaux qui existent, et les prestataires du compte décident lesquels sont activés. | Pays | Devise | Mobile Money | Cartes | | --- | --- | --- | --- | | Cameroun | XAF | MTN, Orange, Express Union | Oui | | Côte d'Ivoire | XOF | MTN, Orange, Wave, Moov | Oui | | Sénégal | XOF | Orange, Wave, Free | Oui | | Bénin | XOF | MTN, Moov | Oui | | Burkina Faso | XOF | Orange, Moov | Oui | | Togo | XOF | T-Money, Moov | Oui | | Mali | XOF | Orange, Moov | Oui | | Ghana | GHS | MTN, Vodafone, AirtelTigo | Oui | | Nigeria | NGN | OPay, par une connexion Flutterwave v4. Aussi virement bancaire et USSD ; PalmPay bientôt disponible | Oui | | Kenya | KES | M-Pesa, Airtel | Oui | | Ouganda | UGX | MTN, Airtel | Oui | | Rwanda | RWF | MTN, Airtel | Oui | | Tanzanie | TZS | M-Pesa, Airtel, Tigo, Halopesa | Oui | | Gabon | XAF | Airtel, Moov | Oui | | Congo | XAF | MTN, Airtel | Oui | | RD Congo | CDF | Orange, Airtel, Vodacom, Africell | Oui | | Guinée | GNF | MTN, Orange | Oui | | Liberia | LRD | MTN | Oui | | Sierra Leone | SLE | Orange | Oui | | Zambie | ZMW | MTN, Airtel, Zamtel | Oui | | Malawi | MWK | Airtel, TNM | Oui | | Mozambique | MZN | M-Pesa | Oui | ## Choisir ce qu'un paiement accepte Rien n'est masqué par défaut : le payeur voit tous les moyens sur lesquels votre compte peut encaisser, et un paiement dans une devise que le portefeuille n'utilise pas est converti, comme décrit dans [Limites](https://docs.wajub.com/fr/resources/limits). Pour réduire la liste, envoyez `accept` à la création du paiement, du lien ou de la facture. Chaque clé est facultative, et une clé omise ne restreint rien. - `accept.countries` (string[]): Uniquement les canaux de ces pays, en codes ISO 3166-1 alpha-2. Les cartes et la crypto n'appartiennent à aucun pays : cette clé ne les retire jamais. - `accept.channels` (string[]): Uniquement ces canaux, comme `cm.mtn`. Un agrégat comme `cm.mobile` désigne tous les opérateurs mobiles du pays, et `mobile` tous les opérateurs mobiles. - `accept.types` (string[]): Uniquement ces types de canal, comme `mobile_money` ou `card`. - `accept.currencies` (string): `any` (par défaut) propose tous les canaux et convertit le montant quand les devises diffèrent. `payment` ne garde que les canaux qui règlent dans la devise du paiement : un paiement en XAF n'affiche plus le Mobile Money kényan. ```json title="Un paiement en USD, Mobile Money camerounais uniquement" { "amount": 99.5, "currency": "USD", "email": "buyer@example.com", "accept": { "countries": ["CM"], "types": ["mobile_money"] } } ``` La restriction est conservée sur le paiement et s'applique deux fois : la page ne propose que ce qu'elle autorise, et un débit qui nomme un autre canal est refusé par un `422` et le code `channel_not_accepted`. Si `accept` ne laisse aucun moyen de payer, c'est la création elle-même qui répond `422` sur `accept`, plutôt que de produire une page sans aucun moyen de paiement. Un débit envoyé sur `mobile` ou sur `cm.mobile` est vérifié sur l'opérateur que donne le numéro, pas sur l'agrégat. Avec la restriction ci-dessus, `cm.mobile` et un numéro MTN Cameroun est débité sur `cm.mtn`, et un numéro ivoirien est refusé. Un paiement restreint à `"channels": ["mobile"]` accepte tout opérateur Mobile Money, quel que soit celui que donne le numéro, et aucun canal carte, bancaire ou crypto. Un lien ou une facture porte son propre `accept`, que chaque paiement ouvert depuis lui hérite. Sur un lien ou une facture, `accept: {}` supprime la restriction. Dans le Dashboard, les mêmes champs se trouvent sous **Moyens de paiement**, dans le composer de lien et sur le formulaire de facture. ## Prévisualiser les moyens avant de créer un paiement `GET /payments/options` liste les canaux qu'un payeur pourrait utiliser pour une devise et un montant, avant qu'aucun paiement n'existe : ceux que votre compte propose sur la page de paiement, restreints au `country` du payeur et au minimum et au maximum de chaque canal. Il prend la même restriction `accept` que `POST /payments`. Servez-vous-en pour dessiner votre propre choix de moyen de paiement ; une fois le paiement créé, c'est lui qui fixe ce qui est réellement proposé au payeur. ```bash title="Moyens pour 25 000 XAF au Cameroun" curl "https://api.wajub.com/payments/options?currency=XAF&amount=25000&country=CM&locale=fr" \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" ``` La réponse porte `code`, `status`, `message` et `channels` : chacun avec son `slug`, `name`, `name.fr`, `type`, `logo` et `countries`, et `operators` pour `cm.mobile`. `logo_png`, sur un canal et sur chaque opérateur, est le même logo en PNG, pour une application qui n'affiche pas de SVG, ou `null` quand il n'y en a pas. [Lister les options de paiement](https://docs.wajub.com/fr/api/payments/options) ## Montants et plafonds Deux limites différentes s'appliquent au même paiement, et elles sont faciles à confondre. La première concerne le paiement lui-même. En XAF et XOF, il doit être compris entre **25 et 2 000 000** ; en dehors de cette plage, l'appel de création est refusé avec un `422` qui indique la borne dans `errors.amount`. La seconde est ce qu'un seul débit Mobile Money peut porter, plafonné à **500 000 XAF**, et au même montant en XOF. Un paiement au-dessus est refusé avec un `422` au moment de le débiter. > [!WARNING] > **Votre propre plafond est plus bas tant que vous n'êtes pas vérifié** > > Les chiffres ci-dessus sont ceux de la plateforme. Ce que votre compte peut réellement encaisser > dépend de votre niveau de vérification, et un compte non vérifié a un plafond live de zéro. > Vérifiez-le dans **Paramètres → Conformité**, comme expliqué dans [Activation du > compte](https://docs.wajub.com/fr/getting-started/account-activation). - [Formats de numéros de téléphone](https://docs.wajub.com/fr/payments/payment-methods/phone-numbers): Ce que chaque opérateur accepte, avant même qu'un paiement puisse démarrer. - [Cycle de vie d'un paiement](https://docs.wajub.com/fr/payments/lifecycle): Chaque état que prend un paiement, et le webhook de chacun. - [Devise de règlement et solde](https://docs.wajub.com/fr/payouts/balance): Dans quelle devise vous êtes payé, et quand. - [Frais et tarifs](https://docs.wajub.com/fr/payouts/balance/fees): Ce que chaque canal vous coûte. - [Envoyer vers ces canaux](https://docs.wajub.com/fr/payouts/transfers): Des payouts Mobile Money avec Transferts. --- # Mobile Money URL: https://docs.wajub.com/fr/payments/payment-methods/mobile-money > Les opérateurs par lesquels Wajub encaisse, leurs canaux, pays et devises. La colonne vertébrale de l'encaissement sur le continent. Le client valide sur son propre téléphone, depuis une invite USSD ou l'application de l'opérateur, et rien n'est encaissé tant qu'il ne l'a pas fait. | Opérateur | Canaux | Pays | Devises | | --- | --- | --- | --- | | MTN MoMo | `cm.mtn` `ci.mtn` `bj.mtn` `gh.mtn` `ug.mtn` `rw.mtn` `zm.mtn` `cg.mtn` `gn.mtn` `lr.mtn` | CM, CI, BJ, GH, UG, RW, ZM, CG, GN, LR | XAF, XOF, GHS, UGX, RWF, ZMW, GNF, LRD | | Orange Money | `cm.orange` `ci.orange` `sn.orange` `bf.orange` `ml.orange` `gn.orange` `cd.orange` `sl.orange` | CM, CI, SN, BF, ML, GN, SL, CD | XAF, XOF, GNF, SLE, CDF | | Wave | `ci.wave` `sn.wave` | CI, SN | XOF | | Airtel Money | `ug.airtel` `rw.airtel` `tz.airtel` `ke.airtel` `zm.airtel` `mw.airtel` `cd.airtel` `cg.airtel` `ga.airtel` | UG, RW, TZ, KE, ZM, MW, CD, CG, GA | UGX, RWF, TZS, KES, ZMW, MWK, CDF, XAF | | Moov Money | `ci.moov` `bj.moov` `bf.moov` `tg.moov` `ml.moov` `ga.moov` | CI, BJ, BF, TG, ML, GA | XOF, XAF | | M-Pesa | `ke.mpesa` `tz.mpesa` `mz.mpesa` | KE, TZ, MZ | KES, TZS, MZN | D'autres opérateurs complètent le catalogue : Express Union au Cameroun (`cm.eu`), Free au Sénégal, T-Money au Togo, Vodafone et AirtelTigo au Ghana, Tigo et Halopesa en Tanzanie, Vodacom et Africell en RD Congo, Zamtel en Zambie, TNM au Malawi, Vodafone Cash en Égypte, Capitec Pay en Afrique du Sud et OPay au Nigeria (`ng.opay`), débité par une connexion Flutterwave v4. `mobile` et `cm.mobile`, pour le Cameroun, ne sont pas des canaux du catalogue. Ce sont les deux raccourcis qu'accepte l'[appel de débit](https://docs.wajub.com/fr/payments/direct-api#letting-wajub-find-the-operator), pour laisser Wajub déduire l'opérateur à partir du numéro plutôt que de le nommer à l'avance. Aucun autre pays n'a d'agrégat : débitez le canal de son opérateur. > [!NOTE] > **`GET /providers` donne la liste de votre compte** > > La couverture évolue. [`GET /channels`](https://docs.wajub.com/fr/api/channels/list) est le catalogue global : tous les > canaux pris en charge par Wajub, la même réponse pour chaque clé, filtrée par `country` si vous le > passez. Ce que votre propre compte peut accepter dépend des prestataires que votre équipe a > activés, et c'est [`GET /providers`](https://docs.wajub.com/fr/api/providers/list) : chaque connexion active avec les canaux > qu'elle propose réellement, ceux qu'affiche le checkout hébergé. Considérez le tableau ci-dessus > comme la forme de l'offre. Un nouveau canal est un changement rétrocompatible, il ne casse donc > jamais une intégration existante. - [Formats de numéros de téléphone](https://docs.wajub.com/fr/payments/payment-methods/phone-numbers): Ce que chaque opérateur accepte, avant même qu'un paiement puisse démarrer. - [Choisir ce qu'un paiement accepte](https://docs.wajub.com/fr/payments/payment-methods#choosing-what-a-payment-accepts): Restreindre un paiement à certains opérateurs ou pays. - [API directe](https://docs.wajub.com/fr/payments/direct-api): Débiter un opérateur vous-même, une fois le numéro en main. --- # Formats de numéros de téléphone URL: https://docs.wajub.com/fr/payments/payment-methods/phone-numbers > Comment Wajub lit un numéro Mobile Money, pays par pays, et ce qu'il rejette. Les formats de numéro que Wajub accepte pour le Mobile Money, dans les paiements, les payouts et les règlements de marketplace. Si le format est faux, le paiement échoue avant même que le client voie une demande de confirmation. ## Envoyer au format E.164 Wajub attend la forme internationale : un `+`, l'indicatif du pays, puis le numéro d'abonné. Pas d'espaces, pas de tirets, pas de parenthèses. Retirez le 0 qu'un format national compose d'abord, comme au Kenya ou au Ghana, mais gardez celui qui fait partie du numéro : en Côte d'Ivoire, au Bénin, au Congo et au Burkina Faso, un numéro peut commencer par 0 après son indicatif. ```bash title="La forme d'un numéro accepté" +[country code][subscriber number] +237670000000 Cameroon, MTN +221770000000 Senegal, Orange +254700000000 Kenya, Safaricom +2250700000000 Côte d'Ivoire, Orange ``` Un numéro qui arrive sans son indicatif n'est pas automatiquement refusé. Quand l'appel porte un pays sur lequel l'ancrer (un `channel` comme `cm.mtn` suffit), un numéro local tel que `670000000` est lu comme `+237670000000`. Sans cet ancrage, il n'y a rien sur quoi s'appuyer pour deviner, et le numéro revient en `422`. Pour un débit, `00` à la place du `+` se lit de la même façon : `00237670000000` est `+237670000000`. Un numéro qui a perdu le 0 qui fait partie de lui, comme `+225707000000`, le retrouve, et les numéros d'une renumérotation se lisent sous leur nouvelle forme : un numéro béninois à huit chiffres prend `01` devant, et un ancien numéro gabonais à huit chiffres son bloc de 2024, `07 28 01 50` devenant `+24177280150`. > [!TIP] > **Envoyez quand même au format E.164** > > Compter sur ce repli, c'est compter sur l'exactitude de votre propre `channel`. Normalisez de votre > côté, au moment où le client saisit le numéro, et vous éliminez toute une catégorie d'échecs de > chaque appel qui suit. ## Tous les pays couverts par Wajub Vingt-quatre pays : chacun de ceux où le catalogue annonce un canal payé avec un numéro de téléphone, avec son indicatif et ces canaux. | Pays | Indicatif | Canaux | | --- | --- | --- | | Afrique du Sud | `+27` | Capitec Pay | | Bénin | `+229` | MTN MoMo, Moov Money | | Burkina Faso | `+226` | Orange Money, Moov Money | | Cameroun | `+237` | MTN MoMo, Orange Money, Express Union | | Congo | `+242` | MTN MoMo, Airtel Money | | Côte d'Ivoire | `+225` | MTN MoMo, Orange Money, Moov Money, Wave, Djamo | | Égypte | `+20` | Vodafone Cash | | Gabon | `+241` | Airtel Money, Moov Money | | Ghana | `+233` | MTN MoMo, Vodafone Cash, AirtelTigo Money | | Guinée | `+224` | MTN MoMo, Orange Money | | Kenya | `+254` | M-Pesa, Airtel Money | | Libéria | `+231` | MTN MoMo | | Malawi | `+265` | Airtel Money, TNM Mpamba | | Mali | `+223` | Orange Money, Moov Money | | Mozambique | `+258` | M-Pesa | | Nigeria | `+234` | OPay | | Ouganda | `+256` | MTN MoMo, Airtel Money | | RD Congo | `+243` | Airtel Money, Vodacom M-Pesa, Orange Money, Africell Money | | Rwanda | `+250` | MTN MoMo, Airtel Money | | Sénégal | `+221` | Orange Money, Free Money, Wave, Djamo | | Sierra Leone | `+232` | Orange Money | | Tanzanie | `+255` | M-Pesa, Tigo Pesa, Airtel Money, HaloPesa | | Togo | `+228` | T-Money, Moov Money | | Zambie | `+260` | MTN MoMo, Airtel Money, Zamtel Kwacha | ## Comment l'opérateur est identifié C'est là que la production et la sandbox diffèrent vraiment, et cette différence compte. **En production**, Wajub identifie l'opérateur qui détient le numéro. Un numéro qu'il ne peut attribuer à aucun opérateur pris en charge est considéré comme n'en ayant aucun. Certains canaux portent le nom d'un portefeuille et non celui d'un opérateur, et le numéro est lu en conséquence. Wave (`ci.wave`, `sn.wave`), Express Union (`cm.eu`), Djamo (`ci.djamo`, `sn.djamo`), Capitec Pay (`za.capitec`), OPay (`ng.opay`) et PalmPay (`ng.palmpay`) se détiennent quel que soit l'opérateur du payeur : un numéro n'y est jamais refusé à cause du réseau auquel il appartient. Les autres portefeuilles appartiennent à un opérateur, et un numéro de cet opérateur paie sur le canal du portefeuille : `ke.mpesa` prend les numéros Safaricom, `tz.mpesa` et `mz.mpesa` prennent les numéros Vodacom, et `gh.vodafone` prend les numéros de Telecel, anciennement Vodafone Ghana. Tous les autres canaux portent le nom de leur opérateur, comme `zm.zamtel`, `mw.tnm` ou `cd.africell`. Un agrégat se résout de la même façon : un numéro Telecel envoyé sur `mobile` est débité sur `gh.vodafone`. **En sandbox**, Wajub compare plutôt les préfixes de test ci-dessous. Ils ne servent qu'à choisir un résultat en sandbox : certains suivent un vrai plan de numérotation, d'autres non, et aucun ne décrit l'attribution des vrais numéros. Un portefeuille détenu quel que soit l'opérateur, comme Capitec Pay, prend le numéro de test de n'importe quel opérateur, le sien (`+2761…`) ou celui d'un autre, mais jamais un numéro qui n'est pas un numéro de test. > [!WARNING] > **Ne construisez pas votre propre table de préfixes** > > Les préfixes ci-dessous sont ceux de la sandbox. Les recopier dans votre code revient à > réimplémenter la détection d'opérateur avec des données fausses en production, et périmées le jour > où une plage est réattribuée. Envoyez le numéro et laissez Wajub le résoudre. | Pays et opérateur | Préfixe sandbox | Canal | | --- | --- | --- | | Cameroun / MTN MoMo | `+23767…` | `cm.mtn` | | Cameroun / Orange Money | `+23769…` | `cm.orange` | | Cameroun / Express Union | `+23768…` | `cm.eu` | | Côte d'Ivoire / MTN MoMo | `+22505…` | `ci.mtn` | | Côte d'Ivoire / Orange Money | `+22507…` | `ci.orange` | | Côte d'Ivoire / Moov Money | `+22501…` | `ci.moov` | | Côte d'Ivoire / Wave | `+22503…` | `ci.wave` | | Sénégal / Orange Money | `+22177…` | `sn.orange` | | Sénégal / Free Money | `+22176…` | `sn.free` | | Sénégal / Wave | `+22178…` | `sn.wave` | | Bénin / MTN MoMo | `+22990…`, `+2290190…` | `bj.mtn` | | Bénin / Moov Money | `+22991…`, `+2290191…` | `bj.moov` | | Burkina Faso / Orange Money | `+22670…` | `bf.orange` | | Burkina Faso / Moov Money | `+22671…` | `bf.moov` | | Ghana / MTN MoMo | `+23324…` | `gh.mtn` | | Ghana / Vodafone Cash | `+23320…` | `gh.vodafone` | | Ghana / AirtelTigo Money | `+23327…` | `gh.airteltigo` | | Kenya / M-Pesa | `+25470…` | `ke.mpesa` | | Kenya / Airtel Money | `+25478…` | `ke.airtel` | | Ouganda / MTN MoMo | `+25677…` | `ug.mtn` | | Ouganda / Airtel Money | `+25675…` | `ug.airtel` | | Rwanda / MTN MoMo | `+25078…` | `rw.mtn` | | Rwanda / Airtel Money | `+25073…` | `rw.airtel` | | Tanzanie / Airtel Money | `+25567…` | `tz.airtel` | | Tanzanie / Tigo Pesa | `+25565…` | `tz.tigo` | | Tanzanie / HaloPesa | `+25562…` | `tz.halopesa` | | Tanzanie / M-Pesa | `+25576…` | `tz.mpesa` | | RD Congo / Airtel Money | `+24399…` | `cd.airtel` | | RD Congo / Orange Money | `+24389…` | `cd.orange` | | RD Congo / Vodacom M-Pesa | `+24381…` | `cd.vodacom` | | RD Congo / Africell Money | `+24390…` | `cd.africell` | | Gabon / Airtel Money | `+2410…`, `+24174…`, `+24177…` | `ga.airtel` | | Gabon / Moov Money | `+2416…`, `+24162…`, `+24165…`, `+24166…` | `ga.moov` | | Congo / MTN MoMo | `+24206…` | `cg.mtn` | | Congo / Airtel Money | `+24204…` | `cg.airtel` | | Zambie / MTN MoMo | `+26096…` | `zm.mtn` | | Zambie / Airtel Money | `+26097…` | `zm.airtel` | | Zambie / Zamtel Kwacha | `+26095…` | `zm.zamtel` | | Malawi / Airtel Money | `+26599…` | `mw.airtel` | | Malawi / TNM Mpamba | `+26588…` | `mw.tnm` | | Mali / Orange Money | `+22370…` | `ml.orange` | | Mali / Moov Money | `+22366…` | `ml.moov` | | Togo / Moov Money | `+22899…` | `tg.moov` | | Togo / T-Money | `+22890…` | `tg.tmoney` | | Guinée / MTN MoMo | `+22466…` | `gn.mtn` | | Guinée / Orange Money | `+22462…` | `gn.orange` | | Liberia / MTN MoMo | `+23188…` | `lr.mtn` | | Mozambique / M-Pesa | `+25884…` | `mz.mpesa` | | Égypte / Vodafone Cash | `+2010…` | `eg.vodafone` | | Sierra Leone / Orange Money | `+23276…` | `sl.orange` | | Afrique du Sud / Capitec Pay | `+2761…` | `za.capitec` | ## Laisser Wajub choisir le canal La page hébergée et les composants choisissent l'opérateur avec le client : ceci ne concerne donc que l'appel de débit d'une intégration [API directe](https://docs.wajub.com/fr/payments/direct-api). Sur cet appel, `channel` est obligatoire. Envoyez `mobile`, ou `cm.mobile` pour le Cameroun, et Wajub résout l'opérateur à partir du numéro. C'est le cas à privilégier. Ce sont les deux seuls agrégats : dans un autre pays, nommez le canal de l'opérateur, comme `ci.orange`. Le corps de l'appel de débit nomme alors l'agrégat et le numéro : ```json title="Opérateur résolu à partir du numéro" { "channel": "cm.mobile", "data": { "phone": "+237670000000" } } ``` Ne nommez un canal précis comme `cm.mtn` que si vous voulez imposer un opérateur. Si le numéro et le canal ne concordent pas, l'appel est refusé plutôt que rerouté en silence. Un agrégat fonctionne aussi sur un paiement restreint par [`accept`](https://docs.wajub.com/fr/payments/payment-methods#choosing-what-a-payment-accepts). La restriction est vérifiée sur l'opérateur que donne le numéro : `cm.mobile` avec un numéro MTN est accepté partout où `cm.mtn` l'est, et refusé là où il ne l'est pas. ## Ce qui revient quand le numéro est faux | Réponse | Cause | Correction | | ----------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `422` sur `phone` | Pas de `+`, pas d'indicatif et rien pour ancrer le numéro | Normalisez au format E.164 avant l'envoi | | `422` sur `channel` | Le canal désigne un opérateur qui ne dessert pas ce pays | Vérifiez les opérateurs du pays ci-dessus | | `422`, numéro et canal discordants | Le numéro appartient à un autre opérateur que celui indiqué | Envoyez `cm.mobile` et laissez Wajub le résoudre | | `422` sur `phone`, aucun opérateur trouvé | Aucun opérateur pris en charge ne détient le numéro | Demandez au client de confirmer son numéro, ou envoyez l'opérateur qu'il a choisi dans `data.operator` | Les quatre sont refusés sur l'appel de débit, `POST /payments/{id}`, et non à la création du paiement. Le paiement reste `pending` et rien n'atteint un opérateur : le même paiement peut donc être débité de nouveau une fois le numéro corrigé. Un numéro que l'opérateur refuse après l'envoi de la demande est un autre cas : le paiement échoue, et le motif figure dans le catalogue des [motifs d'échec](https://docs.wajub.com/fr/api/failure-reasons). - [Moyens de paiement et canaux](https://docs.wajub.com/fr/payments/payment-methods): Chaque opérateur, son canal et où il fonctionne. - [Numéros de test sandbox](https://docs.wajub.com/fr/getting-started/quickstart#4-pay-it-with-a-sandbox-number): Les suffixes qui déclenchent chaque résultat en mode test. - [Motifs d'échec](https://docs.wajub.com/fr/api/failure-reasons): Pourquoi un paiement qui a atteint un opérateur revient en échec. - [Transferts](https://docs.wajub.com/fr/payouts/transfers): Le même format, utilisé comme destination de payout. - [Sync](https://docs.wajub.com/fr/sync): Le même format, utilisé pour régler un vendeur de marketplace. --- # Portefeuilles et cryptomonnaies URL: https://docs.wajub.com/fr/payments/payment-methods/wallets-and-crypto > Apple Pay et Google Pay, et les cryptoactifs dans lesquels un paiement peut être réglé. Deux familles qui viennent avec leurs propres conditions : les portefeuilles ne fonctionnent qu'en live, et aucun prestataire crypto ne peut encore être connecté. ## Portefeuilles Apple Pay et Google Pay tokenisent la carte sur l'appareil : Wajub ne voit donc jamais la carte en clair ni les identifiants de l'appareil. | Portefeuille | `wallet_type` | Nécessite | | --- | --- | --- | | Apple Pay | `apple_pay` | Safari, iOS | | Google Pay | `google_pay` | Chrome, Android | > [!WARNING] > **Les portefeuilles fonctionnent en live uniquement** > > Un portefeuille apparaît sur la page hébergée et dans les composants intégrés quand l'un de vos > prestataires le propose, en live. La sandbox masque tous les portefeuilles : vous ne pouvez pas en > tester un. Consultez [Wajub Components → JS](https://docs.wajub.com/fr/libraries/components/js) pour le côté composants. ## Cryptomonnaies Le paiement est réglé une fois le transfert confirmé sur la blockchain. Les canaux suivent le format `crypto.{asset}`, et si vous ne fournissez pas de `wallet_address`, le payeur voit une adresse de dépôt vers laquelle envoyer les fonds. Quatre actifs figurent au catalogue, les deux stablecoins en dollar et les deux principales blockchains : | Actif | Canal | | --- | --- | | Bitcoin | `crypto.btc` | | Ethereum | `crypto.eth` | | Tether | `crypto.usdt` | | USD Coin | `crypto.usdc` | Ceux que vos clients voient réellement parmi les quatre dépendent du prestataire crypto activé sur votre compte : lisez donc `GET /providers` avant de construire un sélecteur. > [!NOTE] > **La crypto est bientôt disponible** > > Aucun prestataire portant ces quatre actifs ne peut encore être connecté : ils ne peuvent donc pas encore > être débités en live. [Couverture](https://docs.wajub.com/fr/resources/coverage) liste les autres rails > dans la même situation. - [Wajub Components, JS](https://docs.wajub.com/fr/libraries/components/js): Les boutons de portefeuille sur votre propre page. - [Couverture](https://docs.wajub.com/fr/resources/coverage): Les rails qui ne peuvent pas encore être connectés. --- # Créer un remboursement URL: https://docs.wajub.com/fr/payments/refunds/create > L'appel qui restitue des fonds sur un paiement réussi, ses paramètres et sa réponse. Le paiement est désigné par son `id` Wajub. Votre propre `reference` sur le paiement n'est pas acceptée ici. `POST /refunds` - `payment` (string, required): L'`id` du paiement, par exemple `trx_test_CSUGajfv9xh0XQ5wu2lx`. Votre `reference` marchand n'est pas acceptée. - `reason` (enum, required): La raison du remboursement. Les valeurs acceptées sont listées plus bas. - `amount` (number): Montant dans l'unité principale, décimales autorisées et arrondies à deux. Omettez-le pour rembourser en totalité ce qui reste. - `currency` (string): Doit être égale à la devise du paiement, qui est la valeur par défaut. - `fees_bearer` (enum): `merchant` ou `customer` : qui supporte les frais Wajub du paiement pour la part remboursée. Par défaut : vos réglages de remboursement, sinon celui qui a payé les frais au paiement. Voir plus bas. - `reference` (string): Votre propre référence pour ce remboursement, jusqu'à 255 caractères. Renvoyée à la lecture. - `metadata` (object): Données clé-valeur libres, renvoyées telles quelles sur l'objet remboursement. Une clé est réservée : `dispute_settlement` marque le remboursement que Wajub crée quand vous acceptez un litige, et elle est retirée si vous l'envoyez. `reason` est obligatoire et sa liste est fermée. Toute valeur hors de cette liste donne un `422` : choisissez la plus proche plutôt que d'en inventer une. | Motif | Quand l'utiliser | | ----------------------- | -------------------------------------------------------------------------------------- | | `requested_by_customer` | Le client l'a demandé, et vous avez accepté | | `duplicate` | La même commande a été payée deux fois | | `fraudulent` | Vous pensez que le paiement n'a pas été fait par le titulaire de la carte ou du compte | | `product_not_received` | La marchandise n'est jamais arrivée | | `service_not_delivered` | Un service a été payé mais pas fourni | | `wrong_amount` | Vous avez débité plus que prévu | | `customer_complaint` | Une réclamation réglée sans désigner de responsable | | `merchant_error` | Votre propre erreur : mauvais article, mauvais prix, mauvais client | | `network_error` | Le paiement est passé de votre côté mais pas du leur | | `transaction_error` | Une panne technique dans le paiement lui-même | | `reconciliation` | Correction d'un écart trouvé lors d'un rapprochement | Envoyez l'appel depuis votre serveur, avec une `Idempotency-Key` si le remboursement peut être déclenché par un processus qui retente ses appels. **Rembourser une partie d'un paiement** ```bash curl https://api.wajub.com/refunds \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: refund-order-4172" \ -d '{ "payment": "trx_test_CSUGajfv9xh0XQ5wu2lx", "amount": 2000, "reason": "product_not_received", "reference": "rma-881" }' ``` ```javascript const refund = await wajub.refunds.create({ payment: 'trx_test_CSUGajfv9xh0XQ5wu2lx', amount: 2000, reason: 'product_not_received', reference: 'rma-881', }); console.log(refund.id, refund.status); ``` ```python refund = wajub.refunds.create({ "payment": "trx_test_CSUGajfv9xh0XQ5wu2lx", "amount": 2000, "reason": "product_not_received", "reference": "rma-881", }) print(refund.id, refund.status) ``` ```php $refund = $wajub->refunds->create([ 'payment' => 'trx_test_CSUGajfv9xh0XQ5wu2lx', 'amount' => 2000, 'reason' => 'product_not_received', 'reference' => 'rma-881', ]); echo $refund->id; ``` ```go refund, err := client.Refunds.Create(context.Background(), map[string]any{ "payment": "trx_test_CSUGajfv9xh0XQ5wu2lx", "amount": 2000, "reason": "product_not_received", "reference": "rma-881", }, nil) ``` Wajub répond `201 Created`. Rien n'a encore quitté votre solde : le remboursement a été accepté, et `status` vous indique où il en est. ```json title="Réponse · 201 Created" { "code": 201, "status": "Created", "message": "Refund created successfully", "refund": { "id": "rfd_test_9xh0XQ5wu2lxCSUGajfv", "transaction": "trx_test_CSUGajfv9xh0XQ5wu2lx", "reference": "rma-881", "amount": 2000, "currency": "XAF", "status": "processing", "reason": "product_not_received", "metadata": {}, "sandbox": true, "created_at": "2026-09-11T10:30:00+00:00" } } ``` Le paiement est porté par `transaction`, pas par `payment`. Les lectures renvoient aussi un détail `tax` quand une taxe s'applique, une `timeline` des changements de statut, et `failure_reason` avec `failure_message` quand le remboursement a échoué. Un remboursement qui a pris de l'argent sur votre solde renvoie en plus `ledger_balance_currency`, `ledger_balance_before` et `ledger_balance_after` : votre solde juste avant le remboursement et juste après, si bien que la différence est ce qu'il a pris, part des frais du paiement comprise quand elle a bougé avec lui. En sandbox, ce sont ceux de votre solde sandbox. Le contenu de `refund.succeeded` les porte aussi. Un remboursement qui n'a rien pris, parce qu'un litige perdu l'avait déjà fait, n'a aucun des trois. > [!NOTE] > **Idempotency-Key, et ce sur quoi porte la clé** > > La clé n'expire jamais : la même clé renvoie toujours le même remboursement, jamais un second, et > la réutiliser pour un autre paiement ou un autre `amount` répond `422`. Une clé est consommée pour > toujours : > dérivez-la de ce remboursement précis, une commande et un numéro de remboursement, pas de la > commande seule. Un second remboursement du même montant ne ferait que vous rendre le premier. - [Suivre un remboursement](https://docs.wajub.com/fr/payments/refunds/track): Le suivre jusqu'à son propre résultat. - [Idempotence](https://docs.wajub.com/fr/best-practices/idempotency): Rejouer l'appel sans rembourser deux fois. --- # Remboursements URL: https://docs.wajub.com/fr/payments/refunds > Restituer des fonds sur un paiement réussi, puis suivre le remboursement jusqu'à son propre résultat. Un remboursement restitue tout ou partie d'un paiement réussi, et vous pouvez cumuler plusieurs remboursements partiels jusqu'à épuisement du montant d'origine. C'est un objet à part entière, avec son propre id, son propre statut et ses propres webhooks. > [!CAUTION] > **Les remboursements exigent la clé secrète** > > `POST /refunds` exige une clé secrète. Un appel qui porte une clé publique > est refusé avec `406 Not Acceptable` et le message `Private Key Required`. Cet endpoint a sa place > sur votre serveur, jamais dans un navigateur ni dans une application mobile. Deux pages vont plus loin : - [Créer un remboursement](https://docs.wajub.com/fr/payments/refunds/create), l'appel, ses paramètres et sa réponse. - [Suivre un remboursement](https://docs.wajub.com/fr/payments/refunds/track), ses webhooks, pourquoi un remboursement échoue, comment tester un échec, et la liste des remboursements. ## Ce qui peut être remboursé Cinq conditions sont vérifiées avant l'enregistrement d'un remboursement, et chacune échoue avec son propre `422`. | Condition | Ce que vous recevez en cas d'échec | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Le paiement est `succeeded` | `Transaction must be completed to be refunded. Current status: …` | | Aucune rétrofacturation n'est ouverte sur le paiement | `Transaction cannot be refunded while a chargeback is open: the payer's bank may return the funds itself. It can be refunded again once the dispute is decided.` | | Il reste un montant remboursable | `Transaction has already been fully refunded.`, ou `Transaction has already been fully refunded or charged back.` quand une rétrofacturation perdue a pris ce qui restait | | Le montant tient dans ce qui reste | `Refund amount exceeds refundable amount (…)` | | La devise correspond à celle du paiement | `Refunds must be in the transaction currency (XAF).` | Le montant remboursable est le montant du paiement moins tout ce qui a déjà été remboursé, en comptant les remboursements encore `pending` ou `processing` comme ceux qui ont réussi, et moins les rétrofacturations que vous avez perdues sur ce paiement : la banque du payeur lui a déjà rendu cet argent. Une rétrofacturation est un litige que le payeur a ouvert auprès de sa banque : les litiges dont `metadata.source` vaut `provider_webhook`. Tant qu'elle est `open` ou `under_review`, la banque peut rendre l'argent elle-même, alors aucun remboursement de ce paiement n'est accepté jusqu'à ce que le litige soit tranché. Un litige que le payeur a ouvert depuis Pocket ne bloque aucun remboursement. > [!NOTE] > **Un remboursement ne peut pas convertir une devise** > > `currency` est accepté, mais la seule valeur possible est la devise du paiement lui-même. Le champ > existe pour que vous puissiez être explicite, pas pour rembourser en XOF un paiement en XAF. Si > vous l'omettez, Wajub utilise de toute façon la devise du paiement. ## Le remboursement a son propre cycle de vie Cinq états, dont trois terminaux. Un remboursement ne revient jamais à un état précédent. **Remboursement** `pending` (accepté, pas encore envoyé) → [`refund.processing`] `processing` (transmis au prestataire) → [`refund.succeeded`] `succeeded` (fonds restitués, solde débité) Sorties anticipées, depuis pending ou processing: - `failed` (lire failure_reason) - `cancelled` (arrêté par Wajub avant l'envoi, depuis pending) Le délai ne dépend pas de Wajub. Sur une carte, c'est l'émetteur qui décide, et plusieurs jours sont normaux. Sur Mobile Money, le crédit arrive généralement en quelques minutes, parfois en quelques heures. Rien dans votre intégration n'y change quoi que ce soit : annoncez au client une fourchette plutôt qu'une heure précise. > [!WARNING] > **Un remboursement ne démarre pas dans le même état selon l'environnement** > > En production, un remboursement est créé `pending` et passe à `processing` quand il est envoyé. > En sandbox, il est créé directement en `processing` et se résout en quelques secondes. Écrivez votre handler sur les états terminaux et vous > ne verrez pas la différence ; si vous testez `pending`, vos tests en sandbox n'entreront jamais dans > cette branche. ## Qui envoie un remboursement live En production, un remboursement est envoyé de l'une de trois façons. `execution_mode` sur le remboursement dit laquelle, une fois que Wajub l'a planifié, et `manual_reason` dit pourquoi quand il n'est pas envoyé automatiquement. | `execution_mode` | Qui l'envoie | | ---------------- | -------------------------------------------------------------------------------------------------------------- | | `automatic` | Wajub. Voir les trois voies ci-dessous | | `merchant` | Vous : le paiement a été encaissé sur votre propre compte prestataire, qui ne peut ici ni rembourser ni verser | | `manual` | Le support Wajub | Un remboursement automatique repart par l'une de trois voies, essayées dans cet ordre : 1. **L'API de remboursement de votre prestataire**, quand il en a une que Wajub pilote : Stripe, Paystack, Flutterwave et PayPal aujourd'hui. L'argent repart par où il est venu, cartes comprises. 2. **Le réseau Wajub**, pour un paiement qu'il a encaissé : le montant est renvoyé sur le numéro mobile money du payeur. 3. **Un versement sur le numéro du payeur, par le prestataire qui a encaissé le paiement**, quand ce prestataire n'a pas d'API de remboursement mais sait verser sur ce canal : Fapshi, Campay, MeSomb, pawaPay et les prestataires du même type. Le versement part de votre propre compte chez ce prestataire. Il faut que ses versements soient approuvés sur Wajub et que le numéro du payeur soit connu. Quand aucune ne s'applique, le remboursement est à faire par vous (`merchant`) : remboursez le client depuis votre prestataire, puis marquez le remboursement comme fait sur sa page dans le Dashboard, ou annulez-le. Il vous revient aussi quand Wajub a tenté de l'envoyer depuis votre propre compte prestataire et que le prestataire l'a refusé, ou que son issue n'a pas pu être confirmée : Wajub ne peut pas consulter ce compte, vérifiez-le donc avant de rembourser à nouveau. Un tel remboursement est `processing`, et l'annuler le clôt en `failed`. Il se met aussi à jour seul quand le prestataire notifie Wajub du remboursement, ce que font Stripe, Paystack, PayPal, Adyen et FedaPay. `manual_reason` est un objet avec un `code` stable sur lequel brancher votre logique et un `message` que vous pouvez afficher. | `code` | Signification | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `refund_from_your_provider` | Encaissé sur votre propre compte prestataire, qui ne peut ici ni rembourser ni verser : remboursez-le là-bas, puis marquez-le comme fait dans le Dashboard. Il se met aussi à jour quand le prestataire confirme | | `card_or_bank_payment` | Le réseau qui l'a encaissé ne rembourse que le mobile money. Le support Wajub envoie celui-ci | | `insufficient_balance` | Votre solde ne couvre pas encore le remboursement. Il part tout seul dès que le solde le couvre, pendant 72 heures ; passé ce délai, le support Wajub le traite | | `platform_balance_insufficient` | Sur une connexion Sync `lite` : le solde du vendeur ne couvre pas encore le remboursement, et le solde de la plateforme ne contient pas le reste. Il part tout seul dès qu'ils le couvrent, pendant 72 heures ; passé ce délai, le support Wajub le traite. [Quand un marchand passe en négatif](https://docs.wajub.com/fr/sync/payouts#when-a-merchant-goes-negative) | | `payer_number_missing` | Le numéro mobile money du payeur n'est pas connu | | `requested_over_24h` | Demandé il y a plus d'un jour : le support Wajub l'envoie | | `outcome_being_confirmed` | Envoyé, et la réponse de l'opérateur n'est pas encore définitive | | `automatic_attempt_failed` | L'opérateur l'a refusé et aucun argent n'est parti : le support Wajub le traite | | `wajub_review` | Le support Wajub le traite | `execution_mode` et `manual_reason` peuvent changer sans que le statut change ; chaque changement envoie `refund.updated` avec le remboursement tel qu'il est désormais. Dans tous les cas, le remboursement se termine `succeeded` ou `failed`. Les remboursements sandbox n'ont aucun des deux champs. ## Ce que dit le statut du paiement Un paiement affiche `partially_refunded` dès que des remboursements **réussis** couvrent une partie de son montant, et `refunded` dès qu'ils le couvrent en entier. Un remboursement `pending`, `processing` ou `failed` ne change rien. Le statut est une lecture, et rien d'autre ne bouge avec lui : aucun événement de paiement n'est émis, et le paiement n'est pas modifié par ailleurs. Pour savoir ce qui reste remboursable, listez les remboursements du paiement et additionnez ceux qui sont `pending`, `processing` ou `succeeded`. `GET /payments/{id}/refunds` Soustrayez ce total, et le montant des rétrofacturations que vous avez perdues sur le paiement, du montant du paiement et vous obtenez ce qui reste remboursable, c'est-à-dire exactement le chiffre que l'API vérifie quand vous envoyez le remboursement suivant. [Gérer les remboursements](https://docs.wajub.com/fr/guides/handle-refunds) le fait en code. > [!NOTE] > **Filtrer les paiements remboursés** > > `GET /payments?status=refunded` et `?status=partially_refunded` listent ces paiements, et > `?status=succeeded` les laisse de côté. ## Qui supporte les frais Wajub garde les frais d'un paiement que vous remboursez. Ce que vous décidez, c'est qui les supporte au final, pour la part des frais qui correspond au montant remboursé : vous, ou le client. C'est `fees_bearer`. | Les frais ont été payés par | `fees_bearer: merchant` | `fees_bearer: customer` | | ----------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | | Vous (`bearer: merchant` sur le paiement) | Le client récupère le montant. Les frais que vous avez payés ne vous sont pas rendus | La part des frais est déduite de ce que le client récupère, et vous êtes débité d'autant en moins | | Le client, en plus (`bearer: customer`) | Le client récupère le montant et la part des frais, et vous êtes débité des deux | Le client récupère le montant, pas les frais | Sans ce champ, les frais restent à celui qui les a payés : c'est la première et la dernière case du tableau. Pour changer cela pour tous les remboursements, réglez-le une fois dans **Paramètres, Remboursements** ; `fees_bearer` sur un remboursement prend le dessus. Le remboursement vous dit ce qui a été appliqué : `fee_amount` est la part des frais, et `payer_amount` ce que le client reçoit. Votre solde est débité de `payer_amount`, ni plus ni moins. Un remboursement partiel prend la même proportion des frais, et le remboursement qui solde le paiement prend ce qu'il en reste : les parts s'additionnent exactement. Dans une devise sans subdivision, comme le XAF, une part est un nombre entier, et `payer_amount` aussi. Un paiement encaissé sur votre propre compte prestataire est différent. Wajub ne détient rien de son argent : votre solde n'est pas débité, vous envoyez le remboursement vous-même depuis ce prestataire, et le montant à envoyer est `payer_amount`. Avec `bearer: merchant`, Wajub n'a facturé aucuns frais sur ce paiement : `fee_amount` vaut `0` et `payer_amount` est égal à `amount`. Avec `bearer: customer`, le payeur a payé les frais en plus à votre prestataire, et le tableau ci-dessus s'applique. ## L'argent bouge au succès, pas à la création Créer un remboursement réserve le montant sur ce qui est remboursable, mais ne touche à aucun solde. Le débit a lieu quand le remboursement atteint `succeeded`, et seulement à ce moment-là, pour `payer_amount` : le montant, plus ou moins la part des frais. Deux conséquences à anticiper. En sandbox, un remboursement réussi débite votre solde sandbox du montant remboursé, comme un remboursement live débite votre solde. Un remboursement qui rembourse un litige que vous avez accepté le débite même s'il échoue, puisque le litige est perdu dans tous les cas. Et un remboursement émis sur un paiement déjà perdu dans un litige est plafonné au montant principal qui n'a pas déjà été repris : le même argent ne peut pas sortir deux fois par deux portes différentes. Ce que devient ensuite le solde, et comment se comporte un solde négatif, est expliqué dans [Solde et règlements](https://docs.wajub.com/fr/payouts/balance). ## Dans le Dashboard Un remboursement peut être émis sans écrire de code. Ouvrez un paiement dans **Paiements**, utilisez son action de remboursement, et le résultat est le même objet que celui que crée l'API. Le formulaire demande qui supporte les frais quand le paiement en portait, et affiche ce que le client recevra. L'action exige la permission `refund_payments`, distincte de `manage_payments` : un membre de l'équipe peut ainsi gérer les commandes sans pouvoir rendre de l'argent. **Remboursements** les liste tous avec leur statut, et les exporte en CSV ou Excel en production. Les remboursements que les payeurs demandent depuis Pocket se trouvent dans **Litiges**, comme une étape à part : voir [Demandes de remboursement](#refund-requests). ## Demandes de remboursement Un payeur qui utilise [Pocket](https://docs.wajub.com/fr/payments/customers/pocket) peut vous demander le remboursement d'un paiement qu'il a effectué, avec un montant et un motif. La demande apparaît dans la liste **Litiges** du Dashboard, comme une étape à part, et attend que vous l'approuviez ou la refusiez. Rien n'est remboursé avant l'approbation, et l'approbation crée le remboursement exactement comme le ferait l'API. Les membres qui gèrent les paiements reçoivent un e-mail à l'arrivée d'une demande. La demande est l'étape amiable. Si elle ne règle pas le problème, le payeur peut la faire passer en [litige](https://docs.wajub.com/fr/payments/disputes) : | Votre réponse | Quand le payeur peut passer en litige | | --------------------- | --------------------------------------------------------------------------------------------------------------------------- | | Aucune pour l'instant | À partir de 7 jours après la demande. Deux jours avant, les membres qui gèrent les paiements reçoivent un rappel par e-mail | | Un refus | Pendant 30 jours après votre réponse. Passé ce délai, la demande est close | | Une approbation | Jamais, l'argent a été rendu | Tant qu'une rétrofacturation est `open` ou `under_review` sur le paiement, c'est la banque du payeur qui décide. Une demande ne peut être ni approuvée ni passée en litige, et le payeur ne peut pas en envoyer une nouvelle. Ses délais cessent de courir et aucun rappel n'est envoyé. Une fois que la banque a tranché, ils reprennent là où ils en étaient : le jour où le payeur peut passer en litige, et la fin des 30 jours après un refus, arrivent plus tard, du temps qu'a duré la rétrofacturation. - [Gérer les remboursements](https://docs.wajub.com/fr/guides/handle-refunds): Le parcours complet, rapprochement compris. - [Litiges](https://docs.wajub.com/fr/payments/disputes): Quand l'argent est repris plutôt que rendu. - [Solde et règlements](https://docs.wajub.com/fr/payouts/balance): Où arrive un remboursement une fois qu'il a réussi. - [Cycle de vie d'un paiement](https://docs.wajub.com/fr/payments/lifecycle): Pourquoi le paiement reste succeeded pendant tout ce temps. - [Mode sandbox](https://docs.wajub.com/fr/developer-tools/testing/sandbox-mode): Les numéros et cartes de test, et ce que chacun déclenche. - [Référence API des remboursements](https://docs.wajub.com/fr/api/refunds): Tous les champs de la ressource, et les trois endpoints. --- # Suivre un remboursement URL: https://docs.wajub.com/fr/payments/refunds/track > Ses webhooks, pourquoi un remboursement échoue, un échec dans la sandbox, et la liste des remboursements. ## Webhooks Six événements suivent un remboursement. Abonnez-vous à chacun par son nom : un abonnement ne reconnaît que des noms exacts, et `refund.*` ne correspond à rien. | Événement | Déclenché quand | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `refund.created` | Le remboursement a été accepté et enregistré | | `refund.processing` | Le remboursement a été envoyé. En live uniquement | | `refund.succeeded` | Fonds restitués. C'est sur celui-ci qu'il faut faire le rapprochement | | `refund.failed` | Le prestataire l'a refusé ou n'a pas pu le finaliser, lisez `failure_reason` | | `refund.cancelled` | Wajub a arrêté un remboursement live avant de l'envoyer : rien n'a quitté votre solde. Il arrive en `refund.failed`, avec `cancelled_by_wajub` pour `failure_reason` | | `refund.updated` | Un remboursement live a changé de voie : `execution_mode` ou `manual_reason` a changé. Live uniquement | > [!NOTE] > **refund.processing n'arrive jamais en sandbox** > > En live, un remboursement passe de `pending` à `processing` quand il est envoyé, et > `refund.processing` est envoyé. En sandbox, un remboursement est créé directement en `processing` : > cet événement n'arrive donc jamais. Utilisez `refund.created` si vous avez besoin d'un signal au > démarrage dans les deux environnements. **`refund.succeeded`**: Un remboursement total ou partiel est terminé sur le paiement. ```json title="refund.succeeded" { "id": "evt_Lm2Xc94Rf8Qp7Tz3Wk5Yb1Nd", "event": "refund.succeeded", "created": "2026-09-11T11:02:41+00:00", "livemode": true, "data": { "id": "rfd_9xh0XQ5wu2lxCSUGajfv", "transaction": "trx_CSUGajfv9xh0XQ5wu2lx", "reference": "rma-881", "amount": 2000, "currency": "XAF", "status": "succeeded", "reason": "product_not_received" } } ``` Dédupliquez sur l'`id` de l'événement, comme partout ailleurs. L'enregistrement et la vérification de signature sont dans [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks). ## Tester un remboursement en échec dans la sandbox Les résultats en sandbox sont déterministes, et ils dépendent du moyen de paiement du **paiement d'origine**, pas de ce que vous envoyez sur le remboursement. Payez avec le bon numéro, remboursez ensuite, et vous obtenez le résultat voulu. Pour un paiement fait par Mobile Money, ce sont les six derniers chiffres du numéro de téléphone qui décident. | Suffixe sur le paiement d'origine | Résultat du remboursement | | -------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `000000` | Réussit | | `000009` | Le paiement réussit, le remboursement échoue toujours. C'est celui à utiliser pour vos tests | | `000001`, `000002`, `000003`, `000004` | Rien à rembourser : le paiement lui-même n'aboutit jamais, donc l'appel de remboursement répond `422` | | Tout autre suffixe | Réussit | Pour un paiement par carte, `4000000000005423` débite normalement puis fait échouer chaque remboursement. Toutes les autres cartes de test se remboursent sans problème. Les paiements en cryptomonnaies et les paiements bancaires se remboursent toujours avec succès, car il n'existe pas d'adresse d'échec pour les tester. Un remboursement sandbox échoué porte un `failure_reason` tiré au hasard parmi `insufficient_funds`, `refund_rejected_by_issuer`, `transaction_already_reversed`, `network_error`, `provider_error` et `provider_declined`, accompagné d'un `failure_message` lisible. Ce sont des codes qu'utilise aussi un remboursement live, listés dans [Pourquoi un remboursement a échoué](#why-a-refund-failed). > [!NOTE] > **Le seul cas aléatoire** > > Quand le paiement d'origine n'a aucun moyen de paiement rattaché, le résultat en sandbox est > aléatoire. Si vos tests sont instables, voici pourquoi : payez avec un numéro de test pour que le > résultat soit choisi. ## Pourquoi un remboursement a échoué Un remboursement `failed` porte toujours un `failure_reason`, pris dans cette liste en production comme en sandbox, et un `failure_message` à côté : les mots du fournisseur quand il en a envoyé. | `failure_reason` | Ce qu'il signifie | | ------------------------------ | ---------------------------------------------------------------------------------------------------------- | | `insufficient_funds` | Le fournisseur n'a pas pu financer le remboursement | | `refund_rejected_by_issuer` | Un émetteur de carte l'a refusé | | `transaction_already_reversed` | Le paiement était déjà annulé ou remboursé chez le fournisseur | | `invalid_number` | Le numéro ou le compte du payeur ne peut pas le recevoir, par exemple fermé ou non abonné. Live uniquement | | `limit_exceeded` | Un plafond du compte destinataire ou du fournisseur a été atteint. Live uniquement | | `network_error` | Le fournisseur n'a pas pu être joint à temps | | `provider_error` | Le fournisseur était indisponible, ou a refusé l'appel lui-même | | `provider_declined` | Le fournisseur l'a refusé sans dire pourquoi | | `ops_failed` | Le support Wajub n'a pas pu le mener à bien. `failure_message` dit pourquoi. Live uniquement | Un remboursement échoué ne prend rien sur votre solde, à une exception près en sandbox : le remboursement d'un litige que vous avez accepté, qui tient lieu de perte du litige (voir [L'argent bouge au succès](https://docs.wajub.com/fr/payments/refunds#the-money-moves-on-success-not-on-creation)). Une nouvelle tentative est un nouveau remboursement. ## Lister les remboursements Les remboursements sont renvoyés du plus récent au plus ancien, tous paiements confondus. `GET /refunds` | Paramètre de requête | Accepte | | ---------------------- | ----------------------------------------------------------- | | `per_page` | De 1 à 100, 25 par défaut | | `status` | `pending`, `processing`, `succeeded`, `failed`, `cancelled` | | `search` | Texte libre sur la référence et l'id du remboursement | | `date_from`, `date_to` | Dates, `date_to` jamais antérieure à `date_from` | | `cursor` | Passe en pagination par curseur, pour les exports | La récupération d'un remboursement se fait par son id. `GET /refunds/{id}` - [Créer un remboursement](https://docs.wajub.com/fr/payments/refunds/create): L'appel et ses paramètres. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): Recevoir et vérifier les événements. --- # Facturation et abonnements URL: https://docs.wajub.com/fr/billing > Les factures, leur paiement par un client et le fonctionnement actuel de la facturation récurrente. Une facture est un document que vous remettez à un client, qui la règle quand il le décide sur une page hébergée par Wajub. Cette section explique comment émettre, envoyer et suivre vos factures. ## Contenu de la section Un produit est disponible : **Factures**. Il produit un document numéroté, héberge la page de paiement du client et suit les fonds encaissés pour cette facture. Un abonnement, au sens d'un plan auquel un client souscrit et d'un portefeuille débité chaque mois sans intervention, n'est pas encore disponible. | Besoin | Solution | | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Facturer une fois un client et être payé en ligne | [Factures](https://docs.wajub.com/fr/billing/invoice) | | Facturer le même client à intervalle fixe | Une facture récurrente : un nouveau brouillon à chaque cycle, qui reste à envoyer et à payer | | Débiter automatiquement un portefeuille enregistré selon un calendrier | Aucune pour le moment, consultez [Abonnements](https://docs.wajub.com/fr/billing/subscriptions) | | Accepter un paiement lancé par votre propre checkout | [Paiements](https://docs.wajub.com/fr/payments), pas la facturation | > [!WARNING] > **Mode live uniquement et accès selon le plan** > > Toutes les routes `/invoices` sont réservées au mode live. Une clé sandbox renvoie donc `403` > avec `This feature is only available in live mode.`, y compris pour les appels `GET`. La > fonctionnalité s'appelle Invoicing : **10 factures au total avec Pay as you go**, et non dix par > mois, puis un nombre illimité à partir de Growth. Une fois ce plafond atteint, la création renvoie > un code `403` avec une invitation à changer de plan. ## Une facture est un document, pas un débit Créer une facture ne déplace aucun fonds et n'envoie aucune notification. L'opération enregistre un document numéroté avec ses lignes, ses totaux et un statut, puis s'arrête. L'envoi, le paiement et les relances constituent trois opérations distinctes effectuées ensuite. `POST /invoices` - `customer_name` (string, required): Le destinataire de la facture. Un nom suffit, aucun enregistrement client n'est obligatoire. - `items` (array, required): Au moins une ligne. Chacune contient `name`, `quantity` et `unit_price`. - `invoice_date` (string (date), required): La date imprimée sur le document. Elle est obligatoire et ne possède aucune valeur par défaut. - `currency` (string, required): Code ISO 4217 d'une devise que Wajub prend en charge ; toute autre renvoie `422`. Tous les montants de la facture utilisent cette devise. - `language` (enum): `fr` ou `en`, la langue de l'e-mail et du PDF. Par défaut, la langue préférée du client lié, sinon la langue de votre compte ([**Paiement — Langue**](https://dashboard.wajub.com/settings/regional/language)), sinon `en`. - `customer_id` (string): Associe la facture à l'un de vos [clients](https://docs.wajub.com/fr/payments/customers), par son identifiant `cus_`. Ses coordonnées sont copiées dans le document lors de la création. - `customer_email` (string): Adresse à laquelle `/send` envoie la facture et son PDF, et adresse utilisée pour son paiement et son reçu. Facultatif : une facture sans e-mail reste payable, et [sa page demande une adresse au payeur](#where-the-customer-pays). - `due_date` (string (date)): Date égale ou postérieure à `invoice_date`. La facture passe à `overdue` une fois cette date passée. - `payment_terms_days` (integer): Définit `due_date` à ce nombre de jours après aujourd'hui, uniquement en l'absence de `due_date`. - `items[].tax_rate` (number): Pourcentage appliqué à cette ligne, de 0 à 100. Il est calculé par ligne, pas par facture. - `items[].discount_type` (enum): `percentage` ou `fixed`, associé à `items[].discount_value`. - `items[].discount_value` (number): Le pourcentage, ou le montant déduit de cette ligne. Une remise sur toute la facture se donne avec `global_discount_type` et `global_discount_value` : voir [Une remise sur toute la facture](https://docs.wajub.com/fr/billing/invoice#an-invoice-wide-discount). - `document_type` (enum, default `invoice`): `invoice`, `quote` ou `estimate`. Un devis ou une estimation se lit et se liste comme une facture, et reste un brouillon : voir [Devis et estimations](https://docs.wajub.com/fr/billing/invoice#quotes-and-estimates). - `is_recurring` (boolean): Marque le document comme récurrent. Lisez la section sur les factures récurrentes avant de vous y fier. - `notes` (string): Texte libre sous les lignes, limité à 5 000 caractères. `terms` et `footer` se trouvent à côté. Les totaux sont calculés à partir des lignes. Vous n'envoyez donc jamais `subtotal` ou `total`. Envoyez la facture avec une clé secrète live. **Créer une facture** ```bash curl https://api.wajub.com/invoices \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: invoice-amina-september" \ -d '{ "customer_name": "Amina Traoré", "customer_email": "amina@example.com", "invoice_date": "2026-09-11", "due_date": "2026-09-25", "currency": "XAF", "items": [ { "name": "Consulting, September", "quantity": 3, "unit_price": 150000 } ] }' ``` ```javascript const invoice = await wajub.invoices.create({ customer_name: 'Amina Traoré', customer_email: 'amina@example.com', invoice_date: '2026-09-11', due_date: '2026-09-25', currency: 'XAF', items: [ { name: 'Consulting, September', quantity: 3, unit_price: 150000 }, ], }); console.log(invoice.invoice_number, invoice.total); ``` ```python invoice = wajub.invoices.create({ "customer_name": "Amina Traoré", "customer_email": "amina@example.com", "invoice_date": "2026-09-11", "due_date": "2026-09-25", "currency": "XAF", "items": [ { "name": "Consulting, September", "quantity": 3, "unit_price": 150000 }, ], }) print(invoice.invoice_number, invoice.total) ``` ```php $invoice = $wajub->invoices->create([ 'customer_name' => 'Amina Traoré', 'customer_email' => 'amina@example.com', 'invoice_date' => '2026-09-11', 'due_date' => '2026-09-25', 'currency' => 'XAF', 'items' => [ ['name' => 'Consulting, September', 'quantity' => 3, 'unit_price' => 150000], ], ]); echo $invoice->invoice_number; ``` ```go invoice, err := client.Invoices.Create(context.Background(), map[string]any{ "customer_name": "Amina Traoré", "customer_email": "amina@example.com", "invoice_date": "2026-09-11", "due_date": "2026-09-25", "currency": "XAF", "items": []map[string]any{ {"name": "Consulting, September", "quantity": 3, "unit_price": 150000}, }, }, nil) ``` La réponse est `201 Created`. Tous les autres appels utilisent l'`id`. `invoice_number` vaut encore `null` : la référence lisible imprimée sur le document est attribuée à l'envoi de la facture, selon la numérotation de votre compte, la même séquence que celle du Dashboard : `INV-` (ou le préfixe que vous avez choisi), l'année, puis un compteur qui repart à `0001` chaque année. ```json title="Réponse · 201 Created" { "code": 201, "status": "Created", "message": "Invoice created", "invoice": { "id": "inv_LRQqYvlhrgUOE225KMKU", "invoice_number": null, "document_type": "invoice", "status": "draft", "customer_name": "Amina Traoré", "customer_email": "amina@example.com", "invoice_date": "2026-09-11", "due_date": "2026-09-25", "currency": "XAF", "subtotal": 450000, "discount_amount": 0, "tax_amount": 0, "total": 450000, "amount_paid": 0, "amount_due": 450000, "is_recurring": false, "sent_at": null, "paid_at": null, "created_at": "2026-09-11T14:00:00+00:00" } } ``` ## Cycle de vie d'une facture **Facture** `draft` (pas encore payable) → [`invoice.updated`] `sent` (la page s'ouvre) → [`invoice.updated`] `viewed` (le client l'a ouverte) → [`invoice.updated`] `paid` (amount_due atteint zéro) Les autres états possibles d'une facture: - `partial` (une partie du total est encaissée) - `overdue` (la date d'échéance est dépassée) - `cancelled` (fermée et plus payable) - `refunded` (payée, puis remboursée) La répétition sur ces flèches est volontaire. Chaque transition effectuée par l'API arrive sous la forme `invoice.updated`, et le champ `status` du payload indique laquelle. Quatre événements en disent plus : `invoice.sent` quand la facture est envoyée, `invoice.cancelled` quand elle est annulée, `invoice.paid` quand elle est réglée en totalité, et `invoice.payment_succeeded` pour chaque paiement effectué sur sa page, échéance comprise. Il n'existe aucun `invoice.overdue`. Deux états changent automatiquement. `viewed` est écrit lors de la première ouverture de la page de paiement par le client. Une facture passe à `overdue` pendant la nuit une fois sa `due_date` passée. Vous ne définissez aucun de ces deux états. ## Envoyer une facture `POST /invoices/{id}/send` Sur un brouillon, l'appel attribue le `invoice_number`, passe la facture en `sent`, renseigne `sent_at` et envoie à `customer_email` un e-mail avec le lien de la facture et une copie PDF en pièce jointe, dans la `language` de la facture. Rappelé sur une facture déjà envoyée, il renvoie l'e-mail et renseigne de nouveau `sent_at`, sans changer son statut. L'appel a besoin d'un destinataire : `customer_email`, ou l'e-mail du client que désigne `customer_id`. Sans l'un ni l'autre, il répond `422` sur `customer_email` et ne change rien, même sur un brouillon. Une facture déjà `paid`, `cancelled` ou `refunded` répond `400` : il n'y a plus rien à réclamer. Un devis ou une estimation répond `400 Only an invoice can be sent through the API.` Un brouillon adressé à un nom seulement peut être envoyé depuis le Dashboard, qui le numérote et ouvre sa page sans envoyer d'e-mail ; partagez vous-même le lien, et la page demande un e-mail au payeur. C'est aussi l'envoi qui ouvre la page de paiement : la page d'un brouillon ne s'ouvre pas, et seuls quatre statuts sont payables : `sent`, `viewed`, `overdue` et `partial`. ## Page de paiement du client La page de paiement possède son propre domaine et utilise l'id de la facture comme chemin complet. ```text title="URL du client" https://invoice.wajub.com/inv_LRQqYvlhrgUOE225KMKU ``` Cette adresse ne figure pas dans la réponse de l'API. Construisez-la à partir de l'`id` reçu ou copiez-la depuis le Dashboard. C'est aussi le seul endroit où elle peut changer : un marchand qui héberge ses factures sur un domaine personnalisé vérifié utilise ce domaine au lieu de `invoice.wajub.com`. La page s'ouvre dans la `language` de la facture, celle de son e-mail et de son PDF. Le payeur peut l'afficher dans l'autre langue en ajoutant `?locale=fr` ou `?locale=en` à l'adresse. La page constitue un checkout ordinaire. Elle affiche votre marque, les lignes de la facture et les opérateurs disponibles pour sa devise. Un paiement effectué sur cette page reste un paiement ordinaire : il apparaît dans votre liste Payments, émet `payment.succeeded`, rejoint votre solde et peut être remboursé comme les autres. Après sa réussite, la facture passe à `paid`. Elle passe à `partial` si elle est divisée en plusieurs échéances et qu'une seule a été réglée. Le paiement désigne la facture dans son champ `invoice`, l'`id` de la facture. Remboursez ce paiement en totalité, ou tous les paiements faits sur la facture, et la facture passe à `refunded`, avec `refunded_at` renseigné et l'envoi de `invoice.updated`. Cela vaut aussi pour une facture payée en partie, `partial` ou `overdue` avec une part réglée : dès que tout ce qui est entré en ligne est rendu, elle est `refunded`. Un remboursement partiel laisse la facture en l'état. Une facture qui porte de l'argent enregistré avec `mark-paid` garde son statut : cet argent n'est jamais passé par Wajub, un remboursement Wajub ne peut donc pas le rendre. Émettez un avoir depuis le Dashboard pour cette part. Une facture n'a pas besoin d'e-mail pour être payée. Quand elle n'en porte aucun, c'est-à-dire sans `customer_email` ni `customer_id`, la page affiche au payeur un champ e-mail au-dessus du bouton de paiement et n'ouvre le paiement qu'avec une adresse valide. Cette adresse reçoit la confirmation du paiement et son reçu, et le paiement est rattaché à celui de vos [clients](https://docs.wajub.com/fr/payments/customers) qui la porte, créé avec le nom de la facture si vous n'en avez pas encore. L'adresse est aussi inscrite sur la facture comme son `customer_email`, et `invoice.updated` vous en informe : l'échéance suivante ne la redemande pas, et `/send` comme les relances ont désormais un destinataire. Seule la première adresse donnée est conservée, et un e-mail que vous avez mis sur la facture n'est jamais remplacé. La page ne demande rien quand la facture porte un e-mail, et le payeur ne peut pas lui en substituer un autre. Elle ne demande rien non plus quand la facture est associée à un client : c'est ce client qui paie, que sa fiche comporte un e-mail ou non. La page sert aussi la facture au format PDF, pour que le client la conserve, à l'adresse `https://api.wajub.com/i/{id}/pdf`, dans la `language` de la facture sauf si `?locale=fr` ou `?locale=en` demande l'autre. Toute personne qui détient l'`id` peut ouvrir les deux : partagez-le comme vous partageriez le lien lui-même. ## Enregistrer des fonds encaissés ailleurs De nombreuses factures sont payées en espèces ou par un virement bancaire extérieur à Wajub. Vous pouvez enregistrer ce paiement sur le document sans créer un faux paiement. `POST /invoices/{id}/mark-paid` Omettez `amount` pour régler intégralement la facture. Si vous le transmettez, supérieur à zéro, il est ajouté à `amount_paid`. La facture reste alors `partial` jusqu'au règlement du total. La facture doit être ouverte : un brouillon répond `400`, puisqu'il n'a jamais été envoyé, de même qu'une facture déjà `paid`, qui garde son `paid_at`. Une facture `cancelled` ou `refunded` refuse aussi l'appel avec un code `400`. Un document fermé par son propre parcours ne peut donc pas être réactivé. Un `amount` nul répond `422`. ## État actuel des factures récurrentes La création accepte `is_recurring` et `recurring_interval`. L'intervalle peut valoir `daily`, `weekly`, `monthly`, `quarterly` ou `yearly`. Quand un cycle arrive à échéance, Wajub copie la facture récurrente dans un nouveau document avec de nouvelles dates et les coordonnées actuelles du client. La première copie est due un intervalle après la date de la facture elle-même, et chaque cycle est généré une seule fois. Deux points définissent la récurrence sur Wajub. Chaque facture générée est créée avec `draft`. La chaîne produit donc des documents, et non des débits. Chaque document doit encore être envoyé et payé. Elle nécessite la fonctionnalité Facturation récurrente, disponible à partir de **Growth**. Sans elle, aucune copie n'est générée et la facture parente est conservée. Les renouvellements reprennent automatiquement si un compte ayant changé pour un plan inférieur repasse ensuite au plan requis. La création d'une facture récurrente via l'API réussit avec tous les plans. Sans la fonctionnalité, c'est la génération qui est ignorée. [Factures récurrentes](https://docs.wajub.com/fr/billing/invoice/recurring) détaille le calendrier, ce qu'une copie reprend et la façon dont une récurrence se termine. ## Événements envoyés à votre webhook Cinq événements portent la facture, pas les fonds. | Événement | Déclencheur | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invoice.created` | Une facture est créée avec `draft` : une seule fois, avec ses lignes et ses totaux | | `invoice.updated` | Un champ ou un statut change via l'API, y compris `viewed` et un paiement. Un seul par `PUT`, avec ses lignes et ses totaux, et aucun pour un `PUT` qui ne change rien | | `invoice.payment_succeeded` | Un paiement effectué sur la page de la facture réussit, chaque échéance comprise | | `invoice.paid` | La facture est réglée en totalité, en ligne ou avec `mark-paid` | | `invoice.deleted` | Une facture `draft` est supprimée | Les fonds produisent un événement distinct. Lorsqu'un client paie une facture en ligne, vous recevez `payment.succeeded` pour le paiement, puis `invoice.updated` et `invoice.payment_succeeded` pour le document, et `invoice.paid` une fois la facture réglée. Livrez la commande avec `payment.succeeded`, car il contient le montant, le canal et la référence du prestataire, et son champ `invoice` désigne la facture payée. > [!WARNING] > **Seule l'API émet ces événements** > > Une modification effectuée dans le Dashboard n'envoie aucun webhook. L'envoi, le marquage comme > payée ou l'annulation d'une facture depuis l'interface restent silencieux. Les factures passent à > `overdue` pendant la nuit, et ce changement n'envoie aucun webhook non plus. Utilisez le polling sur `GET /invoices` si vous devez les détecter. ## Dans le Dashboard **Factures** va plus loin que l'API : elle suit les relances, exporte la liste, agit sur plusieurs factures à la fois, duplique une facture et émet des avoirs. Le guide du tableau de bord couvre chacun : [le suivi et les relances](https://docs.wajub.com/dashboard/invoices/track-and-remind), [les corrections et les avoirs](https://docs.wajub.com/dashboard/invoices/correct-cancel-refund), et [les actions groupées et l'export](https://docs.wajub.com/dashboard/invoices/export-and-bulk). Un avoir est un document : il ne déplace aucun argent. Il diminue le `amount_paid` de la facture de son montant, et un paiement ultérieur sur la facture en tient compte : la facture passe à `paid` quand ce qui a été payé, moins ses avoirs, couvre le total. Une facture impayée passe à `overdue` pendant la nuit une fois sa `due_date` passée, et les [relances](https://docs.wajub.com/fr/billing/invoice/reminders) partent d'elles-mêmes, avant et après l'échéance, vers les clients dont la facture reste ouverte. - [Factures](https://docs.wajub.com/fr/billing/invoice): Tous les champs, le calcul des totaux et les huit appels. - [Démarrage rapide](https://docs.wajub.com/fr/billing/invoice/quickstart): Émettez votre première facture et faites-la payer. - [Abonnements](https://docs.wajub.com/fr/billing/subscriptions): Les besoins de la facturation récurrente et la raison pour laquelle elle n'est pas encore un produit. - [Clients](https://docs.wajub.com/fr/payments/customers): Associez une facture à un client enregistré plutôt qu'à un simple nom. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): Écoutez payment.succeeded et rapprochez la facture. - [Référence API des factures](https://docs.wajub.com/fr/api/invoices): Tous les champs et les huit endpoints. --- # Factures URL: https://docs.wajub.com/fr/billing/invoice > L'objet facture, les montants calculés et les huit appels qui permettent de le gérer. Une facture est un document que vous émettez et que votre client règle sur une page hébergée par Wajub. Cette page sert de référence pour l'objet facture et ses appels ; [Facturation et abonnements](https://docs.wajub.com/fr/billing) présente le cycle. La facturation est un produit live dont l'accès dépend de votre plan. Une clé sandbox renvoie `403 This feature is only available in live mode.`. Un plan sans cette fonctionnalité renvoie `403 Invoicing is not available on your plan.`. Une fois le plafond total d'un plan atteint, la réponse est `403 You have reached the maximum number of invoices for your plan.`. Seuls les documents de type `invoice` comptent dans ce plafond. ## Les huit appels Voici toutes les opérations proposées par l'API pour les factures. `/send` est l'appel qui envoie une facture par e-mail, son PDF est un lien public ([plus bas](#the-pdf)), et aucun endpoint ne débite un client. | Appel | Fonction | | ------------------------------- | -------------------------------------------------------------------------- | | `GET /invoices` | Lister, filtrer et trier vos factures | | `POST /invoices` | Créer une facture, toujours avec `draft` | | `GET /invoices/{id}` | Récupérer une facture | | `PUT /invoices/{id}` | Remplacer une facture tant qu'elle est un brouillon | | `DELETE /invoices/{id}` | Supprimer une facture tant qu'elle est un brouillon | | `POST /invoices/{id}/send` | La numéroter, l'envoyer par e-mail avec son PDF et ouvrir sa page publique | | `POST /invoices/{id}/mark-paid` | Enregistrer un paiement encaissé ailleurs | | `POST /invoices/{id}/cancel` | Fermer une facture | `{id}` correspond à l'`id` renvoyé par l'API, soit la chaîne `inv_`. ## L'objet facture Tous les appels renvoient cet objet. `items` est présent chaque fois que la facture est chargée avec ses lignes, ce qui est le cas pour les huit appels. ```json title="Réponse · une facture avec une ligne taxée" { "id": "inv_LRQqYvlhrgUOE225KMKU", "invoice_number": "INV-2026-0001", "document_type": "invoice", "status": "sent", "customer": "cus_7Kq2mX9vL4tRb3nP8sZcWd1e", "customer_name": "Amina Traoré", "customer_email": "amina@example.com", "customer_company_name": "Traoré & Fils", "customer_phone": "+237670000000", "customer_address": "BP 1204, Douala", "invoice_date": "2026-09-12", "due_date": "2026-10-12", "currency": "XAF", "language": "fr", "subtotal": 300000, "discount_amount": 0, "has_global_discount": false, "global_discount_type": null, "global_discount_value": null, "tax_amount": 57750, "total": 357750, "amount_paid": 0, "amount_due": 357750, "payment_type": "full", "is_recurring": false, "recurring_interval": null, "next_invoice_date": null, "recurring_parent": null, "notes": null, "terms": null, "footer": null, "accept": {}, "sent_at": "2026-09-12T09:14:02+00:00", "paid_at": null, "cancelled_at": null, "items": [ { "id": "00000000-0000-0000-0000-000000000001", "name": "Consulting service", "description": null, "quantity": 2, "unit": null, "unit_price": 150000, "tax_rate": 19.25, "tax_amount": 57750, "discount_type": null, "discount_value": 0, "discount_amount": 0, "subtotal": 300000, "total": 357750, "sort_order": 0 } ], "created_at": "2026-09-12T09:10:44+00:00", "updated_at": "2026-09-12T09:14:02+00:00" } ``` `invoice_number` vaut `null` sur un brouillon et est attribué au premier envoi de la facture. Il vient de la numérotation de votre compte, la même séquence que celle du Dashboard, que vous envoyiez la facture ici ou là-bas : le préfixe (`INV-` si vous ne l'avez pas changé), l'année, puis un compteur à quatre chiffres, tels que réglés dans les paramètres de facturation du Dashboard. Le compteur repart à `0001` chaque année, sauf si vous l'avez désactivé, et un numéro est unique au sein de votre compte. `status` peut valoir `draft`, `sent`, `viewed`, `partial`, `paid`, `overdue`, `cancelled` ou `refunded`. [Facturation et abonnements](https://docs.wajub.com/fr/billing) présente les transitions entre ces statuts et les webhooks émis. `customer` désigne le client à qui la facture est adressée, par l'identifiant `cus_` que renvoie l'[API Clients](https://docs.wajub.com/fr/payments/customers), et vaut `null` quand vous l'avez adressée à un nom et un e-mail seulement. Rapprochez vos données sur `customer`. `language` est la langue de l'e-mail et du PDF de la facture, `fr` ou `en`, enregistrée à la création de la facture, ici ou dans le Dashboard. `accept` est la restriction des moyens proposés au payeur sur la page de la facture, `{}` quand il n'y en a pas. Deux champs sont calculés plutôt que stockés. `amount_due` vaut toujours `total` moins `amount_paid`, avec un minimum de zéro. Il ne devient donc jamais négatif en cas de trop-perçu. `amount_paid` ne change qu'avec `mark-paid`, un paiement effectué sur la page hébergée ou un avoir émis depuis le Dashboard, qui le diminue de son montant. Un paiement sur la page compte les trois : les paiements en ligne de la facture, plus ce que `mark-paid` a enregistré, moins ses avoirs. Une facture qui porte un avoir de 1 000 ne passe à `paid` qu'une fois 1 000 de plus que son total reçus. ## Créer une facture Les quatre champs obligatoires sont `customer_name`, `items`, `invoice_date` et `currency`. Tous les autres sont facultatifs. La facture est toujours créée avec `draft`, quelle que soit votre requête. `POST /invoices` - `customer_name` (string, required): Le destinataire de la facture. Ce champ reste obligatoire même avec `customer_id`. - `customer_id` (string): L'un de vos clients, par son identifiant `cus_`. Son nom, son e-mail, son entreprise, son téléphone et son adresse sont copiés sur la facture et remplacent les champs `customer_*` envoyés. Un client qui n'est pas le vôtre renvoie `422`. - `customer_email` (string): L'adresse à laquelle `/send` envoie la facture et son PDF, et à laquelle partent ses [relances](https://docs.wajub.com/fr/billing/invoice/reminders). - `customer_company_name` (string): Imprimé sur le document à côté du nom. - `customer_phone` (string): Imprimé sur le document. - `customer_address` (string): Imprimée sur le document. - `items` (array, required): Au moins une ligne. Consultez l'objet ligne ci-dessous. - `invoice_date` (date, required): La date d'émission imprimée sur le document. - `due_date` (date): La date de paiement attendue. Elle doit être égale ou postérieure à `invoice_date`. - `payment_terms_days` (integer): Définit `due_date` à ce nombre de jours après aujourd'hui, uniquement si `due_date` est absent. Le calcul part de la date du jour, pas de `invoice_date`. - `currency` (string, required): Une devise que Wajub prend en charge : `XAF`, `XOF`, `NGN` et les autres de la [liste](https://docs.wajub.com/fr/resources/coverage). Tout autre code renvoie `422`. - `language` (enum): `fr` ou `en` : la langue de l'e-mail envoyé par `/send`, des relances et du PDF. Par défaut, la langue préférée du client que désigne `customer_id`, sinon la langue de votre compte ([**Paiement — Langue**](https://dashboard.wajub.com/settings/regional/language)), sinon `en`. Toute autre valeur renvoie `422`. - `accept` (object): Restreint les moyens proposés au payeur sur la page de la facture, comme sur [`POST /payments`](https://docs.wajub.com/fr/payments/payment-methods#choosing-what-a-payment-accepts). - `is_recurring` (boolean, default `false`): Marque la facture comme modèle. Consultez [Factures récurrentes](https://docs.wajub.com/fr/billing/invoice/recurring). - `recurring_interval` (enum): `daily`, `weekly`, `monthly`, `quarterly` ou `yearly`. - `payment_type` (enum, default `full`): `full`, `split` ou `milestone`. Les paiements en plusieurs fois sont décrits ci-dessous. - `payment_schedules` (array): Les échéances lorsque `payment_type` ne vaut pas `full`. - `notes` (string): Texte libre imprimé sur le document, limité à 5 000 caractères. - `terms` (string): Conditions générales, limitées à 5 000 caractères. - `footer` (string): Texte de pied de page, limité à 500 caractères. - `template_id` (string (uuid)): Un modèle de facture créé dans le Dashboard. Il détermine uniquement la mise en page imprimée. - `document_type` (enum, default `invoice`): `invoice`, `quote` ou `estimate`. Un devis et une estimation restent des brouillons : voir [Devis et estimations](#quotes-and-estimates). - `global_discount_type` (enum): `percentage` ou `fixed` : une remise sur toute la facture. Avec `has_global_discount: true` et sans type, la remise est un `percentage`. Voir [Une remise sur toute la facture](#an-invoice-wide-discount). - `global_discount_value` (number): Le pourcentage, 100 au plus, ou le montant lorsque le type vaut `fixed`, dans l'unité principale, avec au plus deux décimales et pas plus que la devise n'en a ; un montant déduit au plus le montant des lignes. Requis lorsque `has_global_discount` vaut `true`. Sans `has_global_discount`, il va avec `global_discount_type` : l'un sans l'autre renvoie `422`. - `has_global_discount` (boolean): `true` applique la remise que fixe `global_discount_value`, un `percentage` sauf si `global_discount_type` vaut `fixed`. `false` retire la remise sur toute la facture, quoi qu'indiquent les deux autres. Chaque entrée de `items` constitue un objet distinct. - `name` (string, required): Le libellé de la ligne. - `description` (string): Une seconde ligne sous le libellé. - `quantity` (number, required): La quantité. - `unit_price` (integer, required): Le prix unitaire, en unités entières de la devise. - `unit` (string): Un libellé comme `hour` ou `day`. Il sert uniquement à l’affichage. - `tax_rate` (number): Un pourcentage de 0 à 100, ajouté à la ligne. - `discount_type` (enum): `percentage` ou `fixed`. - `discount_value` (number): Le pourcentage, 100 au plus, ou le montant lorsque le type vaut `fixed`, au plus `quantity` × `unit_price` de la ligne : une remise ne fait jamais passer une ligne sous zéro. Au-delà, `422` sur `items.N.discount_value`. **Une facture avec TVA et remise sur une ligne** ```bash curl https://api.wajub.com/invoices \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "customer_name": "Traoré & Fils", "customer_email": "amina@example.com", "invoice_date": "2026-09-12", "payment_terms_days": 30, "currency": "XAF", "items": [ { "name": "Consulting service", "quantity": 2, "unit_price": 150000, "tax_rate": 19.25 }, { "name": "Onboarding", "quantity": 1, "unit_price": 100000, "discount_type": "percentage", "discount_value": 10 } ] }' ``` ```javascript const invoice = await wajub.invoices.create({ customer_name: 'Traoré & Fils', customer_email: 'amina@example.com', invoice_date: '2026-09-12', payment_terms_days: 30, currency: 'XAF', items: [ { name: 'Consulting service', quantity: 2, unit_price: 150000, tax_rate: 19.25 }, { name: 'Onboarding', quantity: 1, unit_price: 100000, discount_type: 'percentage', discount_value: 10 }, ], }); ``` ```python invoice = wajub.invoices.create({ "customer_name": "Traoré & Fils", "customer_email": "amina@example.com", "invoice_date": "2026-09-12", "payment_terms_days": 30, "currency": "XAF", "items": [ {"name": "Consulting service", "quantity": 2, "unit_price": 150000, "tax_rate": 19.25}, {"name": "Onboarding", "quantity": 1, "unit_price": 100000, "discount_type": "percentage", "discount_value": 10}, ], }) ``` ```php $invoice = $wajub->invoices->create([ 'customer_name' => 'Traoré & Fils', 'customer_email' => 'amina@example.com', 'invoice_date' => '2026-09-12', 'payment_terms_days' => 30, 'currency' => 'XAF', 'items' => [ ['name' => 'Consulting service', 'quantity' => 2, 'unit_price' => 150000, 'tax_rate' => 19.25], ['name' => 'Onboarding', 'quantity' => 1, 'unit_price' => 100000, 'discount_type' => 'percentage', 'discount_value' => 10], ], ]); ``` ```go invoice, err := client.Invoices.Create(context.Background(), map[string]any{ "customer_name": "Traoré & Fils", "customer_email": "amina@example.com", "invoice_date": "2026-09-12", "payment_terms_days": 30, "currency": "XAF", "items": []map[string]any{ {"name": "Consulting service", "quantity": 2, "unit_price": 150000, "tax_rate": 19.25}, {"name": "Onboarding", "quantity": 1, "unit_price": 100000, "discount_type": "percentage", "discount_value": 10}, }, }, nil) ``` La création est le seul appel de facture qui respecte `Idempotency-Key`. Rejouer une création avec la même clé renvoie la première facture au lieu d'en émettre une seconde. Rejouer un appel `send` ou `mark-paid` l'exécute une nouvelle fois. ## Les montants sont en unité principale `unit_price`, `subtotal`, `discount_amount`, `tax_amount`, `total` et `amount_paid` sont tous exprimés dans l'unité principale de la devise : `150000` représente cent cinquante mille francs, et non mille cinq cents. Chaque montant est arrondi à l'unité mineure de la devise au fil du calcul, et le suivant part de la valeur arrondie : des francs entiers en XAF et en XOF, donc 19,25 % de 1 000 vaut 193 ; deux décimales dans la plupart des autres devises, trois en KWD, BHD, JOD, OMR et TND. Les montants d'une ligne gardent au plus deux décimales. ## Calcul d'une ligne Chaque ligne effectue ses propres calculs à chaque enregistrement, dans l'ordre suivant. Vous envoyez les quatre premières valeurs. Les quatre autres sont calculées et renvoyées. ``` subtotal = quantity × unit_price discount_amount = discount_type = percentage → subtotal × discount_value / 100 discount_type = fixed → discount_value otherwise → 0 taxable = subtotal − discount_amount tax_amount = taxable × tax_rate / 100 total = taxable + tax_amount ``` La taxe est exclusive. Elle est ajoutée à la ligne et n'en est jamais extraite. Elle est aussi calculée après la remise. Une remise de 10 % sur une ligne taxée réduit donc également la taxe. Sur une facture avec une [remise sur toute la facture](#an-invoice-wide-discount), la taxe de la ligne se calcule sur `taxable` moins la part de cette remise qui revient à la ligne ; la part elle-même reste dans le `discount_amount` de la facture, si bien que le `total` de la ligne reste `taxable` plus cette taxe. La facture additionne ensuite les lignes, chacune nette de sa remise. ``` subtotal = Σ (subtotal de la ligne − discount_amount de la ligne) discount_amount = la remise sur toute la facture, 0 sans elle tax_amount = Σ tax_amount des lignes total = Σ total des lignes − discount_amount amount_due = max(0, total − amount_paid) ``` Une remise sur une ligne est déduite du `subtotal`, du `total` et du `amount_due` de la facture, et sa taxe avec elle. Le `discount_amount` de la facture est la seule remise sur toute la facture : celles des lignes sont dans `items[].discount_amount`. ## Une remise sur toute la facture `global_discount_type` et `global_discount_value` déduisent une remise de toute la facture, après les remises des lignes. Un pourcentage se calcule sur le `subtotal`, les lignes après leurs propres remises et hors taxe ; un montant `fixed` est déduit tel quel, au plus ce `subtotal`. La remise est répartie sur les lignes au prorata de leur montant, avant la taxe : la taxe de chaque ligne se calcule sur ce qui en reste, si bien que la remise baisse aussi la taxe, et qu'une remise de 100 % n'en laisse aucune. Le `total` est le `subtotal` moins la remise, plus la taxe et les éventuels frais de livraison. ```text title="Deux lignes et 10 % sur toute la facture" 2 × 50 000, 10 % de remise, TVA 19,25 % net de la ligne 90 000 part 9 000 1 × 20 000, 5 000 de remise net de la ligne 15 000 part 1 500 subtotal 105 000 (90 000 + 15 000) discount_amount 10 500 (10 % de 105 000, réparti 9 000 + 1 500) tax_amount 15 593 (19,25 % de 81 000, la première ligne moins sa part) total 110 093 (105 000 − 10 500 + 15 593) ``` La facture renvoie la remise choisie dans `has_global_discount`, `global_discount_type` et `global_discount_value`, et ce qu'elle représente dans `discount_amount`. La page de paiement encaisse le total remisé, et le reçu comme la confirmation de paiement indiquent la remise après les lignes. ## Devis et estimations Créez un devis ou une estimation avec `document_type: quote` ou `estimate`. Il se lit, se corrige, s'annule et se supprime par son `id` comme une facture, et `GET /invoices?document_type=quote` liste les devis. Il reste un `draft` : l'API ne l'envoie pas, ne le numérote pas et ne l'encaisse pas. `POST /invoices/{id}/send` renvoie donc `400 Only an invoice can be sent through the API.` et `mark-paid` renvoie `400 Only an invoice can be marked as paid.` Le `document_type` est fixé à la création et conservé : `PUT` ne le change pas. ## Paiement en plusieurs fois Définissez `payment_type` sur `split` ou `milestone`, puis transmettez le calendrier. La page hébergée débite alors une échéance à la fois au lieu du solde total. - `amount` (number, required): Le montant débité pour cette échéance. - `label` (string): Affiché sur la page de paiement. La valeur par défaut est `Installment 1` ou `Milestone 1`. - `due_date` (date): Affichée sur la page de paiement. Le client ouvre la facture et voit la première échéance non payée. Son `amount` est débité dans la limite de l'`amount_due` restant. Après son règlement, Wajub marque cette échéance comme payée, ajoute le montant à `amount_paid` et fait passer la facture à `partial`. La visite suivante propose l'échéance suivante. La facture passe à `paid` lorsque `amount_paid` atteint le total. Si toutes les échéances sont réglées mais qu'un solde reste dû, la page propose le paiement du reste en une fois. > [!WARNING] > **Vous pouvez définir un calendrier, mais pas le relire** > > L'objet facture renvoie `payment_type`, mais jamais `payment_schedules`. Les échéances existantes, > leur paiement et la transaction associée à chacune sont visibles uniquement dans le Dashboard. > Conservez votre propre copie du calendrier envoyé si vous devez le suivre de votre côté. ## Lister les factures `GET /invoices` renvoie vos factures live, de la plus récente à la plus ancienne, par groupes de vingt-cinq. `GET /invoices` - `search` (string): Recherche en texte intégral sur le numéro, le nom et l’e-mail du client. - `status` (enum): Un statut, exactement comme il apparaît sur l’objet : `draft`, `sent`, `viewed`, `partial`, `paid`, `overdue`, `cancelled` ou `refunded`. - `customer_id` (string): Un client, par son identifiant `cus_`. - `date_from` (date): Limite inférieure de `invoice_date`. - `date_to` (date): Limite supérieure de `invoice_date`, égale ou postérieure à `date_from`. - `due_date_from` (date): Limite inférieure de `due_date`. - `due_date_to` (date): Limite supérieure de `due_date`, égale ou postérieure à `due_date_from`. - `amount_min` (number): Limite inférieure de `total`, en unité principale, comme `total` se lit : `10000` vaut dix mille francs. Chaque facture est comparée dans sa propre devise. - `amount_max` (number): Limite supérieure de `total`, en unité principale. - `payment_status` (enum): `unpaid`, `partially_paid` ou `fully_paid`, déterminé en comparant `amount_paid` à `total`. - `sort_by` (enum, default `created_at`): `invoice_date`, `due_date`, `total`, `amount_paid`, `status` ou `created_at`. La liste le suit en premier, puis du plus récent au plus ancien entre factures à égalité. - `sort_dir` (enum, default `desc`): `asc` ou `desc`. - `per_page` (integer, default `25`): Entre 1 et 100. - `document_type` (enum, default `invoice`): `invoice`, `quote` ou `estimate` : un type de document par liste. Sans lui, la liste ne contient que des factures. Un `status`, un `payment_status`, un `document_type`, un `sort_by` ou un `sort_dir` hors de ces valeurs renvoie une `422` sur ce champ, comme un `per_page` hors limites. De même pour une borne de date qui n'est pas une date, ou une borne supérieure antérieure à la borne inférieure. **Toutes les factures en retard d'un client** ```bash curl -G https://api.wajub.com/invoices \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -d status=overdue \ -d customer_id=cus_7Kq2mX9vL4tRb3nP8sZcWd1e ``` ```javascript const { data, meta } = await wajub.invoices.list({ status: 'overdue', customer_id: 'cus_7Kq2mX9vL4tRb3nP8sZcWd1e', }); ``` ```python page = wajub.invoices.list({ "status": "overdue", "customer_id": "cus_7Kq2mX9vL4tRb3nP8sZcWd1e", }) ``` ```php $page = $wajub->invoices->list([ 'status' => 'overdue', 'customer_id' => 'cus_7Kq2mX9vL4tRb3nP8sZcWd1e', ]); ``` ```go page, err := client.Invoices.List(context.Background(), map[string]any{ "status": "overdue", "customer_id": "cus_7Kq2mX9vL4tRb3nP8sZcWd1e", }) ``` La liste utilise une pagination par curseur avec le tri par défaut. Si vous demandez un `sort_by` ou un `sort_dir` personnalisé, elle revient aux numéros de page. ## Corriger une facture `PUT /invoices/{id}` remplace le document au lieu de le modifier partiellement. `customer_name`, `items`, `invoice_date` et `currency` sont obligatoires à chaque appel. Renvoyez donc toute la facture avec votre modification, pas uniquement le changement. Les lignes envoyées remplacent entièrement les précédentes : chaque mise à jour remplace les lignes et leurs id. Tous les `items[].id` changent donc. > [!CAUTION] > **Seul un brouillon est modifiable** > > Dès que la facture a quitté `draft`, et sur un brouillon qui a reçu des fonds, `PUT` renvoie > `400 This invoice cannot be edited (paid, cancelled, or has payments).` et `DELETE` renvoie > `400 This invoice cannot be deleted.` Une facture envoyée est déjà figée. Annulez-la et émettez-en > une nouvelle. Vous pouvez modifier `recurring_interval` pendant une mise à jour. L'alias `recurring_frequency` accepté à la création ne l'est pas. Utilisez donc toujours `recurring_interval`. La remise sur toute la facture est conservée tant que vous ne l'envoyez pas : `has_global_discount: false` la retire. `language` reste tel quel tant que vous ne l'envoyez pas, même quand `customer_id` change. Un `PUT` envoie un seul `invoice.updated`, avec les lignes et les totaux enregistrés, et aucun quand il ne change rien. Une facture supprimée ne vous est plus jamais renvoyée, et son numéro de facture reste utilisé. ## Enregistrer un paiement encaissé ailleurs `mark-paid` sert aux fonds reçus hors de Wajub, en espèces ou par virement bancaire. Il modifie le solde de la facture, mais ne crée aucune transaction et ne règle rien. `POST /invoices/{id}/mark-paid` - `amount` (number): Le montant reçu, supérieur à zéro. Omettez-le pour enregistrer la totalité de `total`. - `payment_date` (date): Le jour où l'argent est arrivé. Devient `paid_at` quand ce paiement règle la facture, y compris un paiement unique du montant total. Aujourd'hui si omis. - `transaction_id` (string): Votre référence pour l'argent reçu, un numéro de virement par exemple. Conservée sur le paiement que la facture enregistre, que le Dashboard affiche dans son historique ; l'API ne la renvoie pas. - `payment_method` (string): Conservé de la même façon, pour vos dossiers. - `notes` (string): Conservées de la même façon, pour vos dossiers. Un `amount` inférieur au total est ajouté à `amount_paid` et fait passer le statut à `partial`. Rappelez l'endpoint pour l'échéance suivante. Les montants s'accumulent et la facture passe à `paid` avec un `paid_at` dès qu'ils atteignent le total. **Enregistrer la moitié d'un paiement reçu par virement bancaire** ```bash curl https://api.wajub.com/invoices/inv_LRQqYvlhrgUOE225KMKU/mark-paid \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 178875, "payment_date": "2026-09-20" }' ``` ```javascript const invoice = await wajub.invoices.markPaid('inv_LRQqYvlhrgUOE225KMKU', { amount: 178875, payment_date: '2026-09-20', }); ``` ```python invoice = wajub.invoices.mark_paid("inv_LRQqYvlhrgUOE225KMKU", { "amount": 178875, "payment_date": "2026-09-20", }) ``` ```php $invoice = $wajub->invoices->markPaid('inv_LRQqYvlhrgUOE225KMKU', [ 'amount' => 178875, 'payment_date' => '2026-09-20', ]); ``` ```go invoice, err := client.Invoices.MarkPaid(context.Background(), "inv_LRQqYvlhrgUOE225KMKU", map[string]any{ "amount": 178875, "payment_date": "2026-09-20", }, nil) ``` La facture doit être ouverte : envoyée, consultée, en retard ou partiellement payée. Un brouillon renvoie `400`, puisqu'il n'a été ni envoyé ni numéroté : envoyez-le d'abord. Une facture déjà `paid` renvoie aussi `400` et garde son `paid_at` ; de même pour une facture `cancelled` ou `refunded`, avec `400 This invoice cannot be marked as paid`, et pour un devis ou une estimation, avec `400 Only an invoice can be marked as paid.` Un `amount` nul ou négatif renvoie `422`. ## Le PDF Une fois envoyée, une facture a un PDF que toute personne qui détient son `id` peut télécharger, sans clé : la copie que votre client archive. Un brouillon renvoie `404`, comme sa page. ```text title="La facture en PDF" https://api.wajub.com/i/inv_LRQqYvlhrgUOE225KMKU/pdf ``` Il est rédigé dans la `language` de la facture. Ajoutez `?locale=fr` ou `?locale=en` pour l'obtenir dans l'autre langue. C'est le lien que propose la page de la facture : partagez-le comme vous partagez la page. ## Annuler une facture `POST /invoices/{id}/cancel` définit le statut sur `cancelled`, renseigne `cancelled_at` et ferme la page publique. Une facture déjà `paid`, `cancelled` ou `refunded` renvoie `400 This invoice cannot be cancelled`. Une facture partiellement payée ne peut plus être modifiée ni supprimée. L'annuler la clôt sans rembourser les fonds encaissés. Rembourser en totalité ce qui a été payé en ligne, avec les [remboursements](https://docs.wajub.com/fr/payments/refunds) sur les paiements sous-jacents, la fait passer à `refunded`, sauf si une part a été enregistrée avec `mark-paid`. - [Démarrage rapide](https://docs.wajub.com/fr/billing/invoice/quickstart): Émettez et suivez votre première facture de bout en bout. - [Factures récurrentes](https://docs.wajub.com/fr/billing/invoice/recurring): Ce que l'indicateur de récurrence configure ou non. - [Relances et suivi](https://docs.wajub.com/fr/billing/invoice/reminders): Quand votre client est relancé d'une facture impayée. - [Facturation et abonnements](https://docs.wajub.com/fr/billing): Les statuts, les transitions et les webhooks. --- # Démarrage rapide URL: https://docs.wajub.com/fr/billing/invoice/quickstart > Émettre une facture, ouvrir sa page de paiement et savoir quand elle a été payée. Quatre étapes suffisent pour passer de rien à de l'argent sur votre solde : créez le document, ouvrez sa page, transmettez l'URL au client, puis attendez le paiement. Rien ne se passe automatiquement entre ces étapes. > [!WARNING] > **Uniquement en live, et votre première facture est réelle** > > Les factures n'existent pas dans la sandbox. Toutes les routes `/invoices`, y compris `GET`, > répondent `403` avec `This feature is only available in live mode.` à une clé `sk_test.`. Vous ne > pouvez donc rien essayer au préalable. Émettez votre première facture à votre propre nom, pour un > petit montant. La fonctionnalité est Invoicing : **10 factures au total avec Pay as you go**, et > un nombre illimité à partir de Growth. ## 1. Créer le document Une facture est créée comme brouillon et le reste jusqu'à ce que vous la fassiez avancer. Sa création enregistre un document numéroté, rien de plus : aucun argent ne circule, aucun e-mail n'est envoyé et le client n'est informé de rien. Quatre champs sont obligatoires, mais la fiche d'un client n'en fait pas partie. Une facture est adressée à un nom. Vous pouvez donc facturer une personne qui ne vous a encore jamais payé. `POST /invoices` - `customer_name` (string, required): Nom de la personne à qui la facture est adressée. - `items` (array, required): Au moins une ligne, chacune avec `name`, `quantity` et `unit_price`. - `invoice_date` (string (date), required): Date imprimée sur le document. - `currency` (string, required): Code ISO 4217. Tous les montants de la facture utilisent cette devise. - `customer_email` (string): Adresse à laquelle `/send` envoie la facture et son PDF, et adresse utilisée pour son paiement et son reçu. Sans elle, `/send` répond `422`, sauf si `customer_id` désigne un client doté d'un e-mail ; une facture envoyée sans e-mail depuis le Dashboard voit sa page le demander au payeur. - `due_date` (string (date)): Égale ou postérieure à `invoice_date`. Détermine quand la facture devient en retard. - `accept` (object): Réduit les moyens de paiement proposés par la page de la facture, par `countries`, `channels`, `types` et `currencies`. Voir [Choisir ce qu'un paiement accepte](https://docs.wajub.com/fr/payments/payment-methods#choosing-what-a-payment-accepts). - `customer_id` (string): Associe un [client](https://docs.wajub.com/fr/payments/customers) existant, par son identifiant `cus_`. Ses informations sont copiées dans le document lors de sa création. La liste complète des champs, les taxes, les remises et le reste se trouvent sur la page [Factures](https://docs.wajub.com/fr/billing/invoice). Envoyez cette requête avec une clé secrète live. **Créer une facture** ```bash curl https://api.wajub.com/invoices \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: invoice-amina-september" \ -d '{ "customer_name": "Amina Traoré", "customer_email": "amina@example.com", "invoice_date": "2026-09-11", "due_date": "2026-09-25", "currency": "XAF", "items": [ { "name": "Consulting, September", "quantity": 3, "unit_price": 150000 } ] }' ``` ```javascript const invoice = await wajub.invoices.create({ customer_name: 'Amina Traoré', customer_email: 'amina@example.com', invoice_date: '2026-09-11', due_date: '2026-09-25', currency: 'XAF', items: [ { name: 'Consulting, September', quantity: 3, unit_price: 150000 }, ], }); console.log(invoice.id, invoice.total); ``` ```python invoice = wajub.invoices.create({ "customer_name": "Amina Traoré", "customer_email": "amina@example.com", "invoice_date": "2026-09-11", "due_date": "2026-09-25", "currency": "XAF", "items": [ { "name": "Consulting, September", "quantity": 3, "unit_price": 150000 }, ], }) print(invoice.id, invoice.total) ``` ```php $invoice = $wajub->invoices->create([ 'customer_name' => 'Amina Traoré', 'customer_email' => 'amina@example.com', 'invoice_date' => '2026-09-11', 'due_date' => '2026-09-25', 'currency' => 'XAF', 'items' => [ ['name' => 'Consulting, September', 'quantity' => 3, 'unit_price' => 150000], ], ]); echo $invoice->id; ``` ```go invoice, err := client.Invoices.Create(context.Background(), map[string]any{ "customer_name": "Amina Traoré", "customer_email": "amina@example.com", "invoice_date": "2026-09-11", "due_date": "2026-09-25", "currency": "XAF", "items": []map[string]any{ {"name": "Consulting, September", "quantity": 3, "unit_price": 150000}, }, }, nil) ``` La réponse est `201 Created`. Les totaux sont calculés à partir des lignes. `subtotal`, `total` et `amount_due` sont donc renseignés dans la réponse, même si vous ne les avez pas envoyés. ```json title="Réponse · 201 Created" { "code": 201, "status": "Created", "message": "Invoice created", "invoice": { "id": "inv_LRQqYvlhrgUOE225KMKU", "invoice_number": null, "status": "draft", "customer_name": "Amina Traoré", "invoice_date": "2026-09-11", "due_date": "2026-09-25", "currency": "XAF", "subtotal": 450000, "total": 450000, "amount_paid": 0, "amount_due": 450000, "sent_at": null, "paid_at": null } } ``` Conservez l'`id` : tous les appels suivants en ont besoin. `invoice_number` vaut encore `null`. La référence lisible imprimée sur le document est attribuée à l'étape suivante, selon la numérotation de votre compte, la même séquence que celle du Dashboard : `INV-` (ou le préfixe que vous avez choisi), l'année, puis un compteur qui repart à `0001` chaque année. ## 2. Ouvrir sa page de paiement Une facture au statut `draft` ne peut pas être payée : sa page ne s'ouvre pas. Seuls quatre statuts permettent le paiement : `sent`, `viewed`, `overdue` et `partial`. Un appel suffit pour la sortir du statut `draft`. `POST /invoices/{id}/send` **Ouvrir la facture au paiement** ```bash curl -X POST https://api.wajub.com/invoices/inv_LRQqYvlhrgUOE225KMKU/send \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` ```javascript const invoice = await wajub.invoices.send('inv_LRQqYvlhrgUOE225KMKU'); console.log(invoice.status); ``` ```python invoice = wajub.invoices.send("inv_LRQqYvlhrgUOE225KMKU") print(invoice["status"]) ``` ```php $invoice = $wajub->invoices->send('inv_LRQqYvlhrgUOE225KMKU'); echo $invoice['status']; ``` ```go invoice, err := client.Invoices.Send(context.Background(), "inv_LRQqYvlhrgUOE225KMKU", nil) if err != nil { log.Fatal(err) } log.Println(invoice["status"]) ``` La réponse est `200`, avec `status: "sent"`, `sent_at` horodaté et le `invoice_number` attribué. L'appel envoie aussi à `customer_email` un e-mail avec le lien de la facture et une copie PDF en pièce jointe. Le rappeler plus tard renvoie l'e-mail et renseigne de nouveau `sent_at`, sans changer le statut. L'appel refuse d'envoyer à personne. Sans `customer_email`, et sans `customer_id` dont le client a un e-mail, il répond `422` sur `customer_email` et la facture reste un brouillon. Une facture déjà `paid`, `cancelled` ou `refunded` répond `400`. ## 3. Transmettre l'URL L'e-mail ne suffit pas toujours : c'est peut-être par WhatsApp ou par SMS que vous joignez vraiment ce client. L'adresse à partager correspond à l'identifiant de la facture sur son propre domaine. ```text title="L'URL du client" https://invoice.wajub.com/inv_LRQqYvlhrgUOE225KMKU ``` Cette URL ne figure pas dans la réponse de l'API. Construisez-la à partir de l'`id` conservé. Seul le domaine peut varier : un marchand qui distribue ses factures depuis un domaine personnalisé et vérifié utilise ce domaine. Le Dashboard affiche l'adresse réelle sur la facture. La page qui s'ouvre est un checkout classique. Elle reprend votre identité visuelle, les lignes de la facture et les opérateurs disponibles pour sa devise. La première fois que le client l'ouvre, la facture passe automatiquement de `sent` à `viewed`. Si vous n'avez pas renseigné `customer_email`, `/send` refuse la facture : envoyez-la plutôt depuis le Dashboard, qui ouvre sa page sans envoyer d'e-mail. La page affiche alors au payeur un champ e-mail au-dessus du bouton de paiement et n'ouvre le paiement qu'une fois ce champ rempli. Cette adresse reçoit la confirmation du paiement et son reçu, et elle est inscrite sur la facture comme son `customer_email` (`invoice.updated` est envoyé) : les échéances suivantes et `/send` l'utilisent. ## 4. Savoir quand elle a été payée Une facture payée produit deux événements qui ne sont pas interchangeables. `payment.succeeded` représente l'argent. Il contient le montant, le canal et la référence du prestataire. C'est cet événement qui doit déclencher la livraison, car lui seul prouve que les fonds ont circulé. `invoice.updated` représente le document. Il est émis à chaque modification de la facture. Le paiement n'est qu'une de ces modifications. **`invoice.updated`**: Émis à chaque modification de la facture. Lisez `data.status` pour connaître laquelle. ```json title="invoice.updated" { "id": "evt_aio5DpN577tNU2vOxdmuZGhT", "event": "invoice.updated", "livemode": true, "created": "2026-09-11T15:42:10+00:00", "api_version": "2026-10-11", "pending_webhooks": 1, "request": { "id": null, "idempotency_key": null }, "data": { "id": "inv_LRQqYvlhrgUOE225KMKU", "invoice_number": "INV-2026-0001", "status": "paid", "currency": "XAF", "total": 450000, "amount_paid": 450000, "amount_due": 0, "paid_at": "2026-09-11T15:42:09+00:00" } } ``` Deux autres événements suivent l'argent du côté du document. `invoice.payment_succeeded` arrive pour chaque paiement effectué sur la page de la facture, échéance comprise, et `invoice.paid` une fois la facture réglée en totalité. Tous deux portent la facture, comme `invoice.sent` quand la facture est envoyée et `invoice.cancelled` quand elle est annulée. Il n'existe aucun `invoice.overdue` : pour celui-là, le statut du payload d'un `invoice.updated` vous indique la transition concernée. Et `payment.succeeded` désigne la facture payée dans son champ `invoice`. > [!NOTE] > **Livrez à partir du paiement, rapprochez à partir de la facture** > > Livrez l'achat du client à la réception de `payment.succeeded`. Utilisez `invoice.updated` pour > maintenir votre copie du document à jour. Faire l'inverse revient à agir selon un statut que le > marquage manuel comme payé peut également produire. ## Quand l'argent a été reçu ailleurs Espèces, virement bancaire ou paiement qui n'est jamais passé par Wajub : enregistrez-le sur le document au lieu de laisser la facture ouverte. `POST /invoices/{id}/mark-paid` N'envoyez aucun `amount` pour régler entièrement la facture. Si vous en envoyez un, supérieur à zéro, il est ajouté à `amount_paid`. La facture reste alors au statut `partial` jusqu'à ce que le total soit couvert. Un brouillon, une facture déjà payée, annulée ou remboursée refusent l'appel avec `400` ; un `amount` nul répond `422`. ## Les statuts et qui les attribue Vous ne pouvez définir que trois des huit statuts. Les autres résultent des actions du client ou de Wajub, pendant la nuit. Il est utile de le savoir avant de construire votre propre machine à états. | Statut | Signification | Défini par | | ----------- | ----------------------------------- | ------------------------------------------------------------------------ | | `draft` | Créée, non payable | Création | | `sent` | Payable, en attente | Votre appel `/send` | | `viewed` | Le client a ouvert la page | Le client, à la première ouverture | | `partial` | Une partie du total a été reçue | Un paiement ou votre appel `/mark-paid` | | `paid` | Entièrement réglée | Un paiement ou votre appel `/mark-paid` | | `overdue` | Échéance dépassée, toujours impayée | Wajub, pendant la nuit une fois `due_date` passée | | `cancelled` | Clôturée, plus payable | Votre appel `/cancel` | | `refunded` | Payée, puis remboursée | Des remboursements couvrant tous les paiements en ligne qui l'ont réglée | - [Factures](https://docs.wajub.com/fr/billing/invoice): Tous les champs, le calcul des totaux et les huit appels. - [Factures récurrentes](https://docs.wajub.com/fr/billing/invoice/recurring): Ce que fait aujourd'hui l'indicateur de récurrence, et ce qu'il ne fait pas. - [Relances et suivi](https://docs.wajub.com/fr/billing/invoice/reminders): Relancer une facture qui n'a plus donné signe de vie. - [Clients](https://docs.wajub.com/fr/payments/customers): Facturer la fiche d'un client plutôt qu'un simple nom. - [Référence API des factures](https://docs.wajub.com/fr/api/invoices): Tous les champs et les huit endpoints. --- # Factures récurrentes URL: https://docs.wajub.com/fr/billing/invoice/recurring > Ce que configure l'indicateur de récurrence, ce qui génère la facture suivante et ce qui ne le fait pas. Une facture récurrente est une facture classique que Wajub copie dans un nouveau brouillon à chaque cycle. Chaque copie doit encore être envoyée et réglée par le client : rien n'est débité automatiquement. ## Marquer une facture comme récurrente Il n'existe ni endpoint distinct ni ressource d'abonnement. Deux champs de l'appel de création classique couvrent toute la fonctionnalité. `POST /invoices` - `is_recurring` (boolean, default `false`): Marque cette facture comme celle que Wajub copie à chaque cycle. La première copie est due un intervalle après `invoice_date`. Seule une facture peut être récurrente : sur un devis ou une estimation, `true` répond `422`. - `recurring_interval` (enum): `daily`, `weekly`, `monthly`, `quarterly` ou `yearly`. Intervalle entre les copies. - `recurring_frequency` (enum): Accepté à la création comme autre nom de `recurring_interval`, avec les cinq mêmes valeurs. - `customer_id` (string): Obligatoire ici. Une facture récurrente sans fiche client ne génère jamais rien. Tout le reste de la facture, notamment les lignes, les totaux et les notes, fonctionne exactement comme sur une facture ponctuelle. **Une facture répétée chaque mois** ```bash curl https://api.wajub.com/invoices \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "customer_id": "cus_7Kq2mX9vL4tRb3nP8sZcWd1e", "customer_name": "Amina Traoré", "invoice_date": "2026-09-11", "currency": "XAF", "items": [ { "name": "Retainer", "quantity": 1, "unit_price": 250000 } ], "is_recurring": true, "recurring_interval": "monthly" }' ``` ```javascript const invoice = await wajub.invoices.create({ customer_id: 'cus_7Kq2mX9vL4tRb3nP8sZcWd1e', customer_name: 'Amina Traoré', invoice_date: '2026-09-11', currency: 'XAF', items: [{ name: 'Retainer', quantity: 1, unit_price: 250000 }], is_recurring: true, recurring_interval: 'monthly', }); ``` ```python invoice = wajub.invoices.create({ "customer_id": "cus_7Kq2mX9vL4tRb3nP8sZcWd1e", "customer_name": "Amina Traoré", "invoice_date": "2026-09-11", "currency": "XAF", "items": [{ "name": "Retainer", "quantity": 1, "unit_price": 250000 }], "is_recurring": True, "recurring_interval": "monthly", }) ``` ```php $invoice = $wajub->invoices->create([ 'customer_id' => 'cus_7Kq2mX9vL4tRb3nP8sZcWd1e', 'customer_name' => 'Amina Traoré', 'invoice_date' => '2026-09-11', 'currency' => 'XAF', 'items' => [ ['name' => 'Retainer', 'quantity' => 1, 'unit_price' => 250000], ], 'is_recurring' => true, 'recurring_interval' => 'monthly', ]); ``` ```go invoice, err := client.Invoices.Create(context.Background(), map[string]any{ "customer_id": "cus_7Kq2mX9vL4tRb3nP8sZcWd1e", "customer_name": "Amina Traoré", "invoice_date": "2026-09-11", "currency": "XAF", "items": []map[string]any{ {"name": "Retainer", "quantity": 1, "unit_price": 250000}, }, "is_recurring": true, "recurring_interval": "monthly", }, nil) ``` La réponse est la même que pour toute autre facture, avec `201 Created`, `status: "draft"`, les deux champs de récurrence et rien de plus. ```json title="Réponse · 201 Created, abrégée" { "invoice": { "id": "inv_LRQqYvlhrgUOE225KMKU", "invoice_number": null, "status": "draft", "currency": "XAF", "total": 250000, "is_recurring": true, "recurring_interval": "monthly" } } ``` > [!WARNING] > **recurring_frequency est un autre nom, pas un multiplicateur** > > `recurring_frequency: "monthly"` signifie chaque mois, pas un nombre de mois. La mise à jour ne > l'accepte pas : envoyez `recurring_interval` partout. ## Ce que l'API ne peut pas définir La récurrence possède d'autres réglages. Aucun n'est disponible dans l'API. Une fin après N occurrences, ou un intervalle de N mois, ne peut pas être défini par l'API. | Réglage | Rôle | Emplacement | | --------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------- | | Une date de début | Place la première copie à la date de votre choix, au lieu d'un intervalle après la facture | Le formulaire du Dashboard | | Une date de fin | Le dernier jour pour lequel un cycle est généré | Le formulaire du Dashboard | | Une fin après un nombre de copies | Arrête la génération après ce nombre de copies | Non disponible | | Un multiple de l'intervalle | Tous les deux mois, toutes les trois semaines | Non disponible | Une date de fin saisie dans le Dashboard est appliquée : le cycle qui tombe ce jour-là est le dernier généré, puis la série s'arrête définitivement. Une récurrence créée par l'API n'a aucune règle de fin : elle court jusqu'à ce que vous [l'arrêtiez](#stopping-a-recurrence). ## Ce qui est renvoyé et ce qui ne l'est pas Quatre champs de récurrence reviennent sur l'objet facture. | Champ | Sur une facture récurrente | Sur une copie générée | | -------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | `is_recurring` | `true` tant que la série court, `false` une fois arrêtée | `false` : une copie ne génère rien | | `recurring_interval` | `daily`, `weekly`, `monthly`, `quarterly` ou `yearly` | Celui du modèle, recopié | | `next_invoice_date` | La date de la prochaine copie, `YYYY-MM-DD`. `null` une fois la série arrêtée ou la facture annulée | `null` | | `recurring_parent` | `null` | L'`id` de la facture récurrente dont elle a été générée | Une copie est donc la facture dont `recurring_parent` est renseigné. La règle de fin ne figure pas dans la réponse, et `GET /invoices` n'a pas de filtre de récurrence, contrairement à la liste du Dashboard. ## Déroulement d'un cycle La première copie est due un intervalle après l'`invoice_date` de la facture, jamais dans le passé : une facture antidatée ne produit donc pas les cycles écoulés avant qu'elle soit récurrente. Un cycle n'est jamais généré deux fois, même pour une série désactivée puis réactivée. Une copie ne peut pas devenir récurrente elle-même (`422`), et le duplicata d'une facture récurrente est un simple brouillon, qui ne se répète que si vous le décidez. À la date de chaque cycle, Wajub copie chaque facture récurrente non annulée, sauf si sa date de fin est passée ou si votre plan n'inclut pas la fonctionnalité. | La copie hérite | La copie a en propre | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Les lignes, avec leurs quantités, prix et taxes | Aucun `invoice_number` avant son envoi, comme tout brouillon | | La devise et la remise globale de la facture | `invoice_date`, définie sur la date du cycle arrivé à échéance | | Les notes, les conditions, le pied de page et les instructions de paiement | `due_date`, trente jours plus tard | | Le modèle, la langue et les réglages d'affichage | Le bloc client, relu depuis la fiche du client | | Les moyens de paiement acceptés | `is_recurring: false`. Une copie est une facture ordinaire et ne génère jamais ses propres copies | Chaque cycle produit exactement une copie. Une série mensuelle, trimestrielle ou annuelle ne saute jamais un mois : un mois après le 31 janvier, c'est le 28 février, et la série continue à partir du 28\. Les dates des cycles sont en UTC. Deux de ces points méritent votre attention. Le bloc client est repris depuis la fiche actuelle à chaque cycle. Une adresse ou un nom d'entreprise corrigé sur la fiche apparaît donc dans le document suivant sans modifier les précédents. Par ailleurs, `due_date` est toujours fixée à trente jours après la date de la copie, quelles que soient les conditions de la facture d'origine. > [!CAUTION] > **Une copie est un brouillon, pas un débit** > > Chaque facture générée arrive au statut `draft`, avec `amount_paid` remis à zéro. Elle n'est ni > ouverte au paiement, ni envoyée par e-mail, ni payée, et elle reste un brouillon après son > échéance : seule une facture envoyée passe `overdue`. Quelqu'un doit encore appeler `/send` et > transmettre l'URL à chaque cycle, exactement comme pour une facture ponctuelle. La récurrence vous > évite seulement de rédiger le document. > [!WARNING] > **Sans fiche client, aucune copie** > > Une facture sans `customer_id` ne génère jamais rien. Une facture adressée uniquement à un > `customer_name`, ce qui est parfaitement valide pour une facture ponctuelle, ne produit aucune > copie et ne signale rien. > Envoyez `customer_id` lorsque vous définissez `is_recurring`. ## Arrêter une récurrence Une date de fin, quand le Dashboard en a enregistré une, arrête la série d'elle-même. Sinon, vous l'arrêtez, à tout moment et quel que soit le statut de la facture, payée comprise. `POST /invoices/{id}/stop-recurring` ```bash title="Arrêter la série et conserver le document" curl -X POST https://api.wajub.com/invoices/inv_LRQqYvlhrgUOE225KMKU/stop-recurring \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` L'appel ne prend pas de corps. La facture revient avec `is_recurring: false` et `next_invoice_date: null`, rien d'autre ne change, et `invoice.updated` est émis. Aucune copie n'est générée après cet appel, et les copies déjà générées restent telles quelles : chacune est une facture à part entière, à envoyer, annuler ou supprimer comme une autre. Arrêter une série déjà arrêtée répond `200` sans rien changer. Dans le Dashboard, la même action s'appelle **Arrêter la récurrence**, dans le menu d'actions de la facture. Appelez-le sur la facture récurrente, pas sur une copie. Une copie n'a pas de série propre : l'appel y répond `400`, avec l'identifiant du modèle dans `recurring_parent` : ```json title="Réponse · 400 sur une copie générée" { "code": 400, "status": "Bad Request", "message": "This invoice was generated by a recurring invoice. Stop the series on that one.", "recurring_parent": "inv_LRQqYvlhrgUOE225KMKU" } ``` Deux autres appels touchent la série, et tous deux sont plus restreints. `PUT /invoices/{id}` avec `is_recurring: false` l'arrête aussi, mais seulement tant que la facture est un brouillon, puisque seul un brouillon est modifiable. Annuler la facture arrête aussi la génération, et efface `next_invoice_date`, mais l'annulation est refusée une fois la facture payée. ## Coût selon le plan La récurrence nécessite la fonctionnalité Facturation récurrente, disponible à partir de **Growth**. Le Dashboard refuse d'enregistrer une facture récurrente sans cette fonctionnalité. Sans le plan, la génération est ignorée et le document n'est pas modifié. Après le passage à un plan inférieur, la génération reprend donc automatiquement si le compte revient à un plan supérieur, avec les cycles arrivés à échéance entre-temps. `POST /invoices` ne vérifie pas le plan. La création d'une facture récurrente par l'API réussit avec tous les plans, mais ne génère simplement rien. - [Factures](https://docs.wajub.com/fr/billing/invoice): Le document, sa page de paiement et le reste de son cycle de vie. - [Démarrage rapide](https://docs.wajub.com/fr/billing/invoice/quickstart): Émettre une facture et obtenir son paiement, du début à la fin. - [Relances et suivi](https://docs.wajub.com/fr/billing/invoice/reminders): Relancer une facture d'un cycle restée impayée. - [Abonnements](https://docs.wajub.com/fr/billing/subscriptions): Pourquoi le débit récurrent sans intervention n'est pas encore un produit. - [Référence API des factures](https://docs.wajub.com/fr/api/invoices): Tous les champs et les neuf endpoints. --- # Relances et suivi URL: https://docs.wajub.com/fr/billing/invoice/reminders > Quand Wajub relance votre client d'une facture impayée, et comment assurer le suivi depuis votre propre code. Wajub relance par e-mail votre client d'une facture impayée, avant et après son échéance, que vous ayez envoyé la facture par l'API ou depuis le Dashboard. Les relances sont actives tant que vous ne les désactivez pas. ## Quand partent les relances Chaque relance tombe un jour compté à partir du `due_date` de la facture. Tant que vous n'en choisissez pas d'autres, ceux d'un nouveau compte sont : | Relance | Jour | | --------------------- | -------------- | | Une semaine avant | `due_date` − 7 | | Trois jours avant | `due_date` − 3 | | La veille | `due_date` − 1 | | Un jour de retard | `due_date` + 1 | | Une semaine de retard | `due_date` + 7 | **Paramètres → Facture → Rappels** dans le Dashboard montre les jours de votre compte, et choisit d'autres jours, 1, 3, 7 ou 14 jours avant l'échéance, le jour même, ou 1, 3, 7 ou 14 jours après, ou désactive les relances. Le choix vaut pour toutes les factures du compte : aucune facture ne les désactive à elle seule, ni par l'API ni ailleurs. Une relance dont le jour tombe le jour de l'envoi de la facture ou avant est sautée : une facture envoyée après son échéance n'est relancée que les jours encore à venir. Une relance ne tombe jamais un jour où le client a déjà été relancé. Quand plusieurs relances sont dues en même temps, seule la plus récente part, et aucune ne part plus d'une semaine après son jour. ## Qui reçoit quoi Une facture est relancée quand elle a un `due_date`, qu'elle a été envoyée (`sent`, `viewed`, `partial` ou `overdue`) et qu'il reste quelque chose à payer. L'e-mail part au client que désigne `customer_id`, sinon à `customer_email` ; une facture sans l'un ni l'autre n'est pas relancée. Les brouillons, les devis et les estimations ne le sont jamais. La relance est rédigée dans la `language` de la facture, avec le PDF en pièce jointe. Elle indique le numéro de la facture, le montant restant dû et l'échéance, avec un bouton vers la page de la facture. Une facture partiellement payée est relancée pour ce qu'il reste. Une relance n'envoie aucun webhook et ne change rien à la facture. ## Ce qui arrête les relances Le paiement, l'annulation ou le remboursement de la facture, ou plus rien à payer. Une relance sur le point de partir quand la facture a été payée n'est pas envoyée. ## Effectuer le suivi depuis votre propre code Pour assurer le suivi sur un autre canal, comme le SMS ou WhatsApp, ou selon votre propre calendrier, vous disposez de deux signaux qui fonctionnent différemment. Le premier est la liste, filtrée sur les montants encore dus. **Toutes les factures échues avec un montant encore dû** ```bash curl "https://api.wajub.com/invoices?status=overdue&payment_status=unpaid" \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` ```javascript const { data } = await wajub.invoices.list({ status: 'overdue', payment_status: 'unpaid', }); for (const invoice of data) { console.log(invoice.invoice_number, invoice.amount_due, invoice.customer_email); } ``` ```python result = wajub.invoices.list({"status": "overdue", "payment_status": "unpaid"}) for invoice in result.data: print(invoice["invoice_number"], invoice["amount_due"]) ``` ```php $result = $wajub->invoices->list([ 'status' => 'overdue', 'payment_status' => 'unpaid', ]); foreach ($result->data as $invoice) { echo $invoice['invoice_number'], ' ', $invoice['amount_due'], PHP_EOL; } ``` ```go result, err := client.Invoices.List(context.Background(), map[string]any{ "status": "overdue", "payment_status": "unpaid", }) if err != nil { log.Fatal(err) } for _, invoice := range result.Data { log.Println(invoice["invoice_number"], invoice["amount_due"]) } ``` `payment_status` accepte `unpaid`, `partially_paid` ou `fully_paid`. Il filtre selon ce qui a réellement été reçu, pas selon le libellé du statut. `due_date_from` et `due_date_to` délimitent la période lorsque vous cherchez les factures échues cette semaine plutôt que leur totalité. > [!NOTE] > **Le statut overdue peut avoir un jour de retard** > > Rien ne fait passer une facture à `overdue` à minuit. Ce passage a lieu pendant la nuit une fois > `due_date` passée. Une facture arrivée à échéance ce matin reste donc au statut `sent` jusqu'au lendemain. > Pour faire la distinction le jour même, comparez vous-même `due_date` à la date actuelle au lieu > de filtrer sur le statut. Le second signal est le webhook. Il présente une lacune dont vous devez tenir compte. **`invoice.updated`**: Émis après les modifications effectuées par l'API, lors de la première consultation et lors d'un paiement. Lisez `data.status`. ```json title="invoice.updated" { "id": "evt_aio5DpN577tNU2vOxdmuZGhT", "event": "invoice.updated", "livemode": true, "created": "2026-09-25T09:12:44+00:00", "api_version": "2026-10-11", "pending_webhooks": 1, "request": { "id": null, "idempotency_key": null }, "data": { "id": "inv_LRQqYvlhrgUOE225KMKU", "invoice_number": "INV-2026-0001", "status": "partial", "currency": "XAF", "total": 450000, "amount_paid": 150000, "amount_due": 300000, "due_date": "2026-09-25" } } ``` Cette lacune concerne le statut `overdue`. Les factures passent à `overdue` pendant la nuit, et ce changement n'envoie aucun webhook. Vous devez rechercher cette situation, elle ne vous est pas signalée. Le modèle qui fonctionne consiste à conserver votre propre liste de factures ouvertes, à la contrôler selon votre propre calendrier et à envoyer vous-même une relance sur le canal que le client consulte vraiment. Le message doit contenir l'URL de paiement, que vous reconstruisez à partir de l'identifiant de la facture. ```text title="Contenu de votre relance" https://invoice.wajub.com/inv_LRQqYvlhrgUOE225KMKU ``` - [Factures](https://docs.wajub.com/fr/billing/invoice): Le document, sa page de paiement et son cycle de vie complet. - [Démarrage rapide](https://docs.wajub.com/fr/billing/invoice/quickstart): Émettre une facture et obtenir son paiement, du début à la fin. - [Factures récurrentes](https://docs.wajub.com/fr/billing/invoice/recurring): Ce que configure l'indicateur de récurrence, et ce qu'il ne fait pas. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): La place d'invoice.updated aux côtés de payment.succeeded. - [Référence API des factures](https://docs.wajub.com/fr/api/invoices): Tous les filtres de l'endpoint de liste. --- # Capacités du compte URL: https://docs.wajub.com/fr/sync/account-types > Les sept capacités, ce que chacune atteint et le calcul de votre commission. ## 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. | Mode | Le marchand | L'argent | À utiliser pour | | --------------------- | --------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------- | | `direct` (par défaut) | Un compte Wajub complet qu'il pilote lui-même | Rail Wajub, ou ses propres contrats providers | Les marchands déjà équipés | | `lite` | Un portail hébergé léger | Rail Wajub, toujours | Les petits vendeurs, le cas courant | | `relay` | Aucun compte Wajub : son portefeuille vérifié | Le vôtre : vous encaissez et Wajub verse à chaque vendeur ce qui lui revient | Les marketplaces *merchant of record* | 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`, `error_code: account_not_on_rail`), et refuse la carte, que le rail n'encaisse pas encore (`422` avec `error_code: card_not_available`, [La réserve carte](https://docs.wajub.com/fr/sync/payouts#the-card-reserve)) ; - une connexion `relay` n'a pas d'onboarding : il n'y a aucun compte marchand à revendiquer. Elle se crée avec `POST /accounts` et le portefeuille du vendeur, n'a pas de lien d'autorisation (`authorization_url` vaut `null`, `POST /accounts/{id}/token` répond `422`) ni de date d'invitation, et devient `active` dès que l'opérateur a confirmé le nom du portefeuille. Les ventes arrivent sur votre solde, et Wajub verse à chaque vendeur ce qui lui revient. [Relay](https://docs.wajub.com/fr/sync/relay) > [!WARNING] > **Ce ne sont pas des paliers Standard, Express ou Custom** > > Le mode n'est pas un niveau de service et ne conditionne aucune fonctionnalité. Deux connexions de > modes différents peuvent porter exactement les mêmes capacités et la même tarification. ## 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`. | Capacité | Fonction désignée | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `read` | Lire les événements de ce que la connexion a apporté | | `payments` | Lancer des paiements et des liens de paiement | | `withdrawals` | Verser des fonds, et gérer les bénéficiaires payés. Pas sur une connexion `lite` : seul Wajub paie un vendeur Lite, elle est donc refusée avec `400` `capability_not_allowed_for_mode`, et un versement ou une écriture de bénéficiaire sous `X-Sync` sur une connexion Lite répond `403` avec le même code | | `refunds` | Émettre des remboursements | | `disputes` | Répondre aux litiges | | `customers` | Gérer des clients | | `invoices` | Émettre des factures | Toute autre capacité répond `422` à la création ou à la modification d'une connexion. ## 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`. | La requête porte sur | Capacité vérifiée | | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `/payments`, `/links` | `payments` | | `/invoices` | `invoices` | | `/customers`, `/customers/{id}/tax_ids` | `customers` | | `/refunds` | `refunds` | | `GET /payments/{id}/refunds`, `POST /payments/{id}/close` avec `outcome: refund` | `payments` et `refunds` | | `/disputes` | `disputes` | | `/transfers`, `/beneficiaries`, `/identity` | `withdrawals` | | `/`, `/providers`, `/events` | `read` | | `/channels`, `/countries`, `/currencies` | aucune : les catalogues répondent la même chose à tout le monde | | `/balance`, `/webhooks`, `/shield`, `/tax` | ne peuvent pas être appelées avec `X-Sync` : elles concernent tout le compte du marchand | | `/accounts` | ne peuvent pas être appelées avec `X-Sync` : elles sont les vôtres | 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é. | Ressource | Ce que la plateforme atteint | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/payments`, `/refunds` | Uniquement ceux qui portent cette connexion | | `/disputes` | Uniquement les litiges sur les paiements de cette connexion | | `/links`, `/invoices` | Uniquement ceux créés avec le `X-Sync` de cette connexion | | `/beneficiaries` | Uniquement ceux créés avec le `X-Sync` de cette connexion, y compris un bénéficiaire fourni directement dans un transfert | | `/transfers` | Uniquement les versements lancés par cette connexion, et seulement vers ses propres bénéficiaires | | `/customers`, `/customers/{id}/tax_ids` | Les clients vus sur les paiements de cette connexion, et ceux qu'elle a créés ou désignés par e-mail ou téléphone, sauf si le marchand lui en a retiré l'accès ; sans les notes, le motif de blocage ni les metadata du marchand | | `/events` | Uniquement les événements des paiements, remboursements, transferts, litiges, liens, factures et bénéficiaires ci-dessus | 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 et l'utiliser sur ses paiements et ses factures, et le marchand en voit le résultat. Un client que la plateforme a créé est le sien à gérer : elle peut le modifier et le bloquer. Sur un client que le marchand avait déjà, une modification ne remplit que les champs que le marchand a laissés vides, et le bloquer, le débloquer, l'activer, le désactiver ou supprimer un numéro fiscal répond `403`. Plusieurs connexions peuvent atteindre le même client. La plateforme ne peut pas supprimer un client : `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. Ce retrait dure jusqu'à ce que le marchand rétablisse l'accès : la plateforme n'atteint plus le client, pas même sur ses propres paiements passés, le désigner à nouveau par son e-mail ou son téléphone ne le lui rend pas, et ses nouveaux paiements pour cet e-mail ou ce téléphone sont créés sans client. 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 forfait), 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é. `POST /events/{id}/resend` avec `X-Sync` envoie l'événement à **vos** endpoints, jamais à ceux du marchand, avec `data.account`. ## 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. | Ensuite | Ce qui se passe | | ----------------------- | ---------------------------------------------------------------------------------------------------- | | Le marchand accepte | Les nouvelles conditions s'appliquent à partir de cet instant, et `account.change_accepted` est émis | | Le marchand refuse | Rien ne change, et `account.change_declined` est émis | | Vous proposez à nouveau | La nouvelle proposition remplace celle encore sur la table | 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. - `percentage_fee` (number): Pourcentage du montant du paiement, entre 0 et 100, avec jusqu'à quatre décimales. - `fixed_fee` (number): Montant fixe ajouté au pourcentage, dans les unités principales de la devise de la règle. - `min_fee` (number): Plancher. Des frais calculés inférieurs à cette valeur sont relevés jusqu'à celle-ci. - `max_fee` (number): Plafond. Des frais calculés supérieurs à cette valeur sont ramenés à celle-ci. - `currency` (string): Code à trois lettres de la devise dans laquelle les frais sont exprimés. Obligatoire dès que vous définissez fixed_fee, min_fee ou max_fee. 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`. | Étape | Déroulement | | ----- | -------------------------------------------------------------------------------------------------- | | 1 | Le paiement réussit et possède une connexion | | 2 | La tarification de la connexion s'applique | | 3 | La devise des frais est le `currency` de la règle, ou celle du paiement si la règle n'en a pas | | 4 | Le pourcentage et les frais fixes sont additionnés, puis limités par `min_fee` et `max_fee` | | 5 | Des frais nuls ne sont pas prélevés | | 6 | Les frais sont prélevés une seule fois pour le paiement | | 7 | Le montant quitte le solde du marchand et arrive sur le vôtre, sous la rétention propre à la vente | Un paiement porte au plus une commission. 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. | Politique | Au remboursement | | ---------------------- | ------------------------------------------------------------------------------------ | | `prorata` (par défaut) | La commission est rendue au prorata du montant remboursé | | `full` | La totalité de la commission est rendue dès le premier remboursement, partiel ou non | | `none` | Rien n'est rendu ; le marchand porte seul le remboursement | 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 la rend selon la même politique : vous pouvez vérifier ce que verront vos marchands. La réserve, la couverture après un remboursement et le recouvrement tournent aussi en sandbox ([Tout essayer en sandbox](https://docs.wajub.com/fr/sync/payouts#trying-it-all-in-sandbox)) ; seules les commissions qu'un marchand doit lorsqu'il encaisse sur son propre contrat n'existent qu'en live. > [!NOTE] > **La devise de la règle indique l'unité, pas un filtre** > > `currency` indique la devise des frais, pas les paiements auxquels la règle s'applique. Des frais > fixes de 500 XAF sur un paiement en NGN sont convertis au taux actif. Une deuxième conversion a > lieu si le solde de votre plateforme utilise une troisième devise. Les `metadata` des frais > enregistrent les deux taux. ## 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. > [!WARNING] > **La tarification aussi demande le consentement** > > Comme pour les capacités, la tarification d'un marchand déjà connecté se propose au lieu de se > modifier : `PUT` répond `202` et le marchand décide. Définissez la commission souhaitée avant > d'envoyer le lien d'autorisation, et vous n'aurez jamais à la demander. ## Ce qui reste librement modifiable Deux champs survivent à l'acceptation sans l'accord du marchand, et seulement ces deux-là. | Champ | Pourquoi il reste ouvert | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `callback` | La page vers laquelle le marchand est renvoyé après avoir accepté, et l'origine que doit partager un `redirect_uri` sur le lien d'autorisation. En HTTPS uniquement (`http://localhost` et `http://127.0.0.1` avec une clé sandbox), sinon `422`. Aucun événement n'y est envoyé : les événements d'une connexion vont à vos [endpoints de webhook](https://docs.wajub.com/fr/developer-tools/webhooks/events#accounts-for-sync-platforms) | | `payment_status` | `active` ou `suspended`, votre propre interrupteur pour autoriser les débits sur la connexion. `active` répond `409` tant que la vérification du marchand est en cours ou refusée | 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. - [Sync](https://docs.wajub.com/fr/sync): La nature d'une connexion et ses limites. - [Démarrage rapide](https://docs.wajub.com/fr/sync/quickstart): Créer une connexion et y recevoir votre premier paiement. - [Intégration des marchands](https://docs.wajub.com/fr/sync/onboarding): Le cycle de vie, le lien d'autorisation et les statuts. - [Référence API des sous-comptes](https://docs.wajub.com/fr/api/subaccounts): La spécification de l'endpoint. --- # Analyses URL: https://docs.wajub.com/fr/sync/analytics > Le volume de vos vendeurs, la commission que vous gardez, ce que vous risquez de perdre et ce que vos vendeurs ont reçu, dans le Dashboard et par l'API. Combien vos vendeurs ont-ils vendu, combien avez-vous gardé, combien pourrait vous revenir à la charge, et combien Wajub leur a-t-il versé ? **Sync, Analyses** dans le Dashboard et `GET /sync/metrics` répondent avec les mêmes chiffres, pour une période comparée à la période de même longueur juste avant. ## D'où viennent les chiffres Rien n'est estimé : chaque montant est une ligne que Wajub a écrite quand l'argent a bougé. | Chiffre | Compté à partir de | Rangé dans la période par | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------- | | Volume, vente d'un vendeur | Un paiement fait avec `X-Sync` sur un de vos comptes, `succeeded`, `refunded` ou `partially_refunded`, son montant brut | Sa date de crédit | | Volume, part d'un paiement partagé | Une part passée à son vendeur ; une part encore en attente ne compte pas | Sa date de passage | | Commission prise | La commission de la vente, de la part, ou celle qu'a enregistrée le dû d'un vendeur Relay | Sa date de prélèvement | | Commission rendue | Rendue sur un remboursement ou un litige perdu | Sa date de retour | | Abandonnée | Ce que votre politique demandait de rendre, moins ce que votre solde a permis | Sa date de retour | | Commission nette | Prise moins rendue | | | Taux effectif | Commission nette sur le volume de la même devise, en pourcentage | | | Versé | Les versements de Wajub à vos vendeurs qui ont réussi | Leur date de valeur | - **Les devises ne s'additionnent jamais.** Chaque chiffre est par devise. Les chiffres d'en-tête sont dans la devise qui a le plus de volume sur la période (`currency`). - Une commission peut être dans une autre devise que sa vente : elle compte dans sa propre devise, et le taux effectif ne rapproche que des montants de même devise. - Un remboursement d'une vente Relay réduit le dû du vendeur et sort de votre solde : aucune ligne de commission « rendue » n'est écrite pour lui, donc aucune n'est comptée. - Les **vendeurs actifs** sont les comptes avec au moins une vente ou une part sur la période. Le **taux de litige** rapporte les litiges ouverts sur la période sur les ventes de vos vendeurs aux ventes de la période faites avec `X-Sync` : les litiges d'un paiement partagé sont les vôtres. ## Ce que vous voyez | Bloc | Dit | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Volume | Par devise et par mode (`direct`, `lite`, `relay`), ventes, vente moyenne, part passée par les paiements partagés | | Commission | Prise, rendue, abandonnée, nette, taux effectif, par mode | | Exposition et risque | Votre [plafond de versement](https://docs.wajub.com/fr/sync/payouts#your-exposure-cap) utilisé, les réserves de vos vendeurs (la réserve Lite, et la [réserve carte](https://docs.wajub.com/fr/sync/payouts#the-card-reserve) des ventes par carte de vos vendeurs Lite et Relay), les ventes [bloquées jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds) et celles libérées d'elles-mêmes sous 7 jours, les remboursements que vous avez couverts et ce qui est revenu, vos vendeurs par [niveau de risque](https://docs.wajub.com/fr/sync/seller-risk) et gelés, les litiges en cours et le taux de litige | | Versements | Versé sur la période, en cours d'envoi, dû à vos vendeurs Relay, sur les soldes de vos vendeurs Lite, et les vendeurs dont les versements sont retenus, par raison | | Vendeurs | Les dix premiers par volume, par commission nette, et les dix plus risqués | Dans le Dashboard, la période est de 7, 30 ou 90 jours, 12 mois, ou des jours que vous choisissez, dans les jours de votre navigateur ; le graphique montre la période précédente en pointillés. Les membres qui peuvent voir les versements l'ouvrent. Quand les chiffres ne peuvent pas être lus pour un moment, la page le dit, avec **Réessayer**. ## Par l'API ```bash title="Les 90 derniers jours" curl "https://api.wajub.com/sync/metrics?period=90d" \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` | Règle | | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Clé | La vôtre, jamais avec `X-Sync` (`403`). Sync dans votre forfait, sinon `403 feature_not_in_plan` | | `period` | `7d`, `30d` (par défaut), `90d` ou `12m` (365 jours, le graphique par mois). Une autre valeur : `422` | | Jours | UTC, aujourd'hui compris | | Sandbox | Une clé de test lit la sandbox : `sandbox: true`, `risk.exposure` est vide, et les soldes de sandbox de vos vendeurs Lite sont entièrement en `lite_available` (`lite_pending` vaut 0) | | Fraîcheur | Ce qui s'est passé sur la période (ventes, commission, versements faits, litiges ouverts, couvertures) compte tout jusqu'à `as_of`, en général une à deux minutes avant l'appel. Ce qui est en cours (réserves, ventes bloquées, litiges ouverts, versements en route, ce qui est dû à vos vendeurs et ce qu'ils détiennent, exposition) est lu au moment du calcul. Dans les deux cas, la réponse est gardée cinq minutes | | Limite | 10 appels par minute par plateforme et par environnement, en plus de la limite de votre forfait : `429` au-delà | ```json title="Réponse · 200 OK, abrégée" { "data": { "period": { "start": "2026-10-22T00:00:00+00:00", "end": "2026-11-20T23:59:59+00:00", "previous_start": "2026-09-22T00:00:00+00:00", "days": 30 }, "sandbox": false, "as_of": "2026-11-20T23:58:00+00:00", "currency": "XAF", "volume": { "active_sellers": 4, "previous_active_sellers": 1, "currencies": [ { "currency": "XAF", "amount": 49000, "previous_amount": 4000, "change_percent": 1125, "sales": 5, "average": 9800, "shared_amount": 6000, "shared_percent": 12.24 } ] }, "commission": [ { "currency": "XAF", "taken": 2450, "returned": 300, "forgone": 70, "net": 2150, "take_rate": 4.39 } ], "risk": { "reserve": [ { "currency": "XAF", "held": 4000, "next_release_at": "2026-11-30T10:00:00+00:00", "card": { "held": 1500, "sales": 3, "next_release_at": "2027-02-18T10:00:00+00:00" } } ], "sellers": { "scored": 3, "elevated": 1, "high": 1, "frozen": 1, "high_not_frozen": 1 }, "disputes": { "open": 1, "opened": 1, "sales": 4, "rate": 25 } }, "payouts": { "currencies": [ { "currency": "XAF", "paid": 11000, "payouts": 2, "in_flight": 2000, "relay_payable": 7600, "lite_available": 12000 } ], "held": [ { "reason": "frozen", "sellers": 1 } ] }, "sellers": { "currency": "XAF", "by_volume": [], "by_commission": [], "by_risk": [] } } } ``` Les montants sont en unités majeures ; les pourcentages sur 100 avec deux décimales, `change_percent` avec une. Un pourcentage vaut `null` quand il n'y a rien à comparer : une période précédente à zéro, aucun volume, aucune vente. `payouts.held[].reason` vaut `frozen`, `new_seller`, `exposure_cap`, `approval_withdrawn`, `insufficient_balance` ou `identity_required`. Dans `sellers`, `connected: false` signale un compte déconnecté ou supprimé depuis, et `risk_score` vaut `null` pour un vendeur jamais évalué. Dans `risk.reserve`, `held` et `next_release_at` comprennent la réserve carte, et `card` la donne à part : ce que gardent les ventes par carte de vos vendeurs, combien de ventes, et sa prochaine libération. [La réponse complète](https://docs.wajub.com/fr/api/subaccounts/metrics) ### Appelez-la en tâche de fond Toute période répond vite, mais appelez cette route depuis une tâche programmée de votre côté, toutes les cinq minutes au plus, et gardez la réponse chez vous : pas à chaque affichage de page. | Réponse | Quand | Que faire | | -------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | `429` avec `error_code: metrics_busy` | Un autre appel calcule les mêmes chiffres, et ils n'étaient pas prêts au bout de quelques secondes | Réessayez après `Retry-After` | | `429` sans `error_code` | Plus de 10 appels dans la minute | Attendez la minute suivante | | `503` avec `error_code: metrics_unavailable` | Les chiffres de la période ne peuvent pas être lus pour un moment | Réessayez après `Retry-After`, pas en boucle | | `503` avec `error_code: metrics_timeout` | Les chiffres n'ont pas pu être calculés à temps | Réessayez plus tard, ou demandez une période plus courte | Un `503` n'est jamais une réponse partielle : les chiffres que vous recevez sont toujours complets jusqu'à `as_of`. - [Rapports et relevés](https://docs.wajub.com/fr/sync/reports): Le même grand livre, ligne à ligne, en CSV, Excel ou PDF. - [Risque vendeur](https://docs.wajub.com/fr/sync/seller-risk): Score, délai des nouveaux vendeurs et gel. - [Lire les chiffres de votre plateforme](https://docs.wajub.com/fr/api/subaccounts/metrics): La spécification de l'endpoint. --- # Litiges sur les ventes de vos vendeurs URL: https://docs.wajub.com/fr/sync/disputes > Laissez un vendeur Lite répondre à un litige sur sa propre vente, avec sa preuve de livraison, et complétez sa réponse par l'API. Un litige sur une vente faite avec `X-Sync` est un litige du compte du vendeur. C'est souvent lui qui détient la preuve : le bon de livraison, les messages échangés avec l'acheteur. Avec Sync, un vendeur Lite peut répondre depuis son portail ou depuis le [composant embarqué](https://docs.wajub.com/fr/sync/embedded-components) `disputes`, et vous en êtes prévenu. ## Qui répond Chaque connexion porte `dispute_handling` : | Valeur | Qui répond | Par défaut | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `both` | Le vendeur envoie ses preuves ; vous en êtes prévenu et pouvez les compléter par l'API. Le vendeur peut encore modifier sa réponse jusqu'à 24 heures avant l'échéance | `lite` | | `seller` | Le vendeur répond ; sa réponse est **définitive** une fois envoyée | | | `platform` | Vous seul, par l'API. Le vendeur voit le litige, en lecture | `relay`, et sa seule valeur : un vendeur Relay n'a pas d'espace d'où répondre | **Vous pouvez toujours répondre par l'API avec `X-Sync`**, quelle que soit la valeur. Un marchand `direct` répond depuis son propre Dashboard : le réglage est refusé pour lui. Un [paiement partagé](https://docs.wajub.com/fr/sync/split-payments#one-payment-several-sellers) est le vôtre : ses litiges aussi. Réglez-le avec `POST /accounts`, ou changez-le tout de suite avec `PUT /accounts/{id}` ; une réponse déjà envoyée par le vendeur reste dans le litige. ```bash title="Le vendeur répond seul" curl -X PUT https://api.wajub.com/accounts/acc_Gt6yU3nE8rM1kS5vX9bQ \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{"dispute_handling":"seller"}' ``` | `error_code` | Statut | Quand | | -------------------------------- | ------ | -------------------------------------------------------------------------------- | | `dispute_handling_not_available` | `400` | `seller` ou `both` sur un compte `relay`, ou toute valeur sur un compte `direct` | | | `422` | Une valeur inconnue (`errors.dispute_handling`) | ## Ce que fait le vendeur 1. **Il prépare un brouillon** Une pièce par type de preuve : `proof_of_delivery`, `customer_communication`, `receipt`, `product_description`, `refund_policy` ou `other`. Un texte de 2 000 caractères au plus, un fichier, ou les deux. Rien n'atteint le litige tant qu'il ne l'a pas envoyé. 2. **Il joint des fichiers** PDF, JPG ou PNG seulement, 5 Mo au plus. Le contenu est contrôlé : un script déguisé en PDF ou en image est refusé. 3. **Il l'envoie** Chaque pièce pas encore envoyée entre dans le litige, le litige passe `under_review`, et vous recevez `account.dispute_evidence_submitted`. **24 heures avant l'échéance**, le vendeur ne peut plus écrire. Ce qu'il a enregistré sans l'envoyer est **envoyé pour lui**, et une réponse `both` devient définitive ; s'il n'a rien écrit, sa réponse passe `lapsed`. Un litige sans échéance n'a ni coupure ni rappel : le vendeur peut répondre tant qu'il est ouvert. Quand un litige se termine alors que la réponse du vendeur est encore ouverte, elle passe `closed`. Avec `platform`, le vendeur lit que « votre plateforme répond à ce litige ». Vous n'êtes pas coupé à ce moment-là : l'API vous reste ouverte jusqu'à la décision du litige. Complétez tout de même la réponse **avant** la coupure du vendeur, pour qu'il la voie entière. Le vendeur est prévenu par e-mail, à [votre marque](https://docs.wajub.com/fr/sync/own-domain#e-mails-in-your-brand), quand le litige s'ouvre, et 3 jours avant l'échéance s'il n'a rien envoyé, quand la connexion le laisse répondre. Un litige sans échéance n'a que l'e-mail d'ouverture. ## Compléter sa réponse Lisez le dossier avec `GET /disputes/{id}` et `X-Sync`, puis complétez-le avec `POST /disputes/{id}/submit-evidence`. Une pièce que vous envoyez sous un type que le vendeur a déjà envoyé **remplace** la sienne : un type, une pièce. Un vendeur qui renvoie en `both` ne réécrit que les pièces qu'il a modifiées, si bien que ce que vous avez envoyé sous un autre type reste. Vous et le vendeur pouvez envoyer en même temps : chaque pièce s'ajoute par son type sans effacer celle de l'autre. Une pièce envoyée après la clôture du litige est refusée avec `422`. Qui a envoyé chaque pièce est dans le `evidence_submitted_by` du litige, par type de preuve, pièce texte seul comprise : | Valeur | Qui | | ---------- | ------------------------------------------------------------- | | `merchant` | Le marchand, dans le Dashboard ou par l'API sans `X-Sync` | | `platform` | Vous, par l'API avec `X-Sync` | | `seller` | Le vendeur Lite, depuis son espace ou le composant `disputes` | | `null` | Une pièce envoyée avant que Wajub garde qui l'a envoyée | ```json title="Qui a envoyé quoi" "evidence": { "proof_of_delivery": { "file_name": "bon-de-livraison.pdf", "submitted_by": "seller", "url": "https://…" }, "customer_communication": "L'acheteur a confirmé la réception par message le 18 novembre." }, "evidence_submitted_by": { "proof_of_delivery": "seller", "customer_communication": "platform" } ``` `evidence` lui-même ne change pas : une pièce texte seul est toujours rendue comme son texte, si bien qu'un code qui lit une chaîne continue de marcher, et une pièce avec fichier est un objet qui porte aussi son propre `submitted_by`. ## L'événement `account.dispute_evidence_submitted` parvient à votre plateforme, dans l'environnement du litige, chaque fois qu'un envoi du vendeur ajoute ou change une pièce, et quand la coupure envoie son brouillon pour lui. C'est une [livraison du cycle de vie Sync](https://docs.wajub.com/fr/developer-tools/webhooks/events#sync-lifecycle-deliveries) : listez-le par son nom dans les événements de votre endpoint. ```json title="Une livraison account.dispute_evidence_submitted" { "event": "account.dispute_evidence_submitted", "account": "acc_Gt6yU3nE8rM1kS5vX9bQ", "sandbox": false, "timestamp": "2026-11-21T09:12:04+00:00", "dispute": { "id": "dsp_8Hq2Lw4Tz6Nc1Vb3Xk9R", "payment": "trx_Lw2Ka8Qd1Fz6Tn4Bc7Xm", "status": "under_review", "reason": "product_not_received", "amount": 20000, "currency": "XAF", "due_date": "2026-11-30T10:00:00+00:00" }, "submitted_by": "seller", "evidence_types": ["proof_of_delivery"], "dispute_handling": "both", "seller_may_change_until": "2026-11-29T10:00:00+00:00" } ``` `submitted_by` vaut `seller`, ou `auto` quand la coupure a envoyé le brouillon. `seller_may_change_until` est renseigné en `both` tant que la réponse reste ouverte au vendeur, `null` sinon. Les copies `dispute.*` que vous recevez déjà ne changent pas. ## Le composant `disputes` Activez-le avec `components: { disputes: { enabled: true } }` sur `POST /accounts/{id}/embedded_sessions`, puis `wajub.create('disputes').mount('#wajub-disputes')`. Comptes `lite` seulement : un compte `relay` répond `component_not_available`. Il n'a aucune fonction à activer : il suit `dispute_handling`, un formulaire pour `seller` et `both`, la lecture seule pour `platform`. Il ne montre jamais vos propres pièces ni l'adresse d'un fichier. ## L'argent ne change pas Un litige perdu est débité comme il l'a toujours été ([Remboursements Sync](https://docs.wajub.com/fr/sync/refunds#a-lost-dispute-is-always-debited)). Un litige gagné sur une vente [bloquée jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds) rend au vendeur ce que le litige retenait, et la vente reste bloquée jusqu'à votre libération. - [Litiges](https://docs.wajub.com/fr/api/disputes): Le cycle de vie d'un litige et l'API des preuves. - [Composants embarqués](https://docs.wajub.com/fr/sync/embedded-components): Le composant `disputes` et les autres. - [Remboursements Sync](https://docs.wajub.com/fr/sync/refunds): Qui paie un remboursement ou un litige perdu. --- # Composants embarqués URL: https://docs.wajub.com/fr/sync/embedded-components > Montrez à un vendeur ses ventes, ses versements, son solde, son compte, ses litiges et ce qui l'attend, dans vos propres pages, à vos couleurs. Vos vendeurs se connectent déjà à votre produit. Les composants embarqués y mettent des morceaux de leur espace Wajub, dans vos pages et à vos couleurs : leurs ventes, leurs versements, leur solde, les actions qui les attendent. Ils ne quittent jamais votre site, et vous ne refaites pas des écrans que Wajub tient déjà à jour. ## Les composants | Composant | Montre | `lite` | `relay` | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------ | | `notifications` | Les actions qui attendent le vendeur : vérification d'identité, compte de versement manquant, pièce d'identité demandée, versements retenus | Oui | Oui | | `payments` | Ses ventes, page par page (montant, frais, votre commission, remboursé, net, statut), et le détail de chaque vente avec ses remboursements | Oui | Non | | `payouts` | Les versements que Wajub lui a envoyés, ce que chacun règle ligne à ligne, le prochain versement, ce qui retient ses versements, et ses relevés annuels | Oui | Oui, les versements de ses dus | | `balance` | Lite : disponible, en attente, en réserve, bloqué jusqu'à la livraison. Relay : ce qui lui est dû et à verser, ce qui est encore retenu | Oui | Oui | | `account` | La vérification d'identité à terminer, ses comptes de versement (4 derniers caractères), et en option leur changement | Oui | Non | | `disputes` | Les litiges sur ses ventes, et sa réponse quand vous le laissez la donner ([Litiges sur les ventes de vos vendeurs](https://docs.wajub.com/fr/sync/disputes)) | Oui | Non | Un marchand `direct` a son propre Dashboard : une session embarquée pour lui est refusée avec `account_type_not_embeddable`. Tout fonctionne en sandbox, avec une clé de test et un compte sandbox. Le portail entier dans une iframe ([`portal_sessions`](https://docs.wajub.com/fr/sync/onboarding#the-portal-in-your-own-pages)) reste disponible. Les composants sont la voie recommandée : vous choisissez quoi montrer, et où. ## Comment les pièces s'assemblent 1. **Déclarez les origines de vos pages** Sous **Paramètres, Sync, Plateforme**, listez jusqu'à 5 origines `https` d'où vos pages sont servies. Les composants s'affichent là, et nulle part ailleurs. 2. **Votre serveur demande une session** `POST /accounts/{id}/embedded_sessions` avec votre clé secrète, en nommant les composants à activer. Vous recevez un `client_secret`, valable une fois pendant 5 minutes, et `loader_url`. 3. **Votre page charge le script** `WajubConnect.init({ fetchClientSecret })` appelle votre serveur quand il lui faut un secret, l'échange contre une session de 30 minutes, puis monte chaque composant dans son propre cadre. 4. **La session finit, une autre commence** Quand la session expire, le chargeur redemande un secret à votre `fetchClientSecret`. Si le vendeur a quitté votre plateforme entre-temps, le composant envoie `exit`. ## Créer une session ```bash title="Une session avec quatre composants" curl https://api.wajub.com/accounts/acc_Gt6yU3nE8rM1kS5vX9bQ/embedded_sessions \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "components": { "notifications": { "enabled": true }, "payments": { "enabled": true }, "payouts": { "enabled": true }, "account": { "enabled": true, "features": { "edit_payout_account": true } } } }' ``` | Champ | | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `components` | Requis. Des clés parmi `notifications`, `payments`, `payouts`, `balance`, `account`, `disputes` ; au moins une avec `enabled: true` | | `components.*.enabled` | `false` par défaut | | `components.account.features.edit_payout_account` | Laisse le vendeur changer son compte de versement depuis le composant. **Toujours** après un code envoyé au propriétaire de son espace, valable pour ce nouveau compte seulement, jamais sur votre seule parole, et le nouveau compte attend la période de refroidissement habituelle ([Changer de compte de versement](#changing-the-payout-account)) | | `components.payments.features.refund_management` | Réservée : `true` est refusé avec `feature_not_available` pour l'instant | ```json title="Réponse · 201 Created" { "code": 201, "status": "Created", "message": "Embedded session created", "embedded_session": { "id": "es_0193f3c2a1b47c9e8d2f5a6b7c8d9e0f", "client_secret": "es_0193f3c2a1b47c9e8d2f5a6b7c8d9e0f_secret_…", "expires_at": "2026-11-20T10:05:00+00:00", "account_type": "lite", "components": { "notifications": { "enabled": true, "features": {} }, "payments": { "enabled": true, "features": { "refund_management": false } }, "payouts": { "enabled": true, "features": {} }, "balance": { "enabled": false, "features": {} }, "account": { "enabled": true, "features": { "edit_payout_account": true } }, "disputes": { "enabled": false, "features": {} } }, "loader_url": "https://acme.wajub.app/embed/v1.js" } } ``` `components` liste toujours les six composants, chacun avec `enabled` et ses fonctions, que vous l'ayez activé ou non. Le `client_secret` sert **une fois**, avant `expires_at`, et seulement depuis une page d'une de vos origines déclarées. Wajub n'en garde que l'empreinte. Donnez-le au navigateur qui l'a demandé et à rien d'autre : ne le journalisez jamais, ne le mettez jamais dans une URL. `loader_url` est sur l'adresse de vos vendeurs : [votre propre domaine](https://docs.wajub.com/fr/sync/own-domain) quand il est actif, `votrenom.wajub.app` une fois le nom validé par Wajub, `lite.wajub.com` avant. | `error_code` | Statut | Quand | | -------------------------------------- | ------ | --------------------------------------------------------- | | `account_type_not_embeddable` | `400` | Un compte `direct` | | `component_not_available` | `400` | `payments`, `account` ou `disputes` sur un compte `relay` | | `feature_not_available` | `400` | `payments.refund_management: true` | | `unknown_component`, `unknown_feature` | `400` | Une clé que Wajub ne connaît pas | | `no_component_enabled` | `400` | Rien d'activé | | `account_not_active` | `409` | La connexion n'est pas encore active | | `frame_origins_missing` | `409` | Vous n'avez déclaré aucune origine | Un compte d'une autre plateforme, ou de l'autre environnement, répond `404`. ## Une intégration complète Votre serveur détient la clé secrète et sait quel vendeur est connecté. Il crée la session et ne donne au navigateur que le `client_secret`. ```js title="Serveur · Node.js (Express)" import express from 'express'; const app = express(); app.post('/wajub/embedded-session', requireSellerLogin, async (req, res) => { const accountId = req.user.wajubAccountId; // acc_… const response = await fetch(`https://api.wajub.com/accounts/${accountId}/embedded_sessions`, { method: 'POST', headers: { Authorization: process.env.WAJUB_SECRET_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ components: { notifications: { enabled: true }, payments: { enabled: true }, payouts: { enabled: true }, balance: { enabled: true }, account: { enabled: true, features: { edit_payout_account: true } }, }, }), }); const body = await response.json(); if (!response.ok) return res.status(502).json({ error: body.error_code }); res.json({ client_secret: body.embedded_session.client_secret }); }); ``` ```php title="Serveur · PHP (Laravel)" $session = Http::withHeaders(['Authorization' => config('services.wajub.secret')]) ->post("https://api.wajub.com/accounts/{$accountId}/embedded_sessions", [ 'components' => [ 'payments' => ['enabled' => true], 'payouts' => ['enabled' => true], ], ]) ->throw() ->json('embedded_session'); return ['client_secret' => $session['client_secret']]; ``` Votre page charge le script depuis `loader_url` et monte les composants où vous les voulez. ```html title="Navigateur"
``` Avant d'essayer : déclarez `https://votre-site.example` sous **Paramètres, Sync, Plateforme**, et en test utilisez une clé de test et un compte sandbox. ## Le chargeur `WajubConnect` est en version `1`, et reste tel quel : un changement ultérieur sortira à une autre adresse. | Appel | Fait | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `WajubConnect.init({ fetchClientSecret, appearance, locale })` | Démarre une session. Tous les composants créés depuis elle la partagent | | `wajub.create(name)` | Un composant : `notifications`, `payments`, `payouts`, `balance`, `account` ou `disputes` | | `component.mount(target)` | Le dessine dans un sélecteur CSS ou un élément. Il prend toute la largeur du conteneur, et sa hauteur suit son contenu | | `component.unmount()` | Le retire | | `component.on(event, handler)` | Écoute `ready`, `loaderror` ou `exit` ; renvoie le composant, les appels s'enchaînent | | `wajub.destroy()` | Retire tous les cadres et l'écouteur | `locale` vaut `en` ou `fr` ; sans elle, la langue du navigateur, et le français à défaut. `WajubConnect.version` vaut `'1'` et `WajubConnect.components` liste les noms. | Événement | Quand | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ready` | Le composant est dessiné : `{ component }` | | `loaderror` | Il n'a pas pu se charger : `{ type, message }`, avec un `type` comme `frame_timeout` (rien n'a répondu en 15 secondes : vérifiez vos origines déclarées), `invalid_client_secret`, `origin_not_allowed`, `component_not_enabled` ou `load_error` | | `exit` | La session est finie et ne peut pas être renouvelée | ### L'apparence L'apparence est vérifiée par Wajub : pas de CSS libre. | Clé | Valeurs | | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `colors.primary`, `colors.background`, `colors.text` | `#rgb` ou `#rrggbb` | | `border_radius` | `0px`, `4px`, `8px`, `12px` ou `9999px` | | `font` | Instrument Sans, Inter, Roboto, Open Sans, Lato, Montserrat, Poppins, DM Sans, Plus Jakarta Sans, Raleway, Nunito, Work Sans, Manrope, Outfit, Space Grotesk, Public Sans, Figtree, Lexend, Sora, Source Sans 3 ou IBM Plex Sans | | `mode` | `light`, `dark` ou `system` | Toute autre valeur est ignorée, signalée dans la console, et remplacée par votre marque de **Paramètres, Image de marque**. Une couleur qui manque de contraste est ajustée pour rester lisible, comme sur le portail. ## Changer de compte de versement Avec `edit_payout_account`, le composant `account` permet à un vendeur Lite de changer l'endroit où il est payé. Ni votre parole ni votre session n'y suffisent : | Étape | | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Le vendeur saisit le nouveau compte | L'opérateur et le numéro, ou le compte bancaire, vérifiés comme dans son portail avant tout envoi de code | | Un code part au propriétaire de son espace | À l'adresse e-mail qui ouvre son espace, jamais à une adresse que vous avez enregistrée. L'e-mail nomme le nouveau compte (l'opérateur, les 4 derniers chiffres) et dit de ne jamais donner le code à personne, pas même à votre plateforme ni à quelqu'un qui dit travailler pour Wajub. Il part de Wajub, sous le nom d'espace validé (« votrenom via Wajub »), sans votre logo, votre couleur ni votre adresse de réponse | | Le code ne confirme que ces coordonnées | Envoyé avec d'autres coordonnées, il est refusé et consommé : le vendeur en demande un nouveau. Demander un code pour d'autres coordonnées annule le précédent | | Le compte change | Après la période de refroidissement habituelle. Le vendeur reçoit un e-mail de Wajub disant que son compte de versement a changé, dont le lien mène à son adresse Wajub, jamais à votre domaine | Sur [votre propre domaine](https://docs.wajub.com/fr/sync/own-domain), rien ne se confirme dans le cadre : vous tenez le certificat de ce domaine. Le composant montre les comptes de versement en lecture seule, et son bouton **Changer de compte de versement** ouvre l'adresse Wajub du vendeur, `https://votrenom.wajub.app/payout-account` (le `change_url` du composant, `null` sur une adresse Wajub), dans un nouvel onglet. Le vendeur s'y connecte avec son propre code et change le compte sur place. Le chargeur et le composant gèrent eux-mêmes ces réponses du cadre : | Réponse | Quand | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `409` `change_on_wajub`, avec `url` | Un code demandé, ou un changement envoyé, sur votre propre domaine : le changement se fait à `url` | | `429` `too_many_codes` | 3 codes par heure ou 6 par jour ; ou un code pour d'autres coordonnées est en route et le délai entre deux codes n'est pas écoulé | | `429` `payout_account_locked` | 5 codes faux en 24 heures : le changement est bloqué pendant 24 heures | ## Fermer les sessions d'un vendeur `POST /accounts/{id}/embedded_sessions/revoke` met fin d'un coup à toutes les sessions embarquées du vendeur : les secrets clients pas encore échangés ne marchent plus, et les sessions ouvertes se terminent. Leurs cadres répondent `session_expired`, et le chargeur redemande un secret à votre `fetchClientSecret`. Appelez-la quand un vendeur quitte votre plateforme, ou quand un secret client a pu fuiter ; si le vendeur ne doit plus rien voir, faites refuser ce secret suivant par votre serveur. ```bash title="Fermer les sessions d'un vendeur" curl -X POST https://api.wajub.com/accounts/acc_Gt6yU3nE8rM1kS5vX9bQ/embedded_sessions/revoke -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` ```json title="Réponse · 200 OK" { "code": 200, "status": "OK", "message": "Embedded sessions revoked", "revoked": 2 } ``` | Règle | | | ------------- | --------------------------------------------------------------------------------------------------------------------------- | | `revoked` | Combien de sessions encore vivantes ont été fermées, secrets pas encore échangés compris ; `0` s'il n'y en avait aucune | | Environnement | Celui du compte : une clé de test ferme les sessions de test | | Clé | Votre clé secrète, sans `X-Sync`. Une clé restreinte est refusée (`403`), comme sur `POST /accounts/{id}/embedded_sessions` | | Refus | `400` `account_type_not_embeddable` sur un compte `direct` ; `404` pour un compte d'une autre plateforme | ## Ce qui le rend sûr | Règle | Pourquoi | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Aucun cookie tiers | La session passe par `postMessage` vers l'origine exacte du cadre, puis dans un en-tête `Authorization`. Ça marche dans les navigateurs qui bloquent les cookies tiers | | Le jeton n'est jamais dans une URL | L'adresse du cadre ne porte que l'identifiant public de la session, qui dit quelles origines peuvent l'encadrer | | Les messages sont vérifiés dans les deux sens | Le cadre n'écoute que son parent sur une origine déclarée ; le chargeur, que ses propres cadres | | Encadré par vos seules origines | Les cadres envoient `frame-ancestors` avec les origines que vous avez déclarées | | `Origin` protège un navigateur, pas un secret | Le secret n'est échangé que depuis une page d'une origine déclarée. Un serveur qui détient un secret client peut envoyer n'importe quel `Origin` : gardez le secret sur votre serveur jusqu'à ce que votre page le demande, et [fermez les sessions du vendeur](#revoking-sessions) s'il a pu fuiter | | Votre clé secrète seulement | Créer et fermer des sessions demande votre clé secrète : une clé restreinte est refusée | | Lecture seule, sauf une fonction | Seule `edit_payout_account` écrit, et seulement après un code à usage unique envoyé à l'adresse du propriétaire de l'espace du vendeur, jamais à une adresse que vous avez enregistrée, et valable pour le seul compte qu'il nomme. Le code sert une fois, pendant 10 minutes. Au plus 3 codes par heure et 6 par jour ; 5 codes faux en 24 heures bloquent le changement pendant 24 heures. Sur votre propre domaine, le changement se fait sur l'adresse Wajub du vendeur. Après tout changement, le vendeur reçoit un e-mail de Wajub disant que son compte de versement a changé | | La session suit vos réglages | Elle se termine aussitôt (le chargeur redemande un secret à votre serveur) quand l'origine qui l'a ouverte n'est plus déclarée, que l'espace du vendeur est fermé, ou que Sync n'est plus dans votre forfait. Origines et forfait sont relus au moins toutes les 60 secondes | > [!NOTE] > **Appeler les cadres vous-même** > > Le chargeur et ses cadres appellent quelques routes sur l'adresse de vos vendeurs > (`/embed/v1/sessions`, `/embed/v1/payments`…). Ce n'est pas une API à appeler à la main, et elles > peuvent changer dans la version `1` tant que le chargeur, lui, ne change pas. - [Votre propre domaine](https://docs.wajub.com/fr/sync/own-domain): Servez le portail et les composants sur un domaine à vous. - [Litiges sur les ventes de vos vendeurs](https://docs.wajub.com/fr/sync/disputes): Laissez les vendeurs répondre depuis le composant `disputes`. - [Créer une session embarquée](https://docs.wajub.com/fr/api/subaccounts/create-embedded-session): La spécification de l'endpoint. - [Fermer les sessions](https://docs.wajub.com/fr/api/subaccounts/revoke-embedded-sessions): Mettre fin à toutes les sessions embarquées d'un vendeur. --- # Bloquer jusqu'à la livraison URL: https://docs.wajub.com/fr/sync/holds > 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. **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. --- # Sync URL: https://docs.wajub.com/fr/sync > Encaissez pour les marchands et les vendeurs de votre plateforme, prélevez votre commission, et choisissez qui tient le compte, selon trois modes. Sync permet à une marketplace ou à une plateforme d'agir au nom des marchands avec lesquels elle travaille : une fois un marchand connecté, vous appelez l'API classique avec un en-tête supplémentaire et la requête s'exécute comme s'il l'avait envoyée. **Une connexion n'est pas un compte que vous créez à la place du marchand** : c'est lui qui l'accepte, après avoir lu ce que vous demandez. ## Choisir un mode Le mode d'une connexion dit ce que le vendeur possède chez Wajub, où se trouve l'argent, et ce que votre plateforme porte quand une vente est défaite. Il se choisit à la création, avec `account_type`, et ne change plus ensuite. | Mode | Le vendeur a | L'argent passe par | Qui lui envoie son argent | Ce que vous portez | Pour qui | | --------------------- | ------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | `direct` (par défaut) | Un compte Wajub complet, avec son Dashboard | Le rail Wajub, ou ses propres contrats de prestataire | Lui-même : il retire | Rien : il porte son propre solde négatif. S'il encaisse sur ses propres contrats, votre commission devient une créance | Les marchands déjà équipés | | `lite` | Un portail vendeur, à vos couleurs | Le rail Wajub, toujours | Wajub, au rythme que vous fixez | Ce qu'il ne peut plus rembourser après avoir été payé, une fois sa réserve épuisée. Vous pouvez le récupérer sur ses versements suivants | Les petits vendeurs, le cas courant | | `relay` | Aucun compte : son portefeuille vérifié | Votre propre solde | Wajub, depuis votre solde, au rythme que vous fixez : la vente moins les frais de Wajub, votre commission et ce qu'il doit | Tout : remboursements et litiges sortent de votre solde, et ce qu'un vendeur déjà payé doit est retenu sur son versement suivant | Les marketplaces *merchant of record* | > [!NOTE] > **Lite et Relay en live passent par la revue de Wajub** > > Une connexion `lite` ou `relay` en live s'ouvre une fois que Wajub a examiné votre plateforme pour > ce mode. Demandez-le sous **Paramètres, Sync, Plateforme**. Tout fonctionne en sandbox sans elle. > [Relay](https://docs.wajub.com/fr/sync/relay) Ce ne sont pas des paliers : deux connexions de modes différents peuvent porter les mêmes capacités et la même commission. Ce qui change est qui tient le compte, et donc [qui rembourse](https://docs.wajub.com/fr/sync/refunds) et [qui paie le vendeur](https://docs.wajub.com/fr/sync/payouts). ## Ce qu'il vous faut avant de commencer | Condition | Détail | | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Forfait | Scale ou Enterprise, ou l'option Sync avec un forfait inférieur. Sans cela, les routes de compte et tout appel portant `X-Sync` répondent `403` avec `error_code: feature_not_in_plan` | | Approbation, pour `lite` et `relay` en live | Wajub examine votre plateforme avant que vous ouvriez des connexions `lite` ou `relay` en live : demandez-la sous **Paramètres, Sync, Plateforme**. D'ici là, un `POST /accounts` live pour ces modes répond `403` avec `error_code: sync_mode_not_approved`. La sandbox et `direct` ne demandent rien. [Votre plafond d'exposition](https://docs.wajub.com/fr/sync/payouts#your-exposure-cap) | | Clé | La clé secrète de votre plateforme. Une clé publique sur une route de compte renvoie `406 Private Key Required` | | Marchand | En `direct`, un compte Wajub existant ou une personne prête à en ouvrir un. En `lite`, un vendeur qui accepte votre invitation et vérifie son identité : il n'a pas de compte à gérer | ## Les quatre fonctions de Sync **Connecter un compte.** Vous créez une connexion, transmettez un lien au marchand, puis celui-ci l'accepte en ligne. Un marchand `direct` le fait avec son propre compte ; un vendeur `lite` n'a pas de Dashboard, et retrouve ensuite ses ventes et ses versements dans son portail. **Vous prêter son identité.** Avec `X-Sync` dans une requête, la requête agit en tant que marchand connecté. Le paiement, le client et le remboursement lui appartiennent. **Prélever votre commission.** Chaque connexion possède une règle tarifaire. Lorsqu'un paiement attribué à cette connexion réussit, les frais quittent le solde du marchand et arrivent sur le vôtre, sous la même rétention que la vente. Ils sont rendus si la vente est remboursée ou si un litige sur elle est perdu, selon la politique fixée sur la connexion. **Vous envoyer une copie de ses événements.** Un paiement, un remboursement ou un transfert sur un compte connecté, et un litige sur l'un de ses paiements, déclenche le webhook du marchand et envoie une deuxième copie aux endpoints de votre plateforme. ## Ce que Sync ne fait pas > [!NOTE] > **Un paiement, plusieurs vendeurs** > > Un paiement porte un seul en-tête `X-Sync`. Pour partager un panier entre plusieurs vendeurs, créez > le paiement avec votre propre clé et listez les parts dans `shares` : l'acheteur paie une fois, et > Wajub répartit l'argent. [Un paiement, plusieurs vendeurs](https://docs.wajub.com/fr/sync/split-payments#one-payment-several-sellers) Deux autres limites doivent être connues avant de concevoir votre système. Qui paie un marchand dépend du mode de la connexion : Wajub paie un marchand `lite`, selon un calendrier ou lorsque vous appelez `POST /accounts/{id}/payouts`, et un marchand `direct` retire lui-même ou via un [transfert](https://docs.wajub.com/fr/payouts/transfers) classique que vous envoyez avec l'en-tête `X-Sync`, sur son solde. [Payer les vendeurs](https://docs.wajub.com/fr/sync/payouts) couvre les trois modes. De plus, les capacités sont figées dès la connexion du marchand, comme l'explique la [page des capacités](https://docs.wajub.com/fr/sync/account-types). ## L'en-tête en un seul endroit Toutes les routes de cette section sont des routes classiques. Seul un en-tête change. ```bash title="Un paiement attribué à une connexion" curl https://api.wajub.com/payments \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "X-Sync: acc_7Yh2MpL4tRb3nP8sZcXv" \ -H "Content-Type: application/json" \ -d '{ "amount": 50000, "currency": "XAF", "customer": { "email": "buyer@example.com" } }' ``` L'en-tête contient l'`id` de la connexion, la valeur renvoyée sous la forme `account.id` lors de sa création. Ce n'est ni l'identifiant du compte du marchand ni l'une de vos clés. `X-Sync` est lu sur toutes les routes authentifiées, pas seulement celles des paiements. Les clients, remboursements, factures, transferts et liens de paiement l'acceptent, selon les capacités accordées. ## Les ressources | Méthode | Endpoint | Rôle | | -------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `POST` `GET` | [`/accounts`](https://docs.wajub.com/fr/api/subaccounts) | Créer, répertorier et récupérer une connexion | | `PUT` `DELETE` | [`/accounts/{id}`](https://docs.wajub.com/fr/api/subaccounts) | Mettre à jour la tarification et le statut, ou déconnecter | | `POST` | [`/accounts/{id}/token`](https://docs.wajub.com/fr/api/subaccounts) | Générer un nouveau lien d'autorisation | | `POST` | [`/accounts/{id}/payouts`](https://docs.wajub.com/fr/api/subaccounts/payouts) | Payer un marchand `lite` immédiatement | | `GET` | [`/accounts/{id}/commission-receivables`](https://docs.wajub.com/fr/api/subaccounts/commission-receivables) | Les commissions qu'un marchand vous doit encore | | `POST` | [`/accounts/{id}/embedded_sessions`](https://docs.wajub.com/fr/api/subaccounts/create-embedded-session) | Montrer l'espace d'un vendeur dans vos pages ([Composants embarqués](https://docs.wajub.com/fr/sync/embedded-components)) | | `POST` | [`/payments/{id}/release`](https://docs.wajub.com/fr/api/subaccounts/release-payment) | Libérer une vente bloquée jusqu'à la livraison ([Bloquer jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds)) | | `POST` | [`/accounts/{id}/freeze`](https://docs.wajub.com/fr/api/subaccounts/freeze), [`/unfreeze`](https://docs.wajub.com/fr/api/subaccounts/unfreeze) | Cesser ou reprendre les versements d'un vendeur ([Risque vendeur](https://docs.wajub.com/fr/sync/seller-risk)) | | `GET` | [`/sync/limits`](https://docs.wajub.com/fr/api/subaccounts/limits) | Votre plafond de versement et ce qui en est utilisé | | `GET` `PUT` `DELETE` | [`/sync/portal_domain`](https://docs.wajub.com/fr/api/subaccounts/retrieve-portal-domain) | Le portail de vos vendeurs sur votre propre domaine ([Votre domaine](https://docs.wajub.com/fr/sync/own-domain)) | | `GET` | [`/sync/metrics`](https://docs.wajub.com/fr/api/subaccounts/metrics) | Les chiffres de votre plateforme ([Analyses](https://docs.wajub.com/fr/sync/analytics)) | | `POST` `GET` | [`/sync/reports`](https://docs.wajub.com/fr/api/subaccounts/create-report) | Exports comptables et relevés des vendeurs ([Rapports](https://docs.wajub.com/fr/sync/reports)) | Tous les autres appels utilisent l'API classique avec l'en-tête. - [Démarrage rapide](https://docs.wajub.com/fr/sync/quickstart): Créer une connexion, obtenir son autorisation et y recevoir un paiement. - [Capacités du compte](https://docs.wajub.com/fr/sync/account-types): Les sept capacités, ce que chacune atteint et le calcul de la tarification. - [Intégration des marchands](https://docs.wajub.com/fr/sync/onboarding): Le cycle de vie d'une connexion et ce qui est figé après l'acceptation du marchand. - [Remboursements](https://docs.wajub.com/fr/sync/refunds): Qui demande, qui envoie et qui paie, selon le mode et l'endroit où la vente a été encaissée. - [Paiements fractionnés](https://docs.wajub.com/fr/sync/split-payments): Les trois fonctionnalités derrière le mot split : paiement en plusieurs fois, votre commission, et un paiement partagé entre vendeurs. - [Composants embarqués](https://docs.wajub.com/fr/sync/embedded-components): Les ventes, versements et solde de vos vendeurs dans vos propres pages. - [Bloquer jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds): Payez le vendeur une fois la marchandise chez l'acheteur. - [Risque vendeur](https://docs.wajub.com/fr/sync/seller-risk): Un score par vendeur, un délai pour les nouveaux, et le gel. - [Référence API des sous-comptes](https://docs.wajub.com/fr/api/subaccounts): La spécification de l'endpoint. --- # Intégration des marchands URL: https://docs.wajub.com/fr/sync/onboarding > 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 live 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. Une connexion annulée renvoie `cancelled`, une connexion associée à un marchand renvoie `active`, une invitation que personne n'a acceptée avant sa date renvoie `expired`, et toutes les autres renvoient `pending`. `expires_at` est la date de l'invitation : elle est effacée quand un marchand accepte, et une connexion acceptée n'expire jamais. ## 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. ```json title="Réponse pour une connexion non revendiquée" { "id": "acc_7Yh2MpL4tRb3nP8sZcXv", "reference": "shop-amina", "status": "pending", "payment_status": "inactive", "authorization_url": "https://sync.wajub.com/oauth/v2/authorize?access_token=…" } ``` 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é. > [!WARNING] > **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 tous les liens déjà émis, y compris celui d'un rappel, et en > génère un nouveau, valable de nouveau 30 jours. 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 la dernière émission de son lien, à la création de la connexion, par `POST /accounts/{id}/token` ou par **Renvoyer l'invitation** dans le Dashboard, chacun relançant les 30 jours. Les deux derniers révoquent les liens déjà envoyés. Trois jours avant, un rappel part à l'adresse du marchand si vous l'avez indiquée, avec `email` sur `POST /accounts` ou `PUT /accounts/{id}` ; elle est conservée dans `profile.email`. Le rappel porte son propre lien, et celui que vous avez déjà envoyé continue de fonctionner. Une fois l'invitation expirée, tous les liens qui dorment dans la boîte du marchand cessent de fonctionner. Une connexion Relay n'a ni invitation, ni lien d'autorisation (`authorization_url` vaut `null`), et n'expire jamais. Vous pouvez avoir au plus 50 invitations ouvertes par environnement : des connexions créées et ni acceptées, ni annulées, ni expirées. Les connexions Relay ne comptent pas, puisqu'aucun marchand ne les accepte. Au-delà, `POST /accounts` répond `429` avec `You have reached the maximum of 50 pending invitations.` Annulez les invitations dont vous n'avez plus besoin, ou laissez-les expirer. Vous ne voyez `authorization_url` qu'une fois, dans la réponse à l'appel qui l'a généré : la création du sous-compte, ou la régénération de son jeton. Lire le sous-compte ensuite ne le renvoie jamais, revendiqué ou non. Conservez-le dès que vous le recevez ; si vous le perdez, générez-en un nouveau. Une fois la connexion revendiquée, `connected_merchant` apparaît dans la réponse avec le nom et l'adresse e-mail de l'entreprise du marchand. ## Ce que le lien ne permet pas Une connexion ne se revendique qu'une fois, et les contrôles ont lieu au moment de la revendication, pas à l'ouverture du lien par le marchand : - une connexion que vous avez annulée reste annulée, et le lien ne peut pas la réactiver. `POST /accounts/{id}/token`, lui, le peut : sur une invitation annulée que personne n'a revendiquée, il génère un nouveau lien et remet la connexion à `pending`, pour 30 jours de nouveau ; - une connexion déjà revendiquée par un autre marchand ne peut pas être reprise ; - une invitation expirée est refusée ; - en mode live, le marchand ne peut pas la revendiquer avant d'avoir déposé son dossier KYC. Le dépôt suffit pour se connecter ; c'est la vérification qui débloque les paiements (voir plus bas) ; - le lien peut porter un `redirect_uri`, mais seulement s'il partage son origine avec le `callback` enregistré sur la connexion. Tout autre hôte est refusé, et une connexion sans callback n'en accepte aucun. Un marchand qui valide deux fois arrive sur sa propre connexion terminée, et non sur une erreur. ## Retour sur votre page Avant d'envoyer le lien, vous pouvez y ajouter `&state=…` (une valeur à vous, par exemple un jeton aléatoire lié à la session du vendeur) et `&redirect_uri=…`. Une fois la connexion acceptée, le marchand est envoyé vers ce `redirect_uri`, ou vers le `callback` de la connexion si le lien n'en porte pas, avec ces paramètres de requête : | Paramètre | Ce qu'il porte | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account` | L'`id` de la connexion (`acc_…`), celui de chaque appel et de chaque événement `account.*` | | `state` | Le `state` que vous avez mis sur le lien d'autorisation, renvoyé tel quel. Comparez-le à celui que vous avez conservé, pour savoir que la visite répond à votre propre lien | | `status` | `connected` | ```text title="Le retour, pour un lien ouvert avec state=8f3a" https://example.com/connected?account=acc_7Yh2MpL4tRb3nP8sZcXv&state=8f3a&status=connected ``` Le `callback` doit être une adresse HTTPS : `POST` et `PUT /accounts` répondent `422` sinon, sauf `http://localhost` et `http://127.0.0.1` avec une clé sandbox. Ce retour sert le navigateur du marchand, ce n'est pas une preuve : n'importe qui peut ouvrir cette adresse. Confirmez la connexion avec `GET /accounts/{account}` ou attendez `account.connected` sur votre endpoint de webhook avant d'agir. ## Activer ensuite les paiements L'acceptation ne donne pas toujours l'autorisation de débiter. `payment_status` est fixé au moment où le marchand accepte. | Le marchand accepte | `payment_status` | | ------------------------------------- | ----------------------------------------------------------------------------------------- | | En sandbox | `active` immédiatement | | En live, vérification déjà validée | `active` immédiatement, à condition qu'une connexion `lite` ait aussi accès au rail Wajub | | En live, vérification encore en cours | `inactive` | Une connexion `inactive` passe seule à `active` lorsque la vérification du marchand est validée et, pour une connexion `lite`, une fois le rail Wajub accordé. Wajub envoie alors `account.payment_activated`. | `payment_status` | Effet sur les requêtes qui contiennent `X-Sync` | | ---------------- | ------------------------------------------------------------------------ | | `inactive` | Appels qui déplacent de l'argent refusés avec `403` ; lectures exécutées | | `active` | Tout ce que permettent les capacités s'exécute | | `suspended` | Appels qui déplacent de l'argent refusés avec `403` ; lectures exécutées | Ce qui est refusé tant que `payment_status` n'est pas `active` : créer, activer, modifier ou débiter un paiement, créer ou modifier un lien de paiement, un remboursement, un transfert ou un lot, ajouter, modifier ou vérifier un bénéficiaire ou enregistrer ce qu'un vendeur doit rendre, et accepter ou clore un litige. Ce qui fonctionne encore : tous les `GET`, pour suivre ce que fait la connexion pendant l'examen de la vérification du marchand, ainsi qu'annuler un paiement, supprimer un lien de paiement ou un bénéficiaire, et les recherches d'identité (`/identity/resolve`, `/identity/validate`). 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. L'interrupteur ne lève qu'une suspension que vous avez posée vous-même. Repasser `payment_status` à `active` répond `409` avec `error_code: merchant_not_verified` tant que la vérification du marchand est en cours ou a été refusée : ces connexions reviennent d'elles-mêmes une fois la vérification validée. ## Le portail du vendeur Lite Un vendeur `lite` n'a pas de dashboard marchand : c'est tout l'objet du mode. Accepter votre invitation lui ouvre un espace vendeur dédié à votre plateforme, distinct de tout autre compte Wajub qu'il possède déjà : une connexion `lite` ne se rattache jamais à une organisation existante. 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 | | 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 | > [!WARNING] > **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 ; le portail indique au vendeur à partir de quand elle peut être > payée. Un transfert vers une destination en attente est refusé jusqu'à la fin de ce délai. ### L'adresse du portail Vos vendeurs se connectent à une adresse à votre nom, que vous choisissez et que Wajub valide. | Adresse | Quand elle sert | | -------------------- | ---------------------------------------------------------------------------------------- | | `votrenom.wajub.app` | Dès que Wajub a validé le nom que vous avez demandé | | `lite.wajub.com` | Tant qu'aucun nom n'est validé, et pour un vendeur qui ne connaît que son adresse e-mail | Vous demandez le nom dans le dashboard, sous **Paramètres, Sync, Plateforme** : 3 à 40 lettres minuscules, chiffres ou tirets isolés, sans tiret au début ni à la fin. - **Wajub valide chaque nom avant que son adresse ne réponde.** Un nom refusé vous revient avec son motif, et vous pouvez en demander un autre. - **Certains noms sont réservés** : ceux qui passeraient pour une adresse de Wajub, pour une page de connexion ou de paiement, pour un opérateur ou pour une banque. - **Demander un autre nom coupe l'adresse en service** jusqu'à la validation du nouveau ; entre-temps vos vendeurs se connectent sur `lite.wajub.com`. Sur votre adresse, le portail porte votre logo et vos couleurs, et la mention « Paiements opérés par Wajub » reste en pied de page. Un vendeur présent sur plusieurs plateformes retrouve chacun de ses espaces depuis `lite.wajub.com` ; une session n'ouvre jamais qu'une plateforme à la fois. Le portail peut aussi répondre sur un domaine à vous, comme `vendeurs.maplateforme.com`, avec les e-mails de Wajub à vos vendeurs à votre marque : [Votre domaine et votre marque](https://docs.wajub.com/fr/sync/own-domain). ### Le portail dans vos propres pages Montrez à un vendeur Lite son espace à l'intérieur de votre produit. `POST /accounts/{id}/portal_sessions` renvoie `portal_session` : `{ url, expires_at }`, un lien à usage unique, valable 5 minutes, qui ouvre le portail du vendeur déjà connecté sur cette seule connexion, pour 30 minutes. | Règle | Pourquoi | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Usage unique, durée courte | Le lien est une clé : ouvrez-le tout de suite, ne le stockez ni ne le partagez | | Cette connexion seulement | La session ne peut ni lister ni ouvrir les autres espaces du vendeur | | Lecture seule | Changer la destination de l'argent du vendeur demande sa propre connexion, avec son code e-mail | | Encadrable seulement par vos origines | Déclarez jusqu'à 5 origines `https` sous **Paramètres, Sync, Plateforme** ; le portail peut être mis dans une iframe sur elles, et nulle part ailleurs | La page de connexion elle-même n'est jamais encadrable : à la fin de la session, ouvrez un nouveau lien. L'onboarding hébergé reste une redirection, jamais une iframe, pour la vérification d'identité et la caméra. Pour ne montrer que certains morceaux de l'espace, ses ventes, ses versements, son solde, là où vous les voulez dans vos pages et à vos couleurs, utilisez plutôt les [composants embarqués](https://docs.wajub.com/fr/sync/embedded-components) : c'est la voie recommandée. ## 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. De son côté, le marchand retrouve toutes les plateformes auxquelles il est connecté sous **Paramètres, Applications connectées** : les capacités accordées, la commission acceptée, l'état des paiements et toute proposition en attente. Accepter ou refuser une proposition depuis cette page vous envoie `account.change_accepted` ou `account.change_declined`. La même page lui permet de se déconnecter de votre plateforme, ce qui met fin à la connexion exactement comme votre propre `DELETE`. ## 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`. ```bash title="Déconnecter un marchand" curl -X DELETE https://api.wajub.com/accounts/acc_7Yh2MpL4tRb3nP8sZcXv \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` 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 Le cycle de vie d'une connexion est décrit par les événements ci-dessous, sur les endpoints de votre plateforme. Créer une connexion envoie `account.created`, avec le compte mais sans son lien : `authorization_url` ne figure que dans la réponse à `POST /accounts`. Le [catalogue des événements](https://docs.wajub.com/fr/developer-tools/webhooks/events#accounts-for-sync-platforms) les décrit tous. | Événement | Moment de l'envoi | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account.created` | Vous la créez avec `POST /accounts` | | `account.onboarding_started` | Le marchand ouvre le lien d'autorisation | | `account.onboarding_email_verified` | Il confirme son adresse e-mail | | `account.onboarding_account_selected` | Il choisit le compte Wajub à connecter | | `account.onboarding_kyc_submitted` | Il dépose son KYC pendant l'onboarding | | `account.onboarding_declined` | Il refuse la connexion ; le lien reste valable, et `reason` contient ses mots quand il en a donné | | `account.connected` | Il accepte la connexion | | `account.payment_activated` | La connexion obtient la capacité de débiter | | `account.payment_suspended` | Elle est suspendue, par vous ou après l'échec d'une vérification | | `account.change_requested` | Vous proposez de nouvelles capacités ou une nouvelle tarification | | `account.change_accepted` | Le marchand accepte une proposition | | `account.change_declined` | Le marchand refuse une proposition | | `account.updated` | Elle change : par `PUT /accounts/{id}` (ni une proposition seule, ni un appel qui ne change rien), quand `POST /accounts/{id}/token` remet une invitation annulée en `pending`, ou quand Wajub envoie le versement d'un marchand Lite (`last_payout_at`) | | `account.commission_receivable_recorded` | Une commission est due sur une vente encaissée hors de Wajub | | `account.commission_receivable_collected` | Cette commission est recouvrée | | `account.deauthorized` | La connexion est déconnectée ou annulée | > [!WARNING] > **Deux formats, deux signatures** > > Les événements qui suivent vos propres appels à l'API (`POST /accounts`, `PUT` et > `DELETE /accounts/{id}`, `POST /accounts/{id}/token`, versements Lite, demandes de modification, > commissions dues) portent l'enveloppe habituelle, `X-Wajub-Signature` et `X-Wajub-Timestamp`. Les > événements des étapes du marchand lui-même (`onboarding_*`, `connected`, `change_accepted`, > `change_declined`, les activations qui suivent une vérification, et une déconnexion faite dans le > Dashboard) portent un en-tête `X-Sync-Event` et un corps à plat avec `event`, `account` (l'id > `acc_…`), `sandbox`, `timestamp` et les champs propres à l'événement. Ils sont signés de la même > façon que les autres, dans `X-Sync-Signature-V1` et `X-Sync-Timestamp`, avec le secret de > signature de votre endpoint : passez ces deux en-têtes à `constructEvent` du SDK, qui vérifie la > signature et refuse un horodatage vieux de plus de 300 secondes. Conservez ensuite le > `X-Idempotency-Key` de chaque livraison traitée et ignorez celle que vous avez déjà vue. Ces > événements n'atteignent qu'un endpoint abonné à leur nom exact, pas un endpoint abonné à `*`, et > ne sont plus relivrés au-delà de deux minutes environ : si votre endpoint était indisponible, > relisez la connexion avec `GET /accounts/{id}`. De plus, chaque paiement, remboursement et transfert effectué sur un compte connecté, et chaque litige ouvert sur l'un de ses paiements, 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é. - [Sync](https://docs.wajub.com/fr/sync): La nature d'une connexion et ses limites. - [Démarrage rapide](https://docs.wajub.com/fr/sync/quickstart): Créer une connexion et y recevoir votre premier paiement. - [Capacités du compte](https://docs.wajub.com/fr/sync/account-types): Les sept capacités et le calcul de la commission. - [Catalogue des événements](https://docs.wajub.com/fr/developer-tools/webhooks/events): Tous les événements envoyés par Wajub et la vérification d'une signature. --- # Votre domaine et votre marque URL: https://docs.wajub.com/fr/sync/own-domain > Servez le portail de vos vendeurs sur un domaine à vous, et envoyez-leur les e-mails de Wajub à votre marque. Vos vendeurs doivent voir votre plateforme, pas la nôtre. Leur portail peut répondre sur un domaine à vous, `vendeurs.maplateforme.com`, au lieu de `votrenom.wajub.app`, et les e-mails que Wajub leur envoie portent votre nom, votre logo et votre couleur. ## Votre propre domaine | Règle | | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Un domaine par plateforme | Un **sous-domaine** seulement, jamais la racine d'une zone : une racine ne peut pas porter de `CNAME` | | Test et live à la fois | Le domaine n'est pas lié à un environnement : il sert le portail dans les deux. Une clé de test le lit ; le déclarer et le retirer demandent une **clé live** (sinon `403 live_key_required`) | | Tout le suit | Une fois actif, le portail, les [composants embarqués](https://docs.wajub.com/fr/sync/embedded-components) et tous les liens que Wajub envoie à vos vendeurs l'utilisent | | L'ancienne adresse marche toujours | `votrenom.wajub.app` répond encore : un lien déjà envoyé s'ouvre toujours | ### Le mettre en place 1. **Déclarez le domaine** Sous **Paramètres, Sync, Plateforme**, dans **Votre propre domaine**, ou avec `PUT /sync/portal_domain`. 2. **Créez deux enregistrements DNS** Chez votre fournisseur DNS, les deux enregistrements que la réponse liste (ci-dessous). 3. **Attendez la vérification** Wajub les vérifie toutes les 10 minutes pendant 72 heures ; **Vérifier maintenant** dans le Dashboard le fait tout de suite. Quand les deux sont bons, Wajub route le domaine et obtient son certificat TLS : le statut passe `active`. ```bash title="Déclarer le domaine" curl -X PUT https://api.wajub.com/sync/portal_domain \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{"domain":"vendeurs.maplateforme.com"}' ``` | Type | Nom | Valeur | | ------- | ----------------------------------------- | ---------------------------------------- | | `CNAME` | `vendeurs.maplateforme.com` | `portals.wajub.app` | | `TXT` | `_wajub-verify.vendeurs.maplateforme.com` | Le jeton de la réponse, `wajub-portal-…` | Gardez les deux enregistrements tant que vous utilisez le domaine. Une fois actif, Wajub les revérifie **chaque jour** : un échec isolé ne coupe rien et affiche un avertissement sous **Paramètres, Sync, Plateforme**, pas plus qu'une vérification dont la lecture DNS n'obtient aucune réponse, sauf si cela dure : quand les résolveurs de Wajub n'obtiennent aucune réponse de votre zone pendant **plus de 72 heures d'affilée**, le domaine est retiré comme après trois échecs. Après **trois échecs d'affilée**, environ 72 heures, le domaine passe `failed`, le portail cesse d'y répondre, tous les liens reviennent à `votrenom.wajub.app`, et le propriétaire et les administrateurs de votre organisation reçoivent un e-mail. Corrigez les enregistrements, puis déclarez de nouveau le domaine : le jeton ne change pas. Wajub ne reprend jamais un hôte déjà routé ailleurs sur Wajub, le domaine de paiement d'un marchand par exemple : la vérification reste alors `verifying` avec `routing_failed`. > [!WARNING] > **Trois pièges** > > Si votre DNS passe par un proxy (un nuage orange, par exemple), mettez le `CNAME` en **DNS seul** : > un enregistrement proxifié cache le `CNAME` (`cname_missing`) et empêche le certificat. Certains > panneaux DNS ajoutent votre domaine au nom tout seuls : saisissez-y `vendeurs` et > `_wajub-verify.vendeurs`. Les guillemets autour de la valeur `TXT` sont acceptés. ### Les statuts | `status` | Signifie | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pending_dns` | Déclaré ; les enregistrements ne sont pas encore bons. `last_error` dit pourquoi | | `verifying` | Les enregistrements sont bons ; Wajub route le domaine et obtient son certificat, en quelques minutes | | `active` | Servi. Tous les liens du portail l'utilisent | | `failed` | Pas vérifié en 72 heures ; ou actif, puis en échec à trois vérifications quotidiennes d'affilée, ou sans réponse de votre zone pendant plus de 72 heures d'affilée. Déclarez-le de nouveau pour relancer 72 heures, **avec le même jeton** : l'enregistrement `TXT` déjà posé reste bon | | `removed` | Retiré par vous | | `blocked` | Bloqué par Wajub, qui dit pourquoi dans `removal_reason` : un domaine en service, retiré, en échec, ou jamais déclaré. Aucune plateforme ne peut le déclarer tant que Wajub n'a pas levé le blocage ; il passe alors `removed` | | `last_error` | Signifie | | -------------------- | ----------------------------------------------------------------------------------------------------------- | | `cname_missing` | Aucun `CNAME` sur le domaine, ou un `CNAME` proxifié | | `cname_wrong_target` | Le `CNAME` pointe ailleurs que sur `portals.wajub.app` | | `txt_missing` | Aucun enregistrement `TXT` sur `_wajub-verify.` | | `txt_mismatch` | L'enregistrement `TXT` ne porte pas le jeton | | `dns_unavailable` | Le DNS n'a pas pu être lu : rien n'est conclu, Wajub réessaie 10 minutes plus tard | | `routing_failed` | Les enregistrements sont bons mais le routage n'est pas encore en place : nouvel essai 10 minutes plus tard | | `expired` | Les 72 heures sont passées sans autre erreur connue | ### Le gérer | Appel | Fait | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET /sync/portal_domain` | Votre domaine, en vérification ou actif ; après un retrait ou un échec, le dernier déclaré ; `null` si vous n'en avez jamais déclaré | | `PUT /sync/portal_domain` | Le déclare : `201`. Le même domaine de nouveau ne change rien : `200`, même jeton. Un autre domaine remplace celui encore en vérification ; un domaine `active` doit d'abord être retiré | | `DELETE /sync/portal_domain` | Le retire : le portail cesse aussitôt d'y répondre et les liens reviennent à `votrenom.wajub.app`. Le routage disparaît dans les 10 minutes ; vous pouvez ensuite supprimer les enregistrements DNS | Tous trois s'appellent avec votre propre clé, jamais avec `X-Sync`. `PUT` et `DELETE` demandent une clé live. Retirer un domaine puis le déclarer de nouveau ne coupe jamais le portail sur la nouvelle déclaration : l'ancien routage n'est retiré que si aucune déclaration ne revendique l'hôte. | `error_code` | Statut | Quand | | ------------------------- | ------ | ---------------------------------------------------------------------------- | | `invalid_domain` | `422` | Pas un nom d'hôte : un chemin, un port, un joker, une adresse IP, une espace | | `apex_domain` | `422` | La racine d'une zone, comme `maplateforme.com` ou `shop.co.uk` | | `reserved_domain` | `422` | Un domaine de Wajub | | `live_key_required` | `403` | `PUT` ou `DELETE` avec une clé de test | | `domain_blocked` | `409` | Wajub a bloqué ce domaine | | `domain_taken` | `409` | Déclaré par une autre plateforme, ou domaine de paiement d'un marchand | | `portal_domain_active` | `409` | Vous avez déjà un domaine actif : retirez-le d'abord | | `portal_domain_not_found` | `404` | `DELETE` sans domaine déclaré | ## Ce que voient vos vendeurs Sous **Paramètres, Sync, Plateforme**, **Ce que voient vos vendeurs** fixe votre marque pour eux. Laissé vide, chaque champ reprend **Paramètres, Image de marque** : le nom de votre organisation, sa couleur principale et son logo. | Champ | | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Nom affiché | 60 caractères au plus | | E-mail de support | Les réponses des vendeurs y arrivent (`Reply-To`), une fois l'adresse confirmée par le code que Wajub y envoie (**Envoyer un code**, puis **Confirmer**). La changer demande une nouvelle confirmation | | Couleur | `#rrggbb` | | Logo | PNG, JPEG ou WebP, 1 Mo au plus, 32 à 2 000 pixels de côté. Le SVG est refusé | Le portail, les composants embarqués, les e-mails ci-dessous et les relevés annuels de vos vendeurs l'utilisent. Dans les e-mails, votre nom affiché et votre logo apparaissent une fois votre plateforme approuvée par Wajub pour Lite ou Relay ; avant, le nom de votre organisation et pas de logo. ### Les comptes de versement sur votre domaine Sur votre domaine, vos vendeurs voient leur compte de versement mais le changent sur leur adresse Wajub, `votrenom.wajub.app/payout-account` : vous tenez le certificat de votre domaine, Wajub n'y laisse donc jamais confirmer un changement de destination de l'argent. La page du portail montre les comptes en lecture seule avec un lien qui ouvre cette adresse dans un nouvel onglet, et le [composant embarqué `account`](https://docs.wajub.com/fr/sync/embedded-components#changing-the-payout-account) fait de même. Là, le vendeur se connecte avec son propre code, envoyé au propriétaire de son espace, et reste sur l'adresse Wajub. L'e-mail du code de connexion nomme l'hôte où il a été demandé : le vendeur n'entre le code que là. ### Les e-mails à votre marque Ces e-mails parviennent à vos vendeurs Lite, et à vos vendeurs Relay pour leur invitation, à votre marque : - le code de connexion au portail ; - l'invitation à une connexion `lite` ou `relay` (une invitation `direct` reste celle de Wajub : le marchand ouvre un compte Wajub) ; - leur vérification d'identité : action requise, échéance dépassée, nouvelle vérification, statut changé ; - paiements suspendus ou réactivés, et fin de la connexion ; - un litige ouvert sur leur vente, et son rappel ([Litiges sur les ventes de vos vendeurs](https://docs.wajub.com/fr/sync/disputes)). | Partie | Ce qu'elle dit | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Expéditeur | « votrenom via Wajub », `votrenom` étant le nom d'espace validé par Wajub (`votrenom.wajub.app`), jamais le nom affiché libre ; « Wajub » seul tant qu'aucun nom n'est validé. Depuis l'adresse d'envoi de Wajub : pas de domaine d'envoi personnalisé | | Reply-To | Votre e-mail de support, une fois confirmé | | En-tête et boutons | Votre logo, ou votre nom ; votre couleur, sauf si elle est trop claire pour un texte blanc | | Pied | « Vous recevez cet e-mail au sujet de votre compte vendeur sur Votre plateforme. », puis « Paiements traités par Wajub » et le lien de confidentialité de Wajub | | Liens | Sur votre domaine actif | Deux e-mails restent à la voix de Wajub, quelle que soit votre marque : le code pour changer de compte de versement, qui nomme le nouveau compte (l'opérateur, les 4 derniers chiffres), et l'avis que le compte de versement a changé (4 derniers chiffres, date, reprise des versements, que faire si le vendeur n'en est pas l'auteur). Leur expéditeur est « votrenom via Wajub », leur en-tête ne porte que votre nom d'espace validé, sans votre logo, votre couleur ni votre Reply-To, et leur lien mène à l'adresse Wajub du vendeur, jamais à votre domaine. - [Onboarding](https://docs.wajub.com/fr/sync/onboarding#a-lite-sellers-own-portal): Le portail, son adresse, et le portail dans vos propres pages. - [Composants embarqués](https://docs.wajub.com/fr/sync/embedded-components): Des morceaux de l'espace vendeur dans vos pages. - [Déclarer le domaine du portail](https://docs.wajub.com/fr/api/subaccounts/declare-portal-domain): La spécification de l'endpoint. --- # Payer les vendeurs URL: https://docs.wajub.com/fr/sync/payouts > Versements automatiques et réserve pour les marchands Lite, versements groupés pour Relay. La façon dont un vendeur reçoit son argent dépend du mode de la connexion. Un marchand `direct` pilote son propre compte et retire lui-même : rien sur cette page ne le concerne. Un marchand `lite` n'a pas de dashboard pour retirer, c'est donc Wajub qui le paie. Une marketplace `relay` encaisse tout, et Wajub verse à chaque vendeur ce qui lui revient depuis son solde. ## Lite : Wajub paie le marchand Un marchand Lite est payé au rythme que vous fixez sur la connexion. Chaque versement est un **balayage** : ce qui est disponible sur son solde, moins la réserve, moins la place des frais du versement. | `payout_schedule` | Ce qui se passe | | --------------------- | ------------------------------------------------------------------------- | | `manual` (par défaut) | Rien, jusqu'à ce que vous le demandiez avec `POST /accounts/{id}/payouts` | | `daily` | Payé une fois par jour | | `weekly` | Payé une fois par semaine | | `monthly` | Payé une fois par mois | Les versements programmés passent chaque heure : un vendeur dû est payé dans l'heure du passage, ne comptez donc pas que tous vos vendeurs soient payés à la même seconde. Définissez-le avec `POST /accounts` ou `PUT /accounts/{id}` à tout moment. Contrairement aux capacités et à la tarification, il change directement : le moment où un marchand reçoit son propre argent ne lui retire rien. Il existe sur les comptes `lite` et [`relay`](https://docs.wajub.com/fr/sync/relay#payouts), les deux que Wajub paie : l'envoyer pour un compte `direct` est refusé avec `400`. ```bash title="Payer un marchand Lite maintenant" curl -X POST https://api.wajub.com/accounts/acc_7Yh2MpL4tRb3nP8sZcXv/payouts \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` | Vous recevez | Quand | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` et le `transfer` | Le versement est parti | | `200` avec `transfer: null`, `netted` et `currency` | Relay seulement : ce que le vendeur devait a absorbé tout le versement, rien n'est parti | | `409 There is nothing to pay out yet.` | Le balayage est inférieur à `payout_min_amount`, ou à 1 000 dans la devise du marchand quand la connexion n'en fixe pas | | `409` avec `error_code: payout_limited` | Votre plafond d'exposition retient le versement : voir [Votre plafond d'exposition](#your-exposure-cap) | | `409` avec `error_code: sync_mode_not_approved` | Wajub a retiré votre approbation pour Lite : les versements attendent sur le solde du marchand | | `409` avec `error_code: account_frozen` | Le vendeur est gelé ([Risque vendeur](https://docs.wajub.com/fr/sync/seller-risk#freezing-a-seller)) | | `409` avec `error_code: new_seller_delay` | Le vendeur est nouveau et aucune de ses ventes n'est encore assez ancienne ([Les nouveaux vendeurs sont payés plus tard](https://docs.wajub.com/fr/sync/seller-risk#new-sellers-are-paid-later)) | | `422` avec un motif | La connexion n'est pas `lite`, n'est pas active, n'a pas encore de marchand ou de destination déclarée, ou un plafond de versement est atteint | Une connexion est balayée **au plus une fois par jour**, quel que soit le demandeur. Un second appel le même jour n'envoie rien et renvoie le balayage du jour, quel que soit son statut : regardez `transfer.status`, il peut valoir `failed`, et le balayage suivant est celui du lendemain. Seuls les balayages comptent : un versement que vous avez envoyé vous-même avec `X-Sync` n'est jamais renvoyé ici. Le montant n'est jamais le vôtre à choisir : c'est ce que le marchand peut recevoir. > [!NOTE] > **Pourquoi le versement est un peu inférieur au solde** > > Le balayage laisse la place des frais du versement. Un marchand payé sur un autre compte Wajub ne > paie aucun frais, et son solde est balayé en entier. Seul le solde dans la devise propre du marchand est balayé ; un solde > qu'il détient dans une autre devise attend qu'il le retire lui-même. Chaque versement part vers la destination que le marchand a déclarée dans son portail, et passe les mêmes contrôles que n'importe quel virement, y compris le délai de carence d'une destination tout juste déclarée ou modifiée. ### Ce qui retient de l'argent | Quoi | Où ça se voit | | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | | La [réserve](#the-reserve) | Gardée sur le solde jusqu'à la fin de sa fenêtre | | La [réserve carte](#the-card-reserve) | Une part d'une vente par carte, gardée 120 jours contre les rétrofacturations | | Une vente [bloquée jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds) | Exclue de tout versement jusqu'à votre libération, ou son échéance | | Le [délai des nouveaux vendeurs](https://docs.wajub.com/fr/sync/seller-risk#new-sellers-are-paid-later) | Seules les ventes plus anciennes que le délai sont payées ; `payout_hold.reason: new_seller` | | Un [gel](https://docs.wajub.com/fr/sync/seller-risk#freezing-a-seller) | Rien n'est payé ; `payout_hold.reason: frozen` | | [Votre plafond d'exposition](#your-exposure-cap) | Le reste du versement attend ; `payout_hold.reason: exposure_cap` | Sur chaque vente, ils ne s'additionnent pas : le plus grand est gardé. La réserve carte reste une fois les autres terminés, jusqu'à sa propre date. ## La réserve Un marchand Lite est payé sans rien demander : l'argent peut donc partir alors que l'acheteur peut encore être remboursé. La réserve retient une part de chaque vente jusqu'à ce que cette fenêtre se ferme : **10 % pendant 30 jours** par défaut. | Ensuite | Ce que devient la réserve | | ----------------------------------------------------- | ---------------------------------------------------------- | | Un versement s'exécute | Il envoie tout sauf ce qui est retenu | | Une vente est remboursée, ou un litige sur elle perdu | Le remboursement ou la perte puise d'abord dans la réserve | | La fenêtre se ferme | Cette part est libérée et rejoint le prochain versement | La réserve n'est ni un prélèvement ni un solde à part. L'argent reste celui du marchand ; la réserve dit seulement quelle part ne peut pas encore sortir. Le taux et la durée sont fixés par Wajub pour une connexion, pas par la plateforme. ## La réserve carte Un paiement par carte peut revenir en rétrofacturation jusqu'à **120 jours** après la vente, bien après sa rétention ; un paiement Mobile Money, non. Chaque vente par carte d'un vendeur `lite` ou `relay` garde donc une **réserve carte** : **10 % pendant 120 jours** par défaut, en plus de la rétention de la vente. Wajub peut fixer d'autres conditions pour votre plateforme lors de sa revue, une pour vos vendeurs Lite et une pour vos vendeurs Relay. Une vente garde les conditions sous lesquelles elle a été faite. | Mode | Où elle est gardée | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `lite` | Sur le solde du vendeur, avec la [réserve](#the-reserve) : la plus grande des deux, pour la plus longue des deux durées. Comme la réserve, elle dit seulement quelle part ne peut pas encore sortir | | `relay` | Sur le dû du vendeur. Le versement paie le dû moins sa réserve carte (une ligne `reserve_held`), et l'argent reste sur votre solde : un retrait de votre part qui l'entamerait est refusé avec `reserve_held`. Le premier versement après sa date la paie au vendeur (`reserve_brought_forward`) | | Ensuite | Ce qui se passe | | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Un remboursement ou une rétrofacturation perdue sur la vente | Ils prennent d'abord la réserve carte de cette vente. En `lite`, les autres réserves du vendeur ne suivent que pour ce que son solde ne couvre plus, puis vous | | Relay : la vente est remboursée avant le paiement de son dû | Le dû et sa réserve carte baissent dans la même proportion | | Relay : une réserve carte échue est sous `payout_min_amount` | Elle attend le minimum, et part même en dessous 30 jours après sa date | | Relay : vous mettez fin à la connexion avec `DELETE /accounts/{id}` | Wajub ne paie plus ses dus. La réserve carte reste retenue jusqu'à sa date, car une rétrofacturation peut encore arriver ; elle sort ensuite du plancher de votre solde, et vous réglez vous-même avec le vendeur | | Sa date arrive | Elle est libérée et rejoint le prochain versement | Les portefeuilles adossés à une carte, et ceux par lesquels un payeur peut reprendre un paiement, comptent comme des cartes : une vente payée avec eux garde la réserve carte. Par exemple, une vente Relay par carte de 20 000 XAF, avec 300 de frais Wajub et une commission de 5 %, laisse un dû de 18 700 et une réserve carte de 1 870 : le vendeur reçoit 16 830, puis 1 870 avec le premier versement après 120 jours. Si la vente est perdue en rétrofacturation entre-temps, la réserve est prise, et le vendeur ne doit plus que 16 830. > [!NOTE] > **Le rail Wajub n'encaisse pas encore la carte** > > Le paiement d'un compte `lite`, ou un [paiement partagé](https://docs.wajub.com/fr/sync/split-payments#one-payment-several-sellers), > est encaissé sur le seul rail Wajub, qui ne prend pas la carte aujourd'hui. Le débiter par carte, ou > par un portefeuille compté comme tel, répond `422` avec `error_code: card_not_available`, avant tout > débit, en live comme en sandbox, et la page de paiement ne les propose pas pour lui. Proposez le > Mobile Money. Le jour où le rail prend la carte, le refus disparaît et la réserve carte s'applique. ## Quand un marchand passe en négatif Un remboursement ou un litige perdu peut arriver après qu'un marchand a été payé, quand la réserve ne suffit plus. **C'est vous qui couvrez le reste.** Le manque passe de votre solde à celui du marchand, au moment même où le remboursement ou la perte est traité, et est enregistré contre lui, à hauteur du montant qu'il a pris. | Ce qui arrive | Ce qui se passe | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Un remboursement que vous demandez | Il part si le solde du marchand, la commission que vous rendez et votre solde disponible couvrent le montant. Sinon rien n'est envoyé : le remboursement porte `manual_reason.code: platform_balance_insufficient` et part tout seul dès que votre solde le couvre, pendant 72 heures. Passé ce délai, le support Wajub le traite | | Un litige perdu | Il est débité quoi qu'il arrive, et vous couvrez même si votre solde ne suffit pas : votre solde passe alors sous zéro, et vos versements sont suspendus jusqu'à ce que vos encaissements le comblent | Wajub n'avance jamais un remboursement : il ne part que lorsque l'argent est là. **Tant que votre solde est sous zéro, Wajub ne verse rien à vos vendeurs Lite**, en sandbox (sur votre solde sandbox) comme en live : leur argent attend sur leur solde, et vous recevez `account.payout_limited` avec `reason: insufficient_balance`, que leur `payout_hold.reason` en live indique aussi. Leurs versements reprennent dès que votre solde repasse au-dessus de zéro. Une rétrofacturation perdue au-delà de la [réserve carte](#the-card-reserve), et les frais de litige forfaitaires quand Wajub les prélève, reviennent à : | Mode | La perte | Les frais de litige | | ------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------- | | `lite` | Vous la couvrez, même sans l'argent : votre solde passe sous zéro | Le vendeur ; ce qu'il ne peut pas payer, vous le couvrez | | `relay` | Votre solde ; la part du vendeur devient sa dette, reprise sur ses versements suivants | Vous | | `direct` | La dette du marchand, recouvrée sur ses ventes suivantes | Le marchand | | Un paiement partagé | Votre solde ; chaque part rend sa quote-part | Vous | ### Récupérer ce que vous avez couvert Par défaut, une couverture est enregistrée et rien n'est repris au marchand. Avec `cover_recovery: payouts` sur la connexion, ce que vous avez couvert revient sur votre solde, pris sur ses versements suivants : | Règle | Ce qui se passe | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------ | | Quand | À chaque versement du marchand, automatique ou demandé avec `POST /accounts/{id}/payouts`, avant qu'il parte | | Combien | Au plus ce qui allait être versé : jamais la réserve, jamais sous zéro | | Dans quel ordre | La couverture la plus ancienne d'abord, jusqu'à ce que tout soit revenu | | Un versement trop petit pour partir | La part due est reprise quand même | C'est une condition de la connexion, comme `commission_refund_policy` : le marchand la lit avant d'accepter, et elle ne se modifie avec `PUT /accounts/{id}` que tant que la connexion est encore `pending`. Elle n'existe que sur un compte `lite` : l'envoyer pour un compte `direct` ou `relay` est refusé avec `400`. > [!WARNING] > **C'est l'autre face de Lite** > > Lite vous permet de recruter des marchands sans leur demander de gérer un compte Wajub. Ces > marchands sont les vôtres, et ce qu'ils doivent après un remboursement aussi. Un marchand Direct, > qui gère son propre compte, porte lui-même son solde négatif. ## Votre plafond d'exposition Chaque versement Lite est de l'argent sorti de Wajub alors que la vente peut encore revenir en remboursement ou en litige perdu, que vous couvrez alors. Wajub borne donc ce qu'il verse à vos vendeurs pour votre compte. | Terme | Ce que c'est | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Exposition | Ce que Wajub a versé à vos vendeurs Lite, et à vos vendeurs Relay depuis votre solde, sur les 90 derniers jours, par devise. Une vente par carte compte pendant 120 jours, pour ce qu'elle a laissé au vendeur au-delà de la réserve carte encore gardée | | Plafond d'exposition | Le maximum que cette exposition peut atteindre, fixé par Wajub quand il examine votre plateforme | | Réserve de la plateforme | 10 % de votre exposition par défaut : le plancher que garde votre propre solde disponible | Lite et Relay partagent une exposition, un plafond et une réserve : ceux de votre revue Lite, ou de votre revue Relay si vous n'avez pas de revue Lite. Une vente [bloquée jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds) n'est pas de l'exposition : elle le devient une fois versée. **Au-delà du plafond, les versements ralentissent ; ils ne s'arrêtent jamais net et ne sont jamais repris.** Un balayage verse ce qui reste sous le plafond et le reste attend sur le solde du vendeur, où il reste remboursable. Il part dès que la marge revient, à mesure que les anciens versements sortent de la fenêtre de 90 jours. La première fois que le plafond retient un versement, vous recevez `account.payout_limited`, et le compte porte `payout_hold` jusqu'à ce qu'un versement reparte en entier. Le vendeur lit dans son portail qu'une partie de son versement suivra. **La réserve est un plancher, pas une retenue.** Un retrait de votre part qui ferait passer votre solde disponible en dessous est refusé avec `platform_reserve`. Couvrir le remboursement d'un vendeur n'est jamais refusé pour elle : la réserve existe précisément pour cela. ### Le suivre `GET /sync/limits`, avec votre propre clé et sans `X-Sync`, renvoie une ligne par devise : ```json title="Réponse · 200 OK" { "data": [ { "mode": "lite", "currency": "XAF", "exposure": 4120000, "cap": 5000000, "reserve_percentage": 10, "used_percent": 82.4, "window_days": 90, "card_window_days": 120 } ] } ``` | Champ | | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `mode` | La revue dont les conditions s'appliquent : `lite`, `relay`, ou `null` quand votre plateforme n'a jamais été examinée (les conditions par défaut) | | `exposure`, `cap` | En unités majeures | | `used_percent` | Exposition sur plafond, deux décimales ; 100 quand le plafond vaut 0 et que quelque chose a été versé | | `window_days` | La fenêtre sur laquelle l'exposition est comptée | | `card_window_days` | Combien de temps une vente par carte compte | Les lignes sont votre devise de règlement, les devises pour lesquelles votre revue fixe un plafond, et celles dans lesquelles Wajub a versé à vos vendeurs. Une clé de sandbox reçoit une liste vide : aucun plafond ne s'applique en sandbox. Quand l'exposition d'une devise dépasse **80 %** de son plafond, vous recevez `platform.exposure_warning`, et `platform.exposure_reached` à **100 %** : une fois par franchissement, réarmé quand l'exposition repasse sous 70 %. Un saut direct au-delà de 100 % n'envoie que `platform.exposure_reached`. Ce sont des [livraisons du cycle de vie Sync](https://docs.wajub.com/fr/developer-tools/webhooks/events#sync-lifecycle-deliveries), en live seulement, vérifiées toutes les 15 minutes, qui parviennent aussi par e-mail au propriétaire et aux administrateurs de votre organisation. Un envoi en échec est retenté quelques minutes plus tard, si bien que la même alerte peut arriver deux fois : dédoublonnez sur `X-Idempotency-Key`. ```json title="Une livraison platform.exposure_warning" { "event": "platform.exposure_warning", "sandbox": false, "timestamp": "2026-11-20T10:15:00+00:00", "currency": "XAF", "exposure": 4120000, "cap": 5000000, "used_percent": 82.4, "reserve_percentage": 10, "window_days": 90, "mode": "lite" } ``` Sous **Paramètres, Sync, Plateforme**, **Plafond de versement** montre, par devise, le plafond utilisé, ce qui a été versé à vos vendeurs sur la fenêtre, la marge restante et votre réserve, et les connexions dont les versements attendent, avec la raison. ### Demander un plafond plus élevé Depuis la même section, **Demander un plafond plus élevé** : le plafond voulu par devise, le volume attendu, vos délais de livraison et votre politique de retour. Une demande à la fois. Wajub l'accorde, en tout ou en partie, ou la refuse avec un motif que vous lisez là, et vous prévient par e-mail. ## Ce que règle un versement Chaque versement que Wajub envoie à un vendeur, Lite ou Relay, est accompagné des lignes qu'il règle, écrites une fois au départ. Elles totalisent le montant versé, à l'unité près. | Appel | Renvoie | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `GET /accounts/{id}/payouts` | Les versements de la connexion, du plus récent au plus ancien : `date_from`, `date_to`, `status` (séparés par des virgules), `per_page` | | `GET /accounts/{id}/payouts/{payout}` | Un versement avec ses `lines` et `lines_total` | | `GET /accounts/{id}/dues` | Relay seulement : les dus du vendeur, par `status` (`held`, `payable`, `paid`, `reversed`) | | `type` de ligne | Ce que c'est | | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `sale`, `share` | Une vente, ou une part d'un paiement partagé, avec son brut, ses frais et votre commission | | `refund`, `dispute` | Ce qu'un remboursement ou un litige perdu a repris | | `cover`, `recovery` | Ce que vous avez couvert pour le vendeur, et ce qui vous est revenu sur ce versement | | `debt` | Relay : ce que le vendeur devait, compensé sur ce versement | | `payout_fee` | Les frais du versement lui-même | | `balance_brought_forward`, `reserve_brought_forward` | Ce que le versement précédent a laissé sur le solde ; en Relay, une réserve carte désormais due | | `reserve_held`, `balance_carried_forward` | Ce que ce versement laisse ; en Relay, la réserve carte gardée sur les dus qu'il paie | | `adjustment` | Tout écart qu'aucune autre ligne n'explique : affiché, jamais fondu dans une autre ligne | Le vendeur lit les mêmes lignes sous chaque versement dans son portail, et vous pouvez tous deux les exporter en CSV depuis le Dashboard. Les versements envoyés avant ce rapport n'ont pas de lignes (`lines_total: null`). Pour rapprocher d'un coup tous les versements d'un mois, demandez un [rapport](https://docs.wajub.com/fr/sync/reports) `payout_reconciliation`. ## Tout essayer en sandbox Lite et Relay tournent en sandbox selon les mêmes règles qu'en live, sur les soldes de sandbox, avec des versements de sandbox qui ne quittent jamais Wajub : la réserve, la couverture après un remboursement, le recouvrement, les dus, les dettes et les paiements partagés compris. Les balayages de sandbox tournent à leur rythme comme en live, et `POST /accounts/{id}/payouts` fonctionne avec une clé de sandbox. Pour ne pas attendre des jours la fin de la rétention, une connexion de sandbox peut être avancée : | `POST /accounts/{id}/simulate` | Ce que ça fait | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `{"action": "release_retention"}` | Libère la réserve, les dus Relay retenus et la rétention des parts partagées ; les réserves carte Relay deviennent dues, et le versement suivant les paie | | `{"action": "run_payout"}` | Paie le vendeur tout de suite, même s'il a déjà été payé aujourd'hui | | `{"action": "expire_holds"}` | Amène les ventes [bloquées jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds) à leur échéance tout de suite : elles sont libérées, avec `payment.released` et `reason: auto` | Une clé live reçoit `400` avec `error_code: sandbox_only`, avant toute lecture. ## Quand votre commission ne peut pas être prélevée tout de suite Un marchand `direct` peut encaisser sur ses propres contrats de prestataire. Ces ventes ne passent jamais par un solde Wajub : il n'y a donc rien sur quoi prélever votre commission au moment de la vente. Elle devient une créance : | Ensuite | Ce qui se passe | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | | La vente a lieu | La commission est enregistrée comme due, et `account.commission_receivable_recorded` est envoyé | | La vente est remboursée | La créance est réduite selon le `commission_refund_policy` de la connexion, comme le serait une commission prélevée | | Le solde Wajub du marchand peut la couvrir | Elle est prélevée en entier, et `account.commission_receivable_collected` est envoyé | Le prélèvement ne fait jamais passer le marchand sous zéro : une commission impayée attend que l'argent arrive. `GET /accounts/{id}/commission-receivables` liste ce qu'une connexion vous doit et totalise ce qui reste à percevoir. ## Relay : payer beaucoup de vendeurs d'un coup Une marketplace Relay encaisse tous les paiements. Avec une connexion `relay` par vendeur, Wajub calcule et verse lui-même ce qui revient à chacun : voir [Relay](https://docs.wajub.com/fr/sync/relay). Vous pouvez aussi payer vous-même vos bénéficiaires, depuis votre solde, et une campagne de versements tient en un appel. ```bash title="Une campagne de versements" curl -X POST https://api.wajub.com/transfers/batch \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Idempotency-Key: payout-run-2026-09-30" \ -H "Content-Type: application/json" \ -d '{ "transfers": [ { "beneficiary": "ben_LRQqYvlhrgUOE225KMKU", "amount": 125000, "reference": "seller-42" }, { "beneficiary": "ben_7Hn2Qw9Xk4Lp3Rv8Tb6MzD", "amount": 48000, "reference": "seller-43" } ] }' ``` | Règle | Pourquoi | | ----------------------------------------- | ------------------------------------------------------------------------------- | | Jusqu'à 500 lignes par appel | Au-delà, découpez la campagne | | `Idempotency-Key` est obligatoire | Relancer après un délai dépassé n'envoie que les lignes qui ne sont pas passées | | Chaque `reference` est unique dans le lot | Chaque ligne est dédoublonnée par sa référence | | Les lignes réussissent ou échouent seules | Un vendeur sans destination vérifiée ne bloque pas les autres | La réponse liste chaque ligne avec `accepted` ou `rejected` et le motif. Chaque virement garde votre `reference` et le `batch_reference` de la campagne : c'est ce qui le relie à vos propres données. ### Les vendeurs sont vérifiés avant leur premier versement Wajub paie des vendeurs que vous avez recrutés : sur un compte Relay, le portefeuille de chaque nouveau bénéficiaire est donc comparé au nom que l'opérateur a enregistré, avant tout versement. Déclarez le nom complet du vendeur exactement tel qu'il figure sur son portefeuille. | `verification` sur le bénéficiaire | Ce que cela veut dire | | ---------------------------------- | ----------------------------------------------------------------------------------- | | `verified` | Les noms correspondent ; le vendeur peut être payé | | `name_mismatch` | L'opérateur connaît ce portefeuille sous un autre nom ; les versements sont refusés | | `lookup_unavailable` | L'opérateur n'a pas pu être interrogé ; réessayez plus tard | `verified` vaut `true` ou `false` sur chaque bénéficiaire que vous lisez. Relancez une vérification avec `POST /beneficiaries/{id}/verify`, après une indisponibilité de l'opérateur ou une fois le nom corrigé. Ici l'appel est une barrière, pas une recherche : il répond `422` sauf si le résultat est `verified`, et il ne renvoie jamais le nom que détient l'opérateur. Dans un lot, une ligne qui paie un vendeur non vérifié est refusée seule, et le reste du lot passe. > [!NOTE] > **Uniquement sur les comptes Relay** > > Un compte qui ne fait pas de Relay continue de créer des bénéficiaires payables immédiatement, comme > toujours, et le même appel ne fait que > [l'informer](https://docs.wajub.com/fr/payouts/beneficiaries/create#checking-the-name-on-a-wallet). Contactez Wajub si cette > vérification ne convient pas à votre marketplace. ### Quand un vendeur payé doit rendre de l'argent Une vente est remboursée après que vous en avez payé le vendeur. Le remboursement sort de votre solde, et personne ne peut reprendre de l'argent sur un portefeuille Mobile Money : le vendeur vous le doit donc. Vous seul savez à quel vendeur appartenait la commande, c'est donc vous qui déclarez la dette : ```bash title="Déclarer ce que doit un vendeur" curl -X POST https://api.wajub.com/beneficiaries/ben_LRQqYvlhrgUOE225KMKU/receivables \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 12500, "reference": "order-9981-refund" }' ``` Déclarer à nouveau la même `reference` renvoie la première dette. Wajub l'enregistre et envoie `beneficiary.receivable_recorded`. La suite dépend de votre compte : | Compensation | Ce qui se passe | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Désactivée (par défaut) | Rien d'autre. Vous la récupérez comme vous voulez, puis la marquez avec `POST /beneficiaries/{id}/receivables/{receivable}/settle` | | Activée | Votre prochaine campagne de versements vers ce vendeur est réduite de ce qu'il doit, et `beneficiary.receivable_recovered` est envoyé | Avec la compensation activée, chaque ligne du lot indique `recovered`. Une ligne dont le versement est inférieur à la dette n'envoie rien, répond `status: recovered`, et le reste reste dû. La compensation ne joue que dans `POST /transfers/batch` ; un `POST /transfers` seul envoie toujours ce que vous demandez. Demandez à Wajub d'activer la compensation pour votre compte. > [!NOTE] > **Une ligne échouée rend la dette** > > Si le versement d'une ligne est refusé, ce qu'elle aurait récupéré revient sur la dette. Relancer la > campagne ne récupère jamais deux fois. ### Relevés `GET /beneficiaries/{id}/statement?from=2026-09-01&to=2026-09-30` renvoie tout ce qui a été versé à un vendeur sur une période, jusqu'à un an. Les totaux sont répartis entre `paid`, `in_progress` et `failed` : un versement échoué figure sur le relevé, mais n'est jamais compté comme payé. > [!NOTE] > **Vélocité des versements** > > Trop de versements, ou un montant versé trop élevé, en peu de temps, et le versement suivant est > refusé avec `422`. Les plafonds sont fixés par compte, pour un marchand qui paie ses fournisseurs > et non pour une marketplace qui paie deux cents vendeurs : écrivez au support pour relever les > vôtres avant votre première campagne. [Limites](https://docs.wajub.com/fr/resources/limits#payouts-have-their-own-brakes) - [Capacités du compte](https://docs.wajub.com/fr/sync/account-types): Les trois modes, et ce que chacun engage. - [Intégration des marchands](https://docs.wajub.com/fr/sync/onboarding): Comment un marchand Lite déclare où va son argent. - [Virements et versements](https://docs.wajub.com/fr/payouts/transfers): Un versement seul, et les contrôles que tout versement passe. --- # Démarrage rapide URL: https://docs.wajub.com/fr/sync/quickstart > Créez une connexion, obtenez son autorisation et recevez votre premier paiement par son intermédiaire. Quatre étapes sont nécessaires, et la troisième ne vous appartient pas. Une connexion devient utilisable uniquement après que le marchand s'est connecté et l'a acceptée. Prévoyez donc un aller-retour avec une personne avant votre premier paiement. Toutes ces étapes nécessitent la clé secrète de votre plateforme et un forfait Scale. ## 1. Créer la connexion Vous déclarez ce que la connexion peut faire et ce que vous retiendrez sur celle-ci. Les capacités sont obligatoires et ne peuvent pas être vides. La tarification est facultative. `callback` est la page sur laquelle le marchand revient après avoir accepté, pas une URL de webhook : aucun événement n'y est jamais envoyé. **Créer une connexion** ```bash curl https://api.wajub.com/accounts \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "reference": "shop-amina", "capabilities": ["read", "payments", "refunds"], "pricing": { "percentage_fee": 2.5, "currency": "XAF" }, "callback": "https://example.com/connected" }' ``` ```javascript const account = await wajub.accounts.create({ reference: 'shop-amina', capabilities: ['read', 'payments', 'refunds'], pricing: { percentage_fee: 2.5, currency: 'XAF' }, callback: 'https://example.com/connected', }); console.log(account.id, account.authorization_url); ``` ```python account = wajub.accounts.create({ "reference": "shop-amina", "capabilities": ["read", "payments", "refunds"], "pricing": { "percentage_fee": 2.5, "currency": "XAF" }, "callback": "https://example.com/connected", }) print(account.id, account.authorization_url) ``` ```php $account = $wajub->accounts->create([ 'reference' => 'shop-amina', 'capabilities' => ['read', 'payments', 'refunds'], 'pricing' => [ 'percentage_fee' => 2.5, 'currency' => 'XAF', ], 'callback' => 'https://example.com/connected', ]); echo $account->id; ``` ```go account, err := client.Accounts.Create(ctx, map[string]any{ "reference": "shop-amina", "capabilities": []string{"read", "payments", "refunds"}, "pricing": map[string]any{ "percentage_fee": 2.5, "currency": "XAF", }, "callback": "https://example.com/connected", }, nil) ``` La réponse est `201 Created`. Deux champs sont particulièrement importants. ```json title="Réponse · 201 Created" { "code": 201, "status": "Created", "message": "Account created", "account": { "id": "acc_7Yh2MpL4tRb3nP8sZcXv", "reference": "shop-amina", "sandbox": false, "capabilities": ["read", "payments", "refunds"], "status": "pending", "payment_status": "inactive", "authorization_url": "https://sync.wajub.com/oauth/v2/authorize?access_token=…", "pricing": { "percentage_fee": 2.5, "fixed_fee": 0, "max_fee": 0, "currency": "XAF" }, "created_at": "2026-09-13T10:24:11+00:00" } } ``` `id` est la valeur que vous enverrez dans `X-Sync`. `authorization_url` est le lien que le marchand doit ouvrir, et cette réponse est le seul endroit où il apparaît. Envoyez-le ou conservez-le maintenant, car une lecture ultérieure du sous-compte ne le renvoie pas. `POST /accounts/{id}/token` en génère un nouveau. ## 2. Envoyer son lien au marchand Présentez `authorization_url` au marchand par le moyen qui vous convient : un e-mail, un bouton dans votre propre parcours d'intégration ou un code QR. Il ouvre le lien, se connecte à son compte Wajub, examine les capacités demandées, puis accepte. > [!NOTE] > **Le marchand apporte son propre compte** > > Votre intégration ne crée rien de son côté. Si le marchand ne possède pas encore de compte Wajub, > la page d'autorisation l'accompagne dans sa création. La connexion se termine ensuite. Après son acceptation, `status` passe à `active` et `connected_merchant` contient le nom et l'adresse e-mail de son entreprise. Vous le découvrez en interrogeant régulièrement le compte ou en recevant `account.connected` sur l'un des endpoints de webhook de votre plateforme. Enregistrez l'endpoint dans le Dashboard ou avec `POST /webhooks` et abonnez-le à `account.connected` par son nom : un abonnement `*` ne le reçoit pas. [Livraisons du cycle de vie Sync](https://docs.wajub.com/fr/developer-tools/webhooks/events#sync-lifecycle-deliveries) décrit ce qui arrive. ## 3. Attendre l'activation des paiements En sandbox, `payment_status` passe à `active` dès que le marchand accepte, et vous pouvez débiter immédiatement. En live, cela dépend du marchand : déjà vérifié, la connexion est `active` tout de suite ; encore en cours de vérification, elle reste `inactive` jusqu'à la validation, puis Wajub envoie `account.payment_activated`. Une connexion `lite` attend aussi que le rail Wajub soit accordé au marchand. ## 4. Recevoir un paiement sur la connexion Vous utilisez désormais l'API de paiement classique. Un seul en-tête détermine le propriétaire du paiement. **Débiter pour le compte de la connexion** ```bash curl https://api.wajub.com/payments \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "X-Sync: acc_7Yh2MpL4tRb3nP8sZcXv" \ -H "Content-Type: application/json" \ -d '{ "amount": 50000, "currency": "XAF", "customer": { "email": "buyer@example.com" }, "callback": "https://example.com/return" }' ``` ```javascript const payment = await wajub.payments.create({ amount: 50000, currency: 'XAF', customer: { email: 'buyer@example.com' }, callback: 'https://example.com/return', }, { sync: 'acc_7Yh2MpL4tRb3nP8sZcXv' }); ``` ```python from wajub import RequestOptions payment = wajub.payments.create({ "amount": 50000, "currency": "XAF", "customer": { "email": "buyer@example.com" }, "callback": "https://example.com/return", }, RequestOptions(sync="acc_7Yh2MpL4tRb3nP8sZcXv")) ``` ```php use Wajub\RequestOptions; $payment = $wajub->payments->create([ 'amount' => 50000, 'currency' => 'XAF', 'customer' => [ 'email' => 'buyer@example.com', ], 'callback' => 'https://example.com/return', ], new RequestOptions(sync: 'acc_7Yh2MpL4tRb3nP8sZcXv')); ``` ```go payment, err := client.Payments.Create(ctx, map[string]any{ "amount": 50000, "currency": "XAF", "customer": map[string]any{"email": "buyer@example.com"}, "callback": "https://example.com/return", }, &wajub.RequestOptions{Sync: "acc_7Yh2MpL4tRb3nP8sZcXv"}) ``` Le paiement appartient désormais au marchand. Il apparaît dans son Dashboard, est réglé sur son solde et déclenche ses webhooks. Les vôtres sont aussi déclenchés avec une copie du même événement. ## Ce que vous recevez après sa réussite Lorsque le paiement est terminé, Wajub applique la tarification de la connexion, calcule votre commission sur le montant du paiement et la crédite à votre plateforme. Un webhook vous en informe. ```json title="fee.received (extrait)" { "id": "evt_2Hq8Ln4Vx7Rb9Tk3Mz6Pd1Wc", "event": "fee.received", "data": { "amount": 1250, "currency": "XAF", "percentage": 2.5, "fixed_amount": null, "account": { "id": "acc_7Yh2MpL4tRb3nP8sZcXv", "reference": "acc_7Yh2MpL4tRb3nP8sZcXv" }, "created_at": "2026-09-29T10:30:00+00:00" }, "livemode": true, "created": "2026-09-29T10:30:00+00:00" } ``` Rapprochez les commissions par connexion, sur `account.id`. Le marchand reçoit l'événement inverse, `fee.charged`, sur ses propres endpoints. Grâce à ces deux événements, chaque partie peut contrôler la commission sans interroger l'autre. > [!WARNING] > **Définissez correctement la tarification avant l'étape 2** > > Une fois que le marchand a accepté, la tarification et les capacités relèvent de son accord : les > modifier répond `202` et attend qu'il accepte dans son propre dashboard, pendant que la connexion > continue sur les conditions convenues. Décider de votre commission avant d'envoyer le lien évite > cet aller-retour à tout le monde. - [Sync](https://docs.wajub.com/fr/sync): La nature d'une connexion et ses limites. - [Capacités du compte](https://docs.wajub.com/fr/sync/account-types): Les sept capacités et le calcul de la commission. - [Intégration des marchands](https://docs.wajub.com/fr/sync/onboarding): Le cycle de vie, le lien d'autorisation et ce qui est figé. - [Paiements fractionnés](https://docs.wajub.com/fr/sync/split-payments): Pourquoi un paiement ne peut pas être partagé entre deux marchands. --- # Remboursements URL: https://docs.wajub.com/fr/sync/refunds > Qui demande un remboursement, qui l'envoie et qui le paie, selon le mode de la connexion et l'endroit où la vente a été encaissée. Un remboursement sur une vente apportée par une connexion pose trois questions distinctes : qui le demande, qui renvoie l'argent au payeur, et sur quel argent. Le mode de la connexion répond à la première ; l'endroit où la vente a été encaissée répond aux deux autres. ## Qui fait quoi | Vente | Qui demande | Qui renvoie l'argent | Sur quel argent | S'il manque de l'argent | | ----------------------------------- | ----------------------------------------------- | ---------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `direct`, sur le rail Wajub | Le marchand, ou vous avec la capacité `refunds` | Wajub | Le solde Wajub du marchand | Le remboursement attend ; un litige perdu devient sa dette | | `direct`, sur ses propres contrats | Les mêmes | Son prestataire, ou lui-même | Son compte chez le prestataire | Entre lui et son prestataire | | `lite` (toujours sur le rail Wajub) | Vous, avec la capacité `refunds` | Wajub | Le solde Wajub du vendeur | Sa réserve, puis votre solde | | `relay` | Vous, avec `X-Sync` | Wajub, ou votre prestataire | Votre solde | Le remboursement attend ; un litige perdu devient votre dette. Côté vendeur, son dû est réduit, ou ce qu'il doit est retenu sur son prochain versement ([Relay](https://docs.wajub.com/fr/sync/relay#when-a-sale-is-refunded)) | Vous demandez un remboursement avec `POST /refunds` et l'en-tête `X-Sync`, sur un paiement que cette connexion a apporté. Un vendeur `lite` ne peut pas en demander : son portail ne fait que montrer ses ventes et ses versements. ## Sur le rail Wajub : l'argent doit être là Wajub renvoie l'argent au payeur, puis débite le solde du marchand une fois le remboursement confirmé. **Wajub n'avance jamais un remboursement** : il ne part que si l'argent qui le couvre est là. | Ce qui compte | Pourquoi | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Le solde du marchand | C'est de là que sort le remboursement | | La commission que vous rendez | Elle revient sur son solde juste avant le débit, selon votre `commission_refund_policy`, dans la limite de ce que vous détenez encore : un marchand qui n'a rien retiré peut donc toujours rembourser sa vente en entier | | En `lite`, votre solde disponible | Vous couvrez ce que le vendeur ne détient plus, à hauteur du montant remboursé | Quand cela ne suffit pas, rien n'est envoyé. Le remboursement reste `pending`, avec `execution_mode: manual` et un `manual_reason.code` : | `code` | Ce qui manque | | ------------------------------- | ------------------------------------------ | | `insufficient_balance` | Le solde du marchand | | `platform_balance_insufficient` | En `lite`, le solde du vendeur et le vôtre | Il **part tout seul** dès que l'argent arrive, pendant 72 heures à compter de la demande, et `refund.updated` vous prévient de chaque changement. Passé ce délai, le support Wajub le traite. > [!NOTE] > **Un remboursement en route réserve son argent** > > Entre l'envoi d'un remboursement et son débit, son montant reste sur le solde : un retrait qui y > toucherait est refusé avec `refund_in_flight`, le versement automatique d'un vendeur `lite` le > laisse en place, et un second remboursement ne compte pas dessus. En `lite`, la part sur laquelle > votre solde a été compté y est réservée de la même façon : ni un retrait de votre part, ni le > remboursement d'un autre vendeur ne peut la dépenser avant le débit du remboursement. ## Un litige perdu est toujours débité Un litige perdu ne demande rien à personne : il est débité quel que soit le solde. Le manque appartient au marchand en `direct`, et à vous en `lite` et en `relay`. En `lite`, vous couvrez même si votre solde ne suffit pas : il passe alors sous zéro, et vos versements sont suspendus jusqu'à ce que vos encaissements le comblent. [Quand un marchand passe en négatif](https://docs.wajub.com/fr/sync/payouts#when-a-merchant-goes-negative) Une vente [bloquée jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds) est encore du côté du vendeur : un remboursement ou un litige perdu est pris sur l'argent bloqué, et vous ne couvrez jamais cette partie. Un vendeur Lite peut répondre lui-même à un litige sur sa vente : [Litiges sur les ventes de vos vendeurs](https://docs.wajub.com/fr/sync/disputes). ## Hors du rail Wajub Une vente qu'un marchand `direct` encaisse sur ses propres contrats n'est jamais passée par un solde Wajub : Wajub n'avance rien et ne débite rien. `execution_mode` dit qui envoie le remboursement, comme pour n'importe quel marchand. [Qui envoie un remboursement live](https://docs.wajub.com/fr/payments/refunds#who-sends-a-live-refund) ## Votre commission `commission_refund_policy`, sur la connexion, dit ce que vous rendez : au prorata du montant remboursé (par défaut), la totalité dès le premier remboursement, ou rien. Une commission qui était encore une créance, parce que la vente a été encaissée hors du rail, est réduite de la même façon. Ce qui revient ne fait jamais passer votre solde sous zéro. C'est plafonné à ce que vous détenez à ce moment-là, dans le solde où se trouve l'argent de la vente, moins ce que d'autres remboursements en route y réservent. Ce que vous ne détenez plus n'est jamais rendu et ne devient pas une dette : le vendeur supporte le remboursement sans cette part. Les frais `sync_fee_reversal` indiquent ce qui a vraiment été rendu et, en cas de plafond, `metadata.capped: true` et `metadata.policy_amount`, ce que votre politique aurait rendu. [Quand la vente est remboursée](https://docs.wajub.com/fr/sync/account-types#when-the-sale-is-refunded) ## Récupérer ce que vous avez couvert En `lite`, `cover_recovery: payouts` reprend ce que vous avez couvert sur les versements suivants du vendeur. [Récupérer ce que vous avez couvert](https://docs.wajub.com/fr/sync/payouts#getting-back-what-you-covered) - [Remboursements](https://docs.wajub.com/fr/payments/refunds): Créer un remboursement, et le suivre jusqu'à son issue. - [Payer les vendeurs](https://docs.wajub.com/fr/sync/payouts): La réserve, la couverture et ce que vous récupérez. - [Capacités du compte](https://docs.wajub.com/fr/sync/account-types): Les trois modes, les capacités et la commission. --- # Relay URL: https://docs.wajub.com/fr/sync/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. --- # Rapports et relevés URL: https://docs.wajub.com/fr/sync/reports > Rapprochez chaque versement à vos vendeurs, déclarez votre commission, et remettez à chaque vendeur un relevé annuel à votre marque. Votre comptable rapproche chaque versement fait à vos vendeurs de votre relevé bancaire ou opérateur, et déclare votre commission. Demandez à Wajub un **rapport**, sous **Sync, Rapports** ou avec `POST /sync/reports` : il est préparé en arrière-plan, en général en une minute ou deux, puis - `report.ready` parvient à vos endpoints ; - le membre qui l'a demandé dans le Dashboard reçoit un e-mail, avec un lien vers le Dashboard, jamais vers le fichier ; - il est gardé **30 jours**, et se télécharge par un lien **signé pour 15 minutes**. ## Les cinq rapports | `type` | Formats | Contient | | ----------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `payout_reconciliation` | `csv`, `xlsx` | Chaque élément de chaque versement à chaque vendeur, une ligne chacun | | `seller_summary` | `csv`, `xlsx` | Par vendeur et devise : ventes, remboursements, litiges perdus, commission prise, rendue et nette, versé ; et, au moment de la préparation, ce qui lui est dû, ce qui est retenu, sa dette de couverture | | `platform_commission` | `csv`, `xlsx` | Votre commission par mois, vendeur et devise : prise, rendue, nette | | `relay_dues` | `csv`, `xlsx` | Les dus de vos vendeurs Relay : leur état, et le versement qui les a payés | | `seller_statement` | `pdf` | Le relevé d'un vendeur Lite ou Relay sur la période | | Règle | | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Période | Jours UTC, de `period_start` à minuit jusqu'à la fin de `period_end`, **366 jours au plus** | | Montants | Unités majeures avec leur devise, en décimal exact avec les décimales de la devise (`19000.00`, `-286.50`). Un montant négatif reste un nombre | | Dates | ISO 8601 UTC avec décalage (`2026-11-06T07:00:00+00:00`) ; un jour seul en `YYYY-MM-DD` | | Colonnes stables | `format_version` (aujourd'hui `1`) est dans le rapport **et dans le nom du fichier** : `payout_reconciliation_v1_2026-11-01_2026-11-30.csv`. Une colonne ne change jamais de sens dans une version | | Données personnelles | Le nom du vendeur seulement. Aucune adresse e-mail, aucun numéro de téléphone, aucune pièce d'identité | | CSV | UTF-8 avec BOM, virgule, guillemets RFC 4180, noms des colonnes en première ligne. Une cellule texte qui commence par `=`, `+`, `-` ou `@` reçoit une apostrophe devant : elle n'est jamais exécutée comme une formule | | XLSX | Une feuille, « Report », en-tête en gras figé ; textes en chaînes, jamais en formules ; montants et compteurs en nombres. Au-delà de 1 048 576 lignes, il échoue avec `too_many_rows` : demandez-le en CSV | | Clé de test | Préparé sur les données de test (`rpt_test_…`), avec `report.ready` en test | | Attente | 5 rapports au plus à la fois, en préparation ou en file. Un rapport encore `pending` peut être annulé sous **Sync, Rapports** : il passe `failed` avec `cancelled` et libère sa place | ## En demander un ```bash title="Les versements de novembre, en CSV" curl https://api.wajub.com/sync/reports \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{"type":"payout_reconciliation","format":"csv","period_start":"2026-11-01","period_end":"2026-11-30"}' ``` | Champ | | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | Requis : l'un des cinq ci-dessus | | `period_start`, `period_end` | Requis, `YYYY-MM-DD`, UTC ; `period_end` le même jour que `period_start` ou après | | `format` | `csv` ou `xlsx` pour un export, requis ; `pdf` pour un relevé, la valeur par défaut | | `account` | Le `acc_…` du vendeur, requis pour `seller_statement` : un de vos comptes `lite` ou `relay`, du même environnement | | `locale` | La langue d'un `seller_statement` : `en`, la valeur par défaut, ou `fr`. Les exports sont les mêmes dans les deux : leurs colonnes ne changent jamais. Toute autre valeur répond `422` | La réponse est `202` avec le `report`, `pending`. Appelé avec votre propre clé, jamais avec `X-Sync`. | `error_code` | Statut | Quand | | ------------------------- | ------ | ------------------------------------------------------------------------------------ | | `format_not_available` | `422` | `pdf` pour un export, `csv` ou `xlsx` pour un relevé, ou aucun format pour un export | | `period_too_long` | `422` | Plus de 366 jours | | `account_required` | `422` | `seller_statement` sans `account` | | `statement_not_available` | `400` | Un relevé pour un compte `direct` : il a ses propres rapports Wajub | | `too_many_reports` | `429` | 5 rapports déjà en attente | | | `404` | `account` inconnu, d'une autre plateforme, ou de l'autre environnement | ## Le télécharger Quand `report.ready` arrive, `GET /sync/reports/{id}` rend le rapport avec `url`, un lien signé pour 15 minutes (`url_expires_at`). Rappelez-le pour un lien neuf, et ne stockez jamais le lien. | `status` | | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pending`, `building` | En route. Une année d'une grande plateforme peut rester `building` quelques minutes : vous recevez tout de même un seul fichier, et un seul `report.ready` | | `ready` | `url`, `row_count` (exports, sans l'en-tête), `file_name`, `file_size` en octets, `completed_at`, `expires_at` | | `failed` | `failure_reason` : `too_many_rows` (un XLSX au-delà de la dernière ligne d'Excel, demandez-le en CSV), `build_failed` (trois essais ont échoué, redemandez-le) ou `cancelled` (annulé dans le Dashboard). Un rapport en échec ne compte plus parmi les 5 | | `expired` | Le fichier a été supprimé après 30 jours | `report.ready` est envoyé une fois par rapport. C'est une [livraison du cycle de vie Sync](https://docs.wajub.com/fr/developer-tools/webhooks/events#sync-lifecycle-deliveries) : listez-le par son nom. Son corps porte `event`, `sandbox`, `timestamp` et le `report`, sans lien. Un rapport en échec n'envoie rien : lisez-le avec `GET`. ## Les colonnes de `payout_reconciliation` Une ligne par **élément** de chaque versement que Wajub a fait à vos vendeurs. Un versement est dans la période par sa **date de valeur**, ou, pas encore payé, par sa création. **Les `amount` des lignes d'un versement totalisent son `payout_amount`, au centime.** Les versements se suivent dans ce même ordre, par date de valeur (ou création), puis versement par versement, et les lignes d'un versement gardent leur ordre (`line`). | Colonne | | | -------------------------------------------------- | ------------------------------------------------------------------------------------- | | `payout_id`, `payout_status` | `po_…` ; `pending`, `processing`, `succeeded`, `failed` ou `cancelled` | | `payout_created_at`, `payout_value_date` | Création ; date de valeur, vide tant qu'il n'a pas réussi | | `operator_reference` | La référence de l'opérateur, celle de votre relevé | | `payout_amount`, `currency` | Ce que le versement a payé | | `account`, `account_type`, `seller_name` | Le vendeur | | `line`, `element`, `amount` | Le rang de la ligne dans le versement, ce qu'elle est, et sa part signée du versement | | `payment`, `refund`, `dispute` | Les identifiants publics concernés | | `occurred_at` | Quand l'élément a eu lieu | | `escrow_amount`, `hold_status`, `hold_released_at` | Le [blocage jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds) de la vente concernée | | `element` | Signe | | | ---------------------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `sale`, `share` | + | Une vente, ou une part d'un paiement partagé, brute | | `wajub_fee` | − | Les frais de Wajub sur elle | | `commission` | − | Votre commission | | `refund`, `dispute` | − | Ce qu'un remboursement ou un litige perdu a repris | | `commission_returned` | + | Votre commission rendue avec lui | | `cover`, `recovery` | + / − | Ce que vous avez couvert pour le vendeur, et ce que vous avez repris | | `debt` | − | La dette d'un vendeur Relay, compensée | | `payout_fee` | − | Les frais du versement lui-même | | `reserve_brought_forward`, `balance_brought_forward` | + | Ce que le versement précédent avait laissé | | `reserve_held`, `balance_carried_forward` | − | Ce que ce versement laisse pour plus tard | | `adjustment` | ± | Un mouvement de solde qu'aucun autre élément n'explique | | `rounding` | ± | Un écart au centime entre le brut, les frais, la commission et ce qui a été versé | | `escrow_released` | 0 | Une vente Lite bloquée libérée depuis le versement précédent, payée au travers de `balance_brought_forward` ; `escrow_amount` dit combien | | `unreported` | + | Un versement dont le détail n'a jamais été écrit : une ligne de tout son montant | Les autres exports donnent leurs colonnes de la même façon, dans l'en-tête du fichier : `seller_summary` (`balance_due`, `withheld` et `cover_debt` sont ceux du moment de la préparation, `as_of`, et vides pour un vendeur `direct` ; sa dernière colonne, `card_reserve`, est ce que les ventes par carte du vendeur gardent contre les rétrofacturations, compris dans `withheld`), `platform_commission` (une ligne par mois, vendeur et devise) et `relay_dues` (un dû par ligne, `outstanding` comme le lit `GET /accounts/{id}/dues`). ## Les relevés de vos vendeurs Un `seller_statement` est un PDF pour un vendeur Lite ou Relay, **à votre marque** : par devise, ce qui a été encaissé pour lui, remboursé, perdu en litige, gardé comme votre commission et versé, puis mois par mois. Il dit être un justificatif pour sa comptabilité, pas une déclaration fiscale ; les frais de Wajub sont dans le détail de chaque versement. Par l'API, il est en anglais sauf si vous demandez `locale: fr` ; depuis le Dashboard, dans la langue du membre qui le demande. Un litige que le marchand a accepté ne compte qu'une fois, dans les litiges perdus, jamais aussi dans les remboursements : dans le relevé, dans `seller_summary` et dans les chiffres du vendeur. Les remboursements ordinaires restent dans les remboursements. | Qui | Où | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Vous | La page du vendeur dans **Sync, Comptes**, un bouton par année depuis sa connexion ; ou `POST /sync/reports` sur toute période de 366 jours au plus | | Un vendeur Lite | Son portail, sous Versements | | Un vendeur Lite ou Relay, dans vos pages | Le [composant](https://docs.wajub.com/fr/sync/embedded-components) `payouts` montre ses relevés par année | - [Analyses](https://docs.wajub.com/fr/sync/analytics): Le même grand livre, en chiffres sur une période. - [Ce que règle un versement](https://docs.wajub.com/fr/sync/payouts#what-a-payout-settles): Les lignes de chaque versement, dans l'API. - [Demander un rapport](https://docs.wajub.com/fr/api/subaccounts/create-report): La spécification de l'endpoint. --- # Risque vendeur URL: https://docs.wajub.com/fr/sync/seller-risk > 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. --- # Paiements fractionnés URL: https://docs.wajub.com/fr/sync/split-payments > Paiement en plusieurs fois, commission par connexion, et un paiement partagé entre plusieurs vendeurs. Trois fonctionnalités sans rapport entre elles se cachent derrière le mot « split ». Cette page dit laquelle est laquelle. | Sens possible | Nom utilisé ici | Emplacement | | ------------------------------------------------------------ | -------------------------- | ----------------------------- | | Un payeur règle en plusieurs fois | Paiement en plusieurs fois | `POST /payments/{id}/splits` | | Votre plateforme conserve une part du paiement d'un marchand | Tarification par connexion | L'en-tête `X-Sync` | | Un paiement est partagé entre plusieurs vendeurs | Paiement partagé | `shares` sur `POST /payments` | ## Paiement en plusieurs fois Cette fonctionnalité n'a aucun rapport avec les marketplaces. Le même payeur règle un seul paiement en deux, trois ou quatre tranches, débitées successivement. `POST /payments/{id}/splits` > [!WARNING] > **Désactivé par défaut, et Mobile Money uniquement en live** > > Activez d'abord **Paiements fractionnés manuels** dans les réglages [**Paiement — Devises**](https://dashboard.wajub.com/settings/regional/currency), où vous > choisissez aussi les nombres de tranches autorisés et un montant minimum. En live, les tranches > ne sont débitées que sur les canaux Mobile Money : carte, banque et crypto répondent `422`. L'appel débite le paiement comme `POST /payments/{id}` et prend donc les mêmes `channel` et `data`. Envoyez `split_count` pour obtenir des tranches égales, ou `split_amounts` pour des tranches différentes. Ces deux champs sont mutuellement exclusifs. La somme de `split_amounts` doit être égale à ce que paie le payeur : le `amount` du paiement, ou son `amount_total` quand le payeur supporte les frais. ```bash title="Trois tranches égales" curl https://api.wajub.com/payments/trx_CSUGajfv9xh0XQ5wu2lx/splits \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "channel": "cm.mtn", "data": { "phone": "+237670000000" }, "split_count": 3 }' ``` `split_count` accepte uniquement les valeurs 2, 3 ou 4. Pour obtenir des tranches inégales, envoyez vous-même les montants. ```bash title="Tranches inégales" curl https://api.wajub.com/payments/trx_CSUGajfv9xh0XQ5wu2lx/splits \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "channel": "cm.mtn", "data": { "phone": "+237670000000" }, "split_amounts": [4000, 3000, 3000], "split_currency": "XAF" }' ``` Envoyez entre deux et quatre valeurs, chacune au moins égale à 0,01 et dans la précision de la devise : des francs entiers en XAF et en XOF. Un payeur, un paiement, plusieurs débits. ### Ce que fait chaque appel Le premier appel fixe le plan et débite la première tranche. Chaque appel suivant débite la suivante : envoyez-le avec les mêmes `channel` et `data`, sans `split_count` ni `split_amounts`, ou avec le même plan. Un plan différent est refusé avec un `422`. Dès qu'un paiement a un plan, tout débit de ce paiement, `POST /payments/{id}` ou la page de paiement, prend la tranche suivante, jamais le montant entier. | L'appel | Ce que vous recevez | | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | Débite une tranche que l'opérateur confirme aussitôt | `200`, le paiement `partial`, ou `succeeded` sur la dernière tranche | | Débite une tranche que le payeur doit approuver | `202`, le paiement `processing` jusqu'à la réponse du payeur | | Arrive alors qu'une tranche attend encore le payeur | `202` qui nomme cette tranche. Rien de plus n'est débité | | Débite une tranche que l'opérateur refuse | `402`, cette tranche `failed`, le paiement revenu à `partial`, ou à `pending` si rien n'a encore été payé | Chaque réponse porte la tranche dans `transaction.split` : son `id`, `split_number`, `total_splits`, `amount` et `status`. Les tranches égales sont en unités entières, et la dernière prend le reste : 10 000 XAF en trois font 3 333, 3 333 et 3 334. Une tranche refusée est débitée de nouveau par l'appel suivant. Les tranches déjà payées le restent : `amount_collected` est leur total, et le paiement ne revient jamais à `pending` une fois qu'une somme a été encaissée. ### Quand l'argent est à vous Chaque tranche est à vous dès qu'elle passe : elle est créditée sur votre solde aussitôt, sous la retenue habituelle, et paie sa part des frais Wajub à ce moment-là, en live comme en sandbox. Quand le payeur prend les frais à sa charge, vous êtes crédité de votre part de chaque tranche et les tranches s'additionnent jusqu'à `amount`. Le paiement passe à `succeeded` avec sa dernière tranche, et n'expire pas tant qu'il est `partial`. Chaque tranche envoie `payment.split.processing`, puis `payment.split.succeeded` ou `payment.split.failed` ; `payment.succeeded` arrive une fois, avec la dernière. [Les événements de tranche](https://docs.wajub.com/fr/developer-tools/webhooks/events#payment-splits) décrivent le contenu. ### Quand le payeur cesse de payer Rien ne clôt un paiement `partial` de lui-même. C'est vous qui décidez, avec [`POST /payments/{id}/close`](https://docs.wajub.com/fr/api/payments/close) et un `outcome` : | `outcome` | Ce qui se passe | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `keep` | Le paiement devient `succeeded` pour ce qui a été encaissé (`amount_paid`), déjà sur votre solde. Les tranches impayées sont abandonnées | | `refund` | La même chose, puis un remboursement de tout ce qui a été encaissé est ouvert aussitôt | `payment.succeeded` est envoyé une fois, comme pour un paiement réglé en entier ; les remboursements et le statut `refunded` se mesurent ensuite à ce qui a été encaissé. Une clôture pendant qu'une tranche attend le payeur répond `409` `payment_in_progress`, et `DELETE /payments/{id}` refuse un paiement dont des tranches sont déjà payées (`409` `payment_partly_paid`) : clôturez-le plutôt. Chaque tranche doit tenir sous le plafond par transaction du Mobile Money. Un débit unique au-dessus est refusé avec un `422`, en live comme en sandbox : rien ne fractionne un paiement de lui-même, les tranches sont votre choix. Le remboursement d'un paiement réglé en tranches n'est pas immédiat : prévoyez un délai plus long que pour un remboursement ordinaire. ## Tarification par connexion Cette fonctionnalité concerne les marketplaces. Un paiement attribué à une connexion appartient au marchand correspondant. Votre plateforme reçoit la commission configurée sur cette connexion. ```bash title="Un paiement qui rapporte une commission à votre plateforme" curl https://api.wajub.com/payments \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "X-Sync: acc_7Yh2MpL4tRb3nP8sZcXv" \ -H "Content-Type: application/json" \ -d '{ "amount": 50000, "currency": "XAF", "customer": { "email": "buyer@example.com" } }' ``` Vous ne pouvez pas remplacer la commission pour une requête particulière. Elle provient des règles associées à la connexion, figées lors de l'acceptation du marchand. Le payload ne contient aucun champ de frais. [Capacités du compte](https://docs.wajub.com/fr/sync/account-types) explique comment la règle est choisie et limitée. ## Un paiement, plusieurs vendeurs Un panier de trois vendeurs peut être **un seul paiement** : l'acheteur autorise une fois, et Wajub répartit l'argent à la réussite. Créez le paiement avec votre propre clé, **sans** `X-Sync`, et listez les parts dans `shares`. ```bash title="Un panier, deux vendeurs et votre propre part" curl https://api.wajub.com/payments \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 30000, "currency": "XAF", "reference": "basket-8812", "shares": [ { "account": "acc_7Yh2MpL4tRb3nP8sZcXv", "amount": 18000, "reference": "basket-8812-a" }, { "account": "acc_Gt6yU3nE8rM1kS5vX9bQ", "amount": 9000, "reference": "basket-8812-b" } ] }' ``` | Règle | | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Chaque part | Nomme une de vos connexions actives, de n'importe quel mode, avec la capacité `payments` et `payment_status: active` ; une fois au plus | | Les parts | Totalisent au plus le montant ; le reste est votre propre part. Même devise que le paiement. 50 parts au plus | | Encaissement | Sur le rail Wajub seulement : l'argent doit arriver chez Wajub pour être réparti. Le rail ne prend pas encore la carte : une carte répond `422` avec `error_code: card_not_available` ([La réserve carte](https://docs.wajub.com/fr/sync/payouts#the-card-reserve)) | | Pas avec | `X-Sync`, un paiement différé, ni un paiement en plusieurs fois | | En live | Une part `lite` ou `relay` demande votre approbation pour ce mode ([Votre plafond d'exposition](https://docs.wajub.com/fr/sync/payouts#your-exposure-cap)) | | Bloqué | `hold` bloque toutes les parts jusqu'à votre libération, `shares[].hold` une seule part ([Bloquer jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds)) | Cinquante parts sont réparties aussi vite qu'une : chaque part passe à son vendeur seule, sans attendre les autres. À la réussite, chaque part va à son vendeur comme s'il l'avait vendue seul : les frais de Wajub sont répartis au prorata des parts (la vôtre comprise), et votre commission vient du `pricing` de cette connexion, appliqué à la part. | Le mode de la part | Ce que reçoit le vendeur | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `direct` ou `lite` | La part, moins sa part de frais et votre commission, sur son solde, sous la rétention de la vente. Une part `lite` alimente aussi la réserve du vendeur | | `relay` | Un dû, versé comme toute vente [Relay](https://docs.wajub.com/fr/sync/relay) | Le paiement est le vôtre : ses webhooks arrivent à votre plateforme, et il renvoie `shares` avec, pour chaque part, `account`, `amount`, `commission`, `status` et `refunded`. Un vendeur ne voit que sa part. ### Rembourser un paiement partagé `POST /refunds` prend `shares`, les parts à rembourser : `[{ "account": "acc_…", "amount": 5000 }]`. Sans cette liste, le remboursement est réparti sur toutes les parts au prorata, la vôtre comprise ; `shares: []` rembourse votre seule part. Une part n'est jamais remboursée au-delà de ce qu'elle a reçu. Un remboursement qui **vide le paiement**, sans `amount` ou pour tout ce qui reste à rembourser, reprend à chaque part tout ce qui lui reste, même à une part déjà remboursée en partie : aucun vendeur ne garde une fraction de ce que l'acheteur récupère, pas même les unités que les remboursements précédents au prorata ont arrondies vers le bas, si bien que chaque part finit à zéro. Il ne le fait que si aucun autre remboursement du paiement n'attend encore d'être réparti, et si ce que gardent les parts tient dans le remboursement, ces arrondis mis à part ; sinon il est réparti au prorata. Un remboursement ne reprend jamais aux vendeurs plus que son propre montant, au-delà de ces arrondis : une unité mineure par part, au plus, pour chaque remboursement ou litige perdu précédent. Chaque part revient selon les règles de son mode : votre commission revient d'abord, puis le solde du vendeur ; sur une part `lite`, vous couvrez ce que le vendeur n'a plus ; sur une part `relay`, le dû est réduit, ou ce que le vendeur doit est enregistré. **Un remboursement ne part que si toutes les parts qu'il touche sont couvertes** : sinon rien n'est envoyé, et il attend avec `insufficient_balance` ou `platform_balance_insufficient`, comme tout remboursement. Un litige perdu est réparti au prorata et toujours débité. | `error_code` (`422` sauf mention) | Quand | | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `too_many_shares`, `share_account_duplicated`, `shares_exceed_amount`, `share_currency_mismatch` | La liste elle-même est fausse | | `share_account_not_found`, `share_account_not_active`, `share_account_not_allowed` | Une part nomme une connexion qui n'est pas la vôtre, pas active, ou sans `payments` | | `shares_with_sync_header`, `shares_with_deferred` | Combinée avec ce qu'elle ne peut pas être | | `shares_with_installments` | `POST /payments/{id}/splits` sur un paiement partagé : il ne peut pas être payé en plusieurs fois | | `sync_mode_not_approved` (`403`) | En live, une part `lite` ou `relay` sans votre approbation pour ce mode | | `account_frozen` (`403`) | Une part pour un vendeur que vous avez gelé avec `block_payments` ([Risque vendeur](https://docs.wajub.com/fr/sync/seller-risk#freezing-a-seller)) | | `hold_not_available_for_direct`, `hold_max_days_exceeded` | Un `hold` sur une part `direct`, ou plus long que le compte ne le permet ([Bloquer jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds#hold-a-sale)) | | `wajub_rail_required` (`409`) | Le rail Wajub n'est pas ouvert sur votre compte | | `card_not_available` | Le paiement est débité par carte, ou par un portefeuille compté comme tel, que le rail Wajub n'encaisse pas encore | | `refund_share_not_found`, `refund_share_exceeds_remaining`, `refund_shares_exceed_amount`, `refund_platform_part_exceeds_remaining` | Les `shares` d'un remboursement ne correspondent pas au paiement | | `payment_not_shared` | Des `shares` de remboursement sur un paiement qui n'en a pas | | `shares_not_distributed` (`409`) | Les parts du paiement ne sont pas encore réparties : réessayez dans quelques minutes | ## Le payout d'un marchand constitue encore une autre opération Aucune de ces fonctionnalités ne transfère de l'argent vers le compte bancaire ou le portefeuille d'un marchand. Les fonds d'un paiement connecté sont réglés sur le propre solde Wajub du marchand, et la façon dont ils en sortent dépend du mode : un marchand `direct` retire lui-même, un marchand `lite` est payé automatiquement par Wajub, et une marketplace `relay` paie ses vendeurs par lots. Les trois sont décrits dans [Payer les vendeurs](https://docs.wajub.com/fr/sync/payouts). Pendant ce temps, votre commission a déjà été créditée sur le solde de votre plateforme sans aucun appel de votre part, retirable dès que la vente dont elle vient a passé sa rétention. - [Sync](https://docs.wajub.com/fr/sync): La nature d'une connexion et ses limites. - [Capacités du compte](https://docs.wajub.com/fr/sync/account-types): Le calcul et le plafonnement de la commission. - [Démarrage rapide](https://docs.wajub.com/fr/sync/quickstart): Créer une connexion et y recevoir votre premier paiement. - [Transferts et payouts](https://docs.wajub.com/fr/payouts/transfers): Retirer l'argent d'un solde, qu'il soit connecté ou le vôtre. --- # Transferts et payouts URL: https://docs.wajub.com/fr/payouts > Envoyez de l'argent, comprenez d'où il vient et les conditions à remplir au préalable. Cette section traite de l'argent qui part vers un fournisseur, un livreur, un vendeur de votre marketplace ou votre propre compte. Un payout dépense des fonds que vous détenez déjà : c'est pourquoi il passe plus de contrôles que toute autre opération de l'API. ## Fonctionnalités disponibles | Besoin | Solution | | -------------------------------------------------------- | ----------------------------------------------------------------------------- | | Payer une personne ou une entreprise | [Transferts](https://docs.wajub.com/fr/payouts/transfers) | | Conserver une liste des personnes que vous payez souvent | [Bénéficiaires](https://docs.wajub.com/fr/payouts/beneficiaries) | | Connaître le montant disponible et celui déjà réglé | [Solde et règlements](https://docs.wajub.com/fr/payouts/balance) | | Payer plusieurs personnes à la fois | [`POST /transfers/batch`](https://docs.wajub.com/fr/api/transfers/batch), jusqu'à 500 lignes par appel | | Payer la même personne selon un calendrier | **Paramètres, Transferts, Automatisation**, à partir du plan Growth | Un lot accepte jusqu'à 500 payouts en un seul appel, sur tous les plans. Son en-tête `Idempotency-Key` est obligatoire, et chaque ligne porte une `reference` unique dans le lot. Chaque ligne passe les mêmes contrôles qu'un payout seul, bornes de la devise comprises, et désigne son bénéficiaire par son `id` seulement : un numéro de téléphone ou un e-mail est refusé avec `beneficiary_not_found`. Chaque ligne réussit ou échoue indépendamment : un vendeur sans destination vérifiée ne bloque pas les autres. Deux choses refusent un lot entier, avant qu'aucune ligne ne parte. Une ligne mal formée, par exemple un champ manquant, une `currency` qui ne fait pas trois lettres ou une `reference` répétée dans le lot, répond `422` pour tout l'appel, avec la ligne fautive nommée dans `errors` (`transfers.3.amount`). L'autre est un en-tête `Idempotency-Key` absent ou vide. Limitez cette clé aux lettres, chiffres et `. _ : -`. Un transfert récurrent paie à un bénéficiaire un montant fixe chaque heure, jour, semaine ou mois. Chaque exécution crée un payout ordinaire, soumis à tous les contrôles ci-dessous, et un calendrier mis en pause peut reprendre. ## Origine des fonds Wajub conserve un solde par devise pour votre compte. Les encaissements l'alimentent, les payouts y puisent, et aucun destinataire ne reçoit de fonds qui n'ont pas d'abord été couverts par le solde. `GET /balance` Un appel renvoie le solde de l'environnement associé à votre clé. Il répartit l'argent entre des montants qui n'ont pas la même signification. ```json title="Réponse · 200 OK" { "code": 200, "status": "OK", "message": "Balance retrieved", "balance": { "total": 1325000, "available": 1250000, "pending": 75000, "reserved": 0, "credit": 0, "currency": "XAF", "environment": "live" } } ``` `available` est le seul montant utilisable pour un payout. `pending` correspond aux fonds encaissés mais pas encore réglés en votre faveur. `reserved` correspond aux fonds déjà engagés dans des payouts en cours. Ajoutez `?currency=` pour consulter le même solde converti dans une autre devise. > [!WARNING] > **Le solde n'est pas en temps réel** > > Un payout créé il y a une minute peut ne pas encore avoir modifié `available`. Ne l'utilisez pas > comme total actualisé dans une boucle. Vérifiez-le une fois avant un lot, puis fiez-vous aux appels > de transfert eux-mêmes. Ils échouent en cas de fonds insuffisants au lieu de créer un découvert. ## Coût d'un payout Sur le circuit Wajub, un payout est facturé **à partir de 1 %**, selon le pays et le canal. Votre plan peut réduire ce taux. Un payout vers un autre compte Wajub (`wajub`) est gratuit, et un virement bancaire (`wire`) porte des frais fixes au lieu d'un taux, voir [Frais et tarification](https://docs.wajub.com/fr/payouts/balance/fees). Les frais sont débités à la fin du transfert, mais ils sont réservés avec le principal dès sa création. Envoyer 10 000 XAF réserve donc 10 100 XAF, et non 10 000 XAF. Le routage vers votre propre compte prestataire change ce fonctionnement. Un payout qui passe par un prestataire que vous avez apporté n'est pas financé par votre solde Wajub. Il n'entraîne donc aucuns frais Wajub et ne réserve rien. Le prestataire vous facture directement selon ses propres conditions. ## Conditions d'exécution d'un payout Cette partie mérite d'être lue avant votre premier transfert live. La création exécute une série de contrôles. Chacun renvoie une réponse `422` avec son propre message et son propre `error_code` plutôt qu'un échec générique. Aiguillez votre code sur ce code ; la liste complète figure dans [Erreurs](https://docs.wajub.com/fr/api/errors#payout-refusals). | Contrôle | Élément vérifié | `error_code` | | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Plafonds du montant | Le minimum et le maximum configurés pour cette devise | `amount_out_of_range` | | Bénéficiaire | Sa résolution sur votre compte, son activation et la présence d'un moyen de paiement | `beneficiary_not_found`, `beneficiary_inactive`, `beneficiary_missing_payment_method` | | Canal | Un canal de payout : Mobile Money, un portefeuille Djamo ou un autre compte Wajub par l'API, et un compte bancaire via un [compte de versement](https://docs.wajub.com/fr/payouts/beneficiaries#payout-accounts) | `channel_not_supported` | | Payouts suspendus sur toute la plateforme | La suspension des payouts sur tout Wajub, pour tous les comptes | `payouts_suspended` | | Restrictions du compte | Une restriction `transfers` active sur votre compte | `merchant_restricted` | | Solde négatif | Aucun payout ne part tant que `available` est sous zéro, quelle que soit la devise | `negative_balance` | | Réserve Sync Lite | Le payout d'un marchand Lite ne peut pas entamer la part retenue pour les remboursements | `reserve_held` | | Remboursement en route | Le montant d'un remboursement envoyé et pas encore débité reste sur le solde | `refund_in_flight` | | Réserve de plateforme Sync | Le retrait d'une plateforme Sync ne peut pas faire passer son solde disponible sous la réserve gardée pour ce que Wajub a versé à ses vendeurs Lite | `platform_reserve` | | Vérification de la destination | La vérification du moyen de paiement | `beneficiary_not_verified` | | Délai de carence de la destination | Une destination ajoutée ou modifiée à l'instant ne peut être payée qu'après son `payout_allowed_after` | `beneficiary_cooling_off` | | Votre propre plafond quotidien | Le nombre et le montant définis dans Transfer security settings. Les payouts échoués ou annulés ne comptent pas | `daily_count_limit_exceeded`, `daily_amount_limit_exceeded` | | Plafond de la plateforme | Une limite stricte selon le palier KYC, que vous ne pouvez pas augmenter vous-même | `single_payout_limit_exceeded`, `daily_payout_limit_exceeded`, `monthly_payout_limit_exceeded`, `payouts_not_enabled` | | Plafond du canal | La limite par transfert de cet opérateur | `amount_above_channel_limit` | | Disponibilité du canal | Les payouts vers ce canal ne sont pas [temporairement indisponibles](#temporarily-unavailable) | `channel_unavailable` | | Disponibilité du prestataire | L'existence d'une route de payout pour ce canal et cette devise | `no_provider` | | Fonds | Sur une route Wajub, `available` couvre le montant et les frais | `insufficient_balance` | L'ordre importe moins que le principe : rien n'est réservé avant la réussite de tous les contrôles, et un transfert qui échoue à l'un d'eux n'a jamais existé. Une chose survit pourtant au refus : un bénéficiaire passé en ligne, sous forme d'objet, est créé avant les contrôles. Il reste sur votre compte et dans `GET /beneficiaries`, et `beneficiary.created` est envoyé pour lui. Une nouvelle tentative avec le même canal et le même numéro paie ce même bénéficiaire, sous le nom de sa création, au lieu d'en créer un second. > [!CAUTION] > **Votre premier payout live n'est pas exécuté immédiatement** > > Un payout est retenu pour examen au lieu d'être envoyé lorsqu'il fait partie des premiers payouts > live de votre compte, lorsque son montant dépasse un seuil que vous avez vous-même défini, lorsque > votre compte exige la confirmation manuelle de ses payouts, ou lorsqu'il fait dépasser à votre > compte son nombre ou son montant de payouts par heure (un lot compte pour un payout). Wajub peut > aussi retenir un payout pour ses propres contrôles. Les lignes de votre premier lot sont examinées > ensemble, en une seule décision. Le transfert retenu est créé avec le statut `review`, ses fonds > sont réservés et il attend la décision de Wajub. Planifiez le > premier et ne réalisez pas un lancement dans une boucle sans surveillance. Les deux seuils qui vous appartiennent se trouvent sous **Paramètres, Transferts** : la confirmation manuelle, avec un montant facultatif en dessous duquel elle ne s'applique pas, dans l'onglet Général, et le montant d'examen ainsi que les plafonds quotidiens en nombre et en montant dans l'onglet Sécurité. Une retenue qu'ils déclenchent reste levée par Wajub, pas depuis votre propre Dashboard. Le même onglet Sécurité porte deux interrupteurs qui s'appliquent aux payouts lancés depuis le Dashboard, sur tous les plans. Pour protéger les payouts faits par l'API, utilisez des [clés restreintes et une liste d'IP autorisées pour l'API](https://docs.wajub.com/fr/best-practices/security#narrow-the-key-before-you-need-to). **Require 2FA** refuse un payout tant que le membre n'a pas saisi de code de vérification de sécurité et validé son second facteur dans les 30 dernières minutes. **IP whitelist** refuse tous les payouts tant que l'équipe n'a pas de liste d'IP pour le Dashboard : la liste elle-même se règle dans la [sécurité de l'organisation](https://docs.wajub.com/dashboard/settings/security#restrict-ip-addresses), cet interrupteur vérifie seulement qu'elle existe. Les deux réglages se modifient en mode live, par le propriétaire ou un membre qui a `manage_settings`. ## Créer un transfert `POST /transfers` Un transfert nécessite un montant, une devise et un destinataire. Le destinataire peut être un bénéficiaire déjà enregistré, transmis par son id, ou ses coordonnées complètes. Dans ce dernier cas, le bénéficiaire est créé pendant l'appel. **Payer un bénéficiaire existant** ```bash curl https://api.wajub.com/transfers \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: payout-892" \ -d '{ "beneficiary": "ben_7Kq2mX9vL4tRb3nP8sZc", "amount": 10000, "currency": "XAF", "description": "Supplier payment #892" }' ``` ```javascript const transfer = await wajub.transfers.create({ beneficiary: 'ben_7Kq2mX9vL4tRb3nP8sZc', amount: 10000, currency: 'XAF', description: 'Supplier payment #892', }, { idempotencyKey: 'payout-892' }); console.log(transfer.id, transfer.status); ``` ```python from wajub import RequestOptions transfer = wajub.transfers.create({ "beneficiary": "ben_7Kq2mX9vL4tRb3nP8sZc", "amount": 10000, "currency": "XAF", "description": "Supplier payment #892", }, RequestOptions(idempotency_key="payout-892")) print(transfer.id, transfer.status) ``` ```php use Wajub\RequestOptions; $transfer = $wajub->transfers->create([ 'beneficiary' => 'ben_7Kq2mX9vL4tRb3nP8sZc', 'amount' => 10000, 'currency' => 'XAF', 'description' => 'Supplier payment #892', ], new RequestOptions(idempotencyKey: 'payout-892')); echo $transfer->id; ``` ```go transfer, err := client.Transfers.Create(context.Background(), map[string]any{ "beneficiary": "ben_7Kq2mX9vL4tRb3nP8sZc", "amount": 10000, "currency": "XAF", "description": "Supplier payment #892", }, &wajub.RequestOptions{IdempotencyKey: "payout-892"}) ``` La réponse est `201 Created` et le transfert revient avec le statut `processing`, alors qu'il est déjà en cours d'acheminement. Les deux environnements se comportent de la même façon. Un transfert dans la sandbox puise dans votre solde sandbox, puis se règle tout seul quelques secondes plus tard. Le résultat dépend du numéro de test du destinataire. > [!NOTE] > **Aucune annulation possible** > > L'API permet de créer, lister et récupérer des transferts. Elle ne permet pas de les annuler. Une > fois créé, un transfert évolue vers `succeeded` ou `failed`. Seuls un examen, que vous ne contrôlez > pas, et un moyen de paiement [temporairement indisponible](#temporarily-unavailable) peuvent le > suspendre. Considérez `POST /transfers` comme irréversible et effectuez vos contrôles avant > l'appel, pas après. ### Quand un moyen de paiement est temporairement indisponible Un opérateur peut être indisponible du côté de Wajub pendant un moment. Si vous avez connecté votre propre prestataire pour ce canal, c'est lui qui verse le payout. Sinon, Wajub fait l'une de deux choses avec un nouveau payout : - **Il le garde.** Le transfert est créé comme d'habitude, `processing`, son montant réservé, et `metadata.rail_queue.queued_at` indique depuis quand il attend. Il part de lui-même dès le retour de l'opérateur (`metadata.rail_queue.released_at`), et les webhooks habituels suivent. D'ici là, vous pouvez l'annuler depuis le Dashboard, ce qui rend son montant de nouveau disponible ; votre délai d'expiration des transferts s'applique toujours. - **Il le refuse** avec `422` et `error_code: channel_unavailable`. Rien n'est réservé : réessayez plus tard, ou utilisez un autre canal. ## Ressources | Méthode | Endpoint | Usage | | --------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------ | | `POST` `GET` | [`/transfers`](https://docs.wajub.com/fr/api/transfers) | Créer, lister et récupérer un payout | | `POST` `GET` `PUT` `DELETE` | [`/beneficiaries`](https://docs.wajub.com/fr/api/beneficiaries) | Conserver les personnes que vous payez | | `GET` | [`/balance`](https://docs.wajub.com/fr/api/balance) | Connaître le montant disponible | | `POST` | [`/transfers/batch`](https://docs.wajub.com/fr/api/transfers/batch) | Payer jusqu'à 500 personnes en un appel | | `POST` | [`/beneficiaries/{id}/verify`](https://docs.wajub.com/fr/api/beneficiaries/verify) | Vérifier qu'un portefeuille appartient bien à la personne attendue | Pour vérifier le nom d'un portefeuille, utilisez `POST /beneficiaries/{id}/verify` : il interroge l'opérateur en live et renvoie ce qu'il détient, à titre d'information. [Vérifier le nom d'un portefeuille](https://docs.wajub.com/fr/payouts/beneficiaries/create#checking-the-name-on-a-wallet) Toutes ces ressources nécessitent la clé secrète. Une clé publique est refusée, tout comme un navigateur. Les routes de payout sont les plus strictement protégées de l'API. Si vous effectuez un payout pour le compte d'un compte connecté, l'en-tête `X-Sync` permet de le sélectionner. La page [Sync](https://docs.wajub.com/fr/sync) détaille ce fonctionnement. - [Transferts](https://docs.wajub.com/fr/payouts/transfers): Le payout lui-même : statuts, routage et signification d'un échec. - [Démarrage rapide](https://docs.wajub.com/fr/payouts/transfers/quickstart): Envoyez votre premier payout dans la sandbox, puis en live. - [Bénéficiaires](https://docs.wajub.com/fr/payouts/beneficiaries): Enregistrez un destinataire une fois, puis payez-le par son id. - [Solde et règlements](https://docs.wajub.com/fr/payouts/balance): Ce qui est disponible, en attente et facturé en frais. - [Idempotence](https://docs.wajub.com/fr/api/idempotency): L’en-tête qui sécurise une nouvelle tentative de payout. --- # Frais et tarification URL: https://docs.wajub.com/fr/payouts/balance/fees > Ce que Wajub facture sur un encaissement et un payout, et où retrouver ces frais. Wajub prélève un pourcentage sur les deux mouvements, mais uniquement lorsqu'une opération réussit. Un paiement qui échoue ne coûte rien, tout comme un payout qui n'atteint jamais son destinataire. Les frais Wajub ne comprennent aucune part fixe ni aucun minimum. Le taux dépend de votre plan. Le calcul consiste en une simple multiplication, arrondie selon la précision de la devise. Pour `XAF`, dont la précision est nulle, les frais correspondent à un nombre entier de francs. ## Coût d'un encaissement Le taux est lu dans votre plan pour chaque canal. Voici les taux configurés aujourd'hui. | Plan | MTN et Orange Cameroun | Tous les autres canaux | | ------------- | ---------------------- | ---------------------- | | Pay as you go | 2,0 % | 2,0 % | | Growth | 1,7 % | 2,0 % | | Scale | 1,5 % | 2,0 % | | Enterprise | 1,2 % | 2,0 % | La deuxième colonne n'est pas un arrondi de la première. Le taux du plan ne s'applique qu'à `cm.mtn` et `cm.orange`. Tous les autres canaux, y compris Express Union et tous les pays hors Cameroun, sont facturés au taux par défaut de **2 %**, quel que soit votre plan. Renseignez-vous avant de calculer vos marges sur un corridor autre que ces deux canaux. > [!NOTE] > **Ces taux viennent de la plateforme, pas de cette page** > > Les taux ci-dessus correspondent à la configuration actuelle des plans, et non à un engagement > commercial. Votre propre accord peut remplacer chacun d'eux. La Konsole affiche le taux > réellement appliqué à votre compte. ## Personne qui paie les frais Par défaut, le marchand les paie. Le client est débité du montant, vous êtes crédité de ce même montant, puis les frais vous sont débités. Le champ `bearer` de `POST /payments` permet de les transférer. Avec `"bearer": "customer"`, le payeur est débité du montant et des frais, tandis que vous recevez l'intégralité du montant demandé. Les frais correspondent à la différence et ne passent jamais par votre solde. ```json title="Faire payer les frais au client" { "amount": 10000, "currency": "XAF", "channel": "cm.mtn", "bearer": "customer" } ``` Ce champ accepte uniquement `merchant` ou `customer`. Si vous l'omettez, sa valeur est `merchant`. ## Solde duquel les frais sont prélevés Les frais d'encaissement ne sont pas soustraits du crédit. Le paiement crédite intégralement votre solde, puis un débit séparé en retire les frais. Ce débit touche **le même solde que celui crédité par le paiement**. Ce point est important, car un nouvel encaissement reste dans `pending` pendant sa période de rétention. Ses frais sont aussi prélevés sur `pending`. Ils ne peuvent donc jamais rendre `available` négatif pour un compte dont les fonds ne sont pas encore disponibles. La page [Solde](https://docs.wajub.com/fr/payouts/balance) détaille ces soldes et la période de rétention. ## Coût d'un payout Le taux est **à partir de 1 %** sur le Mobile Money et les autres canaux d'opérateur, selon le pays et le canal : celui de chacun figure dans votre demande d'accès au réseau Wajub. Deux canaux sont facturés autrement. | Canal | Frais | | ----------------------------------- | ------------------------------------------------------------------------------------------------ | | `wajub`, vers un autre compte Wajub | Aucuns. L'argent ne quitte pas Wajub | | `wire`, un virement bancaire | Des frais fixes par transfert au lieu d'un pourcentage. Traité sous 48 heures ouvrées par défaut | Le moment du prélèvement peut surprendre. Les frais sont estimés et réservés avec le principal dès la création du transfert. Envoyer 10 000 XAF rend donc immédiatement 10 100 XAF indisponibles. Les frais ne sont réellement débités que lorsque le payout atteint `succeeded`. | État final du payout | Frais | | -------------------- | ------------------------------------------------------------------------ | | `succeeded` | Débités, et la réservation est réglée | | `failed` | Jamais débités. Le principal et l'estimation reviennent dans `available` | > [!WARNING] > **Un payout avec votre propre prestataire n'entraîne aucuns frais Wajub** > > Les frais Wajub s'appliquent aux payouts routés et financés par Wajub. Un payout qui passe par un > prestataire que vous avez apporté n'est pas financé par votre solde Wajub. Il ne réserve rien et > n'est pas facturé ici. Ce prestataire vous facture directement selon ses propres conditions. ## La sandbox facture 2 % sur les deux mouvements La sandbox possède son propre taux fixe, différent du taux live. Un encaissement et un payout dans la sandbox sont tous deux facturés **2 %**. Un payout sandbox coûte donc deux fois plus cher que le payout live qu'il est censé simuler. > [!CAUTION] > **Ne reproduisez pas les calculs de la sandbox en production** > > Les frais d'un payout sandbox sont aussi ajoutés au montant au lieu d'en être déduits. Ils ne > sont pas rendus en cas d'échec du payout. Ces deux comportements diffèrent du mode live. Si vous > développez le calcul du coût d'un payout, basez-vous sur les règles live et testez les montants > séparément. ## Retrouver des frais Il n'existe aucun endpoint pour les frais. L'API ne permet ni de les lister, ni d'en récupérer un, ni d'obtenir leur total. Les paiements et transferts ne possèdent pas non plus de champ `fee`. La seule interface programmable est le webhook `fee.charged`, émis une fois pour chaque frais au moment de son prélèvement. Un paiement dont le payeur a payé les frais, avec `bearer` à `customer`, n'en émet pas : rien ne vous a été facturé. ```json title="L'objet data de fee.charged" { "id": "9f4c2b17-6e30-4a58-b2d1-77a0c9e51f84", "type": "platform_fee", "amount": 100, "currency": "XAF", "percentage": 1, "fixed_amount": null, "applied_to": "transfer", "created_at": "2026-09-12T14:31:06+00:00" } ``` Quatre caractéristiques de ce payload sont à connaître avant de l'utiliser. - `id` (string): Un UUID brut, et non un id Wajub préfixé. Les frais font exception à la convention `po_` et `pay_`. - `percentage` (number): Le taux sous forme de pourcentage. `1` signifie donc un pour cent, et non une fraction. - `applied_to` (string): `transaction` pour un encaissement, `transfer` pour un payout. Un encaissement n'est pas appelé paiement ici. - `fixed_amount` (null): Toujours `null` pour des frais Wajub. Seule la commission d'une plateforme peut contenir une part fixe, comme expliqué ci-dessous. Le quatrième point constitue un manque plutôt qu'une particularité. Il détermine votre méthode de rapprochement. > [!CAUTION] > **Les frais d'un payout n'indiquent pas le payout concerné** > > Lorsque les frais concernent un encaissement, l'événement contient un objet `payment` avec son > id. Pour un payout, il ne contient rien de similaire. Vous recevez un montant, une devise et > `applied_to: "transfer"`, sans pouvoir les attribuer à un transfert à partir du seul événement. > Faites la correspondance entre le montant et l'horodatage dans vos propres enregistrements de > payouts, ou effectuez le rapprochement depuis la Konsole. ## Si vous êtes une plateforme Le paiement d'un compte connecté peut comporter des frais supplémentaires totalement distincts : votre propre commission, calculée selon la règle tarifaire Sync définie pour ce compte. Son `type` est `sync_fee`, et non `platform_fee`. Il s'agit des seuls frais de la plateforme pouvant comprendre à la fois un pourcentage et une part fixe. Ils produisent deux événements au lieu d'un, afin que les deux parties voient le même mouvement. | Événement | Destinataire | Signification | | -------------- | ------------------ | ----------------------------------------------------------------- | | `fee.charged` | Le compte connecté | Votre commission lui a été facturée | | `fee.received` | Vous | Vous l'avez gagnée, avec le champ `account` indiquant son origine | Les propres frais `platform_fee` de Wajub s'ajoutent séparément. La page [Sync](https://docs.wajub.com/fr/sync) explique les règles tarifaires et la configuration d'un compte connecté. - [Solde et règlements](https://docs.wajub.com/fr/payouts/balance): Les soldes entre lesquels les frais circulent et la période de rétention. - [Transferts](https://docs.wajub.com/fr/payouts/transfers): Ce qu'un payout réserve à sa création et ce qui libère cette réservation. - [Catalogue des événements](https://docs.wajub.com/fr/developer-tools/webhooks/events): Le catalogue complet, y compris les événements liés aux frais. - [Sync](https://docs.wajub.com/fr/sync): Les comptes connectés, les règles tarifaires et votre propre commission. --- # Solde et règlements URL: https://docs.wajub.com/fr/payouts/balance > Ce que vous détenez, ce que vous pouvez envoyer aujourd'hui et quand le reste devient disponible. Un seul montant de votre solde permet de payer quelqu'un, `available` : le reste correspond à de l'argent que vous détenez sans pouvoir encore le dépenser. Cette page explique chaque montant et le moment où les fonds encaissés deviennent disponibles. ## Un seul appel `GET /balance` La clé secrète est obligatoire. Comme toutes les autres routes de payout, une clé publique renvoie `406 Private Key Required`. Il n'existe aucun autre endpoint de solde : aucun historique, aucune consultation par portefeuille et aucun ajustement. **Consulter le solde** ```bash curl https://api.wajub.com/balance \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` ```javascript const balance = await wajub.balance.retrieve(); console.log(balance.available, balance.currency); ``` ```python balance = wajub.balance.retrieve() print(balance["available"], balance["currency"]) ``` ```php $balance = $wajub->balance->retrieve(); echo $balance['available']; ``` ```go balance, err := client.Balance.Retrieve(context.Background()) if err != nil { log.Fatal(err) } log.Println(balance["available"], balance["currency"]) ``` La réponse contient les montants suivants. ```json title="Réponse · 200 OK" { "code": 200, "status": "OK", "message": "Balance retrieved", "balance": { "total": 1325000, "available": 1250000, "pending": 75000, "reserved": 0, "disputed": 0, "currency": "XAF", "environment": "live" } } ``` Les cinq premiers répondent à des questions différentes sur les mêmes fonds. Les deux derniers indiquent comment les montants sont exprimés. Ignorez tout autre champ. - `total` (number): Tout ce que vous détenez. Somme de `available`, `pending`, `reserved` et `disputed`. - `available` (number): Fonds réglés, sortis de la période de rétention et utilisables. Le seul montant disponible pour un payout. Il passe sous zéro lorsqu'un remboursement, une rétrofacturation ou des frais arrivent après le versement des fonds, et aucun payout ne part tant que de nouveaux encaissements ne l'ont pas couvert. - `pending` (number): Fonds encaissés et réglés, encore dans leur période de rétention. Ils deviennent disponibles après un délai expliqué ci-dessous. - `reserved` (number): Fonds engagés dans des payouts en cours. Vous ne pouvez pas les dépenser deux fois. - `disputed` (number): Fonds retenus pour les litiges ouverts, pris sur `available` à l'ouverture d'un litige. Ils reviennent dans `available` si vous gagnez, et sortent si vous perdez. - `currency` (string): Devise dans laquelle tous les montants précédents sont exprimés. Il s’agit d’une unité, pas d’un portefeuille. - `environment` (string): `live` ou `sandbox`. Les montants utilisent l'unité principale, comme pour un transfert. `1250000` en `XAF` signifie un million deux cent cinquante mille francs, et non douze mille cinq cents. ## Il ne s'agit pas d'un portefeuille, mais de leur ensemble `GET /balance` additionne ce que vous détenez dans chaque devise, converti dans une seule. `currency` est donc une unité d'affichage, pas un filtre. `?currency=XOF` n'affiche pas votre portefeuille XOF, mais tous vos fonds exprimés en XOF. Les fonds sous-jacents ne bougent pas et aucun portefeuille n'est exclu. ```bash title="Les mêmes fonds exprimés dans une autre devise" curl "https://api.wajub.com/balance?currency=USD" \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` Seul cURL est présenté, car les SDK n'acceptent ici aucun argument. `balance.retrieve()` ne possède aucun paramètre dans les différents SDK. Omettez le paramètre d'URL pour obtenir la devise définie sur votre compte. Il s'agit de `XAF` jusqu'à sa modification, quel que soit votre pays d'activité. `currency` accepte la devise de votre compte, ou une devise pour laquelle Wajub a un taux de change, en majuscules ou en minuscules. Tout autre code, une faute de frappe ou une devise vers laquelle Wajub ne peut pas convertir, renvoie un `422` sur `currency`. > [!CAUTION] > **La conversion est indicative** > > Elle ne constitue pas un taux de change négocié : utilisez-la pour lire un montant, jamais pour > régler un compte. ## Pourquoi available est inférieur à total Un encaissement n'arrive pas sous forme de fonds utilisables. Il est crédité dans `pending` et y reste pendant une durée fixe avant son transfert. La durée est calculée pour chaque paiement selon son canal d'origine. | Canal | Rétention de base | | -------------------------------------------------------- | ----------------- | | Mobile Money, y compris `cm.mtn`, `cm.orange` et `cm.eu` | 24 heures | | Banque | 48 heures | | Carte | 72 heures | | Cryptomonnaie | 72 heures | La rétention peut être plus courte ou plus longue que cette base selon le profil de risque de votre compte, et elle ne dépasse jamais sept jours. Votre plan ou un accord avec Wajub peut remplacer directement cette durée de base. ## Signification de reserved `reserved` correspond aux fonds engagés dans des payouts qui ne sont pas terminés. La création d'un transfert retire le montant et une estimation des frais de `available`, puis les place dans `reserved` avant même de contacter l'opérateur. Ces fonds quittent `reserved` au résultat du transfert. Ce résultat détermine leur destination. Avec `transfer.succeeded`, ils sont réellement débités et `total` diminue. Avec `transfer.failed`, ils reviennent dans `available` et aucuns frais ne sont prélevés. Un payout retenu pour examen conserve ses fonds réservés pendant toute la rétention. C'est le seul cas où `reserved` peut rester inchangé pendant des heures. ## Le montant n'est pas en temps réel Un payout créé il y a une minute peut ne pas avoir encore modifié `available`. Le solde ne convient donc pas au suivi d'une boucle. Consultez-le une fois avant un lot pour estimer votre position, puis laissez les appels de transfert faire foi. Un payout impossible à financer est refusé à la création avec sa propre erreur `422`, sans créer de découvert. > [!NOTE] > **Ne conditionnez pas chaque payout à une lecture du solde** > > Consulter le solde avant chacun des cinquante payouts d'une boucle produit cinquante réponses > obsolètes et consomme votre limite de requêtes. Vérifiez une fois, envoyez les payouts, puis gérez > l'erreur de financement si elle survient. ## Solde simplifié dans la sandbox La sandbox n'a ni rétention, ni réservation, ni règlement : `total` et `available` contiennent le même montant. Le solde commence aussi à zéro. Il n'existe aucun endpoint de recharge ni aucun bouton dans la Konsole. Seul un paiement sandbox réussi crédite ce solde. C'est pourquoi le [Démarrage rapide Transferts](https://docs.wajub.com/fr/payouts/transfers/quickstart) commence par encaisser des fonds avant d'en envoyer. ## Suivre les changements Au lieu d'utiliser le polling, abonnez-vous à `balance.updated`. Cet événement est émis à chaque mouvement. Son payload décrit le mouvement lui-même, et non le nouvel objet solde. ```json title="balance.updated" { "currency": "XAF", "amount": 20000, "direction": "credit", "balance_type": "pending", "balance_before": 1305000, "balance_after": 1325000, "reason": "succeeded", "sandbox": false } ``` `balance_type` indique le solde modifié, `pending` ou `available`. Vous pouvez ainsi distinguer un nouvel encaissement d'une rétention qui vient d'expirer. `direction` vaut `credit` ou `debit`. > [!NOTE] > **Les frais ne produisent pas balance.updated** > > Le débit des frais est volontairement exclu de cet événement et publié sous `fee.charged`. Un > rapprochement fondé uniquement sur `balance.updated` trouvera donc des fonds manquants. Abonnez-vous > aux deux événements. ## Règlement vers votre compte de versement Les versements automatiques sont désactivés tant que vous ne les activez pas, dans **Paramètres, Transferts, Comptes de versement** ([comment](https://docs.wajub.com/dashboard/transfers/payout-accounts#automatic-payouts)). D'ici là, votre argent reste sur votre solde, et vous l'envoyez par un [transfert](https://docs.wajub.com/fr/payouts/transfers) quand vous le décidez. Une fois activés, chaque jour à 02:00 UTC, Wajub verse ce que vous avez encaissé sur le rail Wajub vers le [compte de versement](https://docs.wajub.com/fr/payouts/beneficiaries#payout-accounts) que vous avez choisi, avec un payout par devise. Le montant correspond à ce que ces paiements ont crédité, moins les remboursements, les frais et les litiges perdus déjà prélevés sur eux, et jamais plus que ce que votre solde `available` peut payer avec les frais du payout en plus : l'argent que vous avez déjà envoyé vous-même n'est pas envoyé une seconde fois. Les fonds que vous avez ajoutés à votre solde ne sont jamais versés ainsi. Rien n'est envoyé sous 1 000 dans la devise créditée, et les paiements encaissés via votre propre prestataire n'en font jamais partie. Si le compte choisi est archivé ou désactivé, rien n'est envoyé tant que vous n'en choisissez pas un autre : Wajub ne devine jamais où va votre argent. Le premier versement après l'activation comprend les ventes déjà sur votre solde, dans la limite de ce qui est disponible. ## Ajouter des fonds et lire vos revenus **Revenus, Financements** alimente votre solde live, par Mobile Money sur `cm.mtn`, `cm.orange` ou `cm.eu`, ou par virement bancaire lorsqu'il est proposé : vous envoyez le virement, puis vous déposez le justificatif sur la même page. Le reste de **Revenus** présente vos paiements encaissés par canal et par devise, les frais de traitement facturés par Wajub, ce qui a été rendu aux clients, et un rapport de solde qui montre ce qui est retenu pour les litiges et la date de règlement prévue des encaissements récents. Il est réservé au mode live et s'exporte en PDF ou en Excel. ## Aucun endpoint de registre Aucun endpoint de l'API ne renvoie la liste des mouvements d'un solde. Pour rapprocher une période, listez les ressources à l'origine des mouvements avec `GET /payments`, `GET /transfers` et `GET /refunds`, puis ajoutez les frais provenant de vos événements `fee.charged`. La Konsole exporte les mêmes données pour la comptabilité. - [Frais et tarification](https://docs.wajub.com/fr/payouts/balance/fees): Le coût de chaque opération et le moment de son prélèvement. - [Transferts](https://docs.wajub.com/fr/payouts/transfers): Ce qu'un payout réserve et ce qui libère cette réservation. - [Statuts et webhooks](https://docs.wajub.com/fr/payouts/transfers/statuses-and-webhooks): Les événements qui modifient le solde et leur traitement. - [Catalogue des événements](https://docs.wajub.com/fr/developer-tools/webhooks/events): Le catalogue complet, y compris les événements liés au solde et aux frais. --- # Créer un bénéficiaire URL: https://docs.wajub.com/fr/payouts/beneficiaries/create > Enregistrer une destination une fois : le canal qui détermine l'opérateur, un autre compte Wajub, et le nom sur un portefeuille. `POST /beneficiaries` - `channel` (string, required): Le canal de l'opérateur qui dessert le numéro, comme `cm.mtn` ou `ke.mpesa`. Au Cameroun uniquement, `cm.mobile` laisse le numéro décider : voir ci-dessous. - `name` (string, required): Le bénéficiaire, tel qu'il doit apparaître sur le payout. Également utilisé comme nom du titulaire du compte. - `phone` (string): Le numéro qui reçoit les fonds. Obligatoire sauf si vous transmettez `account_number`. Le champ s'appelle `phone`, pas `phone_number`. - `account_number` (string): La destination lorsqu'il ne s'agit pas d'un numéro de téléphone. L'un des deux champs est obligatoire. `phone` renseigne celui-ci si vous l'omettez. - `email` (string): L'adresse de contact du bénéficiaire. Elle ne sert actuellement à aucun envoi. - `country_code` (string): Deux lettres. Par défaut, les deux premières lettres du slug du canal. `cm.mtn` donne donc `CM`. - `note` (string): Texte libre pour votre propre référence, limité à 1 000 caractères. - `metadata` (object): Vos propres paires clé-valeur, renvoyées sans modification à chaque lecture. Envoyez la requête avec la clé secrète. La création d'un bénéficiaire possède une limite de requêtes plus stricte que le reste de l'API. **Enregistrer un bénéficiaire** ```bash curl https://api.wajub.com/beneficiaries \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: beneficiary-amina" \ -d '{ "channel": "cm.mtn", "name": "Amina Traoré", "phone": "+237670000000" }' ``` ```javascript const beneficiary = await wajub.beneficiaries.create({ channel: 'cm.mtn', name: 'Amina Traoré', phone: '+237670000000', }); console.log(beneficiary.id); ``` ```python beneficiary = wajub.beneficiaries.create({ "channel": "cm.mtn", "name": "Amina Traoré", "phone": "+237670000000", }) print(beneficiary.id) ``` ```php $beneficiary = $wajub->beneficiaries->create([ 'channel' => 'cm.mtn', 'name' => 'Amina Traoré', 'phone' => '+237670000000', ]); echo $beneficiary->id; ``` ```go beneficiary, err := client.Beneficiaries.Create(context.Background(), map[string]any{ "channel": "cm.mtn", "name": "Amina Traoré", "phone": "+237670000000", }, nil) ``` La réponse est `201 Created`. Chaque payout utilise le champ `id`, préfixé par `ben_` en live et `ben_test_` dans la sandbox. Les deux environnements ne peuvent donc jamais être confondus. ```json title="Réponse · 201 Created" { "code": 201, "status": "Created", "message": "Beneficiary created successfully", "beneficiary": { "id": "ben_7Kq2mX9vL4tRb3nP8sZc", "name": "Amina Traoré", "phone": "+237670000000", "country_code": "CM", "note": "Retainer, paid on the 1st", "sandbox": false, "is_active": true, "type": "standard", "verified": true, "payment_method": { "id": "pm_4Dw8kR2xN6vQ", "type": "mobile_money", "name": "MTN Mobile Money" }, "created_at": "2026-09-11T14:00:00+00:00", "updated_at": "2026-09-11T14:00:00+00:00" } } ``` > [!NOTE] > **La destination ne figure pas dans la réponse** > > `payment_method` contient un id, un type et un libellé, mais jamais le numéro qui reçoit les > fonds. Aucun endpoint de l'API ne permet de relire la destination d'un bénéficiaire. Si vous > devez montrer au bénéficiaire où ses fonds sont envoyés, conservez votre propre copie lors de la > création. > [!NOTE] > **En sandbox, des numéros de test seulement** > > Un bénéficiaire sandbox doit déjà porter un numéro de test à sa création : toute autre valeur > répond `422` sur `phone` et `account_number` avec `Invalid sandbox test number. Use a Mobile Money > test number, e.g. +237670000000 (success), +237670000001 (insufficient funds), +237670000002 > (failure), +237670000003 (timeout), +237670000004 (canceled).` Chargez de vrais numéros en live > seulement. Les numéros de test de chaque opérateur figurent dans > [Scénarios de test](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios). ## Le canal détermine l'opérateur Indiquez le canal de l'opérateur : `ke.mpesa`, `eg.vodafone`, `cm.mtn`, `cm.orange`. Le Cameroun est la seule exception : quand vous avez un numéro camerounais sans son opérateur, transmettez `cm.mobile`, et l'opérateur, `cm.mtn` ou `cm.orange`, est déterminé à partir du numéro. Aucun autre pays n'a de canal générique : `ke.mobile` ou tout autre `{country}.mobile` est refusé comme un canal inconnu. Cette résolution peut échouer. Elle renvoie alors une erreur claire au lieu de choisir un opérateur au hasard. ```json title="Réponse · 422 quand le numéro ne correspond à aucun opérateur" { "code": 422, "status": "Unprocessable Content", "message": "Could not determine operator from phone number for cm.mobile. Use a valid number of that country or specify the channel explicitly (e.g. cm.mtn, cm.orange). (and 1 more error)", "errors": { "channel": ["Could not determine operator from phone number for cm.mobile. Use a valid number of that country or specify the channel explicitly (e.g. cm.mtn, cm.orange)."], "phone": ["Could not determine operator from this phone number for cm.mobile."] } } ``` Si vous connaissez déjà l'opérateur, indiquez-le. `cm.mobile` sert lorsque vous n'avez qu'un numéro camerounais. > [!CAUTION] > **La même destination renvoie le premier bénéficiaire** > > La création est indexée sur la destination, pas sur les informations envoyées avec celle-ci. Si > un bénéficiaire actif existe déjà pour ce numéro et ce canal, l'appel le renvoie sans le modifier, > avec le même `201 Created` et le même message de réussite qu'une véritable création. Les valeurs > `name`, `email` et `note` que vous venez d'envoyer sont ignorées. Lisez l'`id` renvoyé au lieu de > supposer qu'il est nouveau. Ici, un `201` ne prouve jamais qu'un nouvel enregistrement a été créé. ## Payer un autre compte Wajub Quand la personne que vous payez a déjà un compte Wajub, utilisez le canal `wajub` et son numéro de compte à 11 chiffres. L'argent passe de votre solde au sien, sans attente. ```json title="Un bénéficiaire sur un autre compte Wajub" { "name": "Boutique Ada", "channel": "wajub", "account_number": "12345678901" } ``` Le compte doit exister, ne peut pas être le vôtre, et ne peut pas être un compte que Wajub a gelé : chaque cas est refusé avec `422` à la création du bénéficiaire, et un versement vers un compte gelé depuis échoue de lui-même. Le payer est un virement ordinaire, avec les mêmes plafonds et les mêmes statuts ; il réussit simplement tout de suite, et il est **gratuit**. > [!NOTE] > **En sandbox** > > Un versement sandbox sur ce canal réussit toujours : les scénarios de test ne s'y appliquent pas, > et un échec sur ce canal ne s'observe qu'en live. Le solde sandbox du destinataire n'est jamais > crédité. Seul le live déplace de l'argent entre comptes. ## Vérifier le nom d'un portefeuille `POST /beneficiaries/{id}/verify` L'appel ne prend aucun corps. Il demande à l'opérateur sous quel nom le portefeuille est enregistré et le compare au nom que vous avez déclaré. Sur vos propres bénéficiaires, la réponse est une information. Le bénéficiaire reste payable quel que soit le résultat, l'appel répond `200`, et `registered_name` porte le nom que détient l'opérateur quand il correspond : vous pouvez le montrer à la personne qui s'apprête à envoyer l'argent. En cas d'écart, il n'en porte que les initiales, `P*** N***` : la vérification confirme un bénéficiaire, elle ne dit pas à qui appartient un numéro. | `verification` | Ce qui s'est passé | `registered_name` | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `verified` | Le nom de l'opérateur correspond à celui que vous avez déclaré | Présent | | `name_mismatch` | L'opérateur détient ce numéro sous un autre nom | Ses initiales seulement, `P*** N***` | | `lookup_unavailable` | L'opérateur n'a pas pu être interrogé : il n'offre pas de recherche sur ce canal, il n'a pas répondu, ou il ne connaît pas le numéro | Absent | | `not_found` | Le bénéficiaire n'a aucune destination de versement à vérifier. L'appel répond `422` avec `This beneficiary has no payout destination to verify.` | Absent | ```json title="Réponse · 200 quand l'opérateur détient un autre nom" { "code": 200, "status": "OK", "message": "The operator holds this number under another name. The beneficiary can still be paid.", "verification": "name_mismatch", "registered_name": "P*** N***", "beneficiary": { "id": "ben_7Kq2mX9vL4tRb3nP8sZc", "name": "Amina Traoré", "verified": true, "verification": "name_mismatch" } } ``` Les opérateurs qui répondent aujourd'hui sont MTN, Orange Money et Express Union au Cameroun, `cm.mtn`, `cm.orange` et `cm.eu`, ainsi qu'un compte Wajub, `wajub`. Tout autre canal renvoie `lookup_unavailable`. Le bénéficiaire conserve le dernier résultat : `verification` le porte à chaque lecture, et il est absent tant qu'aucune vérification n'a eu lieu. `verified` est autre chose. Il indique si Wajub paiera le bénéficiaire en live, et ici un `name_mismatch` ne le change pas. Une exception : un bénéficiaire resté non vérifié, par exemple un vendeur que l'opérateur n'a pas pu confirmer quand votre compte était sur Relay, devient payable si les noms correspondent, et il est alors payé sous le nom que détient l'opérateur. Une différence de nom ou un opérateur injoignable le laisse impayable. > [!NOTE] > **En sandbox, le numéro de test décide** > > Aucun opérateur n'est interrogé depuis la sandbox : le numéro de test du bénéficiaire indique ce > qu'il détiendrait. Sur `cm.mtn`, `cm.orange` et `cm.eu`, un numéro qui se termine par `000000` > détient le nom que vous avez déclaré (`verified`), un numéro qui se termine par `000002` un autre > nom (`name_mismatch`), et tout autre numéro de test répond `lookup_unavailable`. Voir > [Scénarios de test](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios#name-check). L'appel a son propre plafond, quel que soit votre plan : 10 vérifications par minute et 200 par jour et par compte en live, 10 par minute en sandbox. Au-delà, la réponse est `429`. Il sert à vérifier vos propres bénéficiaires à mesure que vous les ajoutez, pas à interroger des numéros en masse. > [!NOTE] > **Là où la vérification décide au lieu d'informer** > > Sur un compte Relay, et sur tout compte pour lequel Wajub l'exige, le même appel est une barrière. > Un bénéficiaire déjà vérifié est renvoyé tel quel, tout résultat autre que `verified` répond > `422`, le bénéficiaire reste impayable, et `registered_name` n'est pas renvoyé. En sandbox, aucun > opérateur ne peut être interrogé : un bénéficiaire y est créé vérifié sur un tel compte, et > l'appel répond `verified`. Votre traitement d'un `name_mismatch` ne peut donc être éprouvé qu'en > live. Un compte de versement ajouté dans le Dashboard n'est jamais vérifié par cet appel, sur > aucun compte : vérifiez-le là-bas. - [Gérer les bénéficiaires](https://docs.wajub.com/fr/payouts/beneficiaries/manage): Les modifier, les lister et les supprimer. - [Prestataires et canaux](https://docs.wajub.com/fr/payouts/transfers/providers): Les canaux vers lesquels un payout peut partir. --- # Bénéficiaires URL: https://docs.wajub.com/fr/payouts/beneficiaries > Enregistrez une destination de payout une fois, puis payez-la par son id plutôt que par son numéro. Un bénéficiaire est une destination de payout enregistrée : un nom, un numéro et l'opérateur qui le dessert. Créez-le une fois, puis payez-le par son id, sans ressaisir le numéro à chaque payout. > [!WARNING] > **Mobile Money, Djamo ou un compte Wajub** > > Le canal transmis doit être l'un des cinquante canaux Mobile Money compatibles avec les payouts, listés dans > [Prestataires et canaux](https://docs.wajub.com/fr/payouts/transfers/providers), un portefeuille Djamo (`ci.djamo` ou > `sn.djamo`), ou `wajub` pour un autre compte Wajub. Toute autre valeur renvoie `422` avec > `The selected channel is invalid.` (`The selected beneficiary.channel is invalid.` pour un > bénéficiaire envoyé en ligne avec un transfert). Les destinations bancaires existent sous forme de > [comptes de versement](#payout-accounts), que vous créez dans le Dashboard et non par l'API. Deux pages vont plus loin : - [Créer un bénéficiaire](https://docs.wajub.com/fr/payouts/beneficiaries/create), le canal qui détermine l'opérateur, un autre compte Wajub comme destination, et la vérification du nom sur un portefeuille. - [Gérer les bénéficiaires](https://docs.wajub.com/fr/payouts/beneficiaries/manage), ce qui est modifiable, récupérer, lister et supprimer un bénéficiaire, et ses relevés. ## Payer un bénéficiaire Transmettez l'`id` à l'emplacement où un payout attend un destinataire. Le reste du transfert ne change pas. `POST /transfers` Le corps correspond à celui décrit dans [Transferts](https://docs.wajub.com/fr/payouts/transfers), avec une chaîne à la place de l'objet inline. ```json title="Payer un bénéficiaire enregistré" { "beneficiary": "ben_7Kq2mX9vL4tRb3nP8sZc", "amount": 15000, "currency": "XAF", "description": "September retainer" } ``` > [!NOTE] > **Enregistrer un bénéficiaire ne sécurise pas son paiement** > > Un bénéficiaire est une destination, pas une protection contre les doublons. Chaque `POST > /transfers` nécessite toujours sa propre valeur `Idempotency-Key`, que le bénéficiaire soit > enregistré ou non. Sans elle, une nouvelle tentative paie deux fois. Consultez > [Idempotence](https://docs.wajub.com/fr/api/idempotency). ## Comptes de versement Un compte de versement est la destination de votre propre argent : celle des payouts que vous vous faites et, une fois que vous les activez, des [versements automatiques](https://docs.wajub.com/fr/payouts/balance#settlement-to-your-payout-account) quotidiens. Vous le créez sous **Paramètres, Transferts, Comptes de paiement**, sur Mobile Money, Djamo, un compte Wajub, ou un compte bancaire via `wire`. L'API le liste comme bénéficiaire `privileged`, et il commence non vérifié. Le vérifier depuis la même page compare le compte au nom enregistré par son opérateur. Si les noms ne peuvent pas être rapprochés, Wajub demande au propriétaire du compte de confirmer le compte. Un payout `wire` entraîne des frais fixes et est traité sous 48 heures ouvrées par défaut. ## Événements envoyés à votre webhook | Événement | Déclencheur | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `beneficiary.created` | Un enregistrement est réellement créé : par `POST /beneficiaries`, à la volée par `POST /transfers`, ou comme compte de retrait dans le Dashboard. Pas quand [la même destination](https://docs.wajub.com/fr/payouts/beneficiaries/create#the-channel-decides-the-operator) renvoie le premier bénéficiaire, ce qui ne crée rien | | `beneficiary.updated` | L'un des cinq champs modifiables change | | `beneficiary.deleted` | Un bénéficiaire est supprimé | | `beneficiary.receivable_recorded` | Une dette est enregistrée sur un bénéficiaire | | `beneficiary.receivable_recovered` | Un payout groupé a recouvré tout ou partie d'une dette | - [Transferts et payouts](https://docs.wajub.com/fr/payouts): L'origine des payouts et les conditions à remplir au préalable. - [Transferts](https://docs.wajub.com/fr/payouts/transfers): Le payout lui-même : statuts, routage et échecs. - [Démarrage rapide](https://docs.wajub.com/fr/payouts/transfers/quickstart): Envoyez votre premier payout à un bénéficiaire. - [Idempotence](https://docs.wajub.com/fr/api/idempotency): L'en-tête qui sécurise une nouvelle tentative de payout. - [Référence API des bénéficiaires](https://docs.wajub.com/fr/api/beneficiaries): Tous les champs et les cinq endpoints. --- # Gérer les bénéficiaires URL: https://docs.wajub.com/fr/payouts/beneficiaries/manage > Ce qui est modifiable, récupérer, lister et supprimer un bénéficiaire, et ses relevés. ## Éléments modifiables ou non `PUT /beneficiaries/{id}` La mise à jour accepte cinq champs. La destination n'en fait pas partie. | Champ | Modifiable | | ----------------------------------------------------- | ------------------------------------------- | | `name`, `email`, `country_code`, `metadata` | Oui | | `phone` | Oui, uniquement comme coordonnée de contact | | `channel`, `account_number`, la destination du payout | Non | > [!CAUTION] > **Modifier phone ne change pas la destination des fonds** > > La destination est fixée dans le moyen de paiement associé lors de la création du bénéficiaire. > Aucun endpoint de l'API ne la modifie ensuite. Mettre à jour `phone` change le numéro de contact > dans l'enregistrement, mais le payout continue d'être envoyé au numéro d'origine, sans > avertissement ni différence dans la réponse. Pour payer un autre numéro, créez un second > bénéficiaire et utilisez son id. ## Récupérer un bénéficiaire `GET /beneficiaries/{id}` Cet appel récupère par son id le même objet que celui renvoyé à la création. Utilisez-le pour vérifier qu'un bénéficiaire est toujours actif avant un payout. Rappelez-vous qu'il n'indique toujours pas le numéro qui reçoit les fonds. **Récupérer un bénéficiaire** ```bash curl https://api.wajub.com/beneficiaries/ben_7Kq2mX9vL4tRb3nP8sZc \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` ```javascript const beneficiary = await wajub.beneficiaries.retrieve('ben_7Kq2mX9vL4tRb3nP8sZc'); console.log(beneficiary.is_active); ``` ```python beneficiary = wajub.beneficiaries.retrieve("ben_7Kq2mX9vL4tRb3nP8sZc") print(beneficiary["is_active"]) ``` ```php $beneficiary = $wajub->beneficiaries->retrieve('ben_7Kq2mX9vL4tRb3nP8sZc'); echo $beneficiary->is_active; ``` ```go beneficiary, err := client.Beneficiaries.Retrieve(context.Background(), "ben_7Kq2mX9vL4tRb3nP8sZc") if err != nil { log.Fatal(err) } log.Println(beneficiary["is_active"]) ``` Une réponse `404` couvre trois situations sans les distinguer : l'id n'existe pas, appartient à un autre compte ou dépend de l'autre environnement. Le cas le plus courant est la lecture d'un id `ben_test_` avec une clé live. ## Lister les bénéficiaires `GET /beneficiaries` Les résultats sont renvoyés du plus récent au plus ancien, par groupes de vingt-cinq, sauf si vous augmentez `per_page`, dont le maximum est 100. L'enveloppe contient `items` et `meta`. Transmettre `cursor` change à la fois le mode de pagination et la forme de `meta`, comme pour les transferts. ```json title="Réponse · 200 OK" { "code": 200, "status": "OK", "message": "Beneficiaries retrieved", "items": [ { "id": "ben_7Kq2mX9vL4tRb3nP8sZc", "name": "Amina Traoré", "type": "standard", "is_active": true } ], "meta": { "current_page": 1, "per_page": 25, "total": 1 } } ``` `search` porte sur le nom, l'e-mail, le téléphone et l'id. `is_active` filtre selon l'indicateur correspondant. Le filtre `type` mérite une explication. | Type | Créé par | Vérifié | | ------------ | -------------------------------------------------------------------------------------------- | --------------------------------------------------- | | `standard` | Vos propres appels API | À la création, sauf sur un compte Relay | | `privileged` | Vous, dans le Dashboard, comme [compte de versement](https://docs.wajub.com/fr/payouts/beneficiaries#payout-accounts) | Seulement après votre vérification sur la même page | Par défaut, la liste renvoie uniquement les bénéficiaires `standard`. Ce choix est volontaire. Un bénéficiaire `privileged` peut ne pas être vérifié. Un payout live vers une destination non vérifiée est refusé avec `This beneficiary payment method has not been verified yet and cannot receive live payouts.`. Utilisez `type=privileged` ou `type=all` uniquement si vous souhaitez réellement les afficher. Vos propres bénéficiaires sont marqués comme vérifiés dès leur création, car le marchand garantit ses propres bénéficiaires. Un bénéficiaire standard peut donc être payé immédiatement. Sur un compte Relay, le portefeuille du vendeur est d'abord comparé au nom enregistré par son opérateur, et [Payer les vendeurs](https://docs.wajub.com/fr/sync/payouts) couvre ce cas. ## Relevés et dettes Trois autres routes dépendent d'un bénéficiaire. | Route | Rôle | | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | [`GET /beneficiaries/{id}/statement`](https://docs.wajub.com/fr/api/beneficiaries/statement) | Tout ce qui lui a été versé sur une période d'un an au plus, réparti entre payé, en cours et échoué | | [`POST /beneficiaries/{id}/receivables`](https://docs.wajub.com/fr/api/beneficiaries/create-receivables) | Enregistrer ce qu'il vous doit après un remboursement. `GET` sur le même chemin liste ces dettes | | [`POST /beneficiaries/{id}/receivables/{receivable}/settle`](https://docs.wajub.com/fr/api/beneficiaries/receivables-settle) | Marquer une dette comme recouvrée hors de Wajub | Une dette enregistrée envoie `beneficiary.receivable_recorded`. Si la compensation est activée sur votre compte, le prochain payout groupé vers ce bénéficiaire en est réduit et envoie `beneficiary.receivable_recovered`. [Payer les vendeurs](https://docs.wajub.com/fr/sync/payouts) détaille les deux cas. ## Supprimer un bénéficiaire `DELETE /beneficiaries/{id}` La réponse est `200`. L'enregistrement disparaît des listes et ne peut plus être payé. Les transferts déjà envoyés vers ce bénéficiaire continuent de le référencer, afin que votre historique reste lisible : leur `beneficiary` porte `deleted: true`, et `GET /beneficiaries/{id}/statement` répond toujours pour lui. L'API ne permet aucune restauration. Recréer la même destination produit un nouveau bénéficiaire avec un nouvel `id`, et ne récupère pas l'ancien. - [Créer un bénéficiaire](https://docs.wajub.com/fr/payouts/beneficiaries/create): Enregistrer une destination et vérifier le nom. - [Référence API des bénéficiaires](https://docs.wajub.com/fr/api/beneficiaries): Tous les endpoints des bénéficiaires. --- # Transferts URL: https://docs.wajub.com/fr/payouts/transfers > L'objet transfert, les quatre appels et les conditions qui déterminent son exécution. Un transfert envoie des fonds de votre solde vers le portefeuille d'une autre personne. Cette page sert de référence pour l'objet et ses appels ; [Transferts et payouts](https://docs.wajub.com/fr/payouts) présente le coût d'un payout et les conditions nécessaires à son exécution. Les payouts nécessitent une clé secrète, ou une clé restreinte dont les autorisations couvrent les transferts. Une clé publique renvoie `406 Private Key Required`. Une clé secrète utilisée depuis un navigateur est refusée ; une clé restreinte utilisée depuis un navigateur déclenche une alerte de sécurité, et sera refusée de la même façon plus tard ([clés privées dans le navigateur](https://docs.wajub.com/fr/api/authentication#private-keys-are-blocked-in-the-browser)). ## Les quatre appels Il n'en existe aucun autre. L'API ne permet ni de modifier, ni d'annuler, ni de supprimer un transfert. | Appel | Fonction | | ----------------------- | ------------------------------------------------------------------------ | | `GET /transfers` | Lister et filtrer vos payouts | | `POST /transfers` | Créer un payout et le démarrer immédiatement | | `POST /transfers/batch` | Créer jusqu'à 500 payouts en un appel, chaque ligne démarrant séparément | | `GET /transfers/{id}` | Récupérer un payout | `{id}` correspond à la chaîne `po_` renvoyée par l'API. Dans la sandbox, elle commence par `po_test_`, ce qui permet de distinguer les deux environnements dans un log. ## L'objet transfert Les trois appels portant sur un seul transfert renvoient cet objet, et chaque ligne acceptée d'un lot le porte sous `transfer`. `beneficiary` et `payment_method` sont toujours présents, y compris un bénéficiaire supprimé depuis. ```json title="Réponse · un payout réussi" { "id": "po_CSUGajfv9xh0XQ5wu2lx", "reference": "supplier-892", "provider_reference": "MP260912.1431.A47201", "amount": 10000, "currency": "XAF", "description": "Supplier payment #892", "reason": null, "metadata": { "vendor_id": "v_892", "reservation": { "amount": 10000, "currency": "XAF", "fee_estimate": 100, "reserved_at": "2026-09-12T14:31:02+00:00" } }, "sandbox": false, "status": "succeeded", "complete": true, "source": "api", "provider": { "slug": "mtn_momo", "name": "MTN MoMo" }, "beneficiary": { "id": "ben_7Kq2mX9vL4tRb3nP8sZc", "name": "Aminata Diallo", "phone": "+237670000000", "email": null }, "payment_method": { "id": "pm_3Nq8wR2kL5vT7yD4hB1e", "account_number": null, "phone": "+237670000000" }, "succeeded_at": "2026-09-12T14:31:44+00:00", "created_at": "2026-09-12T14:31:02+00:00", "updated_at": "2026-09-12T14:31:44+00:00" } ``` Certains champs ne fonctionnent pas comme leur nom le suggère. L'un d'eux constitue un piège. - `id` (string): L'identifiant utilisé par tous les autres appels. `po_` en live et `po_test_` dans la sandbox. - `reference` (string): Votre propre identifiant, tel que vous l'avez envoyé à la création, ou la référence de la ligne dans un lot. `null` si vous n'en avez envoyé aucun. - `provider_reference` (string): L'identifiant propre à l'opérateur, renseigné dès que le payout lui parvient. Il vaut null avant cette étape. Le support de l'opérateur du bénéficiaire vous demandera cette valeur. - `amount` (number): Dans l'unité principale de la devise. `10000` représente dix mille francs, pas cent. - `status` (enum): `processing`, `review`, `succeeded`, `failed` ou `cancelled`, ou `pending` pour un payout du Dashboard qui attend votre confirmation, jusqu'à ce que vous le confirmiez ou le rejetiez dans le Dashboard. `cancelled` est un payout arrêté avant son envoi. - `complete` (boolean): Vaut true uniquement avec `succeeded`. Un payout échoué est terminé mais renvoie toujours `false`. Ce champ indique donc le résultat, pas la fin du payout. - `source` (enum): `api` pour toute création par votre intégration, `dashboard` ou `recurring` pour un payout lancé depuis la Konsole. - `metadata` (object): Vos données, avec celles ajoutées par Wajub. Voir ci-dessous. - `failure_reason` (string): Présent uniquement lorsque `status` vaut `failed`, avec `failure_message`. Ce champ est absent pour tous les autres statuts, et non défini à null. - `beneficiary` (object): `id`, `name`, `phone`, `email` et `deleted`. Un bénéficiaire supprimé après le payout reste présent avec `deleted: true`, et son relevé reste lisible. > [!NOTE] > **reference vous appartient, et n'est pas unique** > > `POST /transfers` enregistre la `reference` que vous envoyez, jusqu'à 255 caractères, et la > renvoie à chaque lecture et dans chaque webhook. Wajub ne contrôle jamais son unicité : deux > payouts peuvent porter la même référence, utilisez donc `id` lorsque vous devez identifier un > payout avec certitude. La recherche dans la liste ne la lit pas non plus, seulement l'id `po_` et > la description. Wajub ajoute ses propres clés à `metadata`, comme `reservation`. Lisez vos propres clés par leur nom au lieu de supposer que tout l'objet vous appartient. ## Créer un transfert `POST /transfers` - `beneficiary` (string | object, required): L'id d'un bénéficiaire enregistré ou les coordonnées inline du destinataire. Les deux formes sont détaillées ci-dessous. - `amount` (number, required): Dans l'unité principale, au moins `0.01` et dans les plafonds définis pour la devise. - `currency` (string, required): Trois lettres et une devise active. - `description` (string): Texte libre de 255 caractères, utilisable dans la recherche des deux environnements. - `reason` (string): Un second champ de texte libre de 255 caractères. Il est stocké et renvoyé, sans autre utilisation. - `reference` (string): Jusqu'à 255 caractères. Enregistrée et renvoyée, jamais contrôlée pour son unicité. - `metadata` (object): Vos propres clés libres, renvoyées à chaque lecture. Le destinataire se met dans `beneficiary`, et il y a plusieurs façons de le désigner. Choisissez le cas qui correspond à ce que vous avez. | Vous avez | À envoyer dans `beneficiary` | Cas | | ------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------- | | Un bénéficiaire enregistré plus tôt | Son `id`, en chaîne : `"ben_…"` | [Un bénéficiaire enregistré](#a-saved-beneficiary) | | Les coordonnées du bénéficiaire, pour un premier payout | Un objet : `name`, `channel`, `phone` ou `account_number` | [Un nouveau destinataire](#a-new-recipient-created-by-the-payout) | | Ces coordonnées, pour quelqu'un déjà enregistré | Le même objet | [Quelqu'un déjà enregistré](#a-recipient-you-already-saved-sent-inline-again) | | Un numéro camerounais, sans son opérateur | L'objet, avec `channel: "cm.mobile"` | [Un numéro sans opérateur](#a-number-without-its-operator) | | Un numéro de compte Wajub | L'objet, avec `channel: "wajub"` | [Un autre compte Wajub](#another-wajub-account) | Dans tous les cas, chaque payout a besoin de sa propre `Idempotency-Key` : un bénéficiaire enregistré est une destination, pas une protection contre le double paiement. ### Un bénéficiaire enregistré Envoyez l'`id` en chaîne. Le reste du payout ne change pas. ```json title="Payer un bénéficiaire enregistré" { "beneficiary": "ben_7Kq2mX9vL4tRb3nP8sZc", "amount": 15000, "currency": "XAF", "description": "Forfait de septembre" } ``` Seul l'`id` est reconnu, dans l'environnement de votre clé : un bénéficiaire sandbox n'existe pas pour une clé live. Un numéro de téléphone ou une adresse e-mail ne le sont pas, même s'ils identifient le bénéficiaire ailleurs dans l'API. Chaque refus est un `422` avec un `error_code` : | Quand | `error_code` | Message | | ----------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------- | | Aucun de vos bénéficiaires n'a cet `id` (numéro de téléphone ou e-mail compris), ou il a été supprimé | `beneficiary_not_found` | `The selected beneficiary is invalid.` | | Il est désactivé | `beneficiary_inactive` | `This beneficiary is deactivated. Reactivate it, or pay another beneficiary.` | | Il a été ajouté depuis la Konsole | `beneficiary_not_allowed` | `This beneficiary was added from the Konsole dashboard and cannot be paid out via the API.` | Ce dernier refus est voulu : une clé divulguée ne doit pas pouvoir payer une destination que votre intégration n'a jamais créée. ### Un nouveau destinataire, créé par le payout Envoyez les coordonnées du bénéficiaire sous forme d'objet : le bénéficiaire est créé pendant l'appel. C'est ce qu'il faut pour un premier payout, ou pour une personne que vous ne paierez qu'une fois : un appel au lieu de deux. Les champs appartiennent au bénéficiaire et sont tous décrits dans [Bénéficiaires](https://docs.wajub.com/fr/payouts/beneficiaries). - `beneficiary.name` (string, required): Le bénéficiaire, tel qu'il doit apparaître sur le payout. - `beneficiary.channel` (string, required): Le canal de l'opérateur qui dessert le numéro, comme `cm.mtn` ou `ke.mpesa`. Au Cameroun uniquement, `cm.mobile` détermine l'opérateur à partir du numéro. - `beneficiary.phone` (string): Obligatoire sauf si vous transmettez `account_number`. - `beneficiary.account_number` (string): L'autre partie de cette paire. L'un des deux champs doit être présent. - `beneficiary.email` (string): Adresse de contact. Aucun message n'y est envoyé. - `beneficiary.country_code` (string): Deux lettres. Par défaut, les deux premières lettres du slug du canal. - `beneficiary.note` (string): Texte libre de 500 caractères. **Payer une personne que vous ne paierez plus** ```bash curl https://api.wajub.com/transfers \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: payout-892" \ -d '{ "amount": 10000, "currency": "XAF", "description": "Supplier payment #892", "metadata": { "vendor_id": "v_892" }, "beneficiary": { "name": "Aminata Diallo", "channel": "cm.mtn", "phone": "+237670000000" } }' ``` ```javascript const transfer = await wajub.transfers.create({ amount: 10000, currency: 'XAF', description: 'Supplier payment #892', metadata: { vendor_id: 'v_892' }, beneficiary: { name: 'Aminata Diallo', channel: 'cm.mtn', phone: '+237670000000' }, }, { idempotencyKey: 'payout-892' }); console.log(transfer.id, transfer.status); ``` ```python from wajub import RequestOptions transfer = wajub.transfers.create({ "amount": 10000, "currency": "XAF", "description": "Supplier payment #892", "metadata": {"vendor_id": "v_892"}, "beneficiary": {"name": "Aminata Diallo", "channel": "cm.mtn", "phone": "+237670000000"}, }, RequestOptions(idempotency_key="payout-892")) print(transfer.id, transfer.status) ``` ```php use Wajub\RequestOptions; $transfer = $wajub->transfers->create([ 'amount' => 10000, 'currency' => 'XAF', 'description' => 'Supplier payment #892', 'metadata' => ['vendor_id' => 'v_892'], 'beneficiary' => [ 'name' => 'Aminata Diallo', 'channel' => 'cm.mtn', 'phone' => '+237670000000', ], ], new RequestOptions(idempotencyKey: 'payout-892')); echo $transfer->id; ``` ```go transfer, err := client.Transfers.Create(context.Background(), map[string]any{ "amount": 10000, "currency": "XAF", "description": "Supplier payment #892", "metadata": map[string]any{"vendor_id": "v_892"}, "beneficiary": map[string]any{ "name": "Aminata Diallo", "channel": "cm.mtn", "phone": "+237670000000", }, }, &wajub.RequestOptions{IdempotencyKey: "payout-892"}) ``` La réponse est `201 Created`, et le `beneficiary.id` du transfert est celui du nouveau bénéficiaire. C'est un bénéficiaire normal : il apparaît dans `GET /beneficiaries`, `beneficiary.created` est envoyé pour lui, et le prochain payout à cette personne peut envoyer cet `id` au lieu des coordonnées. ### Un destinataire déjà enregistré, renvoyé inline Envoyer les coordonnées d'une personne déjà enregistrée ne crée pas de second bénéficiaire. Quand un de vos bénéficiaires actifs utilise déjà ce numéro sur ce canal, le payout va vers lui : le `beneficiary.id` du transfert est celui qui existe, et les `name`, `email` et `note` que vous venez d'envoyer sont ignorés, pas écrits à la place des valeurs enregistrées. Pour les changer, utilisez [`PUT /beneficiaries/{id}`](https://docs.wajub.com/fr/payouts/beneficiaries/manage#what-you-can-change-and-what-you-cannot). ### Un numéro sans son opérateur Un payout désigne son canal, et le Cameroun est la seule exception : quand vous avez un numéro camerounais sans son opérateur, envoyez `cm.mobile` avec `phone`. L'opérateur, `cm.mtn` ou `cm.orange`, est déduit du numéro. Un numéro qui ne correspond à aucun des deux est refusé avec un `422` sur `channel` et `phone`, au lieu d'être envoyé au hasard. ```json title="Laisser le numéro choisir l'opérateur" { "amount": 10000, "currency": "XAF", "beneficiary": { "name": "Aminata Diallo", "channel": "cm.mobile", "phone": "+237670000000" } } ``` Aucun autre pays n'a de canal générique : `ke.mobile`, `eg.mobile` ou tout autre `{country}.mobile` est refusé comme un canal inconnu. Indiquez le canal de l'opérateur, comme `ke.mpesa` ou `eg.vodafone` ; [Prestataires de payout](https://docs.wajub.com/fr/payouts/transfers/providers) les liste. Au Cameroun aussi, nommez l'opérateur quand vous le connaissez : `cm.mobile` sert quand vous n'avez que le numéro. ### Un autre compte Wajub Pour payer quelqu'un qui a un compte Wajub, envoyez `channel: "wajub"` et son numéro de compte à 11 chiffres dans `account_number`. L'argent passe de votre solde au sien immédiatement, sans réseau entre les deux, et le payout est gratuit. Le compte doit exister, ne peut pas être le vôtre, ni un compte que Wajub a gelé. [Payer un autre compte Wajub](https://docs.wajub.com/fr/payouts/beneficiaries/create#paying-another-wajub-account) donne le détail. ```json title="Payer un autre compte Wajub" { "amount": 25000, "currency": "XAF", "beneficiary": { "name": "Boutique Ada", "channel": "wajub", "account_number": "12345678901" } } ``` ### Créer d'abord, payer ensuite Vous pouvez aussi créer le bénéficiaire seul avec `POST /beneficiaries`, puis le payer par son `id`. C'est deux appels au lieu d'un, et cela vaut la peine quand vous voulez : - vérifier le nom que l'opérateur connaît pour un wallet avant que l'argent ne parte, avec [`POST /beneficiaries/{id}/verify`](https://docs.wajub.com/fr/payouts/beneficiaries/create#checking-the-name-on-a-wallet) ; - montrer le bénéficiaire dans votre propre interface, ou le faire approuver, avant le premier payout. ### Ce que l'API ne peut pas payer - **Un bénéficiaire ajouté depuis la Konsole, compte de versement compris.** Payez-le depuis le Dashboard. - **Un compte bancaire.** L'API ne crée que des bénéficiaires Mobile Money, wallet adressé par téléphone (comme Djamo) et compte Wajub. Un payout bancaire passe par un [compte de versement](https://docs.wajub.com/fr/payouts/beneficiaries#payout-accounts) `wire`, créé et payé depuis le Dashboard. - **Le bénéficiaire du marchand ou d'une autre plateforme, via `X-Sync`.** Une plateforme qui paie pour un compte connecté ne paie que les bénéficiaires de cette connexion. - **Un destinataire inline dans un lot.** Chaque ligne de `POST /transfers/batch` désigne un bénéficiaire enregistré par son `id` ; la forme objet sert aux payouts unitaires. ## Les montants utilisent l'unité principale Le champ `amount` d'un transfert utilise l'unité principale de la devise et accepte les décimales. `10000` envoie dix mille francs. Une [facture](https://docs.wajub.com/fr/billing/invoice) utilise au contraire des lignes en unités entières de la devise. Ne réutilisez donc pas une conversion de l'un vers l'autre. Chaque devise possède un minimum et un maximum, contrôlés avant toute autre opération. Dépasser l'un de ces plafonds renvoie une erreur `422` qui indique les deux valeurs. | Devise | Minimum | Maximum | | ----------------------- | ------- | ----------- | | `XAF` `XOF` | 25 | 2 000 000 | | `NGN` | 100 | 999 999,99 | | `RWF` | 500 | 999 999 999 | | `UGX` | 1 000 | 999 999 999 | | `GHS` `KES` `USD` `EUR` | 0,50 | 999 999,99 | Ces valeurs constituent les plafonds de la plateforme pour un appel. Les autres plafonds vous sont propres : le plafond quotidien défini par vos soins, la limite liée à votre palier KYC et le plafond par transfert de l'opérateur. [Transferts et payouts](https://docs.wajub.com/fr/payouts) présente toute la séquence. ## L'idempotence est facultative et constitue votre seule protection Envoyez un en-tête `Idempotency-Key`. Une nouvelle tentative du même appel renverra alors le transfert d'origine au lieu d'envoyer les fonds deux fois. Si vous l'omettez, rien n'empêche un doublon, et aucune annulation ne permet de se rattraper. La clé accepte au maximum 128 caractères parmi les lettres, les chiffres et `. _ : -` ; toute autre valeur renvoie `422`. Elle est consommée pour toujours, par compte et par environnement : une clé qui a créé un transfert renvoie toujours ce transfert, et n'en envoie jamais un second. > [!WARNING] > **Une clé, un payout** > > Réutiliser une clé avec un corps différent renvoie `422 This Idempotency-Key was already used with > a different request payload.`, ou renvoie le transfert d'origine sans rien envoyer. Dérivez la clé > de l'élément payé, comme une ligne de commande ou un traitement de paie avec sa période. Une même > clé ne pourra ainsi jamais décrire deux payouts différents : `salaire-amina` réutilisée le mois > suivant ne paie personne. La création de payouts possède sa propre limite de requêtes, qui s'ajoute à celle de votre plan : **20 appels par minute**, par compte et par environnement, quel que soit le plan, partagés par `POST /transfers`, `POST /transfers/batch`, `POST /accounts/{id}/payouts`, `POST /beneficiaries`, `POST /beneficiaries/{id}/receivables` et `POST /beneficiaries/{id}/receivables/{receivable}/settle`. Une boucle qui crée un bénéficiaire puis le paie compte donc deux fois. Sous une forte charge simultanée, un payout live peut être refusé avec `429`, `error_code: payout_queue_busy` et un en-tête `Retry-After`. Rien n'a été créé : renvoyez-le après ce délai, avec la même `Idempotency-Key`. Une ligne de lot dans ce cas est refusée avec le même code et peut repartir avec le lot. ## Réponse reçue et statut initial Un payout est créé avec le statut `processing` et est déjà en cours d'acheminement, ou avec le statut `review` lorsqu'une protection le retient. Un payout que vous créez n'est jamais `pending` quand vous le lisez : seul un payout du Dashboard qui attend votre confirmation porte `pending`. Confirmé, il est contrôlé comme un nouveau payout et peut être [retenu pour vérification](#why-a-live-payout-is-held) (`review`) ou partir en `processing` ; rejeté, il finit `cancelled`. **Transfert** `pending` (payout du Dashboard à confirmer) → [`transfer.processing`] `processing` (transmis à l'opérateur) → [`transfer.succeeded`] `succeeded` (complete passe à true) Autres états possibles pour un payout: - `review` (retenu, fonds réservés) - `failed` (lisez failure_reason) `transfer.created` est émis à la création de chaque payout, y compris pour un payout retenu pour examen. [Statuts et webhooks](https://docs.wajub.com/fr/payouts/transfers/statuses-and-webhooks) détaille les cinq événements et le rôle de chaque handler. Un payout arrêté avant tout envoi, rejeté dans le Dashboard ou annulé par Wajub, se termine en `cancelled`, avec `merchant_rejected` ou `cancelled_by_wajub` pour `failure_reason`. Un payout que Wajub refuse après un examen se termine en `failed`, avec `admin_rejected`. ## Raisons de la retenue d'un payout live Un payout live qui déclenche l'un des contrôles suivants est créé avec le statut `review` au lieu de `processing`. Ses fonds sont réservés, aucun opérateur ne l'a reçu et il attend que Wajub le libère ou le refuse. | Motif de retenue | Signification | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Il fait partie de vos premiers payouts | Les premiers payouts live de votre compte peuvent être retenus pour examen : planifiez-les | | Le montant dépasse votre propre seuil | Le montant d'approbation défini dans Transfer security settings | | Vous avez demandé la confirmation des payouts | Le réglage de confirmation, sauf pour le montant exempté par votre approbation automatique | | Les contrôles de Wajub | Wajub peut retenir tout payout pour examen avant son départ | | Wajub a restreint votre compte | Une restriction comme l'approbation manuelle ou un délai de payout retient chaque payout live, quel que soit son montant, jusqu'à sa levée | Un payout retenu quitte finalement `review` dans l'une de deux directions. S'il est libéré, il passe à `processing` et continue normalement. S'il est refusé, il passe à `failed` avec `failure_reason: admin_rejected`, puis la réservation revient dans votre solde disponible. > [!CAUTION] > **Vous ne pouvez ni lister ni débloquer les payouts en cours d'examen** > > La liste ne peut pas être filtrée sur `review` : pour voir un payout retenu, récupérez-le > directement ou parcourez une liste non filtrée. Aucun endpoint ne permet de l'approuver, de l'annuler ou de le relancer. Le webhook > `transfer.created` vous informe de la retenue. `transfer.processing` ou `transfer.failed` vous > informe de sa résolution. Attendez ces événements au lieu d'utiliser le polling. Les payouts sandbox ne sont jamais retenus. Vous ne pouvez pas reproduire ce comportement avant le passage en live. Votre premier payout live mérite donc une surveillance humaine plutôt qu'un script sans surveillance. ## En cas d'échec Un payout échoué contient `failure_reason`, un code court, et `failure_message`, une phrase. Ces deux champs sont absents pour tous les autres statuts. Ne les lisez qu'après avoir vérifié le statut. Une fois qu'un payout a atteint un opérateur, le code peut être celui de l'opérateur. Considérez ce champ comme un libellé à consigner dans vos logs et à présenter à une personne, pas comme une enum sur laquelle baser vos branches. | `failure_reason` | Problème rencontré | | ------------------------------------------ | --------------------------------------------------------------------------------------- | | `invalid_recipient` | La destination est introuvable ou le bénéficiaire a perdu son canal | | `no_provider` | Aucune route de payout n'était disponible pour ce canal et cette devise | | `provider_rejected` | L'opérateur a refusé le payout et en indique la raison dans `failure_message` | | `team_restricted` | Une restriction de payout a été ajoutée à votre compte entre la création et l'exécution | | `admin_rejected` | Un payout retenu a été refusé pendant l'examen | | `failed`, ou le propre code d'un opérateur | Le payout a atteint un opérateur et a échoué | La sandbox fait exception. Son vocabulaire se limite à `failure`, `network_error` et `invalid_recipient`, chacun associé à un numéro de test. Pour un payout sur le circuit Wajub, un échec libère la réservation. Le principal et l'estimation des frais reviennent dans `available`, sans aucun prélèvement. Vous pouvez recréer le payout avec une nouvelle clé d'idempotence. ## Tester le payout Les payouts sandbox puisent dans votre solde sandbox et se terminent automatiquement environ deux secondes plus tard. Le résultat n'est pas aléatoire. Il dépend du numéro du destinataire, qui doit être un numéro de test reconnu. Sinon, l'appel est immédiatement refusé. | Numéro | Résultat | | --------------- | -------------------------------------------------------------- | | `+237670000000` | `succeeded` | | `+237670000001` | Refus à la création avec `422`, le transfert n'est jamais créé | | `+237670000002` | `failed`, motif `failure` | | `+237670000003` | `failed`, motif `network_error` | | `+237670000004` | `failed`, motif `invalid_recipient` | Le suffixe compte, pas le préfixe. Ces cinq terminaisons fonctionnent donc après tous les préfixes d'opérateurs connus de la sandbox. `+2250700000002` échoue comme `+237670000002`. > [!NOTE] > **Des fonds insuffisants ne produisent pas un payout échoué** > > `…0001` représente un destinataire dont le portefeuille ne peut pas recevoir les fonds. La > sandbox renvoie une erreur `422` avant toute création. Il n'existe aucun transfert à récupérer ni > aucun webhook. Pour tester un handler d'échec, utilisez plutôt `…0002`. Les payouts sandbox entraînent **2 %** de frais de plateforme ajoutés au montant. Ces frais ne sont pas rendus en cas d'échec. Ce taux propre à la sandbox ne correspond pas à la tarification live. ## Lister les transferts `GET /transfers` - `status` (enum): `pending`, `processing`, `succeeded`, `failed` ou `cancelled`. Pas `review`. - `search` (string): Recherche dans l'id et la description. - `per_page` (integer, default `25`): Entre 1 et 100. - `cursor` (string): Le `next_cursor` d'une page précédente. L'envoyer fait passer toute la réponse en mode curseur. Il n'existe aucun filtre par date ou par montant. Une tâche de rapprochement parcourt donc la liste et applique son propre filtre sur `created_at`. **Tous les échecs, du plus récent au plus ancien** ```bash curl -G https://api.wajub.com/transfers \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -d status=failed \ -d per_page=50 ``` ```javascript const { data, meta } = await wajub.transfers.list({ status: 'failed', per_page: 50, }); ``` ```python page = wajub.transfers.list({ "status": "failed", "per_page": 50, }) ``` ```php $page = $wajub->transfers->list([ 'status' => 'failed', 'per_page' => 50, ]); ``` ```go page, err := client.Transfers.List(context.Background(), map[string]any{ "status": "failed", "per_page": 50, }) ``` La liste est triée par date de création, de la plus récente à la plus ancienne. Vous ne pouvez pas modifier cet ordre. Par défaut, elle utilise une pagination par numéro de page. `meta` contient alors `current_page`, `last_page`, `per_page` et `total`, ainsi que le `next_cursor` et le `has_more` qui permettent de continuer avec un curseur. Si vous transmettez ce `next_cursor` comme `cursor`, `meta` change de forme et contient `per_page`, `next_cursor`, `prev_cursor` et `has_more`. Choisissez un mode et écrivez votre boucle en conséquence. Un handler qui lit `last_page` casse dès qu'un curseur est ajouté. ## Récupérer un transfert `GET /transfers/{id}` Seul l'id `po_` permet de retrouver un transfert. Un transfert appartenant à un autre compte ou à l'autre environnement renvoie `404 Transfer Not Found`, sans révéler son existence ailleurs. **Récupérer un transfert** ```bash curl https://api.wajub.com/transfers/po_CSUGajfv9xh0XQ5wu2lx \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` ```javascript const transfer = await wajub.transfers.retrieve('po_CSUGajfv9xh0XQ5wu2lx'); ``` ```python transfer = wajub.transfers.retrieve("po_CSUGajfv9xh0XQ5wu2lx") ``` ```php $transfer = $wajub->transfers->retrieve('po_CSUGajfv9xh0XQ5wu2lx'); ``` ```go transfer, err := client.Transfers.Retrieve(context.Background(), "po_CSUGajfv9xh0XQ5wu2lx") ``` La récupération sert au rapprochement et au support, pas au suivi d'un payout. Attendez plutôt le webhook. Un payout qui atteint un opérateur peut y rester plusieurs minutes. Le polling ne vous apprend rien que l'événement ne vous aurait pas indiqué plus tôt. - [Démarrage rapide](https://docs.wajub.com/fr/payouts/transfers/quickstart): Votre premier payout de test, de bout en bout. - [Prestataires et canaux](https://docs.wajub.com/fr/payouts/transfers/providers): Tous les slugs de canaux, classés par pays et par opérateur. - [Statuts et webhooks](https://docs.wajub.com/fr/payouts/transfers/statuses-and-webhooks): Les cinq événements et le rôle de chaque handler. - [Bénéficiaires](https://docs.wajub.com/fr/payouts/beneficiaries): Enregistrez une destination une fois, puis payez-la par son id. - [Solde et règlements](https://docs.wajub.com/fr/payouts/balance): Les fonds disponibles et ceux déjà réservés. --- # Prestataires et canaux URL: https://docs.wajub.com/fr/payouts/transfers/providers > Les canaux qu'un payout peut utiliser et les conditions qui déterminent leur disponibilité. Un canal désigne un opérateur dans un pays : `cm.mtn` correspond à MTN Cameroun et `sn.wave` à Wave Sénégal. Il appartient au bénéficiaire et reste donc fixé dès la création de la destination ; la liste ci-dessous indique ce que l'API accepte, et l'exécution réelle dépend de votre compte. ## Conditions à remplir Un canal de la liste ci-dessous est accepté lorsque vous l'indiquez, mais un payout ne s'exécute que sur un canal sur lequel votre compte peut effectuer des payouts, dans cette devise. | Cas | Refus avec | | --------------------------------------------------------------------- | -------------------------------------------------------------------- | | Le slug n'est pas un canal de payout | `422 The selected beneficiary.channel is invalid.` | | Votre compte n'a aucune route de payout pour ce canal et cette devise | `422 No payout provider is available for this channel and currency.` | ## Canaux acceptés par l'API L'API accepte cinquante canaux Mobile Money dans vingt-deux pays. Chacun constitue une valeur valide pour `beneficiary.channel`. | Pays | Canaux | | ----------------- | -------------------------------------------------- | | Bénin | `bj.mtn` `bj.moov` | | Burkina Faso | `bf.orange` `bf.moov` | | Cameroun | `cm.mtn` `cm.orange` `cm.eu` | | Congo-Brazzaville | `cg.mtn` `cg.airtel` | | Côte d'Ivoire | `ci.mtn` `ci.orange` `ci.moov` `ci.wave` | | RD Congo | `cd.vodacom` `cd.airtel` `cd.orange` `cd.africell` | | Égypte | `eg.vodafone` | | Gabon | `ga.airtel` `ga.moov` | | Ghana | `gh.mtn` `gh.vodafone` `gh.airteltigo` | | Guinée | `gn.mtn` `gn.orange` | | Kenya | `ke.mpesa` `ke.airtel` | | Liberia | `lr.mtn` | | Malawi | `mw.airtel` `mw.tnm` | | Mali | `ml.orange` `ml.moov` | | Mozambique | `mz.mpesa` | | Rwanda | `rw.mtn` `rw.airtel` | | Sénégal | `sn.orange` `sn.free` `sn.wave` | | Sierra Leone | `sl.orange` | | Tanzanie | `tz.mpesa` `tz.airtel` `tz.tigo` `tz.halopesa` | | Togo | `tg.tmoney` `tg.moov` | | Ouganda | `ug.mtn` `ug.airtel` | | Zambie | `zm.mtn` `zm.airtel` `zm.zamtel` | `cd.vodacom` et `mz.mpesa` désignent tous deux M-Pesa, tandis que `cm.eu` désigne Express Union. Trois autres canaux sont valides pour un bénéficiaire sans être du Mobile Money : `ci.djamo` et `sn.djamo`, des portefeuilles Djamo payés par numéro de téléphone, et `wajub`, un autre compte Wajub payé par son numéro de compte, qui ne quitte jamais Wajub et n'entraîne aucuns frais. Tout autre canal, bancaire compris, renvoie `422 The selected beneficiary.channel is invalid.` Une destination bancaire est un [compte de versement](https://docs.wajub.com/fr/payouts/beneficiaries#payout-accounts) que vous créez dans le Dashboard sur le canal `wire`. ## Canal générique Un payout désigne son canal : le slug de l'opérateur dans ce tableau, comme `ke.mpesa` ou `eg.vodafone`. Il n'y a qu'une exception, le Cameroun : `cm.mobile` détermine à partir du numéro s'il s'agit de `cm.mtn` ou de `cm.orange`. La page [Bénéficiaires](https://docs.wajub.com/fr/payouts/beneficiaries) explique le fonctionnement de cette résolution et ses cas d'échec. Aucun autre pays n'a de canal générique. `ke.mobile`, `eg.mobile` ou tout autre `{country}.mobile` est refusé comme un canal inconnu, avec `422` et `The selected channel is invalid.`. Même au Cameroun, indiquez l'opérateur dès que vous le connaissez : un échec de résolution produit une erreur `422`, alors qu'un slug explicite serait passé directement. ## Couverture propre à votre compte Tous les canaux autres que `cm.mtn`, `cm.orange` et `cm.eu` nécessitent un prestataire de payout connecté à votre compte et **approuvé par Wajub pour les payouts live** ; [`GET /providers`](https://docs.wajub.com/fr/api/providers/list) liste ce que possède votre compte. Connecter un prestataire pour les encaissements n'active pas son côté payout. > [!CAUTION] > **Par défaut, trois canaux effectuent des payouts** > > Tant qu'aucun prestataire de payout n'est approuvé sur votre compte, les payouts live partent > uniquement sur `cm.mtn`, `cm.orange` et `cm.eu`. Vérifiez ce point avant d'intégrer un corridor à > votre produit, plutôt que de le découvrir lors du premier transfert live. ## Ce que la devise détermine ou non Envoyez la devise de règlement de l'opérateur : `XAF` sur `cm.*`, `XOF` sur `ci.*`. Une devise dans laquelle votre compte ne peut pas effectuer de payout sur ce canal renvoie le même message `No payout provider is available for this channel and currency.` que tout autre manque de couverture. ## Prestataire chargé du payout Un transfert ne possède aucun champ `provider` ni aucune surcharge par appel : vous indiquez un canal. Lorsque plusieurs prestataires de payout connectés à votre compte peuvent le traiter, la priorité que vous définissez pour chacun détermine l'ordre, et un échec fait passer au suivant. La page [Orchestration](https://docs.wajub.com/fr/orchestration) explique comment définir cette priorité. Le transfert indique ensuite dans `provider` le prestataire qui l'a exécuté. L'identifiant propre à l'opérateur apparaît dans `provider_reference` une fois que le payout l'a atteint. - [Transferts](https://docs.wajub.com/fr/payouts/transfers): L'objet, les quatre appels et les conditions d'exécution d'un payout. - [Bénéficiaires](https://docs.wajub.com/fr/payouts/beneficiaries): Où définir le canal et comment sa forme générique est résolue. - [Démarrage rapide](https://docs.wajub.com/fr/payouts/transfers/quickstart): Un premier payout dans la sandbox, de bout en bout. - [Orchestration](https://docs.wajub.com/fr/orchestration): La priorité, le repli et le coupe-circuit. --- # Démarrage rapide URL: https://docs.wajub.com/fr/payouts/transfers/quickstart > Alimentez un solde sandbox, envoyez votre premier payout, puis répétez l'opération en live. Alimentez un solde sandbox, envoyez un premier payout et testez ses échecs, puis passez en live. Un payout dépense l'argent que vous détenez déjà : la première étape encaisse donc des fonds. > [!WARNING] > **Un solde sandbox commence à zéro** > > Il n'existe aucun endpoint pour recharger un solde sandbox, aucun bouton dans la Konsole et aucun > crédit initial. Vous l'alimentez exactement comme un solde live, en encaissant un paiement. Si > vous ignorez l'étape 1, l'étape 3 est refusée avec une erreur `422` dont le message commence par > `Insufficient sandbox balance`. Un solde qui couvre le montant mais pas les frais de 2 % qui s'y > ajoutent est refusé aussi : `Insufficient sandbox balance to send this payout and its fee of 100 XAF.` ## 1. Alimenter le solde Créez un paiement sandbox supérieur au montant que vous comptez envoyer, puis payez-le vous-même sur sa page de checkout. [Accepter un paiement](https://docs.wajub.com/fr/payments/quickstart) détaille correctement cet appel. Ici, il sert uniquement à alimenter le solde. **Encaisser 20 000 XAF dans la sandbox** ```bash curl https://api.wajub.com/payments \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 20000, "currency": "XAF", "email": "you@example.com", "description": "Funding my sandbox balance" }' ``` ```javascript const payment = await wajub.payments.create({ amount: 20000, currency: 'XAF', email: 'you@example.com', description: 'Funding my sandbox balance', }); console.log(payment.authorization_url); ``` ```python payment = wajub.payments.create({ "amount": 20000, "currency": "XAF", "email": "you@example.com", "description": "Funding my sandbox balance", }) print(payment["authorization_url"]) ``` ```php $payment = $wajub->payments->create([ 'amount' => 20000, 'currency' => 'XAF', 'email' => 'you@example.com', 'description' => 'Funding my sandbox balance', ]); echo $payment->authorization_url; ``` ```go payment, err := client.Payments.Create(context.Background(), map[string]any{ "amount": 20000, "currency": "XAF", "email": "you@example.com", "description": "Funding my sandbox balance", }, nil) log.Println(payment.AuthorizationURL) ``` Ouvrez l'`authorization_url`, choisissez Mobile Money et payez avec **`+237670000000`**. Ce numéro réussit toujours dans la sandbox. Quelques secondes plus tard, le paiement est réglé et le montant atteint votre solde, après déduction des frais de plateforme sandbox de 2 %. Un encaissement de 20 000 XAF laisse donc **19 600 XAF** à envoyer. ## 2. Vérifier le montant disponible Un seul appel, sans paramètre. Il renvoie le solde de l'environnement associé à votre clé. La même ligne de code lit donc le portefeuille sandbox aujourd'hui et le portefeuille réel demain. `GET /balance` L'appel accepte un paramètre `currency` facultatif pour convertir le montant dans une autre devise. Omettez-le pour obtenir la devise de votre compte. **Consulter le solde sandbox** ```bash curl https://api.wajub.com/balance \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" ``` ```javascript const balance = await wajub.balance.retrieve(); console.log(balance.available, balance.currency); ``` ```python balance = wajub.balance.retrieve() print(balance["available"], balance["currency"]) ``` ```php $balance = $wajub->balance->retrieve(); echo $balance['available']; ``` ```go balance, err := client.Balance.Retrieve(context.Background()) if err != nil { log.Fatal(err) } log.Println(balance["available"], balance["currency"]) ``` La réponse contient cinq montants. ```json title="Réponse · 200 OK" { "code": 200, "status": "OK", "message": "Balance retrieved", "balance": { "total": 19600, "available": 19600, "pending": 0, "reserved": 0, "credit": 0, "currency": "XAF", "environment": "sandbox" } } ``` `available` est le seul montant utilisable par un payout. Vérifiez `environment` si vous avez un doute sur la clé utilisée. ## 3. Envoyer le payout `POST /transfers` Transmettez le destinataire inline. Wajub crée alors le bénéficiaire avec le payout, ce qui convient à un premier essai. Le champ `channel` désigne l'opérateur du numéro. Le téléphone doit être un numéro de test sandbox, sinon l'appel est refusé avant toute création. Envoyez une valeur `Idempotency-Key` dès le premier appel. Elle ne coûte rien et constitue la seule protection d'une nouvelle tentative, ici comme en production. **Payer 5 000 XAF à un numéro de test** ```bash curl https://api.wajub.com/transfers \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: first-payout-01" \ -d '{ "amount": 5000, "currency": "XAF", "description": "First test payout", "beneficiary": { "name": "Aminata Diallo", "channel": "cm.mtn", "phone": "+237670000000" } }' ``` ```javascript const transfer = await wajub.transfers.create({ amount: 5000, currency: 'XAF', description: 'First test payout', beneficiary: { name: 'Aminata Diallo', channel: 'cm.mtn', phone: '+237670000000' }, }, { idempotencyKey: 'first-payout-01' }); console.log(transfer.id, transfer.status); ``` ```python from wajub import RequestOptions transfer = wajub.transfers.create({ "amount": 5000, "currency": "XAF", "description": "First test payout", "beneficiary": {"name": "Aminata Diallo", "channel": "cm.mtn", "phone": "+237670000000"}, }, RequestOptions(idempotency_key="first-payout-01")) print(transfer["id"], transfer["status"]) ``` ```php use Wajub\RequestOptions; $transfer = $wajub->transfers->create([ 'amount' => 5000, 'currency' => 'XAF', 'description' => 'First test payout', 'beneficiary' => [ 'name' => 'Aminata Diallo', 'channel' => 'cm.mtn', 'phone' => '+237670000000', ], ], new RequestOptions(idempotencyKey: 'first-payout-01')); echo $transfer->id; ``` ```go transfer, err := client.Transfers.Create(context.Background(), map[string]any{ "amount": 5000, "currency": "XAF", "description": "First test payout", "beneficiary": map[string]any{ "name": "Aminata Diallo", "channel": "cm.mtn", "phone": "+237670000000", }, }, &wajub.RequestOptions{IdempotencyKey: "first-payout-01"}) ``` Wajub répond `201 Created` et le payout possède déjà le statut `processing`. Aucune confirmation de votre part n'est attendue. ```json title="Réponse · 201 Created" { "code": 201, "status": "Created", "message": "Transfer initiated", "transfer": { "id": "po_test_CSUGajfv9xh0XQ5wu2lx", "amount": 5000, "currency": "XAF", "status": "processing", "complete": false, "sandbox": true, "source": "api", "beneficiary": { "id": "ben_test_7Kq2mX9vL4tRb3nP8sZc", "name": "Aminata Diallo", "phone": "+237670000000" }, "created_at": "2026-09-12T14:31:02+00:00" } } ``` Enregistrez `transfer.id`. C'est le seul identifiant unique : la `reference` que vous pouvez envoyer revient telle quelle mais n'est jamais contrôlée pour son unicité, et aucun appel ne permet d'annuler un payout existant. Votre solde a subi deux mouvements. Les 5 000 XAF en sont sortis, avec 2 % de frais de payout sandbox ajoutés au montant plutôt que déduits. Le solde de 19 600 XAF passe donc à **14 500 XAF**, tandis que le destinataire reçoit bien l'intégralité des 5 000 XAF. ## 4. Suivre son résultat Environ deux secondes plus tard, le payout se termine. Le numéro du destinataire avait déterminé le résultat bien avant. Pour le connaître correctement, utilisez un webhook, pas une boucle. | Événement | Déclencheur | | --------------------- | ------------------------------------------------------------------ | | `transfer.created` | Le payout a été enregistré | | `transfer.processing` | Il a été transmis à l'opérateur | | `transfer.succeeded` | Les fonds sont arrivés. C'est l'événement sur lequel agir | | `transfer.failed` | Les fonds ne sont pas arrivés et `failure_reason` indique pourquoi | [Statuts et webhooks](https://docs.wajub.com/fr/payouts/transfers/statuses-and-webhooks) détaille l'enregistrement, les signatures et le contenu de chaque handler. Pendant vos premiers essais, récupérez plutôt le payout. **Récupérer le payout** ```bash curl https://api.wajub.com/transfers/po_test_CSUGajfv9xh0XQ5wu2lx \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" ``` ```javascript const transfer = await wajub.transfers.retrieve('po_test_CSUGajfv9xh0XQ5wu2lx'); console.log(transfer.status, transfer.complete); ``` ```python transfer = wajub.transfers.retrieve("po_test_CSUGajfv9xh0XQ5wu2lx") print(transfer["status"], transfer["complete"]) ``` ```php $transfer = $wajub->transfers->retrieve('po_test_CSUGajfv9xh0XQ5wu2lx'); echo $transfer->status; ``` ```go transfer, err := client.Transfers.Retrieve(context.Background(), "po_test_CSUGajfv9xh0XQ5wu2lx") if err != nil { log.Fatal(err) } log.Println(transfer["status"], transfer["complete"]) ``` `status` vaut maintenant `succeeded` et `complete` vaut `true`. Ces deux champs ne signifient pas la même chose. `complete` indique la réussite, et non la fin de l'opération. Un payout échoué est donc terminé alors que ce champ vaut toujours `false`. ## 5. Provoquer un échec Un payout toujours réussi ne vous apprend rien sur le jour où un échec surviendra. La fin du numéro du destinataire détermine le résultat. Répétez donc le même appel avec chacune de ces valeurs avant de faire confiance à votre handler. | Numéro | Résultat | | --------------- | ------------------------------------------------------------------------------------------------- | | `+237670000000` | `succeeded` | | `+237670000001` | `422` à la création, `error_code: insufficient_funds`. Aucun payout et aucun webhook de transfert | | `+237670000002` | `failed`, `failure_reason: failure` | | `+237670000003` | `failed`, `failure_reason: network_error` | | `+237670000004` | `failed`, `failure_reason: invalid_recipient` | Seule la fin du numéro compte, pas l'opérateur. Ces cinq valeurs fonctionnent donc avec tous les préfixes connus de la sandbox. Un numéro qui ne correspond à aucune d'elles est immédiatement refusé. > [!NOTE] > **Testez votre handler d'échec avec …0002, pas …0001** > > `…0001` désigne un destinataire dont le portefeuille ne peut pas recevoir les fonds. La sandbox > refuse l'appel au lieu de créer un payout qui échoue. Comme aucun transfert ni événement de > transfert n'existe, le handler testé avec ce numéro n'est jamais appelé. Utilisez `…0002`. > [!WARNING] > **Un payout refusé crée quand même son bénéficiaire en ligne** > > Le bénéficiaire passé sous forme d'objet est créé avant les contrôles. Un appel refusé, `…0001` > compris, le laisse donc sur votre compte, listé par `GET /beneficiaries`, et envoie > `beneficiary.created` comme tout nouveau bénéficiaire. Le même appel relancé avec le même canal et > le même numéro le réutilise au lieu d'en créer un second. ## Passer ensuite en live Remplacez `sk_test.` par `sk.`. Quatre éléments changent, mais aucun ne concerne votre code. | Dans la sandbox | En live | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Le solde est alimenté par des paiements de test et un payout coûte 2 % | Il est alimenté par de vrais encaissements et un payout coûte à partir de 1 %, selon le pays et le canal, réservé avec le principal à la création | | Tous les numéros de test fonctionnent | Le numéro doit être réel et un chiffre incorrect paie une autre personne sans possibilité de récupérer les fonds | | Le payout est exécuté immédiatement | Vos premiers payouts peuvent être **retenus pour examen** jusqu'à leur libération par Wajub | | Les échecs proviennent de trois codes fixes | Ils proviennent de l'opérateur, avec son propre vocabulaire | Vous devez surtout prévoir le troisième cas. Un payout retenu est créé avec le statut `review`, ses fonds sont réservés et aucun appel de votre part ne peut le libérer. Envoyez votre premier payout live à votre propre numéro, pour un petit montant et sous surveillance. N'en faites jamais la première itération d'un lot. [Transferts et payouts](https://docs.wajub.com/fr/payouts) liste tous les contrôles d'un payout live. [Transferts](https://docs.wajub.com/fr/payouts/transfers) décrit l'objet complet. - [Transferts](https://docs.wajub.com/fr/payouts/transfers): Tous les champs, les quatre appels et les conditions d'exécution d'un payout. - [Prestataires et canaux](https://docs.wajub.com/fr/payouts/transfers/providers): Tous les slugs de canaux, classés par pays et par opérateur. - [Statuts et webhooks](https://docs.wajub.com/fr/payouts/transfers/statuses-and-webhooks): Les cinq événements et le rôle de chaque handler. - [Bénéficiaires](https://docs.wajub.com/fr/payouts/beneficiaries): Enregistrez une destination une fois, puis payez-la par son id. --- # Statuts et webhooks URL: https://docs.wajub.com/fr/payouts/transfers/statuses-and-webhooks > La signification du statut d'un payout, les événements émis et leur traitement. Le statut d'un payout indique où il se trouve, et ses webhooks vous informent de son évolution : `201 Created` confirme la réception d'une requête, pas le paiement d'une personne. Cette page explique la signification de chaque statut pour vos fonds, les événements émis et le rôle d'un handler. ## Les six statuts Trois décrivent un payout toujours actif. Les trois autres sont définitifs : un payout ne les quitte jamais. | Statut | Signification | Vos fonds | | ------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------- | | `pending` | Un payout du Dashboard qui attend votre confirmation, que vous confirmez ou rejetez dans le Dashboard | Rien n'est réservé avant votre confirmation | | `review` | Retenu par Wajub avant exécution pendant la vérification d'une mesure de protection | Réservés | | `processing` | Transmis à l'opérateur. Un payout API commence dans cet état | Réservés | | `succeeded` | Le destinataire a reçu les fonds et `complete` passe à `true` | Débités, frais prélevés | | `failed` | Les fonds ne sont pas arrivés et `failure_reason` indique pourquoi | Libérés, aucuns frais prélevés | | `cancelled` | Arrêté avant tout envoi | Libérés, aucuns frais prélevés | `POST /transfers` crée un payout avec `processing`, ou avec `review` lorsqu'une mesure de protection le retient, et rien d'autre. Un payout arrêté avant tout envoi se termine en `cancelled` : rejeté dans le Dashboard, son `failure_reason` est `merchant_rejected` ; annulé par Wajub, `cancelled_by_wajub`. Un payout refusé par la revue de Wajub (`admin_rejected`) ou par l'opérateur se termine en `failed`. ## Événement émis ou non Les événements de transfert ne couvrent pas les six statuts. Ces absences sont importantes. | Statut atteint par le payout | Événement reçu | | --------------------------------------------- | ---------------------------------------------- | | `processing`, à la création | `transfer.created`, puis `transfer.processing` | | `review` | `transfer.created`, puis plus rien | | `processing`, après approbation d'une retenue | `transfer.processing` | | `succeeded` | `transfer.succeeded` | | `failed` | `transfer.failed` | | `cancelled` | `transfer.failed`, avec `status: failed` | Un webhook est structuré pour la version d'API courante de Wajub, pas pour celle que vous fixez : c'est pourquoi un payout annulé est annoncé en `transfer.failed`, avec `status: failed` et le même `failure_reason`. `transfer.created` contient toujours `processing` ou `review`, jamais `pending`. ## Les trois séquences réellement observées ### Le payout réussit Trois événements. Seul le dernier indique un mouvement de fonds. **Un payout réussi** - **transfer.created** (created, 14:31:02, status: processing): Le payout est enregistré et votre solde est réservé. Aucun fonds n'a encore quitté le compte. - **transfer.processing** (processing, 14:31:02, status: processing): Transmis à MTN MoMo. Le statut reste identique à l'événement précédent, car seul le détenteur du payout a changé, pas le payout lui-même. - **transfer.succeeded** (succeeded, 14:31:06, status: succeeded): Le destinataire a reçu les fonds. La réservation est réglée, les frais sont prélevés et trois clés apparaissent sur l’objet. - complete: true - succeeded_at: 2026-09-12T14:31:06+00:00 - provider_reference: MP260912.1431.B84213 Les deux premiers événements ne vous apprennent rien de plus que la réponse `201`. Agissez sur `transfer.succeeded` et ignorez les autres, sauf si vous affichez une chronologie au support. ### Le payout échoue Les deux mêmes événements sont suivis d'un troisième différent. Un échec survenu dans Wajub avant la transmission à un opérateur et un échec renvoyé par l'opérateur sont identiques sur le réseau : même séquence, même plage de temps et même nom d'événement. **Un payout échoué** - **transfer.created** (created, 14:31:02, status: processing): Identique au payout réussi. Rien ici ne permet de prévoir le résultat. - **transfer.processing** (processing, 14:31:02, status: processing): Toujours identique. L'opérateur détient le payout et n'a pas encore répondu. - **transfer.failed** (failed, 14:31:09, status: failed): L'opérateur l'a refusé. Votre réservation est libérée, les frais ne sont jamais prélevés et deux clés propres à ce statut apparaissent. Ces deux clés contiennent toute l'information fournie sur un échec. Lisez-les après avoir vérifié le statut au lieu de supposer leur présence. ```json title="Les clés d'échec dans data" { "status": "failed", "complete": false, "failure_reason": "provider_rejected", "failure_message": "Recipient account is barred for incoming transfers." } ``` `failure_reason` est un code court à utiliser dans vos branches et vos logs. `failure_message` est une phrase à montrer à une personne. [Transferts](https://docs.wajub.com/fr/payouts/transfers) liste les codes. Pour un payout sur le circuit Wajub, `transfer.failed` libère aussi votre réservation. Le principal et l'estimation des frais reviennent dans `available` avant la fin de votre handler. ### Le payout est retenu `transfer.created` arrive avec `status: "review"`, puis plus rien pendant des minutes ou des heures, jusqu'à la fin de l'examen de Wajub. La résolution produit l'un de deux événements. `transfer.processing` signifie que le payout est approuvé et suit maintenant son traitement normal. `transfer.failed` avec `failure_reason: admin_rejected` signifie qu'il est refusé. > [!CAUTION] > **Une retenue pour examen produit un silence, pas un retard** > > Un handler qui considère l'absence de `transfer.processing` après une minute comme une erreur > alertera quelqu'un à trois heures du matin alors que le processus fonctionne normalement. Dans > votre handler `transfer.created`, vérifiez `data.status === 'review'`, informez votre équipe > chargée des opérations, puis arrêtez le chronomètre. ## Structure d'un événement Tous les événements de tous les produits utilisent la même enveloppe. Le transfert constitue l'intégralité de `data`, avec la même structure que la réponse de `GET /transfers/{uid}`. ```json title="transfer.succeeded" { "id": "evt_9Lm4tQ7wRc2vZ8kN5pXbT3jH", "event": "transfer.succeeded", "livemode": true, "created": "2026-09-12T14:31:06+00:00", "api_version": "2026-10-11", "pending_webhooks": 1, "data": { "id": "po_9Kdm2LpXv4tRb7nQ3sZc", "reference": "supplier-892", "provider_reference": "MP260912.1431.B84213", "amount": 10000, "currency": "XAF", "description": "Supplier payment #892", "reason": null, "metadata": { "invoice": "INV-2026-0892", "reservation": { "amount": 10000, "currency": "XAF", "fee_estimate": 100, "reserved_at": "2026-09-12T14:31:02+00:00" } }, "sandbox": false, "status": "succeeded", "complete": true, "source": "api", "succeeded_at": "2026-09-12T14:31:06+00:00", "created_at": "2026-09-12T14:31:02+00:00", "updated_at": "2026-09-12T14:31:06+00:00", "provider": { "slug": "mtn_momo", "name": "MTN MoMo" }, "beneficiary": { "id": "ben_7Kq2mX9vL4tRb3nP8sZc", "name": "Aminata Diallo", "phone": "+237670000000", "email": null }, "payment_method": { "id": "pm_3Nq8wR2kL5vT7bY4hC6d", "account_number": null, "phone": "+237670000000" } } } ``` L'enveloppe contient les clés suivantes. - `id` (string): L'id de l'événement, `evt_` en live et `evt_test_` dans la sandbox. Votre clé de déduplication, voir ci-dessous. - `event` (string): Le nom de l'événement. Ce champ s'appelle `event`, pas `type`. - `data` (object): L'objet transfert lui-même, sans enveloppe supplémentaire. - `livemode` (boolean): `false` pour un payout sandbox. Le seul champ qui distingue les deux environnements. - `api_version` (string): La version qui a déterminé la structure de `data`. - `pending_webhooks` (number): Le nombre de vos endpoints auxquels cet événement est livré. Il ne s'agit pas d'un compteur de nouvelles tentatives. L'une d'elles mérite un avertissement. Une erreur à cet endroit ne produit aucun message. > [!CAUTION] > **Lisez event, pas type** > > Le champ qui nomme l'événement est `event`. Une enveloppe Wajub ne possède aucune clé `type`. > Utiliser `event.type` par habitude produit `undefined`, un `switch` qui ne correspond à rien et un > handler qui renvoie `200` sans rien faire. C'est la cause la plus fréquente d'un échec silencieux > de cette intégration. Pour relier un événement à votre propre appel, utilisez `data.id` ou envoyez votre propre `reference` lors de la création du payout : elle revient dans `data.reference` avec chaque événement. Deux caractéristiques de `data` sont à connaître avant de l'utiliser. Le bénéficiaire, le moyen de paiement et le prestataire sont toujours développés. Un événement de transfert indique donc la destination des fonds sans second appel API. De plus, `metadata` ne contient pas uniquement vos données : Wajub y ajoute ses propres clés, comme `reservation`. Lisez les clés que vous avez ajoutées et ne vérifiez jamais la structure exacte de l'ensemble. ## Le handler Effectuez trois opérations dans cet ordre : prouvez que l'événement vient de Wajub, répondez, puis traitez-le. Répondre avant le traitement n'est pas une optimisation. Cette méthode empêche une base de données lente de provoquer une multiplication des nouvelles tentatives. **Vérifier et accuser réception** ```javascript import express from 'express'; const app = express(); // The client verifies with the secret it was built with: webhookSecret, // or WAJUB_WEBHOOK_SECRET when you pass none. app.post('/webhooks/wajub', express.raw({ type: 'application/json' }), (req, res) => { let event; try { event = wajub.webhooks.constructEvent( req.body, req.headers['x-wajub-signature'], req.headers['x-wajub-timestamp'], ); } catch { return res.status(400).send('invalid signature'); } res.status(200).end(); queue.push(event); }); ``` ```python from wajub import WebhookSignatureVerificationError # The client verifies with the secret it was built with: webhook_secret, # or WAJUB_WEBHOOK_SECRET when you pass none. @app.post("/webhooks/wajub") def wajub_webhook(): try: event = wajub.webhooks.construct_event( request.get_data(), request.headers["X-Wajub-Signature"], request.headers["X-Wajub-Timestamp"], ) except WebhookSignatureVerificationError: return "invalid signature", 400 enqueue(event) return "", 200 ``` ```php use Wajub\Exception\WebhookSignatureVerificationError; use Wajub\Wajub; // The client verifies with the secret it was built with: 'webhook_secret', // or WAJUB_WEBHOOK_SECRET when you pass none. public function __invoke(Request $request, Wajub $wajub): Response { try { $event = $wajub->webhooks->constructEvent( $request->getContent(), $request->header('X-Wajub-Signature', ''), $request->header('X-Wajub-Timestamp', ''), ); } catch (WebhookSignatureVerificationError) { return response('invalid signature', 400); } HandleWajubEvent::dispatch($event); return response('', 200); } ``` ```go func wajubWebhook(w http.ResponseWriter, r *http.Request) { body, _ := io.ReadAll(r.Body) // The client verifies with the secret it was built with: Config.WebhookSecret, // or WAJUB_WEBHOOK_SECRET when you set none. event, err := client.Webhooks.ConstructEvent( body, r.Header.Get("X-Wajub-Signature"), r.Header.Get("X-Wajub-Timestamp"), 0, // 0 keeps the default 300 second window ) if err != nil { http.Error(w, "invalid signature", http.StatusBadRequest) return } w.WriteHeader(http.StatusOK) queue <- event } ``` Le renvoi d'une réponse `400` pour une mauvaise signature est volontaire. Rejouer les mêmes octets échouerait de la même façon, donc une nouvelle tentative n'apporterait rien. [Vérification de signature](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification) détaille l'algorithme, l'obligation d'utiliser le corps brut et la fenêtre de cinq minutes de l'horodatage. Le traitement doit être effectué en dehors de la requête. Il se divise d'abord selon le nom de l'événement, puis selon son statut. **Agir sur l'événement** ```javascript async function handleTransferEvent(event) { const transfer = event.data; if (await alreadyProcessed(event.id)) { return; } switch (event.event) { case 'transfer.succeeded': await markSupplierPaid(transfer.id, transfer.amount, transfer.currency); break; case 'transfer.failed': await flagPayoutFailure(transfer.id, transfer.failure_reason); break; case 'transfer.created': if (transfer.status === 'review') { await notifyOpsPayoutHeld(transfer.id); } break; } await recordProcessed(event.id); } ``` ```python def handle_transfer_event(event): transfer = event["data"] if already_processed(event["id"]): return name = event["event"] if name == "transfer.succeeded": mark_supplier_paid(transfer["id"], transfer["amount"], transfer["currency"]) elif name == "transfer.failed": flag_payout_failure(transfer["id"], transfer.get("failure_reason")) elif name == "transfer.created" and transfer["status"] == "review": notify_ops_payout_held(transfer["id"]) record_processed(event["id"]) ``` ```php public function handle(array $event): void { $transfer = $event['data']; if ($this->alreadyProcessed($event['id'])) { return; } match ($event['event']) { 'transfer.succeeded' => $this->markSupplierPaid( $transfer['id'], $transfer['amount'], $transfer['currency'], ), 'transfer.failed' => $this->flagPayoutFailure( $transfer['id'], $transfer['failure_reason'] ?? null, ), 'transfer.created' => $transfer['status'] === 'review' ? $this->notifyOpsPayoutHeld($transfer['id']) : null, default => null, }; $this->recordProcessed($event['id']); } ``` ```go // ConstructEvent returns the decoded JSON, so every field is read by key. func handleTransferEvent(event map[string]any) error { eventID, _ := event["id"].(string) transfer, _ := event["data"].(map[string]any) transferID, _ := transfer["id"].(string) done, err := alreadyProcessed(eventID) if err != nil || done { return err } switch event["event"] { case "transfer.succeeded": amount, _ := transfer["amount"].(float64) currency, _ := transfer["currency"].(string) err = markSupplierPaid(transferID, amount, currency) case "transfer.failed": reason, _ := transfer["failure_reason"].(string) err = flagPayoutFailure(transferID, reason) case "transfer.created": if transfer["status"] == "review" { err = notifyOpsPayoutHeld(transferID) } } if err != nil { return err } return recordProcessed(eventID) } ``` `transfer.processing` est volontairement absent. Toute action à ce stade serait prématurée. Les fonds n'ont pas bougé. Un handler qui livre une commande avec `processing` la livre avant même la tentative de payout. ## Les quatre causes d'erreur Chacune de ces erreurs produit un handler qui passe la revue, fonctionne en préproduction et paie deux fois une personne en production. | Erreur | Conséquence | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Faire confiance à l'ordre d'arrivée des événements | Les livraisons sont relancées séparément. `transfer.succeeded` peut arriver avant `transfer.processing`. Lisez l'état dans `data.status`, jamais dans la séquence | | Ne pas dédupliquer | Le même événement peut être livré plusieurs fois. Stockez `event.id` et vérifiez-le en premier | | Renvoyer `410` alors que vous souhaitez une nouvelle tentative | `410 Gone` est la seule réponse qui arrête définitivement la livraison. Tout autre échec, `4xx` compris, est retenté pendant 72 heures au plus | | Traiter avant de répondre | Le délai d'expiration est de 30 secondes. Un handler lent transforme un événement en livraisons répétées et vos nouvelles tentatives s'accumulent derrière votre propre latence | > [!NOTE] > **Un abonnement à tous les événements en produit plus de cinq** > > Un endpoint abonné à `*` reçoit `balance.updated` lors du règlement de la réservation et > `fee.charged` lorsque Wajub prélève ses frais, en plus des cinq événements de transfert. Ce > comportement est normal et ne constitue pas un doublon. Abonnez-vous aux cinq événements > nécessaires, sauf si les autres vous sont utiles. ## Délai avant de vous inquiéter Dans la sandbox, environ deux secondes. En live, généralement quelques secondes et parfois plusieurs minutes ; un payout plus long se termine par le même `transfer.succeeded` ou `transfer.failed`, simplement plus tard. > [!WARNING] > **Aucune expiration automatique** > > Un payout peut rester `processing` longtemps, sans rien à faire de votre côté, et votre réservation > reste bloquée. Aucun statut ne signifie « abandon » et aucune expiration > n'existe. Ne créez pas de délai qui marque le payout comme échoué de votre côté. Un payout > `processing` peut encore atteindre le téléphone du destinataire. Vous l'auriez alors payé tandis > que votre comptabilité indiquerait le contraire. ## Lire plutôt qu'écouter Les webhooks conviennent au payout que vous attendez. La lecture convient au payout que vous contrôlez. `GET /transfers/{uid}` Utilisez cet appel pour un rapprochement planifié, pour répondre au support ou pendant le développement, avant de disposer d'une URL publique accessible par Wajub. Ne créez pas une boucle autour d'un payout en attendant `succeeded`. Lire un transfert compte dans la limite générale de votre équipe, soit 120 requêtes par minute avec le plan par défaut, et non dans la part réservée à l'envoi de payouts. Une boucle consomme pourtant la capacité nécessaire à tous les autres appels de votre intégration. Pour un rapprochement en fin de journée, listez les payouts par période et comparez-les aux événements reçus. Si un payout enregistré chez vous comme `processing` est définitif chez Wajub, vous avez manqué une livraison. La [Konsole](https://docs.wajub.com/fr/developer-tools/konsole/log-explorer) affiche chaque tentative effectuée pour vous joindre. ## Si vous êtes une plateforme Un payout effectué pour un compte connecté est livré deux fois : une fois aux endpoints de ce compte et une fois aux vôtres. Votre copie contient un objet `account` supplémentaire qui désigne le marchand concerné. Un seul endpoint peut ainsi servir tous vos comptes connectés. [Sync](https://docs.wajub.com/fr/sync) explique leur configuration. - [Transferts](https://docs.wajub.com/fr/payouts/transfers): L'objet, les statuts détaillés et les codes d'échec. - [Vérification de signature](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification): L'algorithme, le corps brut et la fenêtre de l'horodatage. - [Nouvelles tentatives et ordre](https://docs.wajub.com/fr/developer-tools/webhooks/retries): Ce qui constitue un échec de livraison, et pourquoi un événement arrive deux fois. - [Recevoir des webhooks en local](https://docs.wajub.com/fr/developer-tools/cli/listen): Transférez de vrais événements vers localhost pendant la création du handler. --- # Analyse de l'orchestration URL: https://docs.wajub.com/fr/orchestration/analytics > Où trouver les chiffres du routage, ce que chacun mesure et sur quelle période. Il n'existe aucun tableau de bord unique pour l'orchestration. Les chiffres sont répartis sur quatre interfaces, qui répondent chacune à une question différente sur une période différente. L'erreur la plus courante consiste à comparer deux de ces chiffres et à conclure que l'un est faux. | Interface | Question traitée | Période | | ---------------------------------------- | ------------------------------------------------------------------- | ------------------------------- | | **Orchestration, Vue d'ensemble** | Quelles sont les performances de chaque connexion pour mon compte ? | 7, 30 ou 90 jours | | **Orchestration, Matrice** | Que se passe-t-il actuellement pour chaque opérateur ? | Fenêtre glissante de 15 minutes | | Panneau uplift de la page Vue d'ensemble | Qu'a réellement récupéré la cascade ? | 7 jours | | **Konsole, Journal de routage** | Pourquoi ce paiement précis a-t-il emprunté cette route ? | Par appel de débit | Les quatre sont réservées au mode live. Les paiements de la sandbox ne sont pas routés. Ils sont donc exclus de tous les chiffres de cette page. La section Orchestration elle-même n'est disponible qu'en mode live. ## La page Vue d'ensemble et ce que mesure chaque chiffre Choisissez une période de 7, 30 ou 90 jours. Une commande d'actualisation permet d'obtenir immédiatement la valeur actuelle. Vous obtenez ces chiffres par connexion, tous calculés à partir de vos propres transactions sur cette période. Les noms sont les libellés affichés par le Dashboard. - `Transactions` (nombre): Paiements live attribués à cette connexion pendant la période. - `Taux de succès` (pourcentage): La part de ces paiements réellement créditée sur votre solde. Ce taux d'acceptation est calculé depuis vos comptes. Un payeur qui abandonne la demande le fait donc baisser. - `Volume` (montant): Volume crédité pendant la période. Les montants de toutes les devises sont additionnés sans conversion : lisez-le devise par devise si vous encaissez dans plusieurs. - `Dernière utilisation` (date): Paiement le plus récent sur cette connexion. Il permet de repérer une connexion qui a discrètement cessé de recevoir du trafic. Au-dessus de la liste, les chiffres de la même période sont regroupés pour toutes les connexions, avec deux valeurs supplémentaires. **Durée moyenne** représente le nombre moyen de secondes entre la création du paiement et son crédit. Elle mesure tout le parcours du payeur, y compris le temps passé à chercher son téléphone, pas seulement le délai de réponse du prestataire. La tendance affichée avec **Transactions** compare le nombre de transactions à celui de la période précédente de même durée. > [!NOTE] > **Deux taux de réussite, deux significations** > > La page Vue d'ensemble calcule la réussite à partir des transactions créditées. Une demande > abandonnée fait donc baisser ce taux. Le routage regarde la fiabilité récente, qui ignore les > échecs dus au payeur. Une demande abandonnée ne la modifie pas. Une connexion peut afficher 72 % > sur la page Vue d'ensemble tout en restant saine pour le routage. Les deux chiffres sont justes. ## Quand une connexion est considérée comme dégradée Une seule règle détermine les termes et les couleurs affichés : vert à partir de 95 %, orange à partir de 80 %, rouge en dessous, et aucun verdict sous 5 paiements. Chaque écran l'applique sur sa propre période. | Emplacement | Données nécessaires | Verdict | | -------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Bannière d'avertissement de la page Vue d'ensemble | La page Matrice ci-dessous, en direct | Un canal est signalé dès qu'une de ses cellules est rouge | | Health badge de la page du prestataire | 5 paiements au cours des dernières 24 heures | Vert à partir de 95 %, orange à partir de 80 %, rouge en dessous | | Couleur d'une cellule de la page Matrice | 5 tentatives au cours des 15 dernières minutes | Verte à partir de 95 %, orange à partir de 80 %, rouge en dessous, et rouge dès que le coupe-circuit est ouvert ou que la connexion est refusée | En dessous du minimum, aucune conclusion n'est affichée. Une cellule grise ou l'absence de badge signifie que le trafic ne suffit pas pour se prononcer, pas qu'il existe un problème. ## La matrice et le diagnostic qu'elle permet La matrice place vos canaux d'opérateurs sur les lignes et vos connexions sur les colonnes. Elle remplit chaque cellule avec les données d'une fenêtre glissante de 15 minutes. Elle permet une distinction impossible dans une liste par prestataire. **Une ligne entièrement rouge** signifie que l'opérateur lui-même est en panne. Toutes les connexions qui atteignent MTN Cameroun échouent. Il n'existe donc aucune autre route possible. Vous devez attendre ou cesser de proposer ce canal jusqu'à son rétablissement. **Une cellule rouge alors que les voisines restent stables** indique que votre chemin vers cet opérateur rencontre un problème, pas l'opérateur lui-même. Le trafic peut être préservé, car une autre connexion de la même ligne fonctionne. C'est exactement le cas que la cascade gère seule et celui où une politique sur ce canal produit un effet immédiat : **Acceptation maximale**, ou une santé minimale, place la connexion défaillante derrière celle qui fonctionne, sur ce canal uniquement. Chaque cellule indique également si le circuit de cette route est ouvert. Cela explique pourquoi une connexion semble ne recevoir aucun trafic. Lorsque les identifiants de la connexion manquent ou sont refusés, la cellule passe au rouge et affiche **Connexion refusée** à la place du badge du circuit. ## Ce que la cascade a récupéré Le chiffre qui justifie à lui seul l'orchestration se trouve sur la page Vue d'ensemble. Pour les sept derniers jours, il indique le nombre de paiements qu'un prestataire de repli a débités après l'échec sur le chemin de celui classé avant lui, ainsi que leur volume. Seuls les basculements à l'intérieur d'une même décision de routage comptent : un payeur qui a réessayé de lui-même après un refus a ouvert une nouvelle décision, et n'est pas compté. Chacun de ces paiements aurait été perdu dans une intégration à prestataire unique. Le panneau affiche également le volume traité par les canaux actuellement signalés comme dégradés. Ce chiffre représente votre exposition actuelle, pas un résultat déjà obtenu. > [!TIP] > **Comparez-le à vos avertissements de chemin unique** > > Un nombre élevé de récupérations sur un canal qui affiche également un avertissement de chemin > unique est le meilleur argument pour connecter un deuxième prestataire. La cascade sauve déjà les > paiements lorsqu'elle le peut, mais elle ne possède aucune autre connexion pour les sauver sur ce > canal. ## Le conseiller et les constats qui produisent un effet La page Vue d'ensemble lit votre matrice et génère des constats, classés selon leur gravité et le volume concerné. Ils sont déterministes, calculés à partir de vos propres données, et vous pouvez vérifier tous les chiffres qu'ils contiennent. L'avertissement **single path** conduit toujours à un véritable changement : un canal, une connexion, aucune solution de repli et le volume qui s'arrêterait en cas d'échec. La correction consiste à connecter un deuxième prestataire pour ce canal. Il s'agit de l'action qui apporte le plus de valeur dans tout le module. Le constat **operator down** est informatif, à juste titre. Aucune configuration ne peut corriger la panne d'un opérateur. Le dernier constat signale une connexion qui échoue sur un canal alors qu'une autre est en bonne santé, et renvoie à la politique de ce canal sur la page Matrice : choisissez **Acceptation maximale**, ou fixez une santé minimale, et la connexion défaillante est essayée après la connexion en bonne santé, sur ce canal uniquement. Sur chaque paiement du canal, Wajub applique la politique aux connexions qu'aucune [règle de routage](https://docs.wajub.com/fr/orchestration/routing-rules) n'a placées. Augmenter plutôt la `priority` de la connexion la déplacerait sur tous les canaux. ## Lire une décision ou en filtrer plusieurs Le journal de routage de Konsole contient une entrée par tentative de débit : une par appel à `POST /payments/{id}`. Un payeur qui effectue deux tentatives sur le même paiement en laisse deux. Les filtres permettent de répondre aux questions que les chiffres regroupés ne couvrent pas. | Filtre | Résultat isolé | | ----------------------------------------------------- | --------------------------------------------------------------------------- | | Résultat, **A eu un repli** | Décisions dans lesquelles plusieurs candidats ont été classés | | Résultat, **Fournisseur ignoré par le coupe-circuit** | Décisions dans lesquelles une connexion était en pause sur le canal | | Résultat, **Aucun candidat éligible** | Décisions dont la liste était vide, les cas avec une réponse `422` | | Channel | Un réseau d'opérateur à la fois | | Provider | Décisions que cette connexion a gagnées : c'est elle qui a pris le paiement | | Transaction reference | Un paiement, du début à la fin | La sélection d'une ligne ouvre chaque candidat et la raison de sa place, à côté des tentatives qui ont suivi : chaque candidat essayé affiche son résultat et sa latence. Cette association entre la décision et son résultat n'est présentée qu'à cet endroit. ## Alertes **Orchestration, Alertes** surveille un chiffre pour vous et vous prévient lorsqu'il franchit un seuil, uniquement sur les paiements live. | Champ | Valeurs possibles | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Métrique | Taux de réussite, taux d'erreur, nombre de transactions, volume, taux de livraison des webhooks, nombre d'échecs de webhook, taux d'abandon du tunnel ou profondeur de la file | | Condition | Passe sous un seuil, l'atteint en descendant, le dépasse, l'atteint en montant, ou lui est égal | | Période | Les 5 dernières minutes, 15 minutes, la dernière heure ou les dernières 24 heures | | Portée | Tout, une connexion, un canal ou une règle de routage | | Notification | Des adresses e-mail, un webhook Slack ou votre propre URL | | Délai de répit | De 5 minutes à 24 heures avant qu'une même règle puisse se déclencher à nouveau | Une portée canal compte les paiements débités sur ce canal, un paiement envoyé sur `mobile` ou `cm.mobile` comptant pour l'opérateur auquel il a été résolu. Une portée règle compte les paiements que cette règle a routés. La portée ne restreint que les métriques de paiement. Les métriques de webhook comptent toutes les livraisons vers vos propres endpoints, et la métrique du tunnel toutes les pages de paiement ouvertes. Une cible Slack ou webhook doit être une URL `https` qui ne pointe pas vers une adresse privée ou interne : Wajub n'envoie rien à une autre, et ne suit pas une redirection qu'elle renvoie. Elle reçoit un corps JSON avec `rule_id`, `rule_name`, `observed_value`, `context` et `fired_at`. Les 20 dernières alertes déclenchées sont listées sur la même page. ## Ce qui n'est pas mesuré Connaître les éléments manquants vous évite de chercher des exportations qui n'existent pas. **Le coût est une donnée d'entrée, pas un résultat.** Le tarif négocié saisi sur une connexion sert à trouver la connexion la moins chère pour chaque paiement. Il n'est jamais regroupé sous forme de coût par transaction ou de comparaison des dépenses. Si vous en avez besoin, calculez-le depuis vos propres exportations de transactions et les tarifs saisis. **Aucune de ces informations n'est accessible dans l'API.** Il n'existe aucun endpoint pour les statistiques des prestataires, les décisions de routage, les cellules de la matrice ou les constats du conseiller. Aucune exportation CSV n'est disponible. Les analyses d'orchestration se consultent dans le Dashboard et dans Konsole. **La sandbox ne contribue à aucun chiffre.** Aucune décision n'est enregistrée, aucune tentative n'est comptée et aucune cellule n'est actualisée. Une matrice vide sur un compte de test très actif est donc normale. - [Orchestration des paiements](https://docs.wajub.com/fr/orchestration): La manière dont est prise la décision à l'origine de chacun de ces chiffres. - [Cascade et repli](https://docs.wajub.com/fr/orchestration/waterfall-fallback): Le parcours réellement suivi par les paiements récupérés. - [Prestataires](https://docs.wajub.com/fr/orchestration/providers): La priorité, le poids et les tarifs négociés, à modifier selon les données présentées ici. - [Journal de routage](https://docs.wajub.com/fr/developer-tools/konsole/routing-log): Une décision par paiement, avec sa liste complète de candidats. --- # Orchestration des paiements URL: https://docs.wajub.com/fr/orchestration > Comment Wajub choisit un prestataire pour chaque paiement et ce que vous pouvez modifier. Vous ne nommez jamais de prestataire dans un paiement : pour chaque paiement live, Wajub ordonne les connexions capables de le traiter, les essaie depuis le début et descend dans la liste lorsqu'une connexion échoue avant d'atteindre l'opérateur. Cette page explique ce qui façonne cette liste : ce que vous contrôlez, ce que Wajub décide et ce que vous pouvez observer ensuite. ## Qui décide quoi L'orchestration n'est pas une fonctionnalité à activer. C'est le seul chemin emprunté par un paiement live, et la répartition des responsabilités ne change jamais. | Décision | Prise par | | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Les prestataires auxquels vous êtes connecté | Vous, dans le Dashboard | | Les canaux que chaque connexion peut traiter | Vous | | L'ordre dans lequel les connexions sont essayées | Vous : vos règles de routage d'abord, puis la politique du canal, ou la `priority` de chaque connexion en l'absence de politique | | La répartition du trafic entre les connexions à égalité | Vous, avec le `weight` de vos règles et de vos connexions | | Les connexions admissibles pour ce paiement précis | Wajub | | La connexion placée en premier parmi celles laissées à égalité | Wajub, selon vos coûts et les taux de réussite en direct | | Le moment où les tentatives s'arrêtent | Wajub | Aucune décision de ce tableau ne peut être exprimée au moment de l'appel. Si vous avez besoin d'un prestataire précis dans un cas donné, utilisez une [règle de routage](https://docs.wajub.com/fr/orchestration/routing-rules), une politique de canal ou une priorité, définie une seule fois dans le Dashboard, pas un paramètre envoyé avec la requête. ## La route est décidée au deuxième appel Un paiement nécessite deux appels. Seul le second effectue le routage. | Appel | Ce qu'il fixe | | --------------------- | -------------------------------------------------------------------- | | `POST /payments` | Le montant, la devise et le client. Aucun prestataire n'est consulté | | `POST /payments/{id}` | Le canal et le numéro de téléphone, et donc la route | Cette différence vient du canal. Le routage utilise toujours le canal de l'opérateur, et l'opérateur n'est souvent connu qu'une fois le numéro du payeur connu. Une requête pour `cm.mobile` avec le numéro `+237 6 70 00 00 00` est routée comme `cm.mtn`. Une requête qui indique `cm.mtn` avec un numéro Orange est refusée avec une réponse `422` qui précise l'incompatibilité, au lieu d'être redirigée discrètement. > [!WARNING] > **Écrivez vos règles sur le canal de l'opérateur** > > Le routage utilise toujours le canal de l'opérateur, comme `cm.mtn` ou `sn.wave` : `cm.mobile` > avec un numéro MTN est routé comme `cm.mtn`, écrivez donc vos règles sur `cm.mtn`. Aucun paiement > n'est jamais routé sur `cm.mobile`, le simple terme `mobile` ou des termes de produit comme > `mobile_money`. Une règle de routage portant sur `mobile_money` ne correspond donc à rien. ## Les connexions qui peuvent prendre le paiement Avant tout classement, Wajub ne garde que les connexions capables de traiter ce paiement précis. Une connexion n'est essayée que si toutes ces conditions sont remplies : - la connexion est active, tout comme le prestataire : **Disponible** ou en **Bêta**, ni en maintenance, ni bientôt disponible, ni désactivé ; - le prestataire peut traiter le canal du paiement, et la liste de canaux de votre connexion l'autorise ; - la connexion accepte la devise du paiement ; - Wajub peut débiter par ce prestataire (les prestataires pas encore pris en charge sont marqués **Bientôt disponible**) ; - la connexion n'est pas en pause sur ce canal après des échecs répétés. Une connexion en pause apparaît comme ignorée dans le [Journal de routage](https://docs.wajub.com/fr/developer-tools/konsole/routing-log). Une restriction de pays agit un niveau au-dessus. Lorsqu'une restriction active sur votre compte couvre le pays du payeur, tout le paiement s'arrête avec `403 country_restricted`, et non avec le `422` d'une liste vide ([Erreurs de restriction](https://docs.wajub.com/fr/api/errors#restriction-errors)). Deux de ces conditions sont permissives lorsqu'elles sont vides, ce qui surprend souvent au début. Une connexion sans liste de canaux accepte tous les canaux pris en charge globalement par le prestataire. Une connexion sans liste de devises accepte toutes les devises. La restriction est un choix, pas le comportement par défaut. ## L'instruction la plus précise passe en premier Les connexions restantes sont ordonnées en deux temps. Vos règles placent d'abord leurs connexions. Toutes les autres sont ensuite ordonnées par la politique du canal lorsqu'il en a une active, ou par la priorité lorsqu'il n'en a pas. La liste se lit donc toujours de la même façon : ce que vos règles ont désigné, puis le reste. | Étape | Ce qu'elle place | Comment elle les ordonne | | ------------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1. Règles de routage | La cible de chaque règle qui correspond au paiement, suivie chaque fois du prestataire de secours de la règle | La priorité de règle la plus élevée d'abord, puis la règle la plus précise ; les règles encore à égalité se partagent le trafic selon leur poids | | 2. Politique du canal | Toutes les autres connexions, lorsque le canal a une politique active | Son ordre de cascade fixe, puis son objectif ; une connexion hors garde-fou est essayée après les autres | | 2. Ou priorité de la connexion | Toutes les autres connexions, lorsque le canal n'a pas de politique active | `priority` la plus élevée d'abord ; à l'intérieur d'une même priorité, le coût et la réussite récente ; le poids répartit le trafic entre les connexions encore à égalité | ### Les règles passent en premier, quelle que soit la priorité Une connexion désignée par une règle correspondante est essayée avant toutes les connexions qu'aucune règle ne désigne, quelle que soit la `priority` des unes et des autres. C'est le rôle d'une règle : vous l'avez écrite pour ce cas, elle l'emporte donc sur l'ordre général. Le [prestataire de secours](https://docs.wajub.com/fr/orchestration/routing-rules#the-fallback-provider) de la règle vient juste derrière sa cible. La page [Règles de routage](https://docs.wajub.com/fr/orchestration/routing-rules) explique quelle règle l'emporte lorsque plusieurs correspondent. ### Puis la politique du canal, s'il en a une Une politique se définit par canal d'opérateur, dans **Orchestration, Matrice**, avec le bouton **Politique** de la ligne du canal. Lorsqu'elle est active, elle ordonne toutes les connexions qu'aucune règle n'a placées, et la `priority` de vos connexions ne départage plus que celles qu'elle laisse à égalité. | Réglage | Effet | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Ordre de cascade fixe | Ces connexions d'abord, dans cet ordre | | Objectif de routage | Classe les autres. **Acceptation maximale** : le meilleur taux de réussite récent d'abord. **Coût le plus bas** : les frais les plus faibles pour ce paiement d'abord. **Le plus rapide** : la latence récente la plus faible d'abord | | Santé minimale % | Une connexion dont le taux de réussite récent sur ce canal est inférieur à ce seuil est essayée après toutes celles qui le respectent | | Plafond de coût | Une connexion dont les frais pour ce paiement, dans la devise du paiement, le dépassent est essayée après toutes celles qui le respectent | Une connexion sous votre santé minimale ou au-dessus de votre plafond de coût est essayée après les autres, y compris les connexions de votre ordre de cascade. > [!NOTE] > **Un garde-fou recule une connexion, il ne la retire jamais** > > Une connexion hors garde-fou est essayée après les autres, pas retirée. Lorsque toutes les > connexions dépassent le plafond de coût, le paiement passe quand même par la meilleure d'entre > elles. Un garde-fou ne peut pas vous faire perdre un paiement. ### Puis la priorité, et le coût et la réussite récente à l'intérieur Sur un canal sans politique active, les connexions sont regroupées selon l'entier `priority` de votre connexion. Le groupe le plus élevé est essayé entièrement avant de passer au suivant. La valeur par défaut est `0`. Toutes les connexions d'un marchand qui n'a jamais défini de priorité se trouvent donc dans un même groupe. À l'intérieur d'une même priorité, Wajub favorise la connexion la moins chère pour ce paiement, d'après les tarifs négociés que vous avez saisis sur vos connexions (pas la tarification propre à Wajub), et celle qui réussit le mieux récemment sur ce canal pour votre compte. Seuls les échecs du côté du prestataire ou de l'opérateur pèsent sur la réussite récente : le portefeuille vide d'un payeur n'y change rien. > [!CAUTION] > **Le coût le plus bas a besoin de vos tarifs** > > Si vous n'avez jamais saisi le coût de chaque connexion, Wajub ne peut pas distinguer vos > connexions par leur coût, et le coût ne départage rien. Le routage au coût le plus bas ne > fonctionne qu'après la saisie de vos tarifs négociés. Il en va de même pour l'objectif > **Coût le plus bas** et le plafond de coût d'une politique de canal. Les connexions encore à égalité se partagent le trafic selon leur `weight`, dont la valeur par défaut est `100`. Placez deux connexions à la même priorité, avec des poids de 70 et 30. Lorsque rien d'autre ne les distingue, environ sept paiements sur dix commenceront par la première. Une connexion de poids `0` n'est essayée qu'après celles dont le poids est non nul. Le poids répartit de la même façon le trafic entre les connexions qu'une politique de canal laisse à égalité. ## Une décision complète Prenons un paiement de 25 000 XAF sur `cm.mtn`, pour un compte doté de quatre connexions capables d'atteindre ce numéro et d'une règle qui associe le pays, le canal et la devise à CinetPay, sans politique sur le canal. Les quatre connexions aboutissent au même portefeuille MTN. Le classement décide laquelle le prend en charge. **Décision de routage · cm.mtn · 25 000 XAF** Quatre connexions atteignent le même portefeuille. Une était hors rotation, la cible de la règle est passée en premier et la deuxième a traité le paiement. 1. **cinetpay** (priority 50, failed, 8.0 s, règle correspondante, réussite récente): délai opérateur dépassé 2. **flutterwave** (priority 100, accepted, 0.9 s, coût le plus bas, réussite récente): accepté 3. **pawapay** (priority 50, untried): jamais appelée - ~~notchpay~~: Ignorée (circuit ouvert). La connexion a été mise en pause sur ce canal après des échecs répétés. Lisez cette représentation depuis le bas. NotchPay ne figurait pas du tout dans le classement, car il était en pause sur ce canal. PawaPay a été classé, mais sa priorité de 50 le place sous les 100 de Flutterwave. Il n'aurait donc été appelé qu'après l'échec des deux connexions placées avant lui. CinetPay est passé en premier alors que sa priorité est aussi de 50, uniquement grâce à la règle : une connexion désignée par une règle correspondante est essayée avant l'ordre général, et Flutterwave, moins cher et qui réussissait bien récemment, n'est venu qu'ensuite. CinetPay a ensuite répondu que l'opérateur avait dépassé son délai. Cela ne dit rien sur le payeur. La cascade est donc passée à Flutterwave, qui a atteint le même portefeuille en moins d'une seconde. [Konsole](https://docs.wajub.com/fr/developer-tools/konsole/routing-log) montre pourquoi chaque paiement a été routé de cette façon. La réponse de l'API ne l'indique pas. ## Ce qui arrête la cascade La cascade n'est pas une politique de nouvelle tentative. C'est un seul parcours de la liste, dans l'appel `POST /payments/{id}`. Le tableau ci-dessous indique ce qui l'arrête ou la fait avancer. | Événement | Comportement de la cascade | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | Un prestataire accepte, y compris avec le statut `pending` | Elle s'arrête. Ce prestataire prend désormais en charge le paiement | | Le payeur refuse : portefeuille vide, mauvais numéro, plafond de l'opérateur ou expiration de la demande | Elle s'arrête. Un second prestataire poserait la même question à la même personne | | Le chemin échoue : le prestataire répond que l'opérateur a dépassé son délai ou est en panne, que vos identifiants sont refusés ou que ses fonds de roulement sont épuisés, ou le prestataire est injoignable | Elle passe au candidat suivant et l'échec dégrade l'état de cette route | | La requête a atteint le prestataire et son issue est inconnue | Elle s'arrête. Le prestataire a peut-être agi : le paiement reste `pending` jusqu'à ce que son issue soit connue | | Votre connexion n'a pas d'identifiants pour ce canal | Elle passe au candidat suivant : rien n'a atteint ce prestataire. La connexion est signalée dans le Dashboard | | Trois prestataires ont été essayés | Elle s'arrête, quel que soit le reste de la liste | Une carte saisie dans les champs propres à un prestataire (Stripe, une carte Paystack enregistrée) fait exception : seul le prestataire qui la détient peut la débiter. Elle va donc à cette connexion quel que soit le classement, et jamais à une autre. La fenêtre de paiement propre à un prestataire et un code ou une information que le payeur confirme ensuite restent de la même façon chez le prestataire qui les a ouverts ([Waterfall & fallback](https://docs.wajub.com/fr/orchestration/waterfall-fallback#a-step-the-provider-opened-stays-with-it)). > [!CAUTION] > **Aucun basculement n'a lieu après l'acceptation de la demande** > > Un prestataire Mobile Money renvoie `pending` dès que l'opérateur accepte d'afficher une demande > au client, plusieurs secondes avant toute action sur son téléphone. Cette acceptation arrête la > cascade. Si le client ne confirme jamais, le paiement échoue quelques minutes plus tard, bien après le > retour de votre appel. Aucun autre prestataire n'est alors essayé. Un basculement à ce stade afficherait deux > demandes sur le même téléphone. Une nouvelle tentative relève de votre décision et constitue un > nouveau paiement. [Cascade et repli](https://docs.wajub.com/fr/orchestration/waterfall-fallback) décrit les échecs qui font passer un paiement à la connexion suivante et le moment où une connexion est mise en pause. ## Les deux façons dont le routage peut mal se terminer Ces échecs sont différents et produisent des réponses distinctes. Le code de statut permet de les distinguer sans lire le message. Une liste de candidats vide renvoie `422`. Aucune tentative n'a eu lieu, donc aucune nouvelle tentative ailleurs n'est possible. Aucune de vos connexions ne peut actuellement traiter ce canal et cette devise, ou toutes celles qui le pourraient sont hors rotation. ```json title="Réponse · 422 Unprocessable Content" { "code": 422, "status": "Unprocessable Content", "message": "No eligible payment provider found for this transaction.", "errors": { "channel": ["No eligible payment provider found for this transaction."] } } ``` Une liste parcourue jusqu'à son épuisement renvoie `402`, tout comme un refus définitif unique tel qu'un rejet. `error_code` contient le motif exploitable du prestataire lorsqu'il en existe un. Ce n'est pas le cas lorsque tous les candidats échouent sans fournir de motif. ```json title="Réponse · 402 Payment Required" { "code": 402, "status": "Payment Required", "message": "Insufficient balance", "error_code": "insufficient_funds", "transaction": { "id": "trx_CSUGajfv9xh0XQ5wu2lx", "status": "pending" } } ``` Notez le statut dans les deux cas. L'échec d'une tentative ne met pas fin au paiement. Celui-ci revient à `pending` et le payeur peut réessayer sur le même paiement avec un autre numéro ou une autre carte. Seul votre propre code décide si cette possibilité lui est proposée. ## Ce que l'API indique et ce qu'elle n'indique pas L'orchestration est volontairement invisible dans l'objet paiement. Connaître ses limites vous évite de chercher des champs qui n'existent pas. | Question | Réponse | | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | Quel prestataire a traité mon paiement ? | Cette information n'est pas dans l'API. Un paiement ne contient ni `provider`, ni nombre de tentatives, ni bloc de routage | | Quel prestataire a traité mon payout ? | `provider` et `provider_reference`, sur le transfert lui-même | | Quelles sont mes connexions et que peuvent-elles traiter ? | [`GET /providers`](https://docs.wajub.com/fr/api/providers/list), qui renvoie la connexion et ses canaux, mais pas sa priorité ni son poids | | Comment créer une règle de routage dans le code ? | Ce n'est pas possible. Les règles sont définies dans le Dashboard | | Pourquoi ce paiement a-t-il emprunté cette route ? | [Konsole, Journal de routage](https://docs.wajub.com/fr/developer-tools/konsole/routing-log), qui montre chaque candidat et la raison de sa place | > [!WARNING] > **La sandbox n'effectue aucun routage** > > Les paiements de la sandbox ne sont pas routés : ils n'utilisent ni vos connexions ni vos règles, > n'apparaissent pas dans le Journal de routage et ne sont pas pris en compte dans les analyses. Les > connexions n'existent qu'en mode live. La sandbox sert à tester la structure de votre > intégration. Testez le routage en live avec de petits montants. - [Règles de routage](https://docs.wajub.com/fr/orchestration/routing-rules): Ce qu'une règle peut fixer, et quelle règle l'emporte quand plusieurs correspondent. - [Cascade et repli](https://docs.wajub.com/fr/orchestration/waterfall-fallback): Les échecs qui font passer un paiement à la suite, et la mise en pause d'une connexion. - [Journal de routage](https://docs.wajub.com/fr/developer-tools/konsole/routing-log): La décision à l'origine d'un paiement déjà effectué. - [Démarrage rapide](https://docs.wajub.com/fr/orchestration/quickstart): Modifier le routage sans changer une seule ligne du code d'intégration. --- # Prestataires URL: https://docs.wajub.com/fr/orchestration/providers > Connectez un prestataire, choisissez ce qu'il traite et découvrez l'effet de chaque champ sur le routage. Une connexion à un prestataire correspond à votre propre compte chez un prestataire de paiement : vous signez avec CinetPay, Flutterwave ou MTN, vous collez vos identifiants sous **Orchestration, Fournisseurs**, puis Wajub effectue les débits par son intermédiaire, selon votre contrat et vos tarifs négociés. Cette page explique le rôle de chaque champ. ## Connecter un prestataire L'assistant comporte quatre étapes. Seules les deux premières dépendent du prestataire choisi. **Identifiants.** Chaque prestataire déclare ses propres champs, car le `site_id` de CinetPay n'a pas d'équivalent chez Stripe. Le formulaire demande exactement ce dont le prestataire a besoin, rien de plus. Les valeurs sont chiffrées au repos et ne vous sont ensuite jamais renvoyées entièrement. **Canaux.** Les fonctionnalités du prestataire que vous souhaitez utiliser pour le routage par cette connexion. Ne modifiez rien pour obtenir tout ce que le prestataire prend globalement en charge, à l'exception des canaux qu'il doit d'abord activer pour votre compte. **Routage.** Les quatre nombres au coeur de cette page : la priorité, le poids et votre tarif négocié. **Examiner.** Rien n'est enregistré avant cette étape. Un test devient ensuite disponible sur la page de la connexion. Il appelle le prestataire avec vos identifiants et vous indique s'ils fonctionnent avant qu'un véritable payeur n'en dépende. > [!WARNING] > **Une connexion est toujours live** > > Il n'existe aucune copie de sandbox d'une connexion. Les connexions n'existent qu'en mode live. > `GET /providers` avec une clé de test renvoie donc une liste vide, et aucune connexion ajoutée ici > ne modifie le comportement d'un paiement dans la sandbox. Les paiements de la sandbox ne sont pas > routés : ils n'utilisent ni vos connexions ni vos règles. ## Ce qu'une connexion peut traiter Deux listes restreignent une connexion et fonctionnent de la même manière : une liste vide signifie tout, pas rien. **Canaux.** Un paiement ne passe par la connexion que si le prestataire peut techniquement traiter le canal du paiement et que votre propre liste de canaux l'autorise. Si vous n'avez jamais défini de liste, toutes les fonctionnalités du prestataire sont acceptées. La restriction est un choix. **Devises.** Même règle. Une liste de devises vide accepte toutes les devises que le prestataire peut régler. Vous la réglez dans l'assistant de connexion et sur la page de la connexion, sous **Devises**. Le canal utilisé ici est un slug exact, le canal d'opérateur sur lequel les paiements sont routés : `cm.mtn`, `sn.wave`, `ke.mpesa`, `card`. Aucun paiement n'est routé sur des valeurs de niveau produit comme `mobile_money` ou `bank_transfer`. Choisir une liste de canaux revient à sélectionner les réseaux des opérateurs un par un. > [!NOTE] > **Certains canaux nécessitent d'abord l'accord du prestataire** > > Quelques fonctionnalités doivent être activées par le prestataire sur votre compte avant > d'accepter un débit. Elles sont exclues de la liste par défaut qui contient tout ce que le > prestataire prend en charge. Elles ne peuvent donc pas apparaître par accident. Ajoutez-les > explicitement après la confirmation du prestataire, pas avant. ## Configuration du routage Quatre champs qui ont des effets très différents. - `priority` (integer, default `0`): Ordonne les connexions qu'aucune règle de routage ne désigne, sur un canal sans politique de canal. La valeur la plus élevée est essayée en premier. Un palier inférieur n'est jamais utilisé avant l'échec de toutes les connexions des paliers supérieurs. Sur un canal doté d'une politique, elle ne départage que les connexions que la politique laisse à égalité. - `weight` (integer, 0 à 100, default `100`): Répartit le trafic entre les connexions par ailleurs à égalité, y compris celles qu'une politique de canal laisse à égalité : 70 et 30 envoient environ 70 % de ces paiements à la première. - `Tarif négocié` (pourcentage): Le pourcentage du montant que ce prestataire vous facture. Il sert à trouver la connexion la moins chère pour chaque paiement, ainsi qu'à l'objectif Coût le plus bas et au plafond de coût d'une politique de canal. Sans tarif saisi, vos connexions ne peuvent pas être distinguées par leur coût. - `Frais fixes` (montant): La part du même coût facturée par transaction. Saisissez-la dans votre devise de base : Wajub la convertit dans la devise du paiement pour comparer les coûts. Les deux valeurs peuvent être remplacées pour un canal précis lorsqu'un prestataire applique un tarif différent à un réseau. Utilisez la priorité lorsque vous connaissez la réponse souhaitée pour tous les paiements. Lorsque la réponse dépend du pays, du canal, de la devise ou du montant, une [règle de routage](https://docs.wajub.com/fr/orchestration/routing-rules) l'exprime plus précisément et s'applique en premier, et une [politique de canal](https://docs.wajub.com/fr/orchestration#then-the-channels-policy-when-it-has-one) peut ordonner un canal d'opérateur à part. Sans politique de canal, les trois autres champs ne sont pris en compte qu'à l'intérieur d'un palier, une fois que la priorité a regroupé vos connexions. Avec une politique, le tarif et les frais fixes alimentent aussi son objectif **Coût le plus bas** et son plafond de coût, et le poids répartit le trafic entre les connexions qu'elle laisse à égalité. Prenons un exemple : deux connexions peuvent traiter `cm.mtn`, l'une avec une priorité de `10` et l'autre de `0`, sans règle ni politique sur le canal. La première est toujours appelée en premier, quels que soient le coût et les performances de la seconde. Placez-les toutes les deux sur `10` : le coût et la réussite récente commencent alors à décider, et vos tarifs à compter. > [!TIP] > **Saisissez vos tarifs avant d'attendre un routage au coût le plus bas** > > À l'intérieur d'une même priorité, Wajub favorise la connexion la moins chère pour ce montant et > ce canal précis. Sans tarif saisi, toutes vos connexions se valent sur le coût, et le coût ne > départage rien. La saisie du coût réel de chaque prestataire active le routage au coût le plus > bas. ## Le catalogue et la signification d'une présence dans celui-ci La liste des prestataires du Dashboard présente ceux que vous pouvez connecter. Trois conditions doivent être réunies avant qu'un prestataire puisse traiter un paiement live. | Condition | Origine | | ---------------------------------------- | ------------------------------------------------------------------------------ | | Le prestataire est répertorié et actif | Le catalogue de Wajub | | Wajub peut débiter par son intermédiaire | Les prestataires pas encore pris en charge sont marqués **Bientôt disponible** | | Vous possédez ses identifiants | Votre propre contrat avec le prestataire | Si vous avez connecté un prestataire qui n'apparaît jamais dans une décision de routage, passez son canal, sa devise et un montant dans le [simulateur de routage](https://docs.wajub.com/fr/orchestration/routing-rules#the-simulator-on-the-routing-rules-page), disponible à partir du plan Growth : il indique pourquoi chaque connexion a été écartée. Vous pouvez aujourd'hui connecter 27 prestataires : le **réseau Wajub** (sur demande, voir plus bas), Stripe, PayPal, Flutterwave, Flutterwave v4, Paystack, PawaPay, CinetPay, InTouch, K-PAY, FedaPay, Kkiapay, Maviance, My-CoolPay, Monetbil, Campay, Neero, Notch Pay, Taramoney, Fapshi, MeSomb, Nokash, MTN MoMo, Orange Money, Wave, Djamo et Express Union Mobile Money. Les autres prestataires du catalogue sont marqués **Bientôt disponible** et ne peuvent pas encore être connectés. MeSomb est en **Bêta** : vous pouvez le connecter et il reçoit des paiements, sur MTN et Orange Money au Cameroun, mais il a encore porté peu de trafic réel. Faites-y passer un petit paiement avant d'y router du volume. Flutterwave v4 est une connexion distincte de Flutterwave, sur la nouvelle API de Flutterwave, que Flutterwave présente encore comme une bêta. Elle débite OPay et l'USSD au Nigeria et le Mobile Money dans les pays qu'elle couvre, mais pas les cartes : connectez Flutterwave pour celles-ci. Les connexions étant live, le Dashboard refuse à l'enregistrement les identifiants de test d'un prestataire : - Une clé qui le dit elle-même est refusée dès la saisie : une clé Stripe ou Paystack commençant par `sk_test_` ou `pk_test_`, une clé Flutterwave contenant `_TEST`, une clé K-PAY commençant par `kpay_test_`, une clé FedaPay commençant par `sk_sandbox_`, une clé Notch Pay commençant par `sk_test.`, une clé Fapshi commençant par `FAK_TEST_`. - Les clés PawaPay, PayPal, Campay, MTN MoMo et Wave ont la même forme en test et en production. Wajub interroge l'API de production du prestataire à l'enregistrement et refuse les identifiants auxquels elle répond `401 Unauthorized`. Toute autre réponse, ou aucune, enregistre la connexion comme avant. Lorsque Wajub met un prestataire en **Maintenance**, le routage ignore toutes les connexions vers lui jusqu'à son retour, et la connexion suivante prend le paiement. La décision enregistre cette mise à l'écart avec le motif `provider_in_maintenance`. Seul un prestataire **Disponible** ou en **Bêta** reçoit des paiements : un prestataire marqué **Bientôt disponible** ou **Désactivé** est écarté de la même façon, avec le motif `provider_unavailable`, même si une connexion vers lui est encore active. Il existe six types de prestataires, et leur type indique leur nature : `aggregator`, `mobile_money`, `card`, `wallet`, `bank`, `crypto`. Un agrégateur atteint plusieurs opérateurs avec un seul contrat. Une connexion à un agrégateur peut donc remplir toute une colonne de la [matrice](https://docs.wajub.com/fr/orchestration/analytics). Une connexion Mobile Money directe accède au réseau d'un seul opérateur. Wajub exploite également une connexion interne, le **réseau Wajub**. Il encaisse le Mobile Money sous les accords partenaires de Wajub, sans contrat à signer avec un prestataire, dans 14 pays : le Bénin, le Burkina Faso, le Cameroun, la Côte d'Ivoire, la RD Congo, le Congo, le Gabon, le Kenya, le Rwanda, le Sénégal, la Sierra Leone, la Tanzanie, l'Ouganda et la Zambie. Il verse les payouts sur les mêmes canaux, sauf Wave, qui ne sert qu'à encaisser, et vers Express Union au Cameroun. Chaque pays s'obtient sur demande. Le réseau est accordé après une demande sous **Orchestration, Wajub Rail**, pas en collant des identifiants, et uniquement une fois votre compte vérifié. Vous choisissez les pays et les canaux, vous consultez les tarifs proposés et vous signez le contrat dans le Dashboard. Wajub examine ensuite la demande : elle est approuvée, approuvée pour une partie des canaux seulement, ou refusée. Le contrat signé se télécharge une fois la demande acceptée. Une seule demande est examinée à la fois. Une fois en place, le réseau se comporte comme toutes les autres connexions, y compris pour la priorité et le poids. La page Wajub Rail montre ce que votre connexion fait tourner : si elle est active, les canaux qui vous sont accordés, pays par pays, et ceux que vous avez désactivés, les pays couverts par le réseau que vous n'avez pas encore demandés, chacun avec son lien de demande pour les membres autorisés à modifier les paramètres du compte, et toutes vos demandes. Une demande de pays ou de canaux supplémentaires reprend votre dernier profil d'entreprise : vous ne choisissez que ce que vous ajoutez. Vous pouvez mettre le réseau en pause depuis sa page de connexion, et le réactiver de la même façon. Quand c'est Wajub qui le met en pause, parce qu'un contrat n'a pas été signé à temps ou sur sa propre décision, il le reste : seul Wajub, ou une demande approuvée, le réactive. ## Nombre de connexions autorisées Votre plan définit le plafond. C'est la seule limite qui détermine ce que l'orchestration peut faire pour vous. | Plan | Connexions | Règles de routage | | ------------- | ---------- | ----------------- | | Pay as you go | 2 | Non incluses | | Growth | 6 | Incluses | | Scale | Illimitées | Incluses | | Enterprise | Illimitées | Incluses | Le réseau Wajub ne compte pas dans ce plafond : en Pay as you go, vous pouvez avoir deux connexions à vous et le réseau Wajub. Deux connexions constituent le minimum nécessaire à une cascade. Avec une seule connexion, Wajub enregistre toujours une décision de routage, mais la liste ne contient qu'une ligne et un échec du côté du prestataire met fin au paiement. ## Lorsqu'une connexion rencontre un problème Deux mécanismes agissent seuls, à des échelles de temps différentes. Vous ne configurez aucun des deux. Le **health badge** de la connexion présente les transactions créditées qui l'ont empruntée au cours des dernières 24 heures, [en vert, orange ou rouge](https://docs.wajub.com/fr/orchestration/analytics#when-a-connection-is-called-degraded). Il évalue la dernière journée à votre intention. Le **coupe-circuit** agit en quelques minutes. Lorsqu'une connexion échoue de façon répétée sur un canal, Wajub la met en pause sur ce canal pendant quelques minutes et la remet automatiquement en service dès qu'elle fonctionne de nouveau. Seuls votre compte et ce canal sont concernés : une connexion qui échoue sur `cm.mtn` continue donc de traiter normalement `cm.orange`. [Cascade et repli](https://docs.wajub.com/fr/orchestration/waterfall-fallback#the-circuit-breaker) décrit ce que vous voyez pendant ce temps. Ce que vous seul pouvez corriger est signalé sur la connexion elle-même. Lorsqu'elle n'a pas d'identifiants pour un canal, ou que le prestataire refuse sa clé, la connexion affiche **Connexion refusée** dans la liste, la page du prestataire affiche l'erreur avec **Corriger la connexion**, et votre équipe reçoit un e-mail à ce sujet. Le signalement disparaît lorsque vous enregistrez des identifiants différents, lorsqu'un test de connexion réussit, ou au prochain paiement que la connexion prend en charge. [Cascade et repli](https://docs.wajub.com/fr/orchestration/waterfall-fallback#a-connection-the-provider-refuses) décrit l'effet d'une telle connexion sur un paiement. ## Ce que votre intégration peut consulter Vos connexions sont accessibles depuis l'API, volontairement sans leur configuration de routage. `GET /providers` La réponse donne, pour chaque connexion active, l'identifiant, le slug, le nom, le logo, le type, un indicateur `is_active`, et les canaux réellement disponibles. Ces canaux correspondent à l'intersection entre ceux pris en charge par le prestataire et ceux que vous avez activés. La priorité, le poids, les tarifs et les identifiants n'y figurent pas. Aucun endpoint ne permet de les modifier. Chaque entrée de `channels` est le même objet que celui renvoyé par `GET /channels`, avec tous ses champs. Une connexion avec six canaux en contient donc six. L'exemple ci-dessous est abrégé à une connexion et à quelques champs d'un de ses canaux. ```json title="Réponse · une connexion, un canal" { "id": "00000000-0000-7000-8000-000000000001", "slug": "cinetpay", "name": "CinetPay", "logo": "https://assets.wajub.com/img/providers/cinetpay/icon.png", "type": "aggregator", "is_active": true, "sandbox": false, "channels": [ { "id": "chn.4ALL37uSbXWS", "uid": "chn.4ALL37uSbXWS", "slug": "cm.mtn", "name": "MTN Mobile Money CM", "type": "mobile_money", "countries": ["CM"], "logo": "https://assets.wajub.com/img/channels/momo.svg", "active": true, "collect": true, "payout": true, "currency": "XAF" } ] } ``` Les modifications d'une connexion sont envoyées à vos endpoints de webhook. Votre backend peut ainsi rester à jour sans interroger régulièrement cette liste. | Événement | Moment de l'émission | | ------------------------------ | --------------------------------------------------------------------------- | | `provider.activated` | Une connexion est devenue active, lors de sa création ou de sa réactivation | | `provider.deactivated` | Une connexion a été suspendue ou déconnectée | | `provider.channel_activated` | Un canal est devenu utilisable pour le routage par une connexion | | `provider.channel_deactivated` | Un canal a cessé d'être utilisable pour le routage par celle-ci | Si votre checkout affiche les moyens de paiement, utilisez les événements de canal plutôt qu'une liste codée en dur. Ils sont émis pour l'ensemble exact sur lequel Wajub route les paiements. ## Demander un prestataire absent de la liste Écrivez à **[providers@wajub.com](mailto:providers@wajub.com)** en indiquant le prestataire, les pays et les canaux dont vous avez besoin. Les pays que vous indiquez nous aident à le prioriser. - [Orchestration des paiements](https://docs.wajub.com/fr/orchestration): Ce que Wajub fait de la priorité, du poids et de vos tarifs. - [Règles de routage](https://docs.wajub.com/fr/orchestration/routing-rules): Favoriser une connexion pour un canal, une devise ou une plage de montants. - [Analyse de l'orchestration](https://docs.wajub.com/fr/orchestration/analytics): Les performances réelles de chaque connexion pour votre compte. - [Moyens de paiement et canaux](https://docs.wajub.com/fr/payments/payment-methods): Les pays, opérateurs et devises couverts par ces canaux. --- # Démarrage rapide URL: https://docs.wajub.com/fr/orchestration/quickstart > Rendez le routage visible sur un paiement live, puis déplacez une connexion et observez son changement. L'orchestration ne demande aucune activation ni aucune modification de votre intégration. Ce démarrage rapide rend visible le classement de vos connexions sur un paiement live, puis le modifie une fois pour vous permettre d'observer le changement. > [!WARNING] > **La sandbox n'effectue aucun routage** > > Un paiement dans la sandbox n'est pas routé : il n'utilise ni vos connexions ni vos règles, aucune > décision n'est enregistrée et le journal de routage de Konsole refuse directement une clé de > sandbox. Vous ne pouvez pas simuler une décision de routage > sans argent réel. Utilisez donc le plus petit montant accepté par votre opérateur et payez-vous > vous-même. ## 1. Connecter un deuxième prestataire Une seule connexion n'offre aucune solution de repli. Wajub enregistre toujours une décision de routage, mais la liste ne contient qu'une ligne et l'échec met fin au paiement. Ajoutez un deuxième prestataire dans le Dashboard, sous **Orchestration, Fournisseurs**. Les deux côtés doivent être actifs : le prestataire lui-même et votre connexion. Un prestataire ou une connexion inactifs ne sont jamais essayés. Une connexion inachevée est donc invisible, pas simplement placée en dernier. ## 2. Définir leur ordre Chaque connexion possède deux nombres, tous deux disponibles sur la page du prestataire sous **Configuration du routage**. | Champ | Ce qu'il décide | Valeur par défaut | | ------------ | ------------------------------------------------------------------------------------ | ----------------- | | `priority` | L'ordre de la liste. La valeur la plus élevée passe en premier | `0` | | `weight` (%) | Comment deux connexions se partagent le trafic lorsque rien d'autre ne les distingue | `100` | La priorité ordonne toutes les connexions qu'aucune règle de routage ne désigne, sur un canal sans politique de canal. Une connexion d'un palier inférieur n'est jamais essayée avant que toutes les connexions des paliers supérieurs aient échoué, quel que soit son coût. Une [règle de routage](https://docs.wajub.com/fr/orchestration/routing-rules) correspondante et une politique de canal passent avant elle, c'est pourquoi ce guide de démarrage n'utilise ni l'une ni l'autre : [Orchestration des paiements](https://docs.wajub.com/fr/orchestration#the-most-specific-instruction-goes-first) décrit l'ordre complet. > [!NOTE] > **Le poids ne répartit que ce que rien d'autre ne distingue** > > Le poids répartit le trafic entre des connexions de même priorité que rien d'autre ne distingue : > elles se valent sur le coût et sur la réussite récente. Sur un nouveau compte, ni tarif négocié ni > historique récent ne distinguent les connexions : la priorité, puis le poids, décident. Définissez une connexion sur `10` et laissez l'autre sur `0`. Vous obtenez deux paliers, la configuration minimale qui permet d'observer quelque chose dans les étapes suivantes. ## 3. Envoyer un paiement live Un paiement nécessite deux appels. C'est le point sur lequel la plupart des intégrations se trompent : le premier appel n'effectue aucun routage. Il crée la transaction et n'accepte ni canal ni prestataire. `POST /payments` Envoyez un montant, une devise et l'un des moyens suivants pour identifier le payeur : `email`, `phone`, `customer_id` ou `customer`. **Créer le paiement** ```bash curl https://api.wajub.com/payments \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 500, "currency": "XAF", "phone": "+237670000000", "description": "Watching the router work" }' ``` ```javascript const payment = await wajub.payments.create({ amount: 500, currency: 'XAF', phone: '+237670000000', description: 'Watching the router work', }); console.log(payment.id); ``` ```python payment = wajub.payments.create({ "amount": 500, "currency": "XAF", "phone": "+237670000000", "description": "Watching the router work", }) print(payment["id"]) ``` ```php $payment = $wajub->payments->create([ 'amount' => 500, 'currency' => 'XAF', 'phone' => '+237670000000', 'description' => 'Watching the router work', ]); echo $payment->id; ``` ```go payment, err := client.Payments.Create(context.Background(), map[string]any{ "amount": 500, "currency": "XAF", "phone": "+237670000000", "description": "Watching the router work", }, nil) log.Println(payment.ID) ``` Le deuxième appel effectue le routage. Il indique un canal et tout ce qui est décrit dans [Orchestration des paiements](https://docs.wajub.com/fr/orchestration) se déroule pendant cet appel. `POST /payments/{id}` **Débiter et laisser Wajub choisir la connexion** ```bash curl https://api.wajub.com/payments/trx_CSUGajfv9xh0XQ5wu2lx \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "channel": "cm.mobile", "data": { "phone": "+237670000000" } }' ``` ```javascript const result = await wajub.payments.process(payment.id, { channel: 'cm.mobile', data: { phone: '+237670000000' }, }); console.log(result.transaction.status); ``` ```python result = wajub.payments.process(payment["id"], { "channel": "cm.mobile", "data": {"phone": "+237670000000"}, }) print(result["transaction"]["status"]) ``` ```php $result = $wajub->payments->process($payment->id, [ 'channel' => 'cm.mobile', 'data' => ['phone' => '+237670000000'], ]); echo $result->transaction->status; ``` ```go result, err := client.Payments.Process(context.Background(), payment.ID, map[string]any{ "channel": "cm.mobile", "data": map[string]any{"phone": "+237670000000"}, }, nil) log.Println(result.Transaction.Status) ``` Le routage utilise toujours le canal de l'opérateur. Wajub lit le numéro, reconnaît MTN et route le paiement comme `cm.mtn`. Une connexion qui déclare `cm.orange`, mais pas `cm.mtn`, est donc écartée. ## 4. Lire la décision Ouvrez le paiement dans le Dashboard. Sous la chronologie se trouve **Décision de routage**, et « Voir les détails de routage » ouvre la liste classée, dans l'ordre où les connexions devaient être essayées. **Décision de routage · cm.mtn · 500 XAF** Deux connexions, deux paliers. La première a répondu, donc la seconde n'a jamais été appelée. 1. **cinetpay** (priority 10, accepted, 1.2 s, coût le plus bas): accepté 2. **flutterwave** (priority 0, untried, coût le plus bas): jamais appelée Les deux connexions portent **Coût le plus bas**, ce qui est normal sur un nouveau compte : sans tarif négocié, elles coûtent la même chose pour le routage, et sans historique récent sur ce canal, aucune ne se distingue par sa réussite récente. Rien ne les départage, aucune règle ne correspond et le canal n'a pas de politique : la priorité fait donc tout le travail, exactement comme vous l'avez configurée à l'étape 2. La même liste est disponible dans le [journal de routage](https://docs.wajub.com/fr/developer-tools/konsole/routing-log), avec une ligne par tentative de débit plutôt qu'une ligne par paiement. Cette page est réservée au mode live, pour la raison indiquée dans le premier encadré. ## 5. Déplacer une connexion et observer son changement Inversez les deux priorités : la connexion qui était sur `0` passe à `10`, tandis que l'autre passe à `0`. Envoyez un deuxième paiement identique au premier. La cascade apparaît dans le nouvel ordre. Votre code n'a pas changé, aucun déploiement n'a eu lieu et la requête de paiement est identique octet pour octet à celle envoyée cinq minutes plus tôt. C'est tout l'intérêt de cette fonctionnalité. Observez-la une fois vous-même avant de lui faire confiance en production. ## Ce que l'API ne vous indique pas L'objet paiement n'a aucun champ `provider`. `GET /payments/{id}` renvoie le `channel` débité, jamais la connexion qui l'a traité. Aucun endpoint marchand ne renvoie la priorité, le poids ou la liste des candidats. Le routage est visible dans le Dashboard et dans Konsole, nulle part ailleurs. > [!CAUTION] > **Une réponse 422 sur channel signifie que la liste était vide** > > Lorsqu'aucune connexion ne passe les filtres, le paiement renvoie > `422 No eligible payment provider found for this transaction.` sur la clé `channel` et la > transaction revient à `pending`. Il s'agit d'un problème de configuration du compte, pas du > payeur : le canal, la devise ou des connexions en pause sur ce canal n'ont laissé aucune connexion > à essayer. - [Orchestration des paiements](https://docs.wajub.com/fr/orchestration): Les connexions admissibles, puis les règles, la politique du canal et la priorité, dans cet ordre. - [Règles de routage](https://docs.wajub.com/fr/orchestration/routing-rules): Envoyer d'abord un pays, un canal, une devise ou une plage de montants à une connexion. - [Cascade et repli](https://docs.wajub.com/fr/orchestration/waterfall-fallback): Ce qui parcourt la liste et ce qui l'arrête définitivement. - [Accepter un paiement, guide complet](https://docs.wajub.com/fr/payments/quickstart): Le parcours complet en deux appels, page hébergée comprise. --- # Règles de routage URL: https://docs.wajub.com/fr/orchestration/routing-rules > Ce à quoi une règle peut correspondre, quelle règle l'emporte quand plusieurs correspondent, et les situations où elle ne peut pas aider. Une règle de routage désigne l'une de vos connexions pour les paiements qui présentent certaines caractéristiques : lorsqu'un paiement correspond, cette connexion est essayée en premier, quelle que soit la `priority`, avec le [prestataire de secours](#the-fallback-provider) de la règle juste derrière. Le reste est ordonné comme le décrit [Orchestration des paiements](https://docs.wajub.com/fr/orchestration). > [!NOTE] > **À partir de Growth, uniquement en live** > > Les règles de routage sont une fonctionnalité payante. Avec **Pay as you go**, la page > **Orchestration, Règles de routage** est remplacée par une invitation à changer de plan. Toute la > section Orchestration n'est disponible qu'en mode live. Cette page suppose donc l'utilisation d'une > clé live et d'un plan Growth, Scale ou Enterprise. ## Ce à quoi une règle peut correspondre Une règle possède des conditions, une cible, un secours facultatif et deux nombres qui lui sont propres. Toutes les conditions sont facultatives, et une règle ne correspond qu'à un paiement qui remplit chacune des conditions qu'elle définit. Les noms ci-dessous sont ceux des champs du formulaire de règle dans le Dashboard. - `Canal de paiement` (canal): Un canal d'opérateur exact, celui sur lequel les paiements sont routés : cm.mtn, sn.wave, card. Une valeur vide correspond à tous les canaux. - `Devise` (code ISO): Code ISO, quelle que soit la casse. Une valeur vide correspond à toutes les devises. - `Montant min / Montant max` (montant): Bornes inclusives dans la devise saisie et dans les mêmes unités principales que le paiement. Chaque borne peut rester ouverte. - `Pays` (deux lettres): Redondant sur une règle dont le canal est un canal d'opérateur : cm.mtn désigne déjà le Cameroun. Il restreint une règle sans canal, ou une règle sur un canal sans pays comme card, où il est comparé au pays détecté pour le payeur. Voir ci-dessous. - `Router vers le fournisseur` (connexion, required): La connexion unique que cette règle place. Elle doit correspondre à un prestataire déjà connecté à votre compte, actif et en mode live. - `Fournisseur de repli` (connexion): La connexion essayée après la cible quand la règle correspond, ou à sa place quand la cible ne peut pas être essayée. Facultative, et différente de la cible. Voir Le prestataire de secours, plus bas. - `Priorité` (integer, required, default `0`): Départage les règles correspondantes : la plus élevée place sa connexion en premier. Il s'agit de la priorité propre à la règle, sans aucun rapport avec celle de votre connexion. - `Poids (%)` (integer, de 0 à 100, default `100`): Répartit le trafic entre les règles correspondantes encore à égalité, à chaque paiement. Une règle de poids 0 ne passe jamais en premier tant qu'une autre a un poids non nul. - `Actif` (activé ou non, default `activé`): Les règles inactives et les règles supprimées ne correspondent jamais. ### Conditions avancées La section **Conditions avancées** du formulaire en ajoute quatre. Chacune, lorsqu'elle est définie, doit aussi être remplie. | Condition | Correspond lorsque | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Fenêtres horaires | Le paiement a lieu dans l'une des fenêtres : jours de la semaine, heure de début et heure de fin, lues dans le fuseau horaire de la fenêtre. Une fenêtre qui finit avant de commencer passe minuit : 22:00 à 04:00 couvre la nuit. Les heures après minuit comptent pour le jour suivant : cochez aussi ce jour | | Segments clients | Le payeur appartient à l'un des segments choisis. **VIP** : un client avec l'étiquette `vip`. **Liste noire** : un client que vous avez bloqué, ou avec l'étiquette `blacklist`. **Première transaction** : aucun paiement réussi auparavant chez vous. **Client récurrent** : au moins un. Un paiement sans client ne correspond à aucun des deux derniers | | Filtres de métadonnées | Chaque filtre est vérifié sur les `metadata` envoyées avec le paiement. La clé peut être un chemin à points, comme `device.type`. Une clé absente des métadonnées du paiement fait échouer le filtre, sauf un filtre `eq` enregistré avec une valeur vide, qui ne correspond qu'aux paiements sans cette clé | | Plafonds de fréquence | Aucun plafond de la règle n'est atteint. Voir [Plafonds de fréquence](#frequency-caps) | Les étiquettes d'un client sont les `tags` du [client](https://docs.wajub.com/fr/payments/customers/manage), définis par l'API ou dans le Dashboard. Les filtres de métadonnées comparent `eq` et `in` sur le texte de la valeur : `100` saisi dans le formulaire correspond à `100` envoyé comme nombre ou comme chaîne, et `true` au booléen. `in` prend plusieurs valeurs séparées par des virgules, comme `web, app`, et correspond quand la métadonnée est égale à l'une d'elles. `contains` cherche le texte dans une chaîne, et `gt`, `gte`, `lt` et `lte` comparent des nombres. Une liste ou un objet dans vos métadonnées ne correspond qu'à une valeur identique. Le formulaire affiche ces opérateurs sous la forme `=`, « dans », « contient », `>`, `≥`, `<` et `≤`. ### Plafonds de fréquence Un plafond empêche la règle de correspondre dès qu'elle a compté assez de paiements dans sa fenêtre. La règle correspond de nouveau lorsque la fenêtre suivante commence. | Champ | Ce qu'il définit | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Fenêtre | **par minute**, **par heure** ou **par jour**. Fenêtres calendaires en UTC : cette minute, cette heure, ce jour | | max | Le nombre de paiements comptés dans la fenêtre avant que la règle cesse de correspondre | | Portée | **Règle** : les paiements que cette règle a routés, vers sa cible ou vers son secours. **Fournisseur** : tous les paiements que votre compte a envoyés à la cible de la règle, quelle que soit la façon dont ils ont été routés | Un paiement compte lorsqu'un prestataire l'a pris en charge : réussi, en attente, ou en attente d'une action du payeur. Un paiement refusé en chemin ne compte pas. ## Quelle règle l'emporte Toutes vos règles actives sont évaluées pour chaque paiement live, et chaque règle qui correspond place sa cible. Elles sont prises dans cet ordre. 1. La **Priorité** de règle la plus élevée d'abord. 2. À priorité égale, la règle la plus précise. 3. Les règles encore à égalité se partagent le trafic selon leur **Poids**, à chaque paiement. Avec des poids de 70 et 30, la cible de la première règle passe en premier sur environ sept paiements sur dix. Chaque règle place sa cible, puis son secours, puis la règle suivante fait de même. Prenons un compte connecté à CinetPay et à Flutterwave. Les deux connexions ont une priorité de `0`, peuvent traiter `cm.mtn` en XAF, et une règle associe `cm.mtn` et `XAF` à CinetPay. CinetPay est placé en premier par la règle. Flutterwave vient après, ordonné avec toutes les connexions qu'aucune règle ne désigne, et le fait qu'il soit moins cher avec un meilleur taux de réussite récent n'y change rien. **Décision de routage · cm.mtn · 12 000 XAF** Une règle, deux connexions. La cible de la règle passe en premier, quels que soient le coût et la réussite récente. 1. **cinetpay** (priority 0, accepted, 1.1 s, règle correspondante): accepté 2. **flutterwave** (priority 0, untried, coût le plus bas, réussite récente): jamais appelée C'est tout l'intérêt. Lorsqu'une règle correspond, rien d'autre ne l'emporte : ni la priorité de vos connexions, ni leur coût, ni leur taux de réussite en direct. Écrivez des règles pour les cas où vous connaissez une meilleure réponse que les chiffres. Laissez les chiffres décider dans les autres cas. ### Répartir le trafic **Par montant.** Une règle par tranche, chacune avec sa plage de montants et sa connexion. Un paiement tombe dans une seule tranche : une seule règle correspond. **Par proportion.** Deux règles avec les mêmes conditions et la même priorité, chacune ciblant une connexion différente, avec des poids de 70 et 30. La page Règles de routage signale les règles dont les conditions se chevauchent, sauf deux règles de même priorité qui ont toutes deux un poids inférieur à 100 et des cibles différentes : elle y voit une répartition voulue. ## Le prestataire de secours Une règle peut désigner une seconde connexion, celle que vous voulez voir essayée quand sa cible échoue. Quand la règle correspond à un paiement, le secours est placé de l'une de deux façons. **La cible peut être essayée.** Le secours vient juste derrière elle : c'est la connexion essayée ensuite si la cible échoue du côté du prestataire. **La cible ne peut pas être essayée du tout.** Elle est en pause sur ce canal après des échecs répétés, elle ne prend pas en charge le canal ou la devise, ou la connexion n'est plus active. Le secours prend alors la place de la cible, comme si la règle l'avait désigné. Le secours est une connexion comme les autres. S'il ne peut pas non plus traiter le paiement, la règle ne place rien. Dans le [journal de routage](https://docs.wajub.com/fr/developer-tools/konsole/routing-log), une connexion placée ainsi affiche un badge **Repli**. ## Situations où une règle ne peut pas aider Quatre situations rendent une règle inopérante. Vérifiez-les avant de conclure que la règle a été ignorée. **La cible doit être une de vos connexions.** Le formulaire permet uniquement de choisir parmi les prestataires déjà connectés à votre compte, actifs et en mode live. La suspension ultérieure d'une connexion désactive également ses règles, sauf une règle qui a un secours : le secours prend alors sa place. **Le canal doit être un canal d'opérateur.** Le routage utilise toujours le canal de l'opérateur : `cm.mobile` avec un numéro MTN est routé comme `cm.mtn`, écrivez donc la règle sur `cm.mtn`. Une règle basée sur un terme de produit comme `mobile_money`, `bank_transfer` ou `mobile` ne correspond à rien, car aucun paiement n'est routé sur ces chaînes. **Une règle plafonnée attend la fin de sa fenêtre.** Une fois un [plafond de fréquence](#frequency-caps) atteint, la règle ne correspond plus, et les paiements qu'elle aurait placés suivent l'ordre général. **Une carte reste chez le prestataire qui la détient.** Une carte saisie dans les champs propres à un prestataire ne peut être débitée que par lui : une règle qui vise une autre connexion ne la déplace pas. Voir [Cascade et repli](https://docs.wajub.com/fr/orchestration/waterfall-fallback#a-card-stays-with-its-provider). > [!NOTE] > **Le pays vient du canal** > > Sur un réseau d'opérateur, le pays vient du canal : `cm.mtn` désigne le Cameroun, quelle que soit > la casse dans laquelle vous avez saisi le **Pays** de la règle. Une règle sur `cm.mtn` concerne > déjà le Cameroun. Sur un canal sans pays, comme `card`, Wajub utilise le pays qu'il a détecté pour > le payeur à l'ouverture du checkout, s'il y en a un. ## Une règle qui produit un effet Le modèle à reproduire utilise un canal précis, indique explicitement la devise et cible la connexion que vous voulez pour ce cas. Supposons que MTN Cameroon soit votre principal réseau. Trois connexions peuvent le traiter et l'une d'elles offre le meilleur taux d'acceptation pour les montants inférieurs à 100 000 XAF. Créez une règle. | Champ | Valeur | | -------------------------- | ------------------------ | | Canal de paiement | `cm.mtn` | | Devise | `XAF` | | Montant max | `100000` | | Router vers le fournisseur | votre connexion préférée | | Priorité | `0` | Sous 100 000 XAF, cette connexion est essayée en premier, quelle que soit sa priorité. Au-dessus, la règle ne correspond plus et les trois connexions sont ordonnées par la politique du canal, ou par leur priorité, leur coût et leur réussite récente. C'est généralement le comportement souhaité pour les montants les plus importants. Les bornes de montant utilisent les unités principales, comme le paiement. `100000` représente 100 000 XAF, pas 1 000 XAF. ## Le simulateur de la page Règles de routage Le **Simulateur de routage** de la page Règles de routage prend une décision de routage sans rien débiter. Donnez-lui un canal, une devise et un montant : il répond avec l'ordre dans lequel vos connexions seraient essayées, la raison de chaque place (une règle, le secours d'une règle, la politique du canal ou la priorité de la connexion), tout garde-fou qui a reculé une connexion, et les connexions écartées, avec leur motif. Rien n'est débité et rien n'est enregistré. Une connexion est écartée pour l'un de ces motifs : | Motif | Pourquoi la connexion est écartée | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `provider_in_maintenance` | Wajub a mis le prestataire en **Maintenance** | | `provider_unavailable` | Le prestataire est **Bientôt disponible** ou **Désactivé** | | `channel_not_served` | Le prestataire ne peut pas acheminer ce canal, ou votre connexion ne l'active pas | | `currency_not_supported` | Votre connexion est limitée à d'autres devises | | `no_driver` | Wajub ne peut pas encore débiter par ce prestataire | | `circuit_open` | La connexion est [en pause sur ce canal](https://docs.wajub.com/fr/orchestration/waterfall-fallback#the-circuit-breaker) après des échecs répétés | Il n'envoie ni client ni métadonnées : une règle avec un segment client ou un filtre de métadonnées n'y correspond donc jamais. Il n'envoie pas non plus de pays : le pays ne vient que d'un slug de canal qui commence par un pays, si bien que sur `card` une règle avec un **Pays** n'y correspond jamais, alors qu'elle peut correspondre à un vrai paiement. Les fenêtres horaires sont lues à l'heure actuelle et les plafonds de fréquence à leurs compteurs actuels. Là où le poids répartit le trafic, deux simulations peuvent différer. Comme les règles elles-mêmes, le simulateur demande un plan Growth ou supérieur. Le formulaire d'une règle affiche aussi son impact avant l'enregistrement. Il compte vos paiements live des 7 derniers jours qui correspondent au canal, à la devise, au pays (lu dans le canal sur lequel le paiement a été débité) et à la plage de montants de la règle, et liste les connexions qui les ont traités et qui les perdraient au profit de celle que vise la règle. Il ignore les conditions avancées et suppose que la règle l'emporte à chaque fois : c'est le maximum de ce qu'elle peut déplacer, pas une prévision. - [Orchestration des paiements](https://docs.wajub.com/fr/orchestration): Les filtres, puis les règles, la politique du canal et la priorité, dans cet ordre. - [Cascade et repli](https://docs.wajub.com/fr/orchestration/waterfall-fallback): Ce qui parcourt la liste et ce qui retire une route de la rotation. - [Prestataires](https://docs.wajub.com/fr/orchestration/providers): La priorité, le poids et les tarifs négociés sur la connexion elle-même. - [Journal de routage](https://docs.wajub.com/fr/developer-tools/konsole/routing-log): La règle qui a placé chaque connexion, pour un paiement déjà effectué. --- # Cascade et repli URL: https://docs.wajub.com/fr/orchestration/waterfall-fallback > Ce qui parcourt la liste des candidats, ce qui l'arrête et quand une connexion est mise en pause. La cascade parcourt une seule fois la liste classée des candidats que construit [Orchestration des paiements](https://docs.wajub.com/fr/orchestration), pendant l'appel `POST /payments/{id}`, alors que votre requête est encore ouverte. Aucune chaîne de repli distincte n'est à configurer : cette page explique ce qui fait descendre un paiement dans cette liste, et ce qui l'arrête. ## Ce qui fait avancer la cascade Une seule situation la fait avancer : la tentative a échoué d'une manière qui ne dit rien sur le payeur. | Comportement de la connexion | Étape suivante | | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | Le prestataire n'a pas pu être joint | Le candidat suivant est essayé | | Le prestataire a signalé un problème temporaire de son côté | Le candidat suivant est essayé | | Le prestataire a répondu que l'opérateur a dépassé son délai ou est indisponible, que vos identifiants sont refusés, ou que son float est épuisé | Le candidat suivant est essayé, et la connexion est [signalée](#a-connection-the-provider-refuses) quand les identifiants ont été refusés | | La connexion n'avait pas d'identifiants pour ce canal, et rien n'a été envoyé | Le candidat suivant est essayé, et la connexion est [signalée](#a-connection-the-provider-refuses) | Chacun de ces cas marque la tentative comme échouée, pèse sur l'état de cette connexion sur ce canal et descend d'une ligne. Le payeur n'est informé de rien, car rien ne s'est encore passé de son côté. > [!WARNING] > **Une requête envoyée et restée sans réponse ne bascule jamais** > > Lorsque la requête a atteint le prestataire et qu'aucune réponse n'est arrivée à temps, le > prestataire a pu la traiter : une demande USSD est peut-être déjà sur le téléphone du payeur. Le > paiement reste `pending` et rien d'autre n'est essayé tant que son issue n'est pas connue. ## Ce qui arrête la cascade Outre la requête restée sans réponse décrite plus haut, quatre situations l'arrêtent. Une seule représente une bonne nouvelle. **Un prestataire a accepté.** Cela comprend une acceptation avec `pending` ou `requires_action`. Le prestataire prend en charge le paiement dès cet instant et aucune autre connexion n'est essayée. **Un prestataire a refusé pour un motif qui se reproduirait.** Un portefeuille vide, un numéro non enregistré, un plafond de l'opérateur, une carte refusée ou une demande laissée expirer par le payeur. Wajub renvoie immédiatement `402` sans consulter le candidat suivant, car un deuxième prestataire poserait la même question à la même personne. Une carte refusée l'est définitivement, et `error_code` contient le code de refus. **Une de vos connexions est mal configurée d'une manière que le prestataire ne présente pas comme un refus de vos identifiants.** Un champ obligatoire absent pour ce canal, par exemple. Cela arrête la cascade au lieu de passer à la connexion suivante. Une seule connexion défectueuse au début de votre liste peut donc vous faire perdre tous les paiements qui lui sont routés. Les identifiants font exception : manquants, rien n'est envoyé, et refusés, c'est un échec du chemin. Dans les deux cas la connexion suivante est essayée, et la connexion est signalée, comme [décrit plus bas](#a-connection-the-provider-refuses). **Trois prestataires ont été essayés.** Wajub essaie au plus trois prestataires par appel `POST /payments/{id}`, sur tous les comptes. Même une liste de dix candidats est parcourue sur trois lignes au maximum. La requête se termine avec `402`, alors que des connexions admissibles n'ont pas été essayées. Une connexion ignorée faute d'identifiants compte parmi les trois. ### Combien de temps l'appel peut durer Un prestataire qui ne répond pas à temps correspond à la [requête restée sans réponse](#what-moves-the-ladder-on) décrite plus haut : le paiement reste `pending` et rien d'autre n'est essayé. Avec trois prestataires essayés, `POST /payments/{id}` peut rester ouvert près d'une minute. Donnez à votre propre client HTTP au moins 90 secondes sur cet appel, pour qu'il n'abandonne pas un paiement que Wajub est encore en train de placer. > [!WARNING] > **Un refus ne met pas fin au paiement** > > Une réponse `402` laisse la transaction au statut `pending`, pas `failed`. Le payeur peut réessayer > sur le même paiement avec un autre numéro ou une autre carte. Ce deuxième appel reprend le routage > depuis le début. Vous décidez dans votre propre code si cette possibilité lui est proposée. ## Une carte reste chez son prestataire Une carte que le payeur a saisie dans les champs propres à un prestataire ne peut être débitée que par ce prestataire : un moyen de paiement Stripe.js, une autorisation Paystack enregistrée. Un autre prestataire ne peut pas la lire, et le premier a peut-être déjà débité la carte. Cette connexion est donc la seule essayée, quelle que soit la connexion que le classement place en premier, et un échec ne bascule jamais vers une autre connexion. Si cette connexion ne peut pas être essayée du tout, parce qu'elle est en pause sur ce canal ou qu'elle n'est plus active, le paiement reçoit la même réponse `422` qu'une [liste vide](#when-the-list-was-empty-to-begin-with), plutôt que d'aller chez un prestataire incapable de débiter la carte. ## Une étape ouverte par un prestataire reste chez lui Deux sortes d'appels vont au prestataire qui les a ouverts, et ne basculent jamais : - **La fenêtre de paiement propre au prestataire** (la page hébergée ou la feuille du prestataire que le payeur remplit) : elle s'ouvre chez le premier prestataire du classement, et si celui-ci ne peut pas l'ouvrir, l'appel échoue plutôt que d'essayer la connexion suivante. - **Une confirmation** (un code, un PIN, un numéro de téléphone, une date de naissance ou une adresse que le payeur envoie après le début du débit) : elle va au prestataire qui l'a demandée et qui détient le débit en attente. Un autre prestataire ne connaît pas ce débit. ## Une connexion que le prestataire refuse Lorsqu'une connexion n'a pas d'identifiants pour le canal, ou que le prestataire refuse la clé qu'elle contient, Wajub l'enregistre sur la connexion. | Où | Ce que vous voyez | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | **Orchestration, Fournisseurs**, et la page Matrice | Un badge **Connexion refusée** sur la connexion | | La page du prestataire | Une alerte avec le code d'erreur et la date de la dernière occurrence, et **Corriger la connexion** | | L'e-mail de votre équipe | Un e-mail, lorsque les notifications par e-mail sont activées | Le signalement disparaît lorsque vous enregistrez des identifiants différents, lorsqu'un test de connexion réussit, ou au prochain paiement que la connexion prend en charge. Un paiement qui n'a trouvé que des connexions sans identifiants n'est pas imputé au payeur comme un refus : la configuration était en cause, pas lui. ## Chaque tentative laisse une ligne Chaque tentative est listée sur le paiement avec le prestataire essayé, sa réponse, la latence et son rang dans la décision. Un paiement qui est passé deux fois à la connexion suivante en affiche trois, dans l'ordre. Vous les consultez dans le Dashboard, sous la chronologie du paiement, et dans Konsole à côté de la décision qui les a produits. L'historique des tentatives n'existe qu'à ces endroits. L'objet paiement renvoyé par l'API n'en contient aucune trace. **Un paiement, deux prestataires** - **tentative 1** (failed, 12:31:40, status: failed): Rang 1 de la décision, placée là par une règle de routage. Le prestataire a répondu que l'opérateur avait dépassé son délai. L'échec a donc été comptabilisé pour cette connexion sur ce canal, et la connexion suivante a été essayée. - provider: cinetpay - response: timeout - latency: 8.0 s - **tentative 2** (processing, 12:31:49, status: processing): Rang 2, la première connexion qu'aucune règle ne désigne. L'opérateur a accepté d'envoyer une demande au payeur. Il s'agit d'une acceptation, la cascade s'est donc arrêtée ici. - provider: flutterwave - response: pending - latency: 0.9 s La deuxième ligne explique la majeure partie de la confusion autour de la cascade. > [!CAUTION] > **Aucun basculement n'a lieu après l'acceptation de la demande** > > Un prestataire Mobile Money répond `pending` dès que l'opérateur accepte d'envoyer la demande, > plusieurs secondes avant toute action du payeur sur son téléphone. Cette acceptation arrête la > cascade. Si le payeur ne confirme jamais, le paiement échoue quelques minutes plus tard, bien après le > retour de votre appel. Aucun autre prestataire n'est essayé. La plupart des situations que les marchands interprètent > comme l'échec d'une cascade correspondent à ceci : la cascade n'a jamais démarré, car le premier > prestataire a répondu oui. ## Les échecs qui pèsent sur une connexion Les échecs qui viennent du payeur ne pèsent jamais sur une connexion : un portefeuille vide, un numéro erroné ou non enregistré, un plafond de l'opérateur, une carte refusée par sa banque ou par le filtre antifraude du prestataire, une demande que le payeur n'a pas confirmée. Un autre prestataire obtiendrait la même réponse, et les prendre en compte éloignerait progressivement votre trafic d'une connexion en parfait état. Les échecs du côté du prestataire ou de l'opérateur, eux, comptent. Ils font baisser le taux de réussite récent de la connexion sur ce canal, et une connexion qui échoue de façon répétée est mise en pause, comme décrit ci-dessous. ## Le coupe-circuit Lorsqu'une connexion échoue de façon répétée sur un canal, Wajub la met en pause sur ce canal pendant quelques minutes, avant qu'elle ne vous fasse perdre davantage de paiements, et la remet automatiquement en service dès qu'elle fonctionne de nouveau. Seuls votre compte et ce canal sont concernés : une connexion défaillante sur `cm.mtn` continue de traiter `cm.orange`, sans affecter les autres marchands. Les paiements et les payouts partagent l'état d'une connexion sur un canal. Une connexion en pause n'est pas essayée. Une connexion que vous pensiez voir essayée peut donc être entièrement absente du classement. Elle n'est pas écartée silencieusement : Konsole l'affiche comme **Ignoré (circuit ouvert)**, et la page Matrice montre le circuit sur la cellule de cette connexion. **Décision de routage · cm.mtn · 25 000 XAF** Une connexion en pause, deux connexions classées et la première a traité le paiement. 1. **flutterwave** (priority 100, accepted, 0.9 s): accepté 2. **pawapay** (priority 100, untried): jamais appelée - ~~cinetpay~~: Ignorée (circuit ouvert). La connexion a été mise en pause sur ce canal après des échecs répétés. Si cette connexion était votre connexion préférée, l'effet est visible et difficile à comprendre sans cette page : une règle qui cible CinetPay semble ignorée pendant quelques minutes. Elle ne l'est pas : la connexion était en pause et ne pouvait pas être placée. Si la règle désigne un [prestataire de secours](https://docs.wajub.com/fr/orchestration/routing-rules#the-fallback-provider), celui-ci prend la place de CinetPay tant que dure la pause. ## Deux prestataires ne peuvent jamais débiter en même temps Au cours d'un appel, Wajub s'arrête à la première acceptation. Une seule tentative peut donc réussir. Vous devez surtout faire attention à la répétition de l'appel lui-même. Envoyez un en-tête `Idempotency-Key` avec `POST /payments/{id}` : répéter le même appel dans les 24 heures renvoie la même réponse sans exécuter une deuxième cascade. Sans cet en-tête, aucune protection de ce type n'existe. Un client qui répète une requête dont il n'a jamais reçu la réponse peut lancer une deuxième cascade sur un paiement déjà réussi. > [!TIP] > **Une clé par tentative de paiement** > > Dérivez la clé d'une valeur stable de votre propre système, comme la référence de la commande > suivie du numéro de tentative. Elle accepte jusqu'à 128 caractères parmi `A-Z a-z 0-9 . _ : -`. > La réutiliser dans les 24 heures avec un autre `channel`, d'autres `data` ou un autre découpage > répond `422`. Voir [Idempotence](https://docs.wajub.com/fr/api/idempotency#reusing-a-key-with-a-different-body). ## Lorsque la liste était vide dès le départ Une réponse `422` sur la clé `channel` signifie qu'aucun candidat n'a passé les filtres. Rien n'a donc été essayé et aucune nouvelle tentative ailleurs n'est possible. Il s'agit d'un problème de configuration du compte, pas du payeur : le canal, la devise, un prestataire par lequel Wajub ne peut pas encore débiter ou des connexions en pause sur ce canal n'ont rien laissé à essayer. Une carte détenue par un prestataire dont la connexion ne peut pas être essayée aboutit aussi ici. ```json title="Réponse · 422 Unprocessable Content" { "code": 422, "status": "Unprocessable Content", "message": "No eligible payment provider found for this transaction.", "errors": { "channel": ["No eligible payment provider found for this transaction."] } } ``` La correction ne se trouve jamais dans votre requête. Le journal de routage montre les connexions ignorées parce qu'elles étaient en pause sur le canal. Pour les autres motifs, passez le même canal, la même devise et le même montant dans le [simulateur de routage](https://docs.wajub.com/fr/orchestration/routing-rules#the-simulator-on-the-routing-rules-page), disponible à partir du plan Growth, qui indique pourquoi chaque connexion a été écartée. Une connexion que vous avez vous-même suspendue, ou un prestataire inactif, n'y apparaît pas du tout. - [Orchestration des paiements](https://docs.wajub.com/fr/orchestration): La construction et l'ordre initial de la liste des candidats. - [Règles de routage](https://docs.wajub.com/fr/orchestration/routing-rules): Ce qu'une règle peut fixer et les situations où elle ne peut pas aider. - [Analyse de l'orchestration](https://docs.wajub.com/fr/orchestration/analytics): Le nombre de paiements réellement récupérés par la cascade. - [Idempotence](https://docs.wajub.com/fr/api/idempotency): L'en-tête, sa durée et les critères d'une requête identique. --- # Configuration fiscale URL: https://docs.wajub.com/fr/tax/configuration > Les paramètres, les prix TTC, les exonérations, l'autoliquidation et les identifiants fiscaux des clients. Cinq paramètres déterminent le comportement de Tax pour votre compte. Deux règles propres au client peuvent modifier le résultat d'un paiement donné. Cette page les présente tous. ## Vos paramètres - `enabled` (boolean, default `false`): Indique si une ligne est enregistrée pour chaque paiement encaissé. Lorsque ce paramètre est désactivé, rien n'est écrit ni rétroactif. Les paiements encaissés pendant cette période restent définitivement absents du registre. - `inclusive` (boolean, default `false`): Indique si les montants débités comprennent déjà la taxe. La valeur false signifie que la taxe est calculée en plus du montant. - `default_country` (string): Code à deux lettres. Utilisé lorsque le pays du payeur n'a pas pu être déterminé et comme pays de comparaison pour l'autoliquidation. La valeur par défaut est le pays de votre compte, puis CM. - `tax_id_type` (string, required): Type d'immatriculation que vous possédez, par exemple cm.niu, ci.ifu, ke.pin ou eu.vat. Enregistré tel quel. - `registration_number` (string, required): Votre propre numéro, jamais présenté à vos payeurs par Wajub. À l'activation, il doit respecter le format de tax_id_type, sinon l'appel répond 422. Une différence doit être connue pour automatiser cette configuration : vous écrivez `registration_number`, mais vous relisez `tax_registration_number`. Les quatre autres champs conservent leur nom dans les deux sens. > [!NOTE] > **Votre propre immatriculation est enregistrée, mais pas utilisée** > > Aucun de ces deux champs ne modifie un calcul. Ils permettent à votre compte de porter l'identité > utilisée pour vos déclarations. Le taux d'un paiement ne dépend jamais de votre identité, mais > uniquement de l'emplacement du payeur. ## Prix TTC ou hors taxe L'interrupteur détermine lequel des deux nombres est déjà connu. **Hors taxe**, le comportement par défaut. Votre montant constitue la base. `tax = amount × rate` et le client doit `amount + tax`. Sur 10 000 XAF à 19,25 %, la taxe est de 1 925 XAF et le total de 11 925 XAF. **TTC.** Votre montant constitue le total. `base = amount ÷ (1 + rate)` et la taxe correspond au reste. Sur 10 000 XAF à 19,25 %, la base est de 8 386 XAF et la taxe de 1 614 XAF. Le client paie toujours 10 000 XAF. Ce choix décrit vos prix, pas un paiement particulier. Choisissez celui qui correspond à la façon dont vous annoncez vos tarifs, puis conservez-le. Une modification change la signification de tous les futurs enregistrements, sans recalculer le passé. Le réglage s'applique aux enregistrements écrits sur vos paiements. `POST /tax/calculate` ne le lit pas : envoyez `tax_inclusive: true` dans la requête pour un calcul TTC, sinon le calcul est hors taxe. ## Arrondis La taxe est arrondie selon la précision propre à la devise, pas systématiquement à deux décimales. Le XAF, le XOF, le RWF, l'UGX, le KMF, le GNF, le BIF, le DJF, le JPY, le KRW et les autres devises sans décimales sont arrondis à l'unité. Le KWD, le BHD, l'OMR, le JOD et le TND sont arrondis à trois décimales. Toutes les autres utilisent deux décimales. Un calcul en XAF ne contient donc jamais de centimes. Un même taux de 19,25 % sur un même montant produit une présentation différente en EUR. ## Pays dont provient le taux Pour un **paiement enregistré**, trois étapes s'appliquent dans cet ordre : le pays déterminé depuis l'adresse IP du payeur à l'ouverture de la page de paiement, votre `default_country`, puis `CM`. Pour **`POST /tax/calculate`**, une seule étape s'applique : le `country` envoyé. Ce champ est obligatoire et aucune autre valeur ne le remplace. La devise n'est jamais consultée. Un payeur situé en France qui vous paie en XAF est soumis à la TVA française de 20 %, car la taxe dépend du lieu de consommation du service. ## Clients exonérés Un calcul contient `customer_exempt`, qui vaut `false` aujourd'hui : aucun client ne peut être marqué exonéré. Pour un taux nul sur un client professionnel, passez par l'autoliquidation ci-dessous. ## Autoliquidation Lorsqu'elle s'applique, la taxe est nulle et la réponse contient `reverse_charge: true`. Votre client doit la payer dans son propre pays au lieu de vous la verser. Trois conditions doivent toutes être remplies. | Condition | Vérification | | ---------------------------------------- | ------------------------------------------------------------ | | Le client est une entreprise | Son `type` est `business`, pas un particulier | | Il possède un identifiant fiscal vérifié | Au moins un de ses identifiants fiscaux a atteint `verified` | | Le paiement vient d'un autre pays | Le pays du calcul diffère de votre `default_country` | Le pays du calcul est celui dont provient le taux : le `country` envoyé à `POST /tax/calculate` ou, sur un paiement enregistré, le pays du payeur résolu à l'ouverture de la page de paiement. Le pays propre du client n'est pas lu. Une entreprise étrangère qui vous paie depuis votre propre pays est taxée comme n'importe qui d'autre dans ce pays. Aucun autre élément n'est examiné. La zone économique ne constitue notamment pas une condition. Un marchand camerounais payé par une entreprise vérifiée depuis le Sénégal, l'Allemagne ou le Japon obtient la même autoliquidation. Un paiement venu du Cameroun ne l'obtient pas. Un identifiant fiscal ne mène jamais qu'à l'autoliquidation, jamais à une exonération. Les conditions sont lues pendant le calcul. Un identifiant fiscal encore en cours de vérification produit donc un résultat normalement taxé. Enregistrez d'abord l'identifiant, attendez sa vérification, puis effectuez le calcul. ## Identifiants fiscaux des clients Un identifiant fiscal appartient à un client et est enregistré une seule fois, séparément de tous les paiements. `POST /customers/{customer_id}/tax_ids` Le `type` détermine la méthode de vérification. Utilisez donc sa valeur réelle plutôt qu'un terme générique. ```bash title="Enregistrer le NIU d'un client" curl https://api.wajub.com/customers/cus_sAaim5apjocIgtlhzJY3wQ8s/tax_ids \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "type": "cm.niu", "value": "M071512345678A", "country_code": "CM" }' ``` L'appel renvoie immédiatement `verification_status: "pending"`, puis la vérification s'exécute en arrière-plan. Aucun webhook ne lui est associé. Relisez l'identifiant fiscal lorsque vous avez besoin de connaître le résultat. Ces routes se trouvent sous `/customers` : une clé restreinte a besoin de `customer.read` et `customer.write`, pas des permissions fiscales. Le numéro d'un client est vérifié selon la même liste de formats que votre propre numéro d'immatriculation. | Type | Format vérifié | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cm.niu` | Une lettre, douze chiffres, une lettre | | `ci.ifu` | Treize chiffres | | `sn.ninea` | Huit chiffres, une lettre, un chiffre | | `ke.pin` | Une lettre, neuf chiffres, une lettre | | `ng.tin` | Huit chiffres, un tiret et quatre chiffres | | `gh.tin` | Pour une entreprise, `C`, `G`, `P`, `Q` ou `V`, puis `00` et huit chiffres (`C0001234567`). Pour un particulier, le PIN de sa Ghana Card : trois lettres, huit ou neuf chiffres et un caractère de contrôle (`GHA-123456789-0`) | | `gh.vat` | Le même numéro que `gh.tin`, sous lequel le Ghana déclare la TVA | | `za_vat` | `4`, puis neuf chiffres | | `gb.vat` | `GB`, puis neuf chiffres | | `us.ein` | Deux chiffres, un tiret et sept chiffres | | `au_abn` | Onze chiffres | | `eu.vat` | Le format de l'État membre que désigne son préfixe : `DE` puis neuf chiffres, `FR` puis deux lettres ou chiffres et neuf chiffres, et ainsi de suite. La Grèce est `EL` | Un numéro est accepté avec ou sans les espaces, tirets, points et barres obliques que son format comporte : `12-3456789` et `123456789` sont le même EIN. Ajouter de nouveau le même type et le même numéro ne crée pas de copie : l'appel répond `200` avec l'entrée existante, repassée à `pending` le temps d'une nouvelle vérification. Quatre statuts sont possibles. | Statut | Signification | | ------------- | ------------------------------------------------------------------------------- | | `pending` | Pas encore vérifié | | `verified` | La vérification a réussi. Seul ce statut permet l'autoliquidation | | `failed` | Le format est incorrect ou le registre considère le numéro comme invalide | | `unavailable` | Le registre était inaccessible. Réessayez en ajoutant de nouveau le même numéro | > [!NOTE] > **Seule la TVA européenne est vérifiée dans un registre** > > Un numéro `eu.vat` est vérifié dans le registre officiel de TVA de l'Union européenne. Les autres > types sont contrôlés sur leur format uniquement : Wajub ne confirme pas que le numéro est > enregistré, vérifiez-le vous-même avant de compter sur l'autoliquidation. ## Codes fiscaux des produits Un code fiscal indique ce que vous vendez afin qu'une juridiction puisse appliquer un taux différent de son taux normal. Envoyez-en un pendant un calcul, ou placez `tax_code` dans les `metadata` d'un paiement pour que l'enregistrement le reprenne. ```bash title="Calculer avec un code fiscal" curl https://api.wajub.com/tax/calculate \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 10000, "currency": "XAF", "country": "CM", "tax_code": "txcd_10103001" }' ``` Deux comportements doivent être connus avant d'utiliser un code. `txcd_00000000` désigne les produits non taxables. Lorsqu'il existe dans le catalogue, il impose un taux nul dans tous les pays. Un code sans taux dans le catalogue utilise silencieusement le taux normal du pays. La réponse répète tout de même le code, ce qui donne l'impression qu'il a été appliqué. > [!WARNING] > **Consultez le catalogue avant d'utiliser un code** > > `GET /tax/codes` est la seule référence indiquant les codes existants et les pays qui possèdent un > taux pour chacun. `GET /tax/codes/{code}` présente les taux du code pays par pays. Un code absent > ne produit aucune erreur, mais le taux normal. Consultez le catalogue au lieu de supposer qu'un > code provenant d'un autre prestataire possède une correspondance. Un code fiscal est également entièrement ignoré lorsque l'autoliquidation s'applique. ## Taux infranationaux Certains pays appliquent les taxes au niveau d'un État, d'un comté ou d'une ville plutôt qu'au niveau national. `GET /tax/jurisdictions` répertorie les données conservées par Wajub. Elles peuvent être filtrées par pays, État et niveau. Chaque entrée contient son taux et indique s'il se cumule avec les précédents. Un paiement est enregistré au taux normal du pays, celui que renvoie `POST /tax/calculate`. Un paiement ne porte ni État ni ville : les taux infranationaux sont répertoriés mais pas appliqués. ## Vos lieux d'immatriculation `/tax/registrations` conserve la liste des juridictions où vous êtes immatriculé, avec un type parmi `standard`, `simplified`, `ioss` et `oss`, votre numéro et les dates de validité. Cette liste facilite vos déclarations, mais ne constitue pas un interrupteur. Aucun calcul ni enregistrement ne la consulte. L'ajout d'une immatriculation ne modifie jamais un taux et sa suppression n'arrête aucun enregistrement. La suppression révoque l'entrée au lieu de l'effacer : l'entrée est conservée comme `revoked` dans votre historique. Il existe une entrée par pays et par État : enregistrer de nouveau le même pays et le même État répond `422`, entrée révoquée comprise. Réactivez-la avec `PUT` et `status: "active"`. - [Taxes](https://docs.wajub.com/fr/tax): Ce qui est calculé, ce qui est enregistré et ce qui n'est jamais débité. - [Démarrage rapide](https://docs.wajub.com/fr/tax/quickstart): Activer Tax, calculer, débiter et consulter le premier rapport. - [Rapports fiscaux](https://docs.wajub.com/fr/tax/reporting): Le registre, les remboursements, l'exportation et les éléments absents. - [Numéros fiscaux des clients](https://docs.wajub.com/fr/payments/customers/manage#tax-ids): Ajouter un numéro fiscal à un client entreprise, et suivre sa vérification. --- # Taxes URL: https://docs.wajub.com/fr/tax > Ce que Wajub calcule, ce qu'il enregistre et ce qu'il ne modifie jamais dans le montant. Tax vous indique le montant de la taxe due sur une somme dans un pays, et tient un registre de la taxe de chaque paiement encaissé, qui vous sert à établir vos déclarations. Il ne modifie jamais le montant débité au payeur. > [!CAUTION] > **La taxe n'est jamais ajoutée au montant débité** > > Votre client paie le montant défini lors de la création du paiement, plus les frais de plateforme > si vous les lui répercutez. La taxe n'y est pas ajoutée. Si votre prix doit comprendre la taxe, > vous devez définir vous-même le total : demandez d'abord le calcul de la taxe, puis créez le > paiement avec la somme obtenue. Wajub enregistrera la taxe dans les deux cas, selon le montant > réellement débité. Trois opérations entourent un paiement. Une seule déplace de l'argent. ## Deux opérations sur deux calendriers Tous les éléments de cette section appartiennent à l'une ou l'autre. Les confondre est à l'origine de la plupart des questions. | | Calcul | Enregistrement | | ------------------------ | ----------------------------------- | ---------------------------------------------------- | | Nature | La réponse à une question | Une ligne de votre registre fiscal | | Moment | À votre demande, avant le débit | Automatiquement, après le crédit des fonds | | Déclencheur | `POST /tax/calculate` | La fin du paiement | | Dépend de vos paramètres | Non, sauf pour les règles du client | Oui, rien n'est enregistré lorsque Tax est désactivé | | Modifie le paiement | Jamais | Jamais | Le calcul est une calculatrice. L'enregistrement est une opération comptable. Vous pouvez utiliser l'un sans l'autre : demander des calculs sans jamais activer Tax, ou activer Tax sans jamais appeler l'endpoint. ## Pays d'application de la taxe Tax suit le principe de consommation : le taux appliqué est celui du payeur, pas le vôtre. Trois étapes le déterminent dans cet ordre. | Étape | Source | | ----- | ----------------------------------------------------------------------------- | | 1 | Le pays déduit de l'adresse IP du payeur à l'ouverture de la page de paiement | | 2 | Votre paramètre `default_country` | | 3 | `CM`, le pays d'origine de la plateforme | La devise ne détermine jamais le pays. Le XAF est utilisé dans six pays et un payeur à Paris peut vous payer en XAF depuis une adresse IP française. Le taux français s'applique alors. Avec `POST /tax/calculate`, aucune déduction n'a lieu. Le champ `country` est obligatoire et constitue la seule information utilisée. > [!WARNING] > **La première étape a lieu uniquement sur la page hébergée** > > Le pays du payeur est déterminé à l'ouverture du checkout hébergé. Un paiement entièrement débité > depuis votre serveur, sans passage du payeur sur une page Wajub, ne contient aucun pays. Tous ses > enregistrements utilisent donc votre `default_country`. Si votre propre interface encaisse dans > plusieurs pays, définissez `default_country` sur le pays principal et rapprochez les autres à > partir de vos propres données. ## Contenu d'un enregistrement Une ligne est créée par paiement encaissé, dans la devise du paiement. | Champ | Contenu | | ---------------- | --------------------------------------------------------------------------- | | `country_code` | Le pays dont le taux a été appliqué | | `tax_name` | Le nom local de la taxe : `TVA`, `VAT`, `IVA`, `GST` | | `rate` | Le pourcentage appliqué | | `taxable_amount` | La base à laquelle le taux a été appliqué | | `tax_amount` | La taxe elle-même | | `tax_inclusive` | Indique si la base a été extraite du montant ou ajoutée à celui-ci | | `charged_at` | Le moment où le paiement a été crédité, utilisé pour regrouper les rapports | Un remboursement écrit une deuxième ligne avec les deux montants négatifs. Le registre calcule donc automatiquement le montant net. Consultez [Rapports fiscaux](https://docs.wajub.com/fr/tax/reporting). ## Couverture Deux cents pays possèdent un taux normal, maintenu par Wajub et mis à jour sans intervention de votre part. | Pays | Taxe | Taux | | -------------- | ---- | ------- | | Cameroun | TVA | 19,25 % | | Côte d'Ivoire | TVA | 18 % | | Sénégal | TVA | 18 % | | Kenya | VAT | 16 % | | Ghana | VAT | 15 % | | Afrique du Sud | VAT | 15 % | | Nigeria | VAT | 7,5 % | | France | TVA | 20 % | Seize pays ont un taux de 0 %, soit parce qu'ils ne prélèvent aucune taxe de ce type, soit parce que leur système ne possède aucun taux national unique. Les États-Unis en font partie. La taxe sur les ventes y est définie par État et par ville, ce que Wajub ne détermine pas. > [!NOTE] > **Un taux normal par pays** > > Il n'existe actuellement aucun taux réduit, aucun taux réellement appliqué par produit et aucun > taux propre à un État ou à une ville. Quel que soit le pays, le calcul applique son unique taux > normal. [Configuration fiscale](https://docs.wajub.com/fr/tax/configuration) décrit les deux exceptions qui modifient le > résultat : un client exonéré et l'autoliquidation. ## Uniquement en live et selon le plan Tax est disponible avec **Growth**, **Scale** et **Enterprise**, ainsi que sous forme d'option payante avec les plans inférieurs. Sans le plan ni l'option, les endpoints `/tax` répondent `403` avec `error_code: feature_not_in_plan`, et plus aucun enregistrement n'est écrit sur vos paiements, même si `enabled` vaut encore `true` : un changement de plan ou une option qui prend fin arrête le registre à ce moment-là. Ce qui a été enregistré auparavant reste tel quel, consultable dans le Dashboard, et le remboursement de l'un de ces paiements écrit toujours sa ligne négative. Rien ne s'exécute dans la sandbox. Aucun enregistrement n'est créé pour un paiement de test et les endpoints refusent une clé de test. Vous ne pouvez donc pas simuler un exercice fiscal. Dans le Dashboard, la section **Taxe** nécessite l'autorisation `view_tax`. La modification des paramètres nécessite `manage_tax`. Les transactions d'approvisionnement de votre propre solde Wajub ne produisent jamais d'enregistrement. Le déplacement de votre propre argent n'est pas soumis à la TVA. ## Les endpoints Ils nécessitent tous votre clé privée et sont réservés au mode live. | Méthode | Endpoint | Utilisation | | --------------------------- | ------------------------------------- | ----------------------------------------------------------------- | | `GET` `PUT` | [`/tax/settings`](https://docs.wajub.com/fr/api/tax) | L'interrupteur, votre pays, les prix TTC et votre immatriculation | | `POST` | [`/tax/calculate`](https://docs.wajub.com/fr/api/tax) | La taxe due sur un montant avant son débit | | `GET` | [`/tax/rates`](https://docs.wajub.com/fr/api/tax) | Le taux normal de chaque pays | | `GET` | [`/tax/reports`](https://docs.wajub.com/fr/api/tax) | Le registre, regroupé par pays et par devise | | `GET` | [`/tax/codes`](https://docs.wajub.com/fr/api/tax) | Le catalogue des codes fiscaux des produits | | `GET` | [`/tax/jurisdictions`](https://docs.wajub.com/fr/api/tax) | Les taux infranationaux lorsqu'ils existent | | `GET` `POST` `PUT` `DELETE` | [`/tax/registrations`](https://docs.wajub.com/fr/api/tax) | Les pays où vous êtes immatriculé, pour vos propres dossiers | | `GET` | [`/tax/thresholds`](https://docs.wajub.com/fr/api/tax) | Les seuils d'immatriculation et votre progression | | `GET` `POST` `DELETE` | [`/customers/{id}/tax_ids`](https://docs.wajub.com/fr/api/tax) | Les identifiants fiscaux d'un client et leur vérification | - [Démarrage rapide](https://docs.wajub.com/fr/tax/quickstart): Activer Tax, calculer, débiter et consulter le premier rapport. - [Configuration fiscale](https://docs.wajub.com/fr/tax/configuration): Les paramètres, les prix TTC, les exonérations et l'autoliquidation. - [Rapports fiscaux](https://docs.wajub.com/fr/tax/reporting): Le registre, les remboursements, l'exportation et les éléments absents. - [Factures](https://docs.wajub.com/fr/billing/invoice): L'emplacement où une ligne de taxe apparaît sur le document. --- # Démarrage rapide URL: https://docs.wajub.com/fr/tax/quickstart > Activez Tax, calculez la taxe, débitez-la et consultez le premier rapport. Cinq étapes sont nécessaires. La troisième est souvent oubliée. Wajub calcule et enregistre la taxe, mais son prélèvement vous revient. Le montant défini lors de la création du paiement est celui que votre client paie. > [!WARNING] > **Rien ne fonctionne dans la sandbox** > > Les endpoints Tax refusent une clé de test et un paiement dans la sandbox ne produit aucun > enregistrement. Le premier chiffre observé proviendra d'un paiement réel. Commencez donc par un > petit paiement à vous-même. ## 1. Activer Tax Aucun enregistrement n'est créé avant l'activation. Celle-ci nécessite la déclaration de votre propre immatriculation fiscale. Les deux champs deviennent obligatoires dès que `enabled` vaut `true`, et aucun ne possède de valeur par défaut. ```bash title="Activer l'enregistrement fiscal" curl -X PUT https://api.wajub.com/tax/settings \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "enabled": true, "inclusive": true, "default_country": "CM", "tax_id_type": "cm.niu", "registration_number": "M071512345678A" }' ``` `inclusive` indique si le montant pour lequel vous créez un paiement comprend déjà la taxe. Il vaut `true` ici parce que l'étape 3 débite le total, taxe comprise : lorsque le paiement est crédité, Wajub extrait la taxe du montant débité. Laissez-le sur `false` uniquement si vous débitez le prix hors taxe sans rien y ajouter : Wajub calcule alors la taxe en plus du montant débité, et débiter le total avec `false` enregistre une taxe sur la taxe. Le même interrupteur se trouve sous **Taxe, Paramètres** dans le Dashboard. `registration_number` est contrôlé selon le format de `tax_id_type` : un NIU camerounais compte une lettre, douze chiffres et une lettre, et toute autre valeur répond `422`. ## 2. Demander le montant dû Le pays est obligatoire. Cet endpoint ne le déduit ni du numéro de téléphone, ni de l'adresse IP, ni de la devise. Votre `default_country` n'est pas utilisé comme valeur de repli. ```bash title="Calculer" curl https://api.wajub.com/tax/calculate \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 10000, "currency": "XAF", "country": "CM" }' ``` La réponse contient tout le calcul. Vous n'avez jamais besoin de le refaire. ```json title="Réponse · 200 OK" { "code": 200, "status": "OK", "calculation": { "amount": 10000, "tax_amount": 1925, "taxable_amount": 10000, "total": 11925, "rate": 19.25, "tax_name": "TVA", "country_code": "CM", "currency": "XAF", "tax_inclusive": false, "tax_code": null, "customer_exempt": false, "reverse_charge": false } } ``` `total` est le montant à débiter. Dans un calcul hors taxe, il correspond à `amount + tax_amount`. Dans un calcul TTC, il correspond à l'`amount` envoyé sans modification, et `taxable_amount` est le montant restant après l'extraction de la taxe. Ce calcul ne lit pas votre réglage `inclusive`. Il est hors taxe sauf si vous envoyez `tax_inclusive: true`, et c'est bien un calcul hors taxe qu'il faut ici : 10 000 XAF est votre prix hors taxe, et la question est ce qu'il faut y ajouter. Le réglage décrit autre chose : le montant que vous débitez à l'étape suivante. ## 3. Débiter vous-même le total Vous n'envoyez aucune taxe à la création d'un paiement. Créez-le avec le montant renvoyé par le calcul. **Créer le paiement avec le total** ```bash curl https://api.wajub.com/payments \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 11925, "currency": "XAF", "email": "client@example.com" }' ``` ```javascript const { calculation } = await wajub.tax.calculate({ amount: 10000, currency: 'XAF', country: 'CM', }); const payment = await wajub.payments.create({ amount: calculation.total, currency: 'XAF', email: 'client@example.com', }); ``` ```python calculation = wajub.tax.calculate({ "amount": 10000, "currency": "XAF", "country": "CM", })["calculation"] payment = wajub.payments.create({ "amount": calculation["total"], "currency": "XAF", "email": "client@example.com", }) ``` ```php $calculation = $wajub->tax->calculate([ 'amount' => 10000, 'currency' => 'XAF', 'country' => 'CM', ])->calculation; $payment = $wajub->payments->create([ 'amount' => $calculation->total, 'currency' => 'XAF', 'email' => 'client@example.com', ]); ``` ```go calc, err := client.Tax.Calculate(context.Background(), map[string]any{ "amount": 10000, "currency": "XAF", "country": "CM", }) payment, err := client.Payments.Create(context.Background(), map[string]any{ "amount": calc.Calculation.Total, "currency": "XAF", "email": "client@example.com", }, nil) ``` Le montant débité et ce que `inclusive` en dit doivent concorder. À 19,25 %, pour un prix de 10 000 XAF hors taxe : | Vous créez le paiement pour | `inclusive` | Ce qui est enregistré | | --------------------------- | ----------- | ------------------------------------------------------------------------------------------------ | | 11 925, le total | `true` | 1 925 de taxe sur une base de 10 000. C'est ce que fait ce démarrage rapide | | 10 000, le prix hors taxe | `false` | 1 925 de taxe sur une base de 10 000. Vous n'en avez rien encaissé et la prélevez sur les 10 000 | | 11 925, le total | `false` | 2 296 de taxe sur une base de 11 925 : une taxe sur la taxe | | 10 000, le prix hors taxe | `true` | 1 614 de taxe sur une base de 8 386 : votre prix lu comme s'il comprenait la taxe | Les deux premières lignes sont les deux façons qui fonctionnent. Les deux dernières sont les erreurs, et rien ne les empêche : le paiement passe dans tous les cas, seul l'enregistrement est faux. Si vous ignorez cette étape, rien ne casse non plus. Avec les réglages ci-dessus, le paiement de 10 000 XAF est traité et l'enregistrement est celui de la dernière ligne : 1 614 XAF de taxe, prélevés sur ce que vous avez encaissé. ## 4. L'enregistrement est automatique Lorsque le paiement est crédité, Wajub recalcule la taxe à partir de vos paramètres et du pays du payeur, puis écrit une ligne. Vous n'avez rien à faire ni aucun appel à envoyer. Ce second calcul n'est pas celui demandé à l'étape 2. Il utilise le véritable pays du payeur et le montant réellement débité. Les deux résultats peuvent donc différer si le débit concerne un autre pays que celui du calcul. ## 5. Lire les données enregistrées Le rapport regroupe le registre sur une période, par pays et par devise. `GET /tax/reports` Limitez-le au pays et au mois de votre déclaration. La valeur `net_tax` du résumé correspond aux encaissements moins les annulations. C'est le chiffre à déclarer. ```bash title="Mois en cours, Cameroun uniquement" curl "https://api.wajub.com/tax/reports?period=month&country=CM" \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` Les mêmes chiffres sont disponibles sous **Taxe** dans le Dashboard, avec une exportation CSV. [Rapports fiscaux](https://docs.wajub.com/fr/tax/reporting) décrit la structure complète des deux formats. ## Si vous envoyez plutôt des factures Une facture contient une ligne de taxe par article. Son comportement dépend de son origine. | Origine | Comportement de la taxe de la ligne | | ------------ | --------------------------------------------------------------------------------------------------------------- | | Le Dashboard | Lorsque Tax est actif et que la ligne reste en mode automatique, le taux normal du pays est renseigné pour vous | | L'API | Vous définissez vous-même `items[].tax_rate`. Rien n'est renseigné automatiquement | Dans les deux cas, la taxe de l'article est calculée avec le taux de celui-ci. Le total de la facture correspond à la somme des lignes. Le remplissage automatique utilise le pays du client indiqué sur la facture, puis votre `default_country` comme valeur de repli. - [Taxes](https://docs.wajub.com/fr/tax): Ce qui est calculé, ce qui est enregistré et ce qui n'est jamais débité. - [Configuration fiscale](https://docs.wajub.com/fr/tax/configuration): Les prix TTC, les exonérations, l'autoliquidation et les identifiants fiscaux des clients. - [Rapports fiscaux](https://docs.wajub.com/fr/tax/reporting): Le registre, les remboursements, l'exportation et les éléments absents. - [Démarrage rapide](https://docs.wajub.com/fr/billing/invoice/quickstart): Facturer un client avec la ligne de taxe sur le document. --- # Rapports fiscaux URL: https://docs.wajub.com/fr/tax/reporting > Le registre, la déduction des remboursements, l'exportation et les éléments absents. Chaque paiement encaissé produit une ligne et chaque remboursement une ligne négative. Le rapport additionne ce registre sur une période, aux taux appliqués à l'époque. ## Ce qui entre dans le registre Une ligne est créée lorsque le paiement est crédité, pas lors de sa création ou d'une tentative. Quatre situations l'empêchent. | Condition | Résultat | | -------------------------------------------- | ------------------------------------------------------------- | | Tax est désactivé sur votre compte | Aucune ligne et aucun rattrapage après son activation | | Le paiement est effectué dans la sandbox | Aucune ligne | | Le paiement approvisionne votre propre solde | Aucune ligne | | La taxe calculée est nulle | Aucune ligne. Un pays au taux nul ne laisse donc aucune trace | ## Un remboursement écrit une ligne négative Lors du remboursement d'un paiement, le registre annule la taxe dans la même proportion. Le remboursement d'un tiers du montant annule un tiers de la taxe, selon le taux et le pays d'origine, avec les deux montants négatifs. Cette proportion ne peut pas dépasser la totalité. Le remboursement d'un montant supérieur à la base enregistrée annule au maximum 100 % de la taxe. Lorsque le paiement d'origine ne possède aucune ligne, le remboursement n'en écrit pas non plus : aucune taxe n'a été perçue, aucune n'est rendue. C'est le cas d'un paiement encaissé quand Tax était désactivé, d'un client exonéré, d'une vente en autoliquidation et d'un produit à taux zéro. Seule la ligne du paiement décide, pas vos réglages le jour du remboursement. La taxe enregistrée sur un paiement a été perçue : son remboursement en annule la part même après la désactivation de Tax ou quand votre plan ne le couvre plus. À l'inverse, activer Tax plus tard ne donne jamais d'annulation à un paiement sans ligne. Le résultat attendu est disponible au moment de la déclaration : le rapport calcule automatiquement le montant net des encaissements et des annulations. Vous ne soustrayez rien vous-même. ## Le rapport `GET /tax/reports` Cinq paramètres d'URL facultatifs sont disponibles. Les deux filtres limitent tout le payload au lieu de lui ajouter une section. - `period` (enum, default `30d`): 7d, 30d, 90d, month, year ou custom. month désigne le mois civil en cours et year l'année civile en cours. - `start_date` (date): Lu uniquement lorsque period vaut custom. En son absence, la période commence trente jours auparavant. - `end_date` (date): Fin de la période, quelle que soit sa valeur. Par défaut, la fin de la journée en cours. - `country` (string): Code à deux lettres. Limite tout le rapport à un seul pays. - `currency` (string): Code à trois lettres. Limite tout le rapport à une seule devise. La réponse place toutes les données sous `report` et présente trois fois les mêmes chiffres : sous forme de total, par pays et par devise. ```json title="Réponse · 200 OK" { "code": 200, "status": "OK", "report": { "period": "30d", "start_date": "2026-08-13", "end_date": "2026-09-12", "summary": { "total_tax_collected": 808500, "total_taxable_amount": 4200000, "total_reversals": -12300, "net_tax": 796200, "currency": "XAF" }, "by_country": [ { "country_code": "CM", "tax_collected": 808500, "tax_reversed": -12300, "taxable_amount": 4200000, "transactions": 312 } ], "by_currency": [ { "currency": "XAF", "tax_collected": 808500, "tax_reversed": -12300, "taxable_amount": 4200000, "transactions": 312 } ] } } ``` Trois détails sont importants pour le rapprochement avec vos propres comptes. `tax_collected` compte uniquement les lignes positives et `tax_reversed` les lignes négatives. `net_tax` est leur somme et représente le montant à déclarer. `transactions` compte toutes les lignes du groupe, y compris les annulations. Un pays avec trois cents paiements et douze remboursements indique donc 312. Enfin, pour un compte qui utilise plusieurs devises, `summary` n'a de sens qu'après un filtrage sur une `currency`. > [!TIP] > **Déclarez pays par pays et une devise à la fois** > > Vous devez la taxe à une juridiction dans sa propre devise. Utilisez donc un rapport dont les > paramètres `country` et `currency` sont tous deux définis. La section `by_country` d'un rapport > non filtré permet de repérer les pays où vous avez des obligations, pas de remplir une déclaration. ## Le rapport du Dashboard n'est pas le même objet La section **Taxe** du Dashboard additionne les encaissements et les annulations dans un seul chiffre par ligne, et convertit les totaux de plusieurs devises dans votre devise de base. Un mois avec des remboursements y affiche donc un résultat inférieur à `tax_collected` dans l'API. Les deux sont corrects, car ils répondent à des questions légèrement différentes. ## L'exportation CSV Sous **Taxe**, la commande export télécharge la vue actuelle au format CSV séparé par des points-virgules, avec un marqueur UTF-8. Excel l'ouvre donc correctement dans les paramètres régionaux français et portugais, sans étape d'importation. Le fichier contient la période, les totaux, la conversion dans la devise de base lorsque vous en utilisez plusieurs, puis un bloc par pays et par devise. Les exportations sont comptabilisées dans le quota mensuel de votre plan : dix par mois avec **Pay as you go**, puis un nombre illimité à partir de **Growth**. L'API ne propose aucune exportation. ## Seuils d'immatriculation De nombreuses juridictions imposent une immatriculation uniquement après le dépassement d'un seuil de chiffre d'affaires local. `GET /tax/thresholds` répertorie les seuils suivis par Wajub, avec leur montant, leur devise et leur période de mesure. `GET /tax/thresholds/alerts` les compare à votre propre chiffre d'affaires enregistré sur la période propre à chaque seuil (l'année civile, douze mois glissants ou le trimestre). Il renvoie uniquement les éléments qui nécessitent votre attention : `approaching` à partir de 80 % du seuil et `exceeded` à 100 %. Un tableau vide signifie qu'aucun seuil n'est proche. Il est également renvoyé avant l'enregistrement de toute taxe. Votre chiffre d'affaires est converti dans la devise du seuil aux taux de la plateforme avant la comparaison : des ventes en XAF comptent pour un seuil en GBP à leur valeur en livres. Le seuil `EU` additionne vos ventes dans tous les États membres. Un seuil pour lequel votre chiffre d'affaires ne peut pas être converti, faute de taux pour une devise, n'est pas mesuré et ne lève aucune alerte. Un seuil défini pour un État plutôt que pour un pays entier (avec un `state_code`, comme le nexus économique d'un État américain) figure dans `GET /tax/thresholds`, mais n'est jamais renvoyé comme alerte : une ligne fiscale enregistre le pays, pas l'État, et il n'existe donc rien à quoi le comparer. > [!WARNING] > **La comparaison utilise uniquement les données enregistrées par Wajub** > > Votre chiffre d'affaires local correspond ici à la somme des `taxable_amount` des lignes fiscales > positives sur la période du seuil, convertie dans sa devise. Il exclut les revenus encaissés avant > l'activation de Tax et toutes les factures émises en dehors de Wajub. Considérez l'alerte comme une > invitation à vérifier, pas comme un avis juridique. ## Ce que le registre ne contient pas Connaître ces limites vous évite de chercher des exportations inexistantes. **Aucun taux infranational.** Une ligne est écrite au taux normal du pays, celui que donne `POST /tax/calculate` : un paiement ne porte ni État ni ville auxquels appliquer un taux infranational. **Aucun prélèvement Mobile Money ni aucune taxe sur les services numériques.** Les prélèvements Mobile Money et les taxes sur les services numériques ne sont ni enregistrés, ni affichés sur un paiement, ni ajoutés à un montant. Lorsqu'un pays les prélève, ils ne figurent pas dans vos chiffres Wajub. **Une ligne par paiement, rien de plus.** Un paiement live qui a produit un enregistrement le porte dans un objet `tax` sur `GET /payments/{id}` : `amount`, `taxable_amount`, `rate`, `name`, `country` et `inclusive`. Un remboursement porte son annulation de la même façon. Les totaux et les périodes se lisent uniquement par l'endpoint des rapports et le Dashboard. **Aucun webhook.** Aucun événement n'est émis lors de l'écriture ou de l'annulation d'une ligne. > [!CAUTION] > **Vous restez responsable des déclarations** > > Wajub calcule un taux et conserve un registre. Il ne vous immatricule auprès d'aucune autorité, ne > dépose aucune déclaration et ne reverse aucun montant. Ces obligations vous appartiennent. Les > chiffres présentés ici constituent un point de départ pour votre comptable, pas une déclaration. - [Taxes](https://docs.wajub.com/fr/tax): Ce qui est calculé, ce qui est enregistré et ce qui n'est jamais débité. - [Configuration fiscale](https://docs.wajub.com/fr/tax/configuration): Les prix TTC, les exonérations, l'autoliquidation et les identifiants fiscaux des clients. - [Démarrage rapide](https://docs.wajub.com/fr/tax/quickstart): Activer Tax, calculer, débiter et consulter le premier rapport. - [Remboursements](https://docs.wajub.com/fr/payments/refunds): L'opération qui écrit les lignes négatives. --- # Documentation pour les assistants IA URL: https://docs.wajub.com/fr/developer-tools/ai-assistants > La même documentation en Markdown brut, pour ChatGPT, Claude, Cursor et vos propres agents. Un assistant qui lit ces pages en HTML reçoit la navigation, les scripts et la mise en forme avec le texte, et perd les exemples de code dessinés par des composants. Chaque page est donc aussi servie en Markdown brut, et toute la documentation en un seul fichier : vous donnez à l'assistant exactement le texte qu'une personne lit. ## Trois points d'entrée | Adresse | Ce qu'elle contient | Quand l'utiliser | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | [`/llms.txt`](https://docs.wajub.com/llms.txt) | Un plan : chaque page avec son titre, sa description et son adresse, rangée comme dans la navigation ([llmstxt.org](https://llmstxt.org)) | L'assistant va chercher les pages lui-même et doit savoir laquelle lire | | [`/fr/llms-full.txt`](https://docs.wajub.com/fr/llms-full.txt) | Toutes les pages de la documentation, puis la référence de l'API, en Markdown dans un seul fichier. En anglais : [`/llms-full.txt`](https://docs.wajub.com/llms-full.txt) | Vous collez ou envoyez la documentation une fois, ou vous l'indexez dans votre propre outil | | `.md` | Une seule page en Markdown | Vous voulez un sujet dans le contexte, et rien d'autre | Ajoutez `.md` à l'adresse de n'importe quelle page, dans les deux langues et dans la référence de l'API : ```bash title="Une page, en Markdown" curl https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification.md curl https://docs.wajub.com/payments.md curl https://docs.wajub.com/fr/api/transfers/create.md ``` Chaque page HTML annonce aussi sa version Markdown avec ``, pour qu'un robot qui la cherche la trouve. ## Ce que le Markdown garde Le texte est celui de la page, écrit comme une personne l'écrirait à la main : - Les exemples de code sont des blocs délimités avec leur langage, chaque onglet d'un exemple en plusieurs langages compris. - Les encadrés sont des citations qui commencent par `[!NOTE]`, `[!TIP]`, `[!WARNING]` ou `[!CAUTION]`, titre compris. - Les étapes sont une liste numérotée, les tableaux de paramètres une liste de champs avec leur type et leur caractère obligatoire. - Les schémas, comme un cycle de statuts ou une décision de routage, deviennent leurs étapes en toutes lettres. - Les liens sont absolus : ils marchent encore une fois le texte collé ailleurs. Une page de la référence de l'API donne l'endpoint, ses paramètres, les champs du corps, ses réponses et un exemple de réponse, lus dans le même document OpenAPI que la page. Les aperçus interactifs et les illustrations n'ont pas de texte à donner et sont laissés de côté. > [!TIP] > **Écrire une intégration avec un agent de code** > > Donner une page à l'agent lui apporte des faits. Les [Agent Skills](https://docs.wajub.com/fr/developer-tools/cli/skills) > lui donnent les règles qu'il devinerait sinon, comme `event` plutôt que `event.type` ou la > vérification de la signature avant la lecture du corps. Utilisez les deux. ## À garder en tête - Ces fichiers sont reconstruits à chaque déploiement de la documentation. Un assistant qui a gardé `/llms-full.txt` du mois dernier peut décrire une version de l'API qui a changé depuis : faites-le relire plutôt que de garder une copie. - Les produits encore en préversion, pas encore publiés ici, n'y figurent pas non plus. - Un assistant peut se tromper sur ce qu'il a lu. Avant la mise en production, vérifiez son code avec la page d'où il vient et testez-le en [sandbox](https://docs.wajub.com/fr/developer-tools/testing). - [Agent Skills](https://docs.wajub.com/fr/developer-tools/cli/skills): Les règles Wajub, là où votre agent de code les lit. - [Référence de l'API](https://docs.wajub.com/fr/api): Chaque endpoint, avec ses paramètres et ses réponses. - [Tests](https://docs.wajub.com/fr/developer-tools/testing): Vérifiez ce que l'assistant a écrit face à chaque résultat. --- # Outils développeurs URL: https://docs.wajub.com/fr/developer-tools > Recevez des événements, pilotez la sandbox et découvrez ce qui s'est réellement passé. Les outils pour recevoir des événements, joindre votre ordinateur depuis Wajub, produire n'importe quel résultat à la demande et voir ce qu'a réellement fait votre intégration. ## Le chemin le plus court vers une intégration fonctionnelle 1. **Découvrez les informations reçues, puis écrivez le handler** Vérifiez la signature, répondez avec un code `2xx`, puis placez le traitement dans une file. Vous trouverez l'enveloppe, le catalogue et cinq handlers fonctionnels dans [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks). 2. **Recevez un événement réel sur votre ordinateur** `wajub listen --forward-to localhost:3000/webhooks/wajub`. Aucun tunnel, aucun déploiement, et la signature est réelle. L'installation nécessite une seule commande, présentée dans [CLI](https://docs.wajub.com/fr/developer-tools/cli). 3. **Produisez les résultats nécessaires** `wajub trigger payment.failed`, puis le remboursement, puis l'expiration. Lorsqu'un résultat ne peut pas être déclenché par la CLI, un [numéro de test](https://docs.wajub.com/fr/developer-tools/testing) le force. 4. **Consultez le résultat** [Konsole](https://docs.wajub.com/fr/developer-tools/konsole) conserve la requête, l'événement et chaque tentative de livraison, avec le corps renvoyé par votre endpoint. > [!TIP] > **Les deux commandes qui remplacent la majeure partie d'un environnement de test** > > `wajub listen` et `wajub trigger`, dans deux terminaux, créent une boucle complète d'événements > sans déploiement ni téléphone. Tous les autres outils présentés ici accompagnent ces deux commandes. ## Limites de chaque outil Chaque partie de la boucle possède une limite. Chacune a déjà fait perdre une journée à quelqu'un. | Apparence | Réalité | | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Un abonnement à tout couvre tous les événements | Un abonnement `*` ignore les livraisons du cycle de vie Sync | | La CLI peut produire tous les événements | Elle en déclenche huit. Les quarante-neuf autres sont produits en manipulant la ressource | | Le bouton Envoyer un test de Konsole prouve que votre handler fonctionne | Il prouve l'URL, la signature et l'enveloppe. Son `event` vaut `webhook.test` et son `data` est un exemple : le code qui traite un vrai type d'événement ne s'exécute jamais | | Un canal fonctionnel dans la sandbox fonctionne en live | La sandbox accepte tous les opérateurs pour lesquels elle a des numéros de test. En live, seuls les canaux que votre compte peut débiter sont proposés | | Konsole affiche toutes les décisions de routage | Le routage existe uniquement en live. Rien n'est visible dans la sandbox | ## Choisir selon le symptôme | Symptôme | Point de départ | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Je ne connais pas les événements disponibles | [Catalogue des événements](https://docs.wajub.com/fr/developer-tools/webhooks/events) | | La vérification de ma signature échoue toujours | [Vérification de signature](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification) | | Mon endpoint n'est pas accessible depuis Internet | [`wajub listen`](https://docs.wajub.com/fr/developer-tools/cli/listen) | | J'ai immédiatement besoin d'un paiement échoué | [`wajub trigger`](https://docs.wajub.com/fr/developer-tools/cli/triggers) | | L'API a renvoyé une réponse que je ne comprends pas | [Journaux API](https://docs.wajub.com/fr/developer-tools/konsole/log-explorer) | | L'événement a été émis, mais mon handler ne s'est jamais exécuté | [Livraisons de webhooks](https://docs.wajub.com/fr/developer-tools/konsole/webhook-tester) | | Le paiement a utilisé le mauvais prestataire | [Routage](https://docs.wajub.com/fr/developer-tools/konsole/routing-log) | | Je veux que mon agent écrive correctement l'intégration | [Skills pour agents](https://docs.wajub.com/fr/developer-tools/cli/skills) | - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): L'enveloppe, la signature, les nouvelles tentatives et le catalogue. - [CLI Wajub](https://docs.wajub.com/fr/developer-tools/cli): Quatre-vingt-onze commandes, dont vous utiliserez environ huit. - [Konsole](https://docs.wajub.com/fr/developer-tools/konsole): Ce qu'a réellement fait votre intégration. - [Tests](https://docs.wajub.com/fr/developer-tools/testing): Tous les résultats à la demande, avant qu'un véritable payeur ne les rencontre. --- # Utilisation avancée URL: https://docs.wajub.com/fr/developer-tools/cli/advanced > La CLI dans la CI, dans les scripts et quand un problème survient. Tout ce qui suit montre la CLI en train d'effectuer des tâches que vous feriez autrement à la main : vérifier qu'un déploiement fonctionne, produire un rapport ou vous indiquer quelle partie de votre configuration pose problème. ## Dans un pipeline Il n'y a pas de navigateur dans la CI. La clé provient donc de l'environnement. Chaque commande lit `WAJUB_API_KEY`, et quand elle est définie, elle l'emporte sur tous les profils, `--profile` compris. ```bash title="Un test rapide après le déploiement" #!/usr/bin/env bash set -euo pipefail export WAJUB_API_KEY="$WAJUB_SANDBOX_KEY" # from your CI secret store # Fail the job if the key, the network or the account is wrong wajub doctor --json > doctor.json # Fail the job if the webhook endpoint disappeared wajub webhooks list --json \ | jq -e '.items[] | select(.url == "https://example.com/webhooks/wajub")' > /dev/null ``` L'option `--json` rend la sortie de chaque commande exploitable, et `jq -e` transforme « aucun résultat » en code de sortie différent de zéro. C'est ce qui fait réellement échouer l'étape. > [!CAUTION] > **Une clé live dans la CI est une clé live dans vos logs** > > Utilisez une clé de sandbox pour tout ce qui s'exécute à chaque push. Réservez une clé live à une tâche volontaire et protégée. Ne l'affichez jamais, même masquée. ### Codes de sortie et exécutions sans terminal Une étape échoue selon le code de sortie : voici ce que renvoie la CLI. | Code | Quand | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | La commande a fait ce qui lui était demandé | | `1` | Tout échec : une erreur de l'API, une vérification de `wajub doctor`, une confirmation qui n'a pas pu être demandée, et un `wajub trigger` dont le scénario ne s'est pas terminé comme prévu | | `2` | La ligne de commande elle-même est fausse : une option inconnue, un argument manquant ou en trop, une valeur hors de la liste qu'accepte une option. Rien n'est envoyé à l'API, et l'erreur se termine par `See more help with --help` | | `127` | La commande n'existe pas, comme le « command not found » d'un shell. La CLI propose la plus proche et ne l'exécute jamais à votre place | Un pipeline n'a pas de terminal : la CLI ne peut rien y demander. Une commande qui demanderait une confirmation (une suppression, un paiement, un transfert ou un remboursement avec une clé live, `wajub logout`) échoue avec le code `1` sauf si vous passez `--yes`. `wajub skills install` exige `--scope`. Une saisie masquée de clé (`wajub config set`, `wajub login --manual`) échoue aussi : définissez plutôt `WAJUB_API_KEY`. ## Rapports depuis le terminal Les commandes de liste associées à `jq` remplacent de nombreux petits scripts. ```bash title="Deux rapports utiles" # Yesterday's failures, with the reason wajub payments list --status failed -f date_from=2026-01-14 -f date_to=2026-01-14 -f per_page=100 --json \ | jq -r '.items[] | [.created_at, .id, .amount, .currency, .failure_reason] | @tsv' # Payouts still not settled wajub transfers list --status processing --json \ | jq -r '.items[] | [.id, .amount, .currency, .created_at] | @tsv' ``` Les dates passent par `-f date_from` et `-f date_to`, que seuls les paiements, les remboursements et les litiges acceptent. Elles couvrent des journées calendaires entières. Pour une période plus courte, filtrez les horodatages dans `jq` après avoir récupéré la journée. ## Variables d'environnement Chaque variable ci-dessous s'applique à toutes les commandes. Quand une option fait le même travail, l'option l'emporte : `--api-key` sur `WAJUB_API_KEY`, `--profile` sur `WAJUB_PROFILE`. `--profile` ne l'emporte pas sur `WAJUB_API_KEY` en revanche : un profil ne fournit la clé que si rien d'autre ne la donne. La CLI utilise la première clé qu'elle trouve, dans cet ordre : 1. `--api-key` 2. `WAJUB_API_KEY` 3. La clé du profil désigné par `--profile`, sinon par `WAJUB_PROFILE`, sinon le profil par défaut | Variable | Effet | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WAJUB_API_KEY` | La clé à utiliser. L'emporte sur tous les profils, `--profile` compris. Seule `--api-key` l'emporte sur elle | | `WAJUB_PROFILE` | Le profil à utiliser quand aucun `--profile` n'est passé | | `WAJUB_MAX_RETRIES` | Le nombre de nouvelles tentatives après une requête en échec. `0` les désactive | | `WAJUB_TIMEOUT_MS` | La durée maximale d'une requête, en millisecondes, avant qu'elle échoue avec `Network Error` | | `WAJUB_NO_SKILLS` | `1` empêche la CLI d'installer d'elle-même les [Skills pour agents](https://docs.wajub.com/fr/developer-tools/cli/skills) | | `WAJUB_NO_LOGO` | `1` masque le logo Wajub au-dessus de `wajub`, `wajub help`, `wajub version` et `wajub doctor`. Il n'apparaît de toute façon jamais dans un pipe ni avec `--json` | ## Autocomplétion du shell ```bash title="Installer l'autocomplétion pour votre shell" wajub completion install ``` TAB complète alors les commandes, les options et leurs valeurs : les statuts qu'accepte `--status` sur chaque commande `list`, les types d'événements et les jokers `payment.*` de `wajub listen --events` (l'un après l'autre, séparés par des virgules), les événements de `wajub trigger`, vos profils pour `--profile` et `wajub config use`, et les chemins de l'API pour `wajub get`, `post` et `delete`. Cela fonctionne dans bash (3.2 et suivants, y compris celui de macOS), zsh, fish et PowerShell. La commande détecte votre shell, ou prend `--shell bash|zsh|fish|powershell`. Elle ajoute un bloc, entre des marqueurs `# >>> wajub completion >>>`, à `~/.zshrc`, `~/.bashrc` (`~/.bash_profile` sous macOS) ou `$PROFILE` ; pour fish, elle écrit `~/.config/fish/completions/wajub.fish`. Ouvrez un nouveau terminal, c'est tout. ```bash title="Vérifier ou retirer" wajub completion # quels shells l'ont, et où wajub completion zsh # les lignes à ajouter vous-même, si vous gérez vos dotfiles à la main wajub completion uninstall # retire le bloc, le fichier fish et les scripts ``` ## Partir d'un exemple fonctionnel ```bash title="wajub samples" $ wajub samples --list Available samples: webhooks Minimal webhook receiver with signature verification (Node.js, no dependencies) quickstart-node Create a sandbox payment and verify its webhooks with the Node.js SDK quickstart-php Create a sandbox payment and verify its webhooks with the PHP SDK quickstart-python Create a sandbox payment and verify its webhooks with the Python SDK quickstart-ruby Create a sandbox payment and verify its webhooks with the Ruby SDK quickstart-go Create a sandbox payment and verify its webhooks with the Go SDK quickstart-dotnet Create a sandbox payment and verify its webhooks with the .NET SDK $ wajub samples webhooks my-receiver $ wajub samples quickstart-go ``` L'exemple de webhook ne contient volontairement aucune dépendance. Vous pouvez ainsi lire toute la vérification dans un seul fichier, sans passer par un framework. Les exemples de démarrage font le même travail avec les SDK officiels Node.js, PHP, Python, Ruby, Go et .NET, avec en plus un paiement sandbox à régler : voir [Exemples](https://docs.wajub.com/fr/libraries/sdks/examples). ## Accéder au Dashboard ```bash title="wajub open" wajub open # the dashboard home wajub open payments wajub open keys ``` Les pages reconnues sont `balance`, `customers`, `dashboard`, `disputes`, `keys`, `payments`, `refunds`, `settings`, `transfers` et `webhooks`. ## Quand un problème survient Trois commandes, dans l'ordre croissant du niveau de détail fourni. ```bash title="De la plus rapide à la plus complète" $ wajub version @wajub/cli/1.8.0 darwin-arm64 node-v22.11.0 $ wajub status ● Wajub API is reachable — https://api.wajub.com (HTTP 200) $ wajub doctor Wajub CLI diagnostics ✓ Config 2 profile(s), default: sandbox ✓ Credentials key=sk_test.… env=sandbox base=https://api.wajub.com source=profile … ``` `status` répond à la question « le problème vient-il de chez eux ou de chez moi ? » sans demander d'identifiants. `doctor` indique quelle partie de votre configuration pose problème, une ligne par contrôle, et termine par un identifiant de requête à transmettre au support. | Symptôme | Vérification probable | | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `401` pour chaque commande | Les identifiants et le champ `source` affiché à côté | | Les commandes ciblent le mauvais compte | `source=env`, une variable `WAJUB_API_KEY` restée exportée | | Une commande n'existe pas | `wajub help`, et rappelez-vous que les sujets utilisent une espace | | Rien n'arrive dans `wajub listen` | Les identifiants, et si le profil utilise la sandbox ou le mode live | | Une stack trace apparaît au démarrage | La version de Node, la version minimale est 22 | | `wajub login` vous demande de le relancer | Personne ne l'a approuvé dans les 15 minutes que dure une demande | | La page d'approbation indique qu'un administrateur ou un développeur doit approuver | Votre rôle ne permet pas d'approuver : envoyez l'adresse de la page au propriétaire, à un Administrator ou à un Developer | | `wajub login --environment live` a enregistré un profil sandbox | La personne qui approuve a laissé la page sur Sandbox, où elle démarre toujours | Une commande inconnue échoue clairement au lieu d'effectuer une action inattendue. Quand une commande est proche de ce que vous avez tapé, l'erreur la nomme ; lancez-la vous-même, la CLI ne le fait jamais à votre place. Le code de sortie est `127`. ```bash title="Une faute de frappe reçoit une suggestion, jamais une supposition" $ wajub paymnts list › Error: "paymnts list" is not a wajub command. Did you mean `wajub payments list`? Run `wajub help` for the list. ``` ## Nous signaler ce qui manque ```bash title="wajub feedback" wajub feedback ``` La commande ouvre le formulaire de retour dans votre navigateur. Ajoutez-y l'identifiant de requête obtenu avec `wajub doctor` : les deux premières questions d'un échange avec le support auront déjà leur réponse. - [Commandes API et ressources](https://docs.wajub.com/fr/developer-tools/cli/api-commands): La grammaire sur laquelle reposent ces scripts. - [Skills pour agents](https://docs.wajub.com/fr/developer-tools/cli/skills): L'autre élément que la CLI installe dans votre projet. - [Surveillance](https://docs.wajub.com/fr/resources/monitoring): Les mêmes vérifications, exécutées régulièrement plutôt que dans votre terminal. - [Passer en live](https://docs.wajub.com/fr/getting-started/going-live): Les points à vérifier avant le premier paiement réel. --- # Commandes API et ressources URL: https://docs.wajub.com/fr/developer-tools/cli/api-commands > Une même grammaire pour toutes les ressources, plus une requête brute lorsque vous en avez besoin. La plupart des commandes appliquent les cinq mêmes verbes à onze ressources. Apprenez cette grammaire une fois pour piloter toute l'API sans ouvrir la référence. ```bash title="La structure" wajub list wajub retrieve wajub create -d field=value wajub update -d field=value wajub delete ``` `payments`, `customers`, `refunds`, `transfers`, `beneficiaries`, `links`, `invoices`, `events`, `disputes`, `accounts` et `webhooks` suivent cette structure, sans les verbes qui n'ont aucun sens pour eux. `refunds update` n'existe pas, car un remboursement ne peut pas être modifié. `shield`, `identity` et `skills` possèdent leur propre structure, présentée à la fin de cette page. `links` et `invoices` ne fonctionnent qu'avec une clé live. Avec une clé sandbox, la CLI s'arrête avant d'envoyer quoi que ce soit et sort avec le code `1` : `invoices is available in live mode only — use a live key (sk.).` ## Envoyer un corps de requête Deux méthodes sont disponibles. Utilisez `-d` dans le cas courant et `--data-raw` pour un corps que vous avez déjà ou des types que vous voulez fixer vous-même. Elles se combinent : `--data-raw` est lu d'abord, puis chaque `-d` s'applique par-dessus, si bien qu'un champ `-d` l'emporte sur le même champ du JSON. ```bash title="Champs répétables ou objet JSON unique" # Repeatable key=value. Dots build nested objects. wajub payments create \ -d amount=25000 \ -d currency=XAF \ -d channel=cm.mtn \ -d customer.email=amina@example.com \ -d customer.phone=+237670000000 # An array, written as inline JSON wajub webhooks create -d url=https://example.com/webhooks/wajub -d 'events=["payment.succeeded","payment.failed"]' # Or a body you already have wajub webhooks create --data-raw '{ "url": "https://example.com/webhooks/wajub", "events": ["payment.succeeded", "payment.failed"] }' ``` Un champ nommé `phone`, se terminant par `_phone` (`customer.phone`, `payout_phone`), `account_number` ou `reference` part toujours en texte, tel que saisi, à n'importe quelle profondeur. `-d` lit toute autre valeur ainsi : - `true`, `false` et `null` comme ces valeurs JSON ; - une valeur qui commence par `[` et finit par `]`, ou par `{` et `}`, comme du JSON en ligne, quand elle s'analyse ; - un nombre quand elle n'a pas de zéro initial et au plus 15 chiffres : `amount=25000` donne le nombre `25000`, tandis que `iban=00123` et un numéro de commande de 19 chiffres restent du texte ; - tout le reste comme du texte. > [!WARNING] > **Les crochets ne font pas des tableaux** > > `events[0]=payment.succeeded` ne construit pas de liste : les crochets fonctionnent comme des > points, et la CLI envoie `"events": {"0": "payment.succeeded"}`, un objet que l'API refuse. Écrivez > le tableau en JSON en ligne, comme ci-dessus. Envoyez le corps avec `--data-raw` quand une > valeur doit garder un type que ces règles ne lui donnent pas. ## Répertorier des ressources Toutes les commandes `list` proposent les mêmes options. | Option | Effet | | ---------------- | --------------------------------------------------------------- | | `--page` | Une page précise | | `--all` | Suit la pagination jusqu'à la fin, 25 éléments par requête | | `--limit` | Avec `--all`, limite le total | | `-q`, `--search` | Recherche en texte intégral | | `-f`, `--filter` | `key=value`, répétable et envoyé tel quel comme paramètre d'URL | | `--status` | Filtre selon le statut | Passez par `-f` pour `per_page`, de 1 à 100, et pour les paiements, les remboursements et les litiges, `date_from` et `date_to`. ```bash title="Limiter une liste" wajub payments list -f per_page=5 wajub payments list --status failed -f date_from=2026-01-01 wajub payments list -q amina@example.com wajub transfers list --all --limit 500 --json > transfers.json ``` `date_from` et `date_to` représentent des journées entières. L'API filtre selon la date civile. Vous ne pouvez pas demander uniquement les deux dernières heures. Pour une période plus courte, répertoriez la journée et filtrez vous-même le JSON. ## Requêtes brutes Lorsqu'une route ne possède aucune commande dédiée, ou si vous voulez voir la réponse exacte de l'API, trois commandes acceptent n'importe quel chemin. ```bash title="get, post et delete" wajub get /balance wajub get "/payments?per_page=5&status=succeeded" wajub get /tax/settings wajub post /customers -d email=amina@example.com -d name="Amina Nkem" wajub post /transfers --data-raw '{"amount":100000,"currency":"XAF","beneficiary":"ben_…"}' wajub delete /payments/trx_CSUGajfv9xh0XQ5wu2lx ``` Le chemin est relatif à la base de l'API et la clé provient de votre profil. Vous n'avez donc aucun en-tête à retenir et aucune clé dans votre historique. Placez entre guillemets tout chemin contenant `&`, sinon votre shell l'interprétera. ## Deux options qui changent le sens de la requête **`--idempotency-key`** définit l'en-tête `Idempotency-Key`. Elle existe sur `payments create`, `payments process`, `transfers create`, `refunds create` et `wajub post`, les appels que l'API rend idempotents. Indiquez-la pour que deux exécutions soient traitées comme une même tentative. **`--sync`** définit l'en-tête `X-Sync` et exécute l'appel au nom d'un compte connecté. Elle est disponible sur chaque `create` et `update`, sur les commandes d'action comme `payments process`, et sur `wajub post`. `list`, `retrieve` et `delete` ne la prennent pas. ```bash title="Réessayer sans risque et agir pour un marchand connecté" # Run this twice: the second call returns the first result, it does not charge twice wajub payments create -d amount=25000 -d currency=XAF --idempotency-key order-4172 # Create the payment on a connected merchant's account wajub payments create -d amount=25000 -d currency=XAF --sync acc_7Yh2MpL4tRb3nP8sZcXv ``` ## Sortie La sortie destinée aux humains est un tableau. `--json` affiche l'enveloppe de réponse de l'API sans modification. Les listes se trouvent donc sous `items` et le solde sous `balance`. Utilisez cette sortie dans vos pipelines. Une liste fait exception : `wajub events list --json` range les événements sous `events`, comme `GET /events`, et le filtre est donc `jq '.events[]'`. ```bash title="Composer avec jq" wajub payments list --status failed --json \ | jq -r '.items[] | [.id, .amount, .failure_reason] | @tsv' wajub balance --json | jq '.balance.available' # Every failed payout of the month, as CSV wajub transfers list --status failed --all --json \ | jq -r '.items[] | [.id, .amount, .currency, .failure_reason] | @csv' ``` ## Commandes qui demandent une confirmation Une commande qui déplace de l'argent demande une confirmation quand elle s'exécute avec une clé live ; avec une clé sandbox, elle s'exécute aussitôt. Une commande qui détruit ou remplace quelque chose demande toujours. `--yes`, `-y` ou son alias `--force` ignore cette demande. Utilisez cette option dans un script et nulle part ailleurs. | Commande | Quand elle demande | | ----------------------------- | ------------------------------------------------------------- | | `transfers create` | Avec une clé live : envoie de l'argent | | `refunds create` | Avec une clé live : rembourse de l'argent | | `payments process` | Avec une clé live : débite le payeur | | `webhooks rotate-secret` | Toujours : invalide le secret utilisé par votre serveur | | `accounts token` | Toujours : remplace le lien d'invitation d'un compte connecté | | Toutes les commandes `delete` | Toujours : suppriment l'enregistrement | ## Commandes en lecture seule Quatre commandes sans argument répondent à des questions que vous devriez autrement rechercher. ```bash title="Données de référence et votre propre solde" wajub balance # your balance, per currency wajub channels # every channel slug Wajub supports wajub countries # supported countries wajub currencies # supported currencies ``` Utilisez `wajub channels` lorsqu'un paiement échoue à cause d'un canal inconnu. La commande présente tous les slugs pris en charge par Wajub, le même catalogue pour chaque compte. Ce que votre propre compte peut utiliser dépend de ses prestataires, et c'est `wajub get /providers` qui y répond. ## Identity et Shield Deux thèmes ne suivent pas la grammaire CRUD, car les produits sous-jacents ne la suivent pas. ```bash title="Opérateur d'un numéro, contrôle d'IBAN et contrôles contre la fraude" # Which operator a number belongs to (sandbox key only) wajub identity resolve -d account_number=+237670000000 -d channel=cm.mtn -d country=CM -d type=mobile # Whether an IBAN is well formed wajub identity validate -d iban=FR7630006000011234567890189 # Shield (live key only) wajub shield stats wajub shield settings wajub shield update-settings --enabled --block-threshold 70 --review-threshold 40 wajub shield blocklist wajub shield block +237670000000 --type phone --reason "chargeback ring" # The id is the entry's, a UUID, as `wajub shield blocklist` shows it wajub shield unblock 9b1f6c2e-4a7d-4f0b-8c3e-2d5a7b9e1f40 ``` Les deux commandes `identity` demandent le plan Growth, Scale ou Enterprise. `identity resolve` ne répond qu'à partir des données de la sandbox : avec une clé live, elle renvoie `501`. `identity validate` vérifie le format et la clé de contrôle d'un IBAN, pas l'identité de son titulaire. Toutes les commandes `shield` demandent une clé live. Avec une clé sandbox, la CLI s'arrête avant d'envoyer quoi que ce soit, sort avec le code `1` et indique `Shield is available in live mode only — use a live key (sk.).` `--type` accepte `email`, `phone`, `ip`, `country` et `card_bin`. `update-settings` accepte `--[no-]enabled`, `--review-threshold` et `--block-threshold` sur tous les plans, ainsi que `--[no-]auto-3ds` et `--[no-]blocklist`, qui demandent Shield Advanced. - [Utilisation avancée](https://docs.wajub.com/fr/developer-tools/cli/advanced): La CI, l'autocomplétion, les exemples et le raccourci vers le Dashboard. - [Déclencher des événements](https://docs.wajub.com/fr/developer-tools/cli/triggers): Produire un paiement au lieu d'en décrire un. - [Idempotence](https://docs.wajub.com/fr/best-practices/idempotency): Ce contre quoi l'en-tête vous protège réellement. - [Vue d'ensemble de la référence API](https://docs.wajub.com/fr/api): Toutes les routes, tous les paramètres et toutes les réponses. --- # Diagnostiquer un problème URL: https://docs.wajub.com/fr/developer-tools/cli/debug > Demandez à la CLI ce qui est arrivé à un paiement, un transfert, un remboursement ou un événement, qui doit agir et quoi faire ensuite. `wajub debug` prend un identifiant et explique l'objet qui se trouve derrière : ce qui s'est passé et quand, pourquoi il a échoué ou reste bloqué, qui doit agir, et l'étape suivante avec la page de documentation qui la décrit. `wajub explain` est la même commande. > [!NOTE] > **Si votre CLI ne connaît pas la commande** > > La réponse `"debug" is not a wajub command` signifie que votre CLI lui est antérieure, et > `npm install -g @wajub/cli` la met à jour. ```bash title="Une commande payée dont votre serveur n'a rien su" $ wajub debug trx_test_CSUGajfv9xh0XQ5wu2lx Payment trx_test_CSUGajfv9xh0XQ5wu2lx succeeded (sandbox) Nothing reliable tells your server this payment succeeded Timeline (UTC) 2026-11-20 09:14:02 payment created 5000 XAF · reference order-4172 2026-11-20 09:14:31 event payment.succeeded evt_test_Nq8rT3vK6mX2pW9cB5jL7hYs · delivered 2026-11-20 09:14:31 last update succeeded · cm.mtn Diagnosis ✗ Nothing reliable tells your server this payment succeeded [your integration] Only the callback redirect tells you, and it never comes when the payer closes the tab before being sent back. → Subscribe an endpoint to `payment.succeeded` and fulfil from it, after retrieving the payment server-side. https://docs.wajub.com/developer-tools/webhooks/quickstart ✗ No endpoint receives `payment.succeeded` [your integration] 1 enabled endpoint(s), none subscribed to `payment.succeeded`. → Add `payment.succeeded` to your endpoint's events with `wajub webhooks update --data-raw '{"events":[…]}'` (the list replaces the old one), then `wajub events resend `. https://docs.wajub.com/developer-tools/webhooks/events • Sandbox scenario A sandbox number ending in 000000 succeeds: this outcome is the scenario you chose, not a bug. https://docs.wajub.com/developer-tools/testing/test-scenarios ✓ The payer paid ``` ## Ce qu'elle prend Un seul argument : un identifiant tiré d'une réponse, d'un webhook ou du Dashboard, ou votre propre référence. | Vous passez | La CLI lit | | -------------------------------------- | --------------------------------------------------------------------------- | | Un paiement, `trx_…` | Le paiement, ses événements, ses remboursements et vos endpoints de webhook | | Un transfert, `po_…` | Le transfert, ses événements et vos endpoints de webhook | | Un remboursement, `rfd_…` | Le remboursement et sa chronologie | | Un événement, `evt_…` | L'événement, et ceux de vos endpoints qui reçoivent son type | | L'identifiant d'un endpoint de webhook | L'endpoint : s'il est activé, et à quoi il est abonné | | Votre propre `reference` | Le paiement le plus récent qui la porte, sinon le transfert qui la porte | Un identifiant de sandbox contient `test_`, comme `trx_test_…`. Quand l'identifiant et votre clé appartiennent à des environnements différents, la commande le dit avant tout appel, puisque l'API ne répondrait que `404`. ```bash title="Un identifiant live lu avec une clé de sandbox" $ wajub debug trx_CSUGajfv9xh0XQ5wu2lx Payment trx_CSUGajfv9xh0XQ5wu2lx (sandbox) This id belongs to live, and you are using a sandbox key Diagnosis ✗ This id belongs to live, and you are using a sandbox key [your integration] trx_CSUGajfv9xh0XQ5wu2lx was created in live (its id has no `test_`), and the key in use is a sandbox key. The two share no data: the API answers 404. → Use a live key: `--profile ` or WAJUB_API_KEY=sk.…. If your server reads this id with the same key, it has the same problem. https://docs.wajub.com/getting-started/environments ``` Une référence que portent plusieurs paiements fait expliquer le plus récent et liste les autres. L'identifiant d'une livraison de webhook (`whd_…`) ou d'une requête API ne se lit pas par l'API : la commande le dit et vous envoie dans Konsole, où [Webhooks](https://docs.wajub.com/fr/developer-tools/konsole/webhook-tester) et [Logs API](https://docs.wajub.com/fr/developer-tools/konsole/log-explorer) les affichent. ## Ce qu'elle affiche Les deux premières lignes nomment l'objet, son statut et son environnement, puis le problème le plus sérieux trouvé, ou l'état de l'objet quand rien ne va de travers. **Timeline**, en UTC, suit l'objet depuis sa création : chaque événement avec l'accusé de réception de vos endpoints ou son absence, les remboursements, l'expiration d'un paiement en attente, la dernière mise à jour. **Diagnosis** liste les constats, ceux à corriger en premier. | Marque | Signification | | ------ | -------------------------------------------------------------------------- | | `✗` | Un problème à corriger | | `!` | À regarder, sans rien bloquer | | `•` | Une information, comme le scénario de sandbox choisi par un numéro de test | | `✓` | Ce qui s'est passé comme prévu | À côté d'un problème, les crochets disent qui doit agir : `[the payer]` (le payeur), `[the operator]` (l'opérateur), `[your account settings]` (les réglages de votre compte), `[Wajub]` ou `[your integration]` (votre intégration). Dessous viennent le détail, l'étape suivante après `→`, et la page de documentation. Une dernière ligne, `Related:`, liste les identifiants qui méritent leur propre `wajub debug`, comme les remboursements d'un paiement. ## Ce qu'elle reconnaît - **Paiements.** Un échec côté payeur (fonds insuffisants, un plafond, un code PIN refusé, aucune confirmation à temps) ou de votre côté (un numéro que l'opérateur ne connaît pas, un code généré par le payeur qui manque), et un code d'opérateur que la CLI ne connaît pas, laissé à l'opérateur. Un paiement en attente dont la dernière tentative a été refusée, un paiement expiré avant que le payeur atteigne le checkout, un paiement réussi qu'aucun endpoint ne signale, un callback sur `localhost`, deux paiements payés avec la même référence, des remboursements échoués, et le scénario choisi par un numéro de test de la sandbox. - **Transferts et remboursements.** Chaque `failure_reason` des [motifs d'échec](https://docs.wajub.com/fr/api/failure-reasons), avec ce qu'il faut faire, et ce que signifient `review` et `processing` pendant que vous attendez. - **Webhooks.** Aucun endpoint dans cet environnement, tous les endpoints désactivés, aucun endpoint abonné à l'événement, un motif comme `payment.*` qui ne correspond à rien, un endpoint en `http://` simple, et un événement que votre endpoint n'a pas acquitté, qu'il soit encore en cours de livraison, en échec ou abandonné après 72 heures, avec `wajub events resend` pour le rejouer. - **La mauvaise clé.** Un identifiant d'un environnement lu avec une clé de l'autre. Les règles sont fixes et s'exécutent dans la CLI : les mêmes réponses donnent toujours le même diagnostic, et rien n'est envoyé à un modèle. ## Dans les scripts et les agents de développement `--json` renvoie le diagnostic : `id`, `kind`, `found`, `environment`, `status`, `summary`, `timeline`, `related`, l'objet tel que l'API l'a renvoyé, et `findings`. Chaque constat porte un `code` stable sur lequel brancher votre logique, une `severity` (`error`, `warning`, `info` ou `ok`), une `cause` (`integration`, `payer`, `provider`, `account`, `wajub`, `none` ou `unknown`), un `title` et, quand il les a, `detail`, `next` et `docs`. ```bash title="Seulement ce qu'il faut corriger" $ wajub debug trx_test_CSUGajfv9xh0XQ5wu2lx --json | jq -r '.findings[] | select(.severity == "error") | .code' payment.no_fulfilment_signal webhook.not_subscribed ``` La commande se termine avec le code `0` quand elle a trouvé l'objet, quel que soit son état, et `1` quand elle n'a rien trouvé pour l'identifiant, y compris un identifiant de l'autre environnement. ## La clé qu'elle utilise La même clé et la même adresse d'API que toutes les autres commandes : le profil par défaut, ou `--profile`, `WAJUB_API_KEY` et `--api-base`. [Utilisation avancée](https://docs.wajub.com/fr/developer-tools/cli/advanced#environment-variables) donne l'ordre dans lequel la CLI choisit la clé. Utilisez une clé secrète ou restreinte : une clé publiable (`pk.`) ne peut pas lire les paiements. Pour un objet ancien, la chronologie peut manquer certains de ses événements ; la commande le signale alors et renvoie au [flux d'événements](https://docs.wajub.com/fr/developer-tools/konsole/event-stream) de Konsole. - [Dépannage des webhooks](https://docs.wajub.com/fr/resources/troubleshooting/webhooks): Les raisons habituelles pour lesquelles un endpoint n'acquitte pas un événement. - [Dépannage des paiements](https://docs.wajub.com/fr/resources/troubleshooting/payments): Paiements échoués, en attente et expirés, et ce qu’il faut faire. - [Scénarios de test](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios): Les numéros de sandbox derrière chaque résultat. - [Recevoir des webhooks en local](https://docs.wajub.com/fr/developer-tools/cli/listen): Reproduisez une livraison en échec sur votre machine. --- # CLI Wajub URL: https://docs.wajub.com/fr/developer-tools/cli > L'API, vos webhooks et votre sandbox depuis le terminal. La CLI appelle l'API Wajub depuis votre terminal : elle garde vos clés hors de l'historique du shell, transmet les événements live à `localhost`, produit de vrais paiements dans la sandbox à la demande et installe les recommandations de Wajub dans votre agent de programmation. ```bash title="Les trois commandes utiles dès le premier jour" npm install -g @wajub/cli wajub login wajub doctor wajub listen --forward-to localhost:3000/webhooks/wajub ``` `wajub login` attend que votre équipe l'approuve dans le Dashboard : le propriétaire, un Administrator ou un Developer (un Sandbox User aussi, pour une clé sandbox) y choisit l'environnement, et la clé que reçoit la CLI dure 90 jours. [Installation et authentification](https://docs.wajub.com/fr/developer-tools/cli/installation#approving-the-login) en donne les règles. De toutes ses commandes, vous en utiliserez environ huit. ## Ses points forts | Votre objectif | Commande | | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | | Recevoir des événements live sur votre ordinateur | [`wajub listen`](https://docs.wajub.com/fr/developer-tools/cli/listen) | | Produire un véritable paiement dans la sandbox | [`wajub trigger`](https://docs.wajub.com/fr/developer-tools/cli/triggers) | | Lire ou écrire une ressource | [`wajub payments list`, `wajub get /balance`](https://docs.wajub.com/fr/developer-tools/cli/api-commands) | | Comprendre pourquoi un paiement, un transfert ou un webhook a mal tourné | [`wajub debug`](https://docs.wajub.com/fr/developer-tools/cli/debug) | | Comprendre pourquoi rien ne fonctionne | `wajub doctor` | | Apprendre l'API à votre agent de programmation | [`wajub skills install`](https://docs.wajub.com/fr/developer-tools/cli/skills) | ## Grammaire des commandes Les thèmes sont séparés par une **espace**, pas par deux-points. Écrivez `wajub payments list`, jamais `wajub payments:list`. ```bash title="Les quatre mêmes verbes pour chaque ressource" wajub payments list -f per_page=5 wajub payments retrieve trx_CSUGajfv9xh0XQ5wu2lx wajub customers create -d email=amina@example.com -d name="Amina Nkem" wajub customers update cus_4tRb3nP8sZcXvK2mQ9wL -d name="Amina N." ``` Tous les thèmes ci-dessous utilisent la même structure. En apprendre un suffit pour comprendre les autres. | Thème | Commandes | Couverture | | ------------------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------- | | `payments` | 6 | Créer, traiter, annuler, répertorier, récupérer et répertorier les remboursements | | `customers` | 9 | Les quatre verbes, plus bloquer, débloquer, activer, désactiver et supprimer | | `invoices` | 8 | Les quatre verbes, plus envoyer, marquer comme payée, annuler et supprimer. Clé live uniquement | | `accounts` | 6 | Les comptes connectés Sync, dont `token` | | `disputes` | 6 | Accepter, clôturer, envoyer un message, fournir des justificatifs, répertorier et récupérer | | `shield` | 6 | Paramètres et leur modification, statistiques, liste de blocage, blocage et déblocage. Clé live uniquement | | `webhooks` | 6 | Endpoints, plus `rotate-secret` | | `beneficiaries`, `links` | 5 chacun | Les quatre verbes, plus supprimer | | `refunds`, `transfers`, `events`, `skills` | 3 chacun | Créer ou installer, répertorier et récupérer | | `identity` | 2 | Trouver l'opérateur d'un numéro en sandbox et valider un IBAN | | `config` | 2 | `set` et `use` pour les profils | S'y ajoutent les commandes sans thème : `balance`, `channels`, `countries`, `currencies`, `listen`, `trigger`, `debug`, `login`, `logout`, `doctor`, `status`, `version`, `open`, `samples`, `feedback`, ainsi que les commandes brutes `get`, `post` et `delete`. ## Trois options disponibles sur chaque commande | Option | Effet | | ----------- | ------------------------------------------------------------------------------------- | | `--json` | Produit une sortie exploitable par une machine au lieu d'un tableau | | `--profile` | Utilise un profil nommé à la place du profil par défaut | | `--api-key` | Transmet directement une clé. **À éviter** : elle apparaît dans l'historique du shell | La dernière option est volontairement absente de `--help`. Utilisez `wajub login`, ou `WAJUB_API_KEY` dans la CI. ## En cas de problème, interrogez d'abord la CLI `wajub doctor` contrôle dans l'ordre tout ce qui peut casser une intégration : vos profils, la clé et sa provenance, l'API, votre compte, Node.js, et si vos agents de développement voient les [Skills pour agents](https://docs.wajub.com/fr/developer-tools/cli/skills). Une ligne par contrôle, leur nombre dépend donc de votre machine, et celui qui échoue est nommé précisément. ```bash title="wajub doctor" Wajub CLI diagnostics ✓ Config 2 profile(s), default: sandbox ✓ Credentials key=sk_test.… env=sandbox base=https://api.wajub.com source=profile ✓ API reachability https://api.wajub.com (HTTP 200) ✓ Auth API key accepted — Boutique Akwa (sandbox) ✓ Node.js v22.11.0 (≥ 22 required) ✓ Agent Skills · Claude Code sees the 10 skills in ~/.claude/skills ✓ Agent Skills · Codex sees the 10 skills in ~/.agents/skills ✓ Environment wajub-cli v1.8.0 node v22.11.0 darwin/arm64 ✓ Support last request id: fbe6773e9ce64f158af89e5740fc5817 (include this if you contact support) Everything looks good. ``` Copiez la ligne `Support` dans votre message au support. L'identifiant de requête lui permet de retrouver votre appel dans les logs sans autre information. > [!TIP] > **Vérifiez le profil actif avant toute opération destructive** > > `wajub config` répertorie vos profils, masque leurs clés et marque celui utilisé par défaut. Une > commande `delete` ou `transfers create` exécutée sur le mauvais profil déplace de l'argent réel. - [Installation et authentification](https://docs.wajub.com/fr/developer-tools/cli/installation): Node 22, les gestionnaires de paquets, la connexion et les profils. - [Recevoir des webhooks en local](https://docs.wajub.com/fr/developer-tools/cli/listen): Les événements live transmis à localhost avec une signature. - [Déclencher des événements](https://docs.wajub.com/fr/developer-tools/cli/triggers): Huit événements produits par l'utilisation de l'API de la sandbox. - [Commandes API et ressources](https://docs.wajub.com/fr/developer-tools/cli/api-commands): La grammaire CRUD, les requêtes brutes et la sortie JSON. --- # Installation et authentification URL: https://docs.wajub.com/fr/developer-tools/cli/installation > Installez la CLI sur votre machine, puis fournissez-lui une clé qu'elle peut conserver. La CLI est un paquet Node. Une installation globale et un aller-retour dans le navigateur suffisent. ## Prérequis **Node.js 22 ou version ultérieure.** `wajub doctor` le vérifie : un ancien runtime échoue donc avec un message clair plutôt qu'une trace de pile. ```bash title="Vérifier avant l'installation" node --version ``` ## Installation ```bash npm install @wajub/cli ``` Confirmez l'installation et notez le runtime indiqué. Le support vous demandera cette ligne. ```bash title="wajub version" $ wajub version @wajub/cli/1.8.0 darwin-arm64 node-v22.11.0 ``` > [!TIP] > **Sans rien installer** > > `npx @wajub/cli listen --forward-to localhost:3000/webhooks` exécute la version actuelle sans rien > laisser derrière. Cette méthode est utile sur une machine qui ne vous appartient pas ou dans un > conteneur temporaire. Pour effectuer une mise à jour, relancez l'installation. La CLI vous avertit aussi lorsqu'une nouvelle version est publiée. ## Authentification `wajub login` ouvre votre navigateur. Un membre de votre équipe approuve la demande dans le Dashboard et la CLI reçoit une clé qu'elle conserve localement. Vous ne saisissez rien dans le terminal, donc aucune clé n'apparaît dans l'historique du shell. ```bash title="Le parcours normal" wajub login wajub login --environment live ``` La sandbox est utilisée par défaut. Connectez-vous deux fois, une fois par environnement, pour obtenir deux profils entre lesquels basculer. | Option | Utilisation | | --------------- | ----------------------------------------------------------------------------------------------------------------- | | `--environment` | `sandbox` ou `live`, l'environnement que vous demandez. La personne qui approuve choisit celui de la clé | | `--manual` | Colle une clé existante dans une invite masquée, sans navigateur | | `--no-browser` | Affiche l'URL au lieu de l'ouvrir, pour un shell distant | | `--no-skills` | N'installe aucun [Skill pour agents](https://docs.wajub.com/fr/developer-tools/cli/skills), ni maintenant ni lors des exécutions suivantes | | `--profile` | Nomme le profil créé | Les identifiants sont enregistrés dans `~/.config/wajub/config.json`, accessible uniquement par vous. Vous pouvez le sauvegarder, mais traitez-le exactement comme un fichier de clés. ### Approuver la connexion Le terminal affiche un code d'appairage et la page à ouvrir, et la page montre le même code : vérifiez qu'ils correspondent avant de continuer. La page démarre toujours sur **Test**, quoi que demande `--environment`, et c'est la personne qui approuve qui y choisit l'environnement. **Production** est proposé une fois le compte vérifié, et jamais à un Sandbox User. La personne qui approuve choisit aussi **Accès complet**, ou **Restreint** avec les permissions que reçoit la clé. Approuver crée une clé d'API pour l'équipe, si bien que tous les membres ne le peuvent pas : - Le propriétaire, un Administrator ou un Developer approuve, et un Sandbox User le peut aussi, pour une clé sandbox. Tout autre membre voit « Un administrateur ou un développeur doit approuver cette demande », avec le code : envoyez l'adresse de la page à l'un d'eux. - **Autoriser** exige un code de vérification de sécurité récent (il vaut 30 minutes), comme l'affichage ou le renouvellement d'une clé. La page en demande un quand il le faut, depuis votre application d'authentification ou envoyé par SMS ou par e-mail. Le propriétaire et chaque Administrator reçoivent un e-mail pour chaque clé créée par une connexion, qui indique qui l'a approuvée, l'environnement, le type de clé et son expiration, avec un lien vers la page des clés API. Une connexion que personne de votre équipe n'a lancée est une raison de supprimer cette clé. La demande dure 15 minutes. Sans approbation dans ce délai, la CLI s'arrête et vous demande de relancer `wajub login`. Un refus se termine par `Login was denied in the browser.`, et les deux cas sortent avec le statut `1`. ### La clé créée Votre première connexion sandbox devient le profil par défaut, celui qu'utilise toute commande sans `--profile`. Une connexion suivante ne le déplace pas : une connexion live ne devient jamais le profil par défaut d'elle-même, si bien que la commande qui suit `wajub login --environment live` s'exécute toujours en sandbox. La CLI le signale quand le nouveau profil n'est pas celui par défaut ; `wajub config use live` en fait le profil par défaut, délibérément. Sans `--profile`, le profil porte le nom de l'environnement choisi à l'approbation, quoi que demande `--environment`. La clé créée par `wajub login` expire toujours 90 jours plus tard : la page d'approbation ne propose aucune autre durée pour la CLI. La CLI affiche la date à la connexion, `wajub doctor` la montre sur la ligne `Key expiry` et échoue pendant les 7 derniers jours, où chaque commande vous prévient aussi. Relancez `wajub login` pour en obtenir une nouvelle. ### Dans la CI, utilisez l'environnement Un pipeline ne possède aucun navigateur. Définissez `WAJUB_API_KEY` pour que toutes les commandes l'utilisent sans qu'aucun profil n'existe. ```bash title="Une étape de pipeline" # From your CI secret store, never from the job definition export WAJUB_API_KEY=sk.xxxxxxxxxxxxxxxx… wajub doctor --json wajub payments list -f per_page=5 --json ``` > [!CAUTION] > **Ne transmettez jamais une clé avec `--api-key`** > > Une clé passée dans la ligne de commande est écrite dans l'historique du > shell et visible dans la liste des processus par tous les utilisateurs de la machine. Utilisez > `wajub login` en local et `WAJUB_API_KEY` dans la CI. ## Profils Un profil est un ensemble d'identifiants nommé. La CLI utilise ce concept parce que les clés de la sandbox et du mode live ne doivent jamais être séparées par une simple faute de frappe. ```bash title="Créer, examiner et changer de profil" # What do I have, and which one is default? wajub config # Register a key under a name, without calling the API to validate it. # The CLI asks for the key through a hidden prompt. wajub config set staging # Make it the default wajub config use staging # Or override for a single command wajub payments list --profile sandbox ``` `wajub config` affiche les clés masquées. `--show-secrets` les affiche entièrement, ce qui est presque toujours déconseillé sur un écran partagé. Une variable `WAJUB_API_KEY` exportée l'emporte sur tous les profils, `--profile` compris : tant qu'elle est définie, `wajub payments list --profile sandbox` utilise toujours la clé exportée. `WAJUB_PROFILE` choisit le profil pour toutes les commandes du shell, comme `--profile` le fait pour une seule. > [!WARNING] > **`config set` ne vérifie pas la clé** > > La commande enregistre le profil tel quel. Une faute de frappe n'est découverte que plus tard, > lorsqu'une commande échoue avec `401`. Exécutez `wajub doctor` après avoir créé manuellement un > profil. ## Vérifier toute la chaîne ```bash title="wajub doctor" $ wajub doctor Wajub CLI diagnostics ✓ Config 2 profile(s), default: sandbox ✓ Credentials key=sk_test.… env=sandbox base=https://api.wajub.com source=profile ✓ Key expiry expires on 2/19/2027 (in 89 day(s)) ✓ API reachability https://api.wajub.com (HTTP 200) ✓ Auth API key accepted — Boutique Akwa (sandbox) ✓ Node.js v22.11.0 (≥ 22 required) ✓ Agent Skills · Claude Code sees the 10 skills in ~/.claude/skills ! Agent Skills · Codex no skills in ~/.agents/skills — run `wajub skills install --scope user` ✓ Environment wajub-cli v1.8.0 node v22.11.0 darwin/arm64 ✓ Support last request id: fbe6773e9ce64f158af89e5740fc5817 (include this if you contact support) No failures, 1 warning(s) — see above. ``` Le champ `source` de la ligne des identifiants est souvent ignoré. Il indique si la clé provient d'un profil, de `WAJUB_API_KEY` ou d'une option. Lorsqu'une commande semble appartenir à un autre compte, ce champ vous donne la réponse. Le nombre de lignes dépend de votre configuration. `Key expiry` apparaît pour une clé créée par `wajub login`. Chaque agent de développement présent sur la machine a sa propre ligne `Agent Skills`, et un dépôt git qui contient des skills de projet ajoute `Agent Skills (project)`. Une ligne marquée `!` est un avertissement : elle indique la correction et ne fait jamais échouer le diagnostic. Un `✗` le fait échouer : il se termine alors par `Some checks failed — see above for details.` et le code de sortie `1`. ## Déconnexion `wajub logout` révoque la clé créée par `wajub login`, puis supprime le profil local. La révocation est importante. La simple suppression du fichier laisserait une clé live active chez Wajub. Une clé que vous avez placée vous-même dans un profil (`--manual`, `wajub config set`) reste active, et la CLI le signale : révoquez-la dans le Dashboard si elle doit cesser de fonctionner. ```bash title="Se déconnecter proprement" wajub logout # the current profile wajub logout --profile sandbox # a named one wajub logout --all # every profile wajub logout --keep-key # forget it locally, leave the key active ``` Utilisez `--keep-key` uniquement lorsque la clé sert également ailleurs, par exemple sur un serveur configuré avec une copie provenant du Dashboard. - [Commandes API et ressources](https://docs.wajub.com/fr/developer-tools/cli/api-commands): Les commandes à exécuter après votre connexion. - [Recevoir des webhooks en local](https://docs.wajub.com/fr/developer-tools/cli/listen): La principale raison pour laquelle la plupart des utilisateurs installent la CLI. - [Skills pour agents](https://docs.wajub.com/fr/developer-tools/cli/skills): Ce que `--no-skills` désactive et comment les ajouter plus tard. - [Environnements et API keys](https://docs.wajub.com/fr/getting-started/environments): Les types de clés, leurs permissions et leur renouvellement. --- # Recevoir des webhooks en local URL: https://docs.wajub.com/fr/developer-tools/cli/listen > Des événements live transmis à localhost, signés par Wajub et sans tunnel. `wajub listen` transmet les événements de votre compte à l'URL locale de votre choix, signés comme des livraisons de production, sans déployer votre handler ni ouvrir de tunnel. ```bash title="Toute la configuration" wajub listen --forward-to localhost:3000/webhooks/wajub ``` Aucun de vos services n'est exposé : ni URL publique, ni port entrant. ## Ce que vous voyez ```bash title="wajub listen" $ wajub listen --forward-to localhost:3000/webhooks/wajub Ready! Streaming sandbox events for your account. Your webhook signing secret is whsec_test_xxxxxxxxxxxxxxxx… (^C to quit) It stays the same between runs: set WAJUB_WEBHOOK_SECRET=whsec_test_xxxxxxxxxxxxxxxx… in your app's .env once. Forwarding to http://localhost:3000/webhooks/wajub subscribed — waiting for events… 6:37:35 AM customer.created evt_test_Example00000000000000001 → 200 http://localhost:3000/webhooks/wajub 6:37:35 AM payment.created evt_test_Example00000000000000002 → 200 http://localhost:3000/webhooks/wajub 6:37:36 AM payment.processing evt_test_Example00000000000000003 → 200 http://localhost:3000/webhooks/wajub 6:37:39 AM payment.succeeded evt_test_Example00000000000000004 → 200 http://localhost:3000/webhooks/wajub 6:37:39 AM balance.updated evt_test_Example00000000000000005 → 200 http://localhost:3000/webhooks/wajub 6:37:39 AM fee.charged evt_test_Example00000000000000006 → 200 http://localhost:3000/webhooks/wajub ``` Le nombre à droite est la réponse de votre propre endpoint. Un `500` indique donc l'échec de votre handler, pas celui de la CLI. L'exécution ci-dessus correspond à un seul `wajub trigger payment.succeeded`. Une commande a produit six événements, comme un véritable paiement. C'est le moyen le plus rapide de découvrir le nombre de types silencieusement ignorés par votre handler. ## La requête transmise est un véritable webhook Chaque livraison locale est signée comme une livraison de production, avec le même corps et les mêmes en-têtes. | En-tête | Valeur | | --------------------- | ------------------------------------------------------------------------------------- | | `X-Wajub-Signature` | `v1=` suivi du HMAC | | `X-Wajub-Timestamp` | Secondes Unix, incluses dans la chaîne signée | | `X-Wajub-Event` | Le type d'événement | | `X-Wajub-Delivery-Id` | `whd_` suivi d'un UUID, identique pour chaque livraison d'un événement à cette écoute | Votre code de vérification s'exécute donc réellement en local, au lieu d'être ignoré derrière un `if (process.env.NODE_ENV === 'development')` qui masque un défaut jusqu'à la production. ```json title="Contenu reçu par votre endpoint" { "id": "evt_test_Example00000000000000002", "event": "payment.created", "data": { "id": "trx_test_Example0000000000001", "amount": 5000, "status": "pending", "currency": "XAF", "sandbox": true, "amount_paid": 0, "description": "Payment", "customer": { "id": "cus_test_Example00000000000000001", "name": "CLI Trigger", "email": "cli-trigger@example.com" }, "created_at": "2026-09-14T04:37:34+00:00", "updated_at": "2026-09-14T04:37:34+00:00" }, "livemode": false, "pending_webhooks": 0, "api_version": "2026-10-11", "request": { "id": null, "idempotency_key": "idem_Example0000000000000000000000001" }, "created": "2026-09-14T04:37:34+00:00" } ``` Comme le corps est celui de la production, un handler qui vérifie la signature sur le corps brut réussit en local exactement quand il réussira une fois déployé. Le secret de signature reste le même à chaque `wajub listen` pour ce compte et cet environnement : un pour la sandbox, un pour le live. Placez-le une seule fois dans votre `.env` et votre handler effectue la vérification sans autre modification. Ce n'est pas le secret d'un endpoint enregistré : chaque endpoint garde le sien. ```bash title="Configurer votre application avec le secret d'écoute" export WAJUB_WEBHOOK_SECRET=$(wajub listen --print-secret) npm run dev ``` `--print-secret` affiche le secret seul puis s'arrête, ce qui le rend utilisable dans un script. Avec une clé live, ajoutez `--live` (`wajub listen --live --print-secret`) : sans lui la commande échoue, et `$(…)` récupère alors un secret vide. > [!CAUTION] > **`--unsigned` supprime entièrement la signature** > > Cette option permet d'envoyer de force un payload dans un handler qui ne sait pas encore le > vérifier. Elle transmet les événements **sans signature**. Votre endpoint ne peut alors plus > distinguer Wajub de toute autre source capable de l'atteindre. Ne la laissez jamais dans un script > et ne l'utilisez jamais avec un endpoint également déployé. Si votre application répond sur une adresse `https://` avec un certificat auto-signé ou émis par une autorité locale, comme un site local avec un certificat auto-signé, ajoutez `--insecure-tls`. La vérification du certificat est ignorée uniquement pour la transmission à votre handler ; les appels de la CLI à l'API Wajub restent vérifiés. Faire pointer `NODE_EXTRA_CA_CERTS` vers votre autorité locale fonctionne aussi. ## Options | Option | Effet | | ---------------- | ------------------------------------------------------------------------------------------------ | | `--forward-to` | Destination du POST. `http://` est utilisé lorsque le schéma est absent | | `--events` | Types séparés par des virgules, jokers acceptés (`payment.*`), à la place de tous les événements | | `--live` | Obligatoire avec une clé live : les événements de vrais clients arrivent sur cette machine | | `--print-secret` | Affiche le secret de signature puis s'arrête | | `--unsigned` | Transmet sans signature. Consultez l'avertissement ci-dessus | | `--insecure-tls` | Accepte un certificat auto-signé ou d'une autorité locale sur une URL `https://` de transmission | | `--profile` | Compte et environnement dont le flux est utilisé | ```bash title="Limiter le flux" # Only what your handler currently implements wajub listen \ --forward-to localhost:3000/webhooks/wajub \ --events "payment.*,refund.succeeded" # Watch without forwarding anywhere wajub listen ``` Sans `--forward-to`, la commande affiche les événements sans les envoyer. Utilisez-la pour vérifier si un événement est émis avant d'accuser votre handler. Une valeur `--events` mal formée arrête la commande avant tout démarrage, et Wajub n'envoie que les types demandés. ## À connaître **L'environnement provient de votre profil.** Une clé de sandbox diffuse les événements de la sandbox. Une clé live diffuse les événements live, et seulement avec `--live` : les données de vrais clients arrivent alors sur votre machine. `wajub doctor` indique le profil utilisé. `--profile` le remplace pour une exécution. **Il faut une clé secrète, ou une clé restreinte avec `event.read`.** La clé créée par `wajub login` a un accès complet, sauf si vous la restreignez. Une clé publique ne peut pas écouter, et une clé révoquée par `wajub logout` arrête un flux en cours. **Aucun endpoint enregistré n'est nécessaire.** Le flux est indépendant de `POST /webhooks`. Même un compte sans endpoint transmet tous ses événements à `wajub listen`. **Il ne remplace pas vos endpoints enregistrés.** Un endpoint live abonné aux mêmes événements continue de les recevoir. L'écoute ne détourne rien. **Vos écoutes apparaissent dans le Dashboard.** Konsole › Webhooks liste chaque `wajub listen` en cours pour l'environnement actuel, avec la réponse de votre handler aux derniers événements. **Il survit à la mise en veille.** Il se reconnecte tout seul, rien à faire. **Vingt à la fois.** Un compte peut avoir 20 sessions `wajub listen` ouvertes par environnement ; la vingt et unième est refusée avec `429`. Arrêter une commande avec ^C libère sa place aussitôt. **Un `503` signifie que le flux n'a pas pu être ouvert.** La commande s'arrête avant de commencer. Réessayez dans un instant ; si cela persiste, transmettez au support l'identifiant de requête affiché par la CLI. Toutes les autres commandes continuent de fonctionner. **Aucune donnée n'est mise en mémoire tampon.** Les événements produits lorsque la commande est arrêtée ne sont pas rejoués à son démarrage. Pour les récupérer, consultez [`wajub events list`](https://docs.wajub.com/fr/developer-tools/cli/api-commands) et renvoyez ceux qui vous intéressent. ## La boucle Deux terminaux suffisent, sans toucher à un téléphone. ```bash title="Terminal 1, puis terminal 2" # 1: forward everything to your handler wajub listen --forward-to localhost:3000/webhooks/wajub # 2: make something happen wajub trigger payment.succeeded wajub trigger payment.failed --amount 2500 ``` Écrivez le handler, enregistrez, puis déclenchez de nouveau l'événement. La boucle dure quelques secondes, ce qui est précisément son intérêt. - [Déclencher des événements](https://docs.wajub.com/fr/developer-tools/cli/triggers): Les huit événements que vous pouvez produire à la demande. - [Vérification de signature](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification): Ce que votre handler doit faire avec ce secret. - [Recevoir un webhook](https://docs.wajub.com/fr/developer-tools/webhooks/quickstart): Le handler lui-même, dans cinq langages. - [Catalogue des événements](https://docs.wajub.com/fr/developer-tools/webhooks/events): Tous les types acceptés par `--events`. --- # Skills pour agents URL: https://docs.wajub.com/fr/developer-tools/cli/skills > Fournissez à votre agent de développement les règles Wajub qu'il devrait autrement deviner. Les Skills pour agents placent les règles d'intégration de Wajub là où votre agent de développement les lit : il ne devine plus des détails comme `event` plutôt que `event.type`, la vérification de la signature avant l'analyse du corps ou les montants en unités principales. Vous avez rarement quelque chose à lancer : la première commande exécutée après l'installation ou la mise à jour de la CLI copie les skills dans les dossiers des agents de développement trouvés sur votre machine, et l'indique. `wajub login` fait de même. **Redémarrez ensuite votre agent** : Claude Code, Codex et les autres lisent leurs skills au démarrage d'une session, jamais pendant. ```bash title="Les commiter avec un projet, pour toute l'équipe" wajub skills install --scope project ``` ## Contenu de l'installation Dix skills sont installés. Chacun contient un fichier `SKILL.md` accompagné d'un document de référence. Un agent charge celui dont la description correspond à la tâche en cours et ignore les autres. | Skill | Domaine couvert | | -------------------- | -------------------------------------------------------------------------------------------------------------- | | `wajub-integrate` | De bout en bout : détecter la stack, choisir le SDK et le mode de checkout, coordonner les différents éléments | | `wajub-payments` | Checkout, remboursements, Checkout hébergé, liens de paiement, Composants intégrés, feuilles mobiles | | `wajub-webhooks` | Signatures, corps bruts, nouvelles tentatives, idempotence, transfert local | | `wajub-payouts` | Transferts, bénéficiaires, suivi du statut des payouts | | `wajub-billing` | Création, livraison et mise à jour des factures, marquage comme payées et annulation | | `wajub-platform-api` | Comptes, clients, solde, litiges, événements, requêtes authentifiées brutes | | `wajub-shield` | Contrôles antifraude, listes de blocage, paramètres de risque, décisions | | `wajub-tax` | Intégrations fiscales et processus liés aux taxes | | `wajub-sync` | Synchronisation Sync, rapprochement, cohérence pilotée par les événements | | `wajub-testing` | Scénarios de sandbox, CLI, transfert de webhooks, vérifications avant le passage en live | La suite est liée à une version de l'API, actuellement `2026-08-01`. Les conseils et la plateforme ne peuvent donc pas diverger silencieusement. ## Emplacement de l'installation Deux dossiers par scope : `.agents/skills`, la convention ouverte que lisent la plupart des agents, et `.claude/skills`, le seul que lit Claude Code. | Scope | Destinations | | --------- | -------------------------------------------------------------------------------------------------- | | `project` | `./.agents/skills`, `./.claude/skills`, à la racine du dépôt git | | `user` | `~/.agents/skills`, `~/.claude/skills` (`$CLAUDE_CONFIG_DIR/skills` si cette variable est définie) | Chaque agent lit sa propre sélection. | Agent | Projet | Utilisateur | Depuis un sous-dossier | | ------------------ | ------------------------------------------ | -------------------------------------------------- | ---------------------- | | Claude Code | `.claude/skills` | `~/.claude/skills`, ou `$CLAUDE_CONFIG_DIR/skills` | Oui | | Codex | `.agents/skills` | `~/.agents/skills` | Oui | | GitHub Copilot CLI | `.agents/skills`, `.claude/skills` | `~/.agents/skills` | Oui | | Gemini CLI | `.agents/skills`, dans un dossier approuvé | `~/.agents/skills` | Non | | OpenCode | les deux | les deux | Oui | | Cursor | les deux | les deux | Non vérifié | | Windsurf | `.agents/skills`, `.claude/skills` | `~/.agents/skills` | Non vérifié | Les deux scopes écrivent les deux dossiers : aucun n'atteint à lui seul Claude Code et Codex, et un agent installé la semaine prochaine, ou celui d'un membre de l'équipe, doit aussi les trouver. Cursor et OpenCode lisent les deux. `--target agents` ou `--target claude` n'en écrit qu'un. Le scope du projet est commité avec votre dépôt. Toute l'équipe et chaque exécution d'agent disposent ainsi des mêmes règles. Le scope utilisateur vous suit d'un dépôt à l'autre. Vous pouvez installer les deux. La copie du projet prévaut lorsqu'un agent lit les deux. ```bash title="Prévisualiser les changements avant leur application" $ wajub skills install --scope project --dry-run Planned destinations (project): agents: /Users/you/code/shop/.agents/skills claude: /Users/you/code/shop/.claude/skills ✓ install wajub-integrate (agents) ✓ install wajub-payments (agents) ✓ install wajub-webhooks (agents) … ``` ## Vérifier les skills installés `wajub doctor` répond à la question qui compte, agent par agent : voit-il les skills, et sinon, quelle commande lancer. `wajub skills status` affiche chaque skill de chaque scope ainsi que son intégrité. ```bash title="wajub skills status" $ wajub skills status Wajub Agent Skills 1.8.0 (API 2026-08-01) Coding agents found: Claude Code and Codex — `wajub doctor` checks which ones see the skills current wajub-integrate project/agents current wajub-payments project/agents modified wajub-webhooks project/agents absent wajub-billing project/agents … ``` `modified` signifie que le dossier ne correspond plus à ce que la CLI a installé, généralement parce qu'une personne a modifié un skill à la main. Une installation ordinaire ne touche pas à ces dossiers afin de ne pas écraser vos changements. `--force` les remplace. | Option | Commande | Effet | | ------------- | ---------------------- | ---------------------------------------------------------------- | | `--scope` | les trois | `project` ou `user`. `status` accepte aussi `all` | | `--target` | `install` | `all` (par défaut), `agents` ou `claude` : les dossiers à écrire | | `--dry-run` | `install`, `uninstall` | Affiche le plan sans rien écrire | | `--force` | `install` | Remplace les dossiers existants ou modifiés localement | | `--force` | `uninstall` | Supprime également les dossiers non gérés | | `-y`, `--yes` | `uninstall` | Ignore la demande de confirmation | | `--json` | les trois | Produit une sortie exploitable par une machine | ## Maintenir les skills à jour Les skills sont fournis dans le package de la CLI. Le scope utilisateur se met à jour de lui-même à la première commande qui suit chaque mise à jour de la CLI, sans toucher aux skills que vous avez modifiés. Le scope d'un projet fait partie de votre dépôt : il ne change que lorsque vous le demandez. ```bash title="Mettre à jour un projet" npm install -g @wajub/cli wajub skills install --scope project ``` Rien n'est installé automatiquement en CI (lorsque `CI` est définie), pour une commande lancée avec `--json`, ni après un refus de votre part. > [!TIP] > **Commitez le scope du projet** > > `.agents/skills` et `.claude/skills` contiennent du texte. Si vous les commitez, un membre de l'équipe qui clone le dépôt reçoit les mêmes conseils sans rien exécuter. Une revue de code montre aussi précisément les changements apportés lors d'une mise à jour. ## Supprimer les skills ```bash title="Désinstaller" wajub skills uninstall --scope project --dry-run wajub skills uninstall --scope project --yes ``` Sans `--force`, les dossiers que vous avez modifiés restent en place, car vos changements sont supposés avoir plus de valeur qu'une suppression complète. Supprimer le scope utilisateur désactive aussi l'installation automatique, pour que la commande suivante ne les remette pas ; `wajub skills install --scope user` la réactive. `WAJUB_NO_SKILLS=1` et `wajub login --no-skills` la désactivent sans rien supprimer. ## Quand un agent ne les voit pas Lancez `wajub doctor` : il nomme chaque agent qui ne voit pas les skills et la commande qui corrige le problème. Les causes habituelles, dans l'ordre : - **L'agent tournait déjà.** Les skills sont lus au démarrage d'une session. Redémarrez-le. - **Les skills n'ont jamais été copiés.** Lancez `wajub skills install --scope user`. - **Gemini CLI et une installation de projet.** Il ne lit les skills d'un projet que dans un dossier approuvé, et seulement dans le dossier où il démarre, pas depuis un sous-dossier du dépôt. Approuvez le dossier quand il le demande et démarrez-le à la racine, ou comptez sur le scope utilisateur. - **`CLAUDE_CONFIG_DIR` est définie.** Claude Code lit alors `$CLAUDE_CONFIG_DIR/skills` au lieu de `~/.claude/skills`. Lancez `wajub skills install --scope user` depuis un shell où elle est définie. - **Le skill existe mais l'agent ne s'en sert pas.** Un agent charge un skill quand sa description correspond à la demande. Formulez la tâche simplement : « vérifie la signature du webhook » plutôt que « corrige l'endpoint ». - [Installation et authentification](https://docs.wajub.com/fr/developer-tools/cli/installation): La première exécution, et l'option `--no-skills`. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): Les règles enseignées par `wajub-webhooks`, expliquées en prose. - [SDKs](https://docs.wajub.com/fr/libraries/sdks): Les bibliothèques que les skills recommandent à l'agent. - [Tests](https://docs.wajub.com/fr/developer-tools/testing): Les vérifications effectuées par `wajub-testing` avant votre passage en live. --- # Déclencher des événements URL: https://docs.wajub.com/fr/developer-tools/cli/triggers > Produisez un véritable paiement dans la sandbox et les événements qui le suivent. `wajub trigger` crée un vrai paiement dans la sandbox avec le numéro de test du résultat demandé : votre handler reçoit exactement les événements qu'aurait produits un véritable payeur. ```bash title="Une commande, un paiement complet" $ wajub trigger payment.succeeded Triggering payment.succeeded … ✓ created payment trx_test_Example0000000000001 ✓ dispatched cm.mtn charge (+237670000000) ✓ payment trx_test_Example0000000000001 is succeeded ``` Le numéro composé révèle le mécanisme : `+237670000000` est le préfixe MTN Cameroun de la sandbox, suivi du suffixe de réussite. Pour un autre résultat, la commande compose un autre suffixe. ```bash title="La même commande avec l'autre résultat" $ wajub trigger payment.failed --amount 2500 Triggering payment.failed … ✓ created payment trx_test_Example0000000000002 ✓ dispatched cm.mtn charge (+237670000002) ✓ payment trx_test_Example0000000000002 is failed ``` ## Les huit événements ```bash title="wajub trigger --list" Triggerable events: customer.created Create a customer customer.updated Create then update a customer payment.cancelled Create and cancel a payment (mobile money canceled) payment.created Create a payment and leave it unpaid payment.failed Create and fail a payment (mobile money failure) payment.succeeded Create and complete a payment (mobile money success) refund.failed Complete a payment whose refund deterministically fails refund.succeeded Complete a payment then refund it (refund succeeds) ``` Huit arguments produisent bien plus de huit événements, car chacun exécute un véritable parcours. | Déclencheur | Numéro composé | Événements reçus par votre endpoint, dans l'ordre | | ------------------- | --------------- | ---------------------------------------------------------------------------------------------- | | `payment.created` | Aucun | `payment.created` | | `payment.failed` | `+237670000002` | `payment.created`, `payment.processing`, `payment.failed` | | `payment.cancelled` | `+237670000004` | `payment.created`, `payment.processing`, `payment.cancelled` | | `payment.succeeded` | `+237670000000` | `payment.created`, `payment.processing`, `payment.succeeded`, `balance.updated`, `fee.charged` | | `refund.succeeded` | `+237670000000` | Les cinq précédents, puis `refund.created`, `refund.succeeded`, `balance.updated` | | `refund.failed` | `+237670000009` | Les cinq événements du paiement, puis `refund.created`, `refund.failed` | Le tout premier déclenchement sur un compte émet également `customer.created`, car la CLI crée le client `CLI Trigger` qu'elle réutilise ensuite. > [!TIP] > **La chaîne est l'enseignement principal, pas un effet secondaire** > > Un véritable paiement se comporte de la même manière. Si votre handler traite uniquement > `payment.succeeded`, vous découvrez ici que quatre autres types arrivent déjà sans être traités, > et que `fee.charged` manquait dans votre registre. ## Adapter la ressource créée | Option | Valeur par défaut | Effet | | -------------- | ----------------- | -------------------------------------------------------------------------------------------------- | | `--amount` | `5000` | Montant de la ressource créée | | `--currency` | `XAF` | Devise | | `--channel` | `cm.mtn` | Réseau à débiter. Le numéro composé prend le préfixe sandbox de cet opérateur et garde son suffixe | | `--phone` | Déduit | Remplace le numéro du payeur. Option avancée qui détermine le résultat | | `-d`, `--data` | | Champ `key=value` supplémentaire sur la ressource, répétable | | `--list` | | Affiche la liste ci-dessus et s'arrête | ```bash title="Se rapprocher de votre propre trafic" wajub trigger payment.succeeded --amount 250000 --currency XOF --channel ci.orange wajub trigger customer.created -d name="Boutique Akwa" -d email=contact@example.com wajub trigger payment.succeeded -d reference=order-4172 -d description="Order #4172" ``` L'option `-d reference=order-4172` rend le test réaliste. Votre handler retrouve la commande comme en production, sans traitement spécial pour un faux paiement. > [!WARNING] > **`--phone` remplace le résultat attendu** > > Le numéro détermine le comportement de la sandbox. Ainsi, `wajub trigger payment.succeeded --phone > +237670000002` crée un paiement qui **échoue**. Utilisez cette option pour obtenir des résultats > absents des huit arguments, comme une expiration. Consultez les > [scénarios de test](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios) pour tous les suffixes. ## Événements impossibles à déclencher directement La liste est volontairement courte. Un événement y figure uniquement si la CLI peut le produire sans configuration supplémentaire. Produisez les autres comme dans votre propre code. | Événement | Méthode | | ----------------- | ------------------------------------------------------------------------------------- | | `transfer.*` | `wajub beneficiaries create`, puis `wajub transfers create` | | `dispute.*` | Les litiges sont ouverts par l'acquéreur, pas par vous | | `invoice.*` | `wajub invoices create` avec une clé live, car les factures n'existent pas en sandbox | | `link.*` | `wajub links create` avec une clé live, pour la même raison | | `account.*` | `wajub accounts create`, puis l'onboarding du marchand, pour les plateformes Sync | | `payment.expired` | Laissez un paiement `pending` atteindre la fin de sa période | | `payment.split.*` | `wajub post /payments/{id}/splits` sur un paiement de la sandbox | ## Clés sandbox uniquement `wajub trigger` refuse toute clé qui n'est pas une clé sandbox, avant d'envoyer la moindre requête. Avec un profil live actif, ou une `WAJUB_API_KEY` live exportée, la commande s'arrête là : ```bash title="Avec une clé live" $ wajub trigger payment.succeeded › Error: `wajub trigger` only works with a sandbox API key (sk_test…). ``` Choisissez le profil sandbox pour la commande, et vérifiez qu'aucune clé live n'est exportée, puisque `WAJUB_API_KEY` l'emporte sur `--profile`. ```bash title="Soyez explicite lorsque c'est important" wajub config # which profile is default? wajub trigger payment.succeeded --profile sandbox ``` ## La boucle ```bash title="Deux terminaux" # 1 wajub listen --forward-to localhost:3000/webhooks/wajub # 2 wajub trigger payment.succeeded wajub trigger payment.failed wajub trigger refund.succeeded ``` Trois commandes couvrent les cas souvent mal gérés : la réussite, l'échec qui doit libérer la réservation et le remboursement qui ne doit pas être pris pour un nouveau paiement. - [Recevoir des webhooks en local](https://docs.wajub.com/fr/developer-tools/cli/listen): L'autre moitié de la boucle. - [Scénarios de test](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios): Tous les numéros et cartes de la sandbox avec leur résultat. - [Catalogue des événements](https://docs.wajub.com/fr/developer-tools/webhooks/events): Le contenu de chacun de ces types. - [Mode test](https://docs.wajub.com/fr/developer-tools/testing/sandbox-mode): Ce que la sandbox simule et ce qu'elle ne simule pas. --- # Événements URL: https://docs.wajub.com/fr/developer-tools/konsole/event-stream > Ce que la plateforme a enregistré et les endpoints qu'elle a atteints. Les événements forment le premier onglet de la vue Webhooks de Konsole : l'historique de ce qui s'est passé sur votre compte, comme un paiement réussi ou un transfert échoué. Vérifiez ici qu'un événement a bien été créé avant de chercher pourquoi votre endpoint ne s'est pas déclenché. ## Contenu d'une ligne | Colonne | Remarque | | -------------------------- | ---------------------------------------------------------------------------------------- | | Identifiant de l'événement | `evt_` en mode live, `evt_test_` dans la sandbox | | Type | `payment.succeeded` et le reste du [catalogue](https://docs.wajub.com/fr/developer-tools/webhooks/events) | | Objet | La ressource concernée, avec son identifiant | | Livraisons | Jusqu'à cinq tentatives récentes, chacune avec l'endpoint, le code de statut et la durée | | En attente | Le nombre d'endpoints qui doivent encore répondre | | Version de l'API | La version pour laquelle le payload a été construit | La colonne des livraisons rend cette vue plus utile que la liste brute des événements de l'API : vous voyez l'événement et son résultat sur la même ligne. ## Filtres | Filtre | Élément recherché | | -------------------------- | ------------------------------------------------------------------------------------------------- | | Recherche | L'identifiant de l'événement, le type, l'identifiant de l'objet ou celui de la requête | | Type | Un type précis, choisi parmi ceux réellement produits par votre compte | | Catégorie | Tout ce qui se trouve sous un préfixe, par exemple tous les types `payment.` | | Date de début, date de fin | Des journées calendaires entières | | Statut de livraison | `delivered` signifie que rien n'est en attente, `pending` qu'au moins un endpoint n'a pas répondu | Cinquante résultats par page, du plus récent au plus ancien. Le sélecteur de type repose sur votre historique. Il propose uniquement les types réellement produits. Vous repérez ainsi plus rapidement un type manquant qu'en parcourant le catalogue. ## Deux types présents uniquement ici `payment.checkout_page_opened` et `payment.redirected_to_callback` sont enregistrés comme événements et visibles dans cette liste, mais ne sont jamais envoyés à un endpoint. Ils permettent de reconstituer un checkout après coup : le moment où le payeur a ouvert la page et son éventuel retour vers votre URL de retour. Si un paiement n'a jamais réussi et qu'il n'existe aucun événement `payment.checkout_page_opened`, le payeur n'a jamais atteint la page. Le problème vient généralement du lien ou de la redirection, pas du paiement. ## Relancer une livraison Chaque livraison de la page d'un événement a son propre bouton **Renvoyer**, et l'onglet **Livraisons** de [Webhooks](https://docs.wajub.com/fr/developer-tools/konsole/webhook-tester) propose le même. Vous relancez une livraison, donc l'événement repart vers cet endpoint seulement : sur un compte avec deux endpoints, celui qui fonctionne ne le reçoit pas une deuxième fois. Les renvois ne sont pas décomptés de votre plan, mais un même événement repart vers le même endpoint au plus une fois toutes les 5 minutes, depuis l'une ou l'autre page ou depuis l'API : un renvoi dans ce délai est refusé, avec un message qui indique quand réessayer. > [!WARNING] > **La relance compte comme une nouvelle tentative** > > Elle garde le même `X-Wajub-Delivery-Id` et le même identifiant d'événement : un handler qui déduplique sur l'un ou l'autre répond `200` sans refaire le travail s'il a déjà enregistré l'événement. La relance sert aux livraisons que votre endpoint n'a pas acceptées. ## Exportation Vous pouvez exporter les filtres actuels au format CSV ou JSON. Cette opération est décomptée du quota **Exports par mois** de votre plan. Un exemple utile : filtrez sur `delivery_status: pending` pendant les sept derniers jours, puis exportez les résultats. Cette liste correspond exactement aux événements que votre intégration n'a pas fini de traiter. - [Catalogue des événements](https://docs.wajub.com/fr/developer-tools/webhooks/events): Chaque type, son déclencheur et son contenu. - [Webhooks](https://docs.wajub.com/fr/developer-tools/konsole/webhook-tester): Les livraisons créées à partir de ces événements. - [Journaux API](https://docs.wajub.com/fr/developer-tools/konsole/log-explorer): L'appel qui a produit l'événement. - [Nouvelles tentatives et ordre](https://docs.wajub.com/fr/developer-tools/webhooks/retries): Pourquoi un événement peut être livré deux fois. --- # Konsole URL: https://docs.wajub.com/fr/developer-tools/konsole > Quatre vues sur ce que votre intégration a réellement effectué. Konsole est la partie du Dashboard qui répond à la question « que s'est-il passé ? » : elle montre chaque appel d'API, événement, tentative de livraison d'un webhook et décision de routage de votre intégration. ## Les quatre vues | Vue | Réponse apportée | | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | [Vue d'ensemble](https://docs.wajub.com/fr/developer-tools/konsole/overview) | Y a-t-il un problème en ce moment ? | | [Journaux API](https://docs.wajub.com/fr/developer-tools/konsole/log-explorer) | Qu'ai-je envoyé précisément et quelle réponse ai-je reçue ? | | [Webhooks](https://docs.wajub.com/fr/developer-tools/konsole/webhook-tester) | La plateforme a-t-elle enregistré l'[événement](https://docs.wajub.com/fr/developer-tools/konsole/event-stream), mon endpoint l'a-t-il reçu et a-t-il répondu ? | | [Journal de routage](https://docs.wajub.com/fr/developer-tools/konsole/routing-log) | Quel prestataire a traité ce paiement et pourquoi ? Live uniquement | Les événements ne sont pas une vue à part : ils forment le premier onglet de Webhooks, à côté de **Livraisons** et de **Points de terminaison**. ## Partir du symptôme | Symptôme | Ouvrir | Rechercher | | ------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------- | | Un appel a renvoyé une erreur que vous ne comprenez pas | Journaux API | La requête, le corps de la réponse, le message d'erreur | | Un paiement est resté `pending` | Webhooks, Événements | La présence de `payment.processing` et de `payment.failed` | | Votre handler ne s'est jamais exécuté | Webhooks, Livraisons | Le code de statut renvoyé par votre endpoint ou l'absence d'une ligne | | Un paiement a réussi sur le mauvais rail | Journal de routage | La liste des candidats et la raison pour laquelle le premier a été ignoré | | Une opération est lente sans raison évidente | Vue d'ensemble | Les cartes d'anomalie, puis les logs associés | ## La sandbox et le mode live sont deux ensembles distincts Konsole affiche un seul environnement à la fois selon le sélecteur du Dashboard. Un paiement de sandbox n'apparaît jamais dans les logs du mode live : la sandbox et le mode live sont entièrement séparés. Vous n'avez donc aucun filtre à appliquer et aucun risque de les mélanger. > [!WARNING] > **Le routage n'existe qu'en mode live** > > La vue Journal de routage est réservée au mode live. Les paiements de sandbox ne passent pas par la sélection d'un prestataire. Aucune décision n'est donc enregistrée. ## Qui peut y accéder Konsole exige l'autorisation **View Webhooks**. Les actions proposées, comme créer un endpoint, révéler un secret, relancer une livraison, lancer **Diagnostiquer** ou exporter des logs ou des événements, exigent **Manage Webhooks**. Un membre de l'équipe qui ne possède aucune de ces autorisations ne voit pas Konsole. ## Tarification Une seule action dans Konsole est mesurée selon votre plan : exporter des logs ou des événements au format CSV ou JSON, décompté du quota **Exports par mois**. Il est calculé par mois et par équipe, et il n'est pas propre à Konsole : toutes les exportations du Dashboard (paiements, transferts, factures, clients, revenus…) puisent dans le même quota. Consultez [Plafonds et quotas](https://docs.wajub.com/fr/resources/limits) pour connaître la valeur de chaque plan. Relancer manuellement la livraison d'un webhook n'est décompté sur aucun plan. Un événement repart vers le même endpoint au plus une fois toutes les 5 minutes, que vous le renvoyiez depuis Konsole ou avec `POST /events/{id}/resend`. - [Vue d'ensemble](https://docs.wajub.com/fr/developer-tools/konsole/overview): Les cartes d'anomalie et le diagnostic en un clic associé. - [Journaux API](https://docs.wajub.com/fr/developer-tools/konsole/log-explorer): Chaque requête, avec le corps envoyé et celui reçu. - [Webhooks](https://docs.wajub.com/fr/developer-tools/konsole/webhook-tester): Endpoints, livraisons, relances et test de connectivité. - [Surveillance](https://docs.wajub.com/fr/resources/monitoring): Les mêmes signaux, surveillés automatiquement plutôt qu'à l'œil. --- # Journaux API URL: https://docs.wajub.com/fr/developer-tools/konsole/log-explorer > Chaque requête effectuée, avec les deux corps et la raison de son échec. Chaque appel à l'API est enregistré : la méthode, le chemin, le statut, sa durée, les en-têtes et les deux corps. Lorsqu'un appel ne produit pas le résultat attendu, cette vue est la seule qui puisse vous indiquer ce que vous avez réellement envoyé. ## Filtres Neuf filtres peuvent être combinés. Ils figurent tous dans l'URL, ce qui permet de partager une vue filtrée. | Filtre | Élément recherché | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | Recherche | Recherche en texte intégral dans l'URL, l'identifiant de la requête, l'adresse IP, la méthode et le message d'erreur | | Statut | `success` pour un code inférieur à 400, `error` à partir de 400, ou un code précis | | Méthode | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` | | Endpoint | Une partie de l'URL | | Adresse IP | Une partie de l'IP telle que Konsole l'affiche. L'adresse de l'appelant est enregistrée sous forme pseudonymisée, pas en clair | | Date de début, date de fin | Des journées calendaires entières | | Durée minimale, durée maximale | Des millisecondes, pour trouver les appels les plus lents | > [!NOTE] > **Il n'existe aucun langage de requête** > > La recherche porte sur du texte brut, pas sur une syntaxe. `status:5xx` ne renvoie aucun résultat, car cette chaîne est recherchée telle quelle. Utilisez le sélecteur de statut pour les codes et le champ de recherche pour les chaînes de caractères. Les résultats sont paginés par groupes de 50, du plus récent au plus ancien. Les logs sont conservés 90 jours, en live comme en sandbox : exportez ce que vous devez garder au-delà. ## Contenu d'une ligne | Champ | Remarque | | --------------------------------- | ------------------------------------------------------------------------- | | ID de requête | L'identifiant de corrélation, également renvoyé dans `X-Request-Id` | | Méthode, endpoint et URL complète | L'URL complète inclut les paramètres d'URL | | Statut | Le code et son libellé | | Durée | Durée côté serveur, sans votre réseau | | Adresse IP | L'adresse de l'appelant, sous forme pseudonymisée | | Erreur | Présente uniquement si l'appel a échoué | | Version de l'API | La version utilisée pour traiter cet appel | | Clé API | La clé utilisée : ses 15 premiers caractères, comme la page Keys la liste | | Compte connecté | Défini lorsque l'appel agit sur un compte connecté | La clé permet de trouver rapidement les appels effectués par un composant oublié. Un ancien script qui utilise encore une clé renouvelée apparaît sous sa propre clé. ## Le panneau de détail La sélection d'une ligne ouvre l'enregistrement complet : en-têtes de requête, en-têtes de réponse, corps de la requête, corps de la réponse, agent utilisateur et, quand l'appel a échoué, le message d'erreur. Aucune trace d'exécution n'est conservée. Vous pouvez ainsi lever vos propres doutes. Le corps affiché correspond à ce que l'API a reçu après le traitement par votre framework, votre client HTTP et votre sérialiseur. > [!WARNING] > **Les gros corps ne sont pas conservés, ni les corps qui ne sont pas du JSON** > > Un corps de requête de plus d'environ 250 Ko, ou une réponse de plus de 500 Ko, n'est pas > enregistré du tout : le log garde à sa place `{"_truncated": true, "_size": …}`, la taille en > octets. Une réponse qui n'est pas du JSON (un fichier, une page) est enregistrée vide. En dessous > de ces tailles, les deux sont conservés en entier. ## Données masquées et données volontairement visibles Les secrets sont masqués avant l'écriture du log. Aucune donnée sensible n'est donc stockée. | Masqué | Laissé visible | | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | En-têtes d'authentification (`Authorization`, `X-Sync`) et cookies | Tous les autres en-têtes | | Mots de passe, clés privées et codes de sécurité de carte (`password`, `private_key`, `cvv`, `cvc`), où qu'ils apparaissent | `phone`, `email`, `name`, `address` | | Codes PIN et numéros de carte : tout champ nommé comme un PIN ou un PAN, `card.number` à n'importe quel niveau et un champ `number` isolé | `account_number`, `iban`, `phone_number` | | Expiration de la carte (`exp_month`, `exp_year`, `expiry_date`) | Montants, devises, métadonnées, références | Un champ dont le nom ressemble à un code PIN ou à un numéro de carte peut aussi s'afficher `***REDACTED***`. > [!TIP] > **Votre clé ne figure jamais dans le log** > > Pour savoir quelle clé a effectué un appel, utilisez la clé API affichée sur le log. L'en-tête `Authorization` lui-même est enregistré sous la forme `***REDACTED***`. ## Faire le lien avec vos propres logs Chaque réponse de l'API contient `X-Request-Id`. Enregistrez-le de votre côté. Toute discussion avec le support ou recherche dans Konsole devient alors une simple recherche au lieu d'une exploration des horodatages. **Conserver l'identifiant de requête** ```bash curl -i https://api.wajub.com/payments \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -d amount=25000 -d currency=XAF \ | grep -i x-request-id ``` ```javascript const res = await fetch('https://api.wajub.com/payments', { method: 'POST', headers, body }); logger.info({ wajubRequestId: res.headers.get('x-request-id') }, 'payment created'); ``` ```python res = requests.post("https://api.wajub.com/payments", headers=headers, json=body) logger.info("payment created", extra={"wajub_request_id": res.headers.get("X-Request-Id")}) ``` ```php $response = Http::withToken($key)->post('https://api.wajub.com/payments', $body); Log::info('payment created', [ 'wajub_request_id' => $response->header('X-Request-Id'), ]); ``` ```go resp, err := client.Do(req) if err != nil { return err } defer resp.Body.Close() log.Printf("payment created, wajub_request_id=%s", resp.Header.Get("X-Request-Id")) ``` ## Exportation Vous pouvez exporter les filtres actuels au format CSV ou JSON, avec une limite de 10 000 lignes par exportation. Le CSV contient l'identifiant, la méthode, le chemin, le statut, la durée, l'IP pseudonymisée, l'erreur et l'horodatage. Le JSON contient les enregistrements complets. Exporter demande la permission **Manage Webhooks**, pas seulement celle qui permet de lire les logs. Les exportations sont décomptées du quota **Exports par mois** de votre plan, que partagent toutes les exportations du Dashboard (paiements, transferts, factures, clients, Konsole…). Une fois le quota dépassé, l'exportation renvoie une erreur `403` explicite, pas un fichier tronqué. - [Événements](https://docs.wajub.com/fr/developer-tools/konsole/event-stream): Ce que la plateforme a enregistré, par opposition à ce que vous avez appelé. - [Gestion des erreurs](https://docs.wajub.com/fr/best-practices/error-handling): La signification de chaque code de statut et la marche à suivre. - [Plafonds et quotas](https://docs.wajub.com/fr/resources/limits): La raison pour laquelle certaines lignes renvoient une erreur 429. - [Vue d'ensemble](https://docs.wajub.com/fr/developer-tools/konsole/overview): Les cartes qui renvoient vers ces lignes. --- # Vue d'ensemble URL: https://docs.wajub.com/fr/developer-tools/konsole/overview > Ce que la plateforme a remarqué sur votre intégration avant vous. La page Vue d'ensemble est le premier écran de Konsole. Elle affiche cinq chiffres pour la période sélectionnée, puis une liste de cartes d'anomalie. Chaque carte correspond à une règle déclenchée par votre propre trafic. ## Les cinq chiffres | Chiffre | Méthode de calcul | | ---------------- | ------------------------------------------------------------------------------------------------ | | Demandes | Chaque appel d'API de la période, pour l'environnement actuel | | Erreurs | Les appels qui ont renvoyé `400` ou un code supérieur | | Taux d'erreur | La part des erreurs dans les requêtes | | P95 Latence | Le 95e percentile de `duration_ms`, qui correspond le mieux à ce que ressentent les utilisateurs | | Webhooks échoués | Les livraisons marquées `failed` sur la période, rapportées à l'ensemble des livraisons | Demandes est accompagné d'un écart par rapport à la période précédente de même durée. Une vue sur sept jours se compare donc aux sept jours précédents. Taux d'erreur et P95 Latence restent vides sous 20 requêtes sur la période : sur quelques appels, un seul échec ressemblerait à une panne. > [!TIP] > **Consultez le p95** > > Le p95 montre les valeurs extrêmes qu'une moyenne masquerait. S'il affiche 4 200 ms, un appel sur vingt prend plus de quatre secondes. Ce sont ces appels que vos clients abandonnent. ## Les cartes d'anomalie Neuf règles s'exécutent sur votre compte. Les cartes sont classées par gravité et la page affiche les trois premières ; le nombre à côté du titre de la section compte toutes les cartes déclenchées. Chaque carte mène à la vue qui présente les lignes concernées. | Carte | Condition de déclenchement | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | p95 élevé sur un endpoint | p95 supérieur à 2 s au cours des dernières 24 heures, sur au moins 2 appels. Gravité élevée au-dessus de 5 s | | Taux d'erreur élevé sur un endpoint | Au moins un quart des appels vers ce chemin ont renvoyé une erreur, sur au moins 2 appels | | Échecs de livraison de webhooks | Au moins 3 échecs vers un endpoint au cours de la dernière heure | | Erreurs d'authentification | Réponses `401` au cours des dernières 24 heures. Gravité élevée à partir de 20 | | Endpoint de webhook inactif | Un endpoint créé depuis plus de 14 jours qui n'a rien reçu depuis 14 jours | | API key inutilisée | Une clé créée depuis plus de 30 jours, jamais utilisée ou inutilisée depuis 60 jours | | Secret de signature vieux de plus de 6 mois | Le secret de l'endpoint n'a pas été renouvelé depuis 180 jours | | Endpoint de webhook sans HTTPS | Un endpoint live dont l'URL commence par `http://` : ses livraisons circulent en clair. Live uniquement | | Dégradation de la latence | La moyenne d'hier dépasse nettement la valeur de référence sur 7 jours | > [!NOTE] > **Certaines cartes concernent l'hygiène, pas les incidents** > > Une clé inutilisée et un secret vieux de six mois ne constituent pas des pannes. Ils vous rappellent que le meilleur moment pour réduire votre exposition est avant toute fuite. ## Le diagnostic en un clic Les cartes liées aux webhooks, à l'authentification et à la latence possèdent un bouton **Diagnostiquer**. Il lance un ensemble de vérifications côté serveur et fournit un verdict. Vous n'avez pas à parcourir les logs vous-même. Pour un endpoint de webhook, cet ensemble comporte sept vérifications, dans cet ordre. 1. **L'endpoint existe** Il n'a pas été supprimé depuis la création de la carte. 2. **L'endpoint est activé** Un endpoint désactivé ne reçoit rien. C'est l'explication la plus fréquente des endpoints silencieux. 3. **L'URL est valide** Une URL impossible à analyser a été mal copiée. 4. **HTTPS est obligatoire en mode live** Les livraisons en mode live sont envoyées uniquement en HTTPS. 5. **Le secret de signature est configuré** Sans lui, rien ne peut être signé ni envoyé. 6. **L'endpoint est accessible** Wajub envoie immédiatement une requête `HEAD` sortante vers votre URL. 7. **Taux d'échec récent** Le nombre de tentatives récentes qui ont échoué vous aide à distinguer un incident passager d'une panne. Le verdict compte les échecs et les simples avertissements. Un échec désigne un problème à corriger avant une nouvelle tentative. Un avertissement indique un point à examiner. Pour une carte d'authentification, l'ensemble compte les réponses `401` des dernières 24 heures. Pour une carte de latence, il vérifie la taille de l'échantillon, puis liste les endpoints les plus lents des dernières 24 heures. ## Fraîcheur des chiffres Les chiffres ne sont pas instantanés : si vous venez de corriger un endpoint et que la carte est toujours affichée, laissez-lui un moment avant de conclure que la correction n'a pas fonctionné. - [Journaux API](https://docs.wajub.com/fr/developer-tools/konsole/log-explorer): Les lignes à l'origine des cartes de latence et d'erreur. - [Webhooks](https://docs.wajub.com/fr/developer-tools/konsole/webhook-tester): L'endpoint que le diagnostic vient de sonder. - [Surveillance](https://docs.wajub.com/fr/resources/monitoring): Transformez ces signaux en alertes que vous n'avez pas à rechercher. - [Plafonds et quotas](https://docs.wajub.com/fr/resources/limits): Les plafonds à l'origine des erreurs de limite de requêtes que vous observez peut-être. --- # Routage URL: https://docs.wajub.com/fr/developer-tools/konsole/routing-log > Les prestataires envisagés pour un paiement, dans l'ordre, et les raisons de ce classement. Lorsqu'un paiement peut passer par plusieurs prestataires, Wajub les classe et essaie le premier. La vue Journal de routage conserve ce classement : chaque candidat et la raison de sa place, les candidats ignorés et les tentatives qui ont suivi. > [!WARNING] > **Mode live uniquement** > > La vue Journal de routage est réservée au mode live. Les paiements de sandbox ne passent pas par la sélection d'un prestataire. Un compte de sandbox ne contient donc aucune donnée ici. ## Filtres | Filtre | Élément recherché | | ----------- | --------------------------------------------------------------------------------------------- | | Recherche | L'identifiant du paiement | | Canal | `cm.mtn`, `ci.orange` et les autres | | Fournisseur | Celui qui a été sélectionné | | Date | Des journées calendaires entières | | Résultat | **A eu un repli**, **Fournisseur ignoré par le coupe-circuit** ou **Aucun candidat éligible** | Le filtre de résultat est un raccourci utile à connaître. | Résultat | Signification | | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **A eu un repli** | Plusieurs candidats ont été classés. La cascade disposait donc d'une solution de repli | | **Fournisseur ignoré par le coupe-circuit** | Au moins un prestataire a été ignoré parce que Wajub l'avait mis en pause sur ce canal après des échecs répétés | | **Aucun candidat éligible** | Aucun candidat n'était admissible. Ces paiements ont échoué avant tout appel à un prestataire | Filtrer sur **Aucun candidat éligible** pendant une semaine est le moyen le plus rapide d'auditer votre configuration. Chaque ligne correspond à un paiement que vous n'auriez pas pu accepter. ## Ce qu'affiche une décision Sélectionnez une ligne pour ouvrir la décision. Elle affiche le paiement (son identifiant, son canal, son montant et sa devise, avec **Voir paiement** pour l'ouvrir), puis, sous **Pourquoi le routeur a classé les candidats ainsi**, les candidats classés, et en dessous les tentatives. | Ce que vous voyez | Ce que cela indique | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **BLOQUÉ** | Une restriction de pays sur votre compte a arrêté le paiement avant qu'un prestataire soit envisagé | | **Ignoré (circuit ouvert)** | Les prestataires que Wajub avait mis en pause sur ce canal après des échecs répétés. Ils n'ont pas été classés | | Les candidats classés | Toutes les connexions qui pouvaient traiter le paiement, dans l'ordre où elles devaient être essayées. La première a le rang 1 | | **Tentatives** | Les appels réellement envoyés aux prestataires, dans l'ordre, avec le résultat de chacun | Chaque candidat affiche sa **Priorité** et son **Score**, puis des badges qui expliquent sa place. | Sur un candidat | Signification | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Priorité** | La priorité de cette connexion sur votre compte. Un secours qui remplace la cible de sa règle prend la plus élevée des deux | | **Score** | La comparaison que fait Wajub du coût et de la réussite récente. Il n'ordonne que les connexions de même priorité, le plus élevé d'abord, et une règle ou une politique de canal passe avant lui | | **Règle correspondante** | Une de vos règles de routage l'a placé, comme cible ou comme secours qui remplace cette cible | | **Repli** | C'est le prestataire de secours d'une règle, essayé juste après la cible de la règle ou à sa place | | **Politique du canal** | La politique du canal l'a placé | | **Coût le plus bas** | C'était la connexion la moins chère pour ce paiement, d'après les tarifs que vous avez saisis | | Badge de réussite récente | Il a obtenu de bons résultats sur ce canal récemment | Un candidat sans badge **Règle correspondante** ni **Politique du canal** a été ordonné par sa priorité, puis son score, puis son poids. La lecture des badges indique si un paiement a emprunté un rail en raison de votre règle, de la politique du canal, de son coût inférieur ou des échecs récents du prestataire attendu. ## Trois points à examiner **Un candidat classé premier alors que vous ne l'attendiez pas.** Lisez d'abord ses badges. **Règle correspondante** signifie qu'une de vos règles de routage correspond : ouvrez **Orchestration, Règles de routage** pour voir celle qui s'applique à ce canal. **Politique du canal** signifie que la politique du canal l'a ordonné. Sans l'un ni l'autre, la priorité, le score et le poids ont décidé. **Un prestataire absent de la liste des candidats.** Il n'a pas été ignoré, il n'a jamais été admissible. La cause se situe avant le routage : prise en charge de la devise, du canal ou du pays, ou prestataire non activé sur votre compte. Le simulateur de routage d'**Orchestration, Règles de routage**, disponible à partir du plan Growth, indique la raison de chaque connexion qu'il écarte. Une connexion que vous avez vous-même suspendue, ou un prestataire inactif, n'y apparaît pas du tout. **Un prestataire sous Ignoré (circuit ouvert).** Wajub l'avait mis en pause sur ce canal parce qu'il échouait de façon répétée. Il revient de lui-même dès qu'il fonctionne de nouveau. > [!NOTE] > **BLOQUÉ n'est pas une décision du prestataire** > > Il s'agit d'une restriction au niveau du compte, vérifiée avant qu'un prestataire soit envisagé. La liste des candidats est vide et aucun prestataire n'a été contacté. ## La chaîne de tentatives Sous le classement figurent les actions réellement effectuées : une ligne par appel à un prestataire, dans l'ordre, avec le résultat de chacun. Pour un paiement réussi avec le deuxième candidat, l'échec du premier apparaît au-dessus. C'est tout l'intérêt d'une cascade vérifiable. - [Règles de routage](https://docs.wajub.com/fr/orchestration/routing-rules): Les règles derrière un badge Règle correspondante. - [Cascade et repli](https://docs.wajub.com/fr/orchestration/waterfall-fallback): Comment le classement devient une suite de tentatives. - [Prestataires](https://docs.wajub.com/fr/orchestration/providers): Les conditions qui rendent d'abord un prestataire admissible. - [Journaux API](https://docs.wajub.com/fr/developer-tools/konsole/log-explorer): La requête à l'origine de tout ce processus. --- # Webhooks URL: https://docs.wajub.com/fr/developer-tools/konsole/webhook-tester > Les endpoints, chaque tentative de livraison et la manière d'en relancer une. La vue Webhooks comporte trois onglets : **Événements**, ce que votre compte a produit, **Livraisons**, les envois faits à partir de ces événements, et **Points de terminaison**, les adresses qui les ont reçus. Les événements disposent de [leur propre page](https://docs.wajub.com/fr/developer-tools/konsole/event-stream). Celle-ci traite des deux autres onglets. ## Livraisons Une ligne correspond à une tentative, pas à un événement. Une livraison relancée trois fois produit trois lignes qui partagent le même identifiant de livraison. | Colonne | Remarque | | --------------- | ------------------------------------------------------------------------------------------ | | Statut | `success`, `retrying` ou `failed` | | Code de réponse | La réponse de votre endpoint, vide en cas d'erreur réseau | | Durée | Le temps de réponse de votre endpoint. Une ligne à 30 000 ms correspond à un délai dépassé | | Tentative | 1 pour le premier essai, puis un de plus à chaque nouvelle tentative et à chaque relance | | Endpoint | L'URL concernée, lorsque vous en avez plusieurs | Filtres : recherche dans l'événement, statut, endpoint et plage de dates en journées entières. Cinquante résultats par page. Le panneau de détail contient le payload envoyé et le corps renvoyé par votre endpoint. Vous pouvez ainsi découvrir que votre erreur `500` contient une stack trace lisible directement ici. ## Relancer des livraisons Deux méthodes sont proposées, sur tous les plans, sans quota mensuel. | Action | Portée | | -------------------------------- | ---------------------------------------------------------------------------------------------------- | | Renvoyer | Une livraison | | Relancer les livraisons échouées | Jusqu'à 100 livraisons échouées en une fois, sur une période et éventuellement pour un seul endpoint | **Relancer les livraisons échouées** sélectionne uniquement les livraisons dont le statut est `failed`, dans la période choisie, qui couvre par défaut les dernières 24 heures. Filtrez la liste sur `failed` pour voir le bouton : avec des lignes cochées, il relance celles-ci ; sans aucune, il demande la période. Une livraison dont l'endpoint a accepté l'événement depuis n'est pas renvoyée : une relance isolée le dit, et un lot l'ignore. Un événement qui a échoué plusieurs fois ne part qu'une fois. Un même événement repart vers le même endpoint au plus une fois toutes les 5 minutes, que vous le renvoyiez d'ici, depuis la page de l'événement ou avec `POST /events/{id}/resend`. Dans ce délai, **Renvoyer** indique combien de minutes il reste. **Relancer les livraisons échouées** ignore ces livraisons et les compte dans son message ou, quand toutes celles qu'il trouve sont dans ce délai, indique quand les relancer. > [!WARNING] > **Corrigez l'endpoint avant de relancer les livraisons** > > Une relance renvoie le même payload vers la même URL. Si le handler produit encore une exception, vous n'avez fait que reproduire l'échec, et cet événement ne peut plus repartir vers cet endpoint pendant 5 minutes. Déployez la correction, relancez une livraison, vérifiez sa réussite, puis relancez les autres en lot. ## Endpoints La création d'un endpoint exige une URL et une liste de types d'événement. | Champ | Règle | | ----------- | -------------------------------------------------------------------------------------------------- | | URL | Une URL valide, limitée à 2 048 caractères et qui ne pointe pas vers une adresse privée ou interne | | Événements | Au moins un type parmi ceux proposés par Konsole | | Description | Du texte libre, utile lorsque vous avez plusieurs endpoints | > [!NOTE] > **Vérifiez les noms d'événements envoyés par l'API** > > Le sélecteur propose uniquement des types valides. Avec `POST /webhooks`, vérifiez chaque nom dans le [catalogue des événements](https://docs.wajub.com/fr/developer-tools/webhooks/events) : un type mal orthographié ne correspond jamais à rien. Les adresses privées et internes sont volontairement refusées. Un endpoint qui pointe vers `localhost` ou vers une plage privée permettrait aux webhooks d'atteindre des réseaux privés. Pour le développement local, utilisez [`wajub listen`](https://docs.wajub.com/fr/developer-tools/cli/listen). ### Le secret Chaque endpoint possède son propre secret de signature, affiché une seule fois lors de sa création. Ensuite, **Afficher** l'affiche à nouveau après la saisie d'un code de vérification de sécurité. Cette action est enregistrée. Pour le renouveler, utilisez **Régénérer le secret de signature** sur la page de l'endpoint, dans son menu d'actions ou avec **Régénérer** à côté du secret, derrière la même vérification de sécurité, ou `POST /webhooks/{id}/rotate-secret` depuis l'API. Le nouveau secret n'est affiché qu'une fois. Depuis le Dashboard, vous pouvez garder l'ancien secret actif pendant 24 heures. Chaque livraison porte alors une signature faite avec chacun : le nouveau dans `X-Wajub-Signature`, l'ancien dans `X-Wajub-Signature-Previous`, au même format. Un gestionnaire qui n'a encore que l'ancien secret continue d'accepter les livraisons le temps de déployer le nouveau, comme l'explique [Le secret](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification#the-secret). Sans cette période, et toujours depuis l'API, le nouveau secret remplace l'ancien immédiatement. Chaque tentative envoyée ensuite est signée avec lui, y compris les nouvelles tentatives d'événements envoyés avant le renouvellement : tant que votre gestionnaire ne le connaît pas, il les rejette. Faites-lui accepter deux secrets avant de renouveler, ajoutez le nouveau dès qu'il s'affiche, puis retirez l'ancien. Une livraison refusée entre-temps est retentée, signée avec le nouveau secret. La carte « Secret de signature de plus de 6 mois » de la vue d'ensemble compte depuis le dernier renouvellement. ### Passer un endpoint en live Les endpoints de sandbox et de live sont distincts. Pour recevoir les événements live, basculez le Dashboard sur **Production** et créez de nouveau l'endpoint avec la même URL et la même liste d'événements. Il reçoit un **nouveau secret**. > [!CAUTION] > **Mettez à jour la variable d'environnement live** > > Le secret de l'endpoint live diffère de celui de la sandbox. Un serveur qui conserve l'ancienne valeur rejettera chaque livraison live avec une erreur de signature. La page d'un endpoint de sandbox porte un bouton **Copier en production** qui fait cette copie en une seule action : il crée l'endpoint live avec la même URL et les mêmes événements, bascule le Dashboard sur **Production** et affiche une seule fois le nouveau secret live. Il refuse lorsqu'un endpoint live porte déjà cette URL, ou lorsque l'URL n'est pas en `https://`. ## Envoyer un test : une vraie livraison, avec des données de test **Envoyer un test** envoie à l'endpoint une livraison construite clé pour clé comme une vraie, signée avec le véritable secret de l'endpoint. Il prouve que l'URL est accessible, que votre vérification de signature réussit et que votre handler accepte l'enveloppe. Seul son contenu est fictif : l'événement est `webhook.test` et `data` est un exemple, il n'exerce donc pas le code qui traite un vrai type d'événement. ```json title="Le contenu qu'envoie le bouton Envoyer un test" { "id": "evt_test_kZ3qP8mWvL2xR7tB5nY4hC6d", "event": "webhook.test", "data": { "id": "test_123", "message": "This is a test webhook from Wajub." }, "livemode": false, "pending_webhooks": 1, "api_version": "2026-10-11", "request": { "id": null, "idempotency_key": null }, "created": "2026-01-15T10:30:00+00:00" } ``` Il porte l'en-tête `X-Wajub-Delivery-Id` comme toute livraison, `livemode` suit l'environnement dans lequel se trouve le Dashboard, et la tentative est enregistrée dans les livraisons de l'endpoint avec le statut `success` ou `failed`, selon votre réponse. Il n'est pas relancé, et ce n'est pas un événement : `GET /events` ne le liste pas. > [!TIP] > **Répondez-y par un 2xx** > > Un handler qui aiguille sur `event` doit traiter un type inconnu, `webhook.test` compris, en > répondant `200` sans rien faire. Pour exercer le code d'un vrai type, utilisez > [`wajub trigger`](https://docs.wajub.com/fr/developer-tools/cli/triggers), qui produit de vrais événements. - [Nouvelles tentatives et ordre](https://docs.wajub.com/fr/developer-tools/webhooks/retries): Pourquoi une livraison est tentée plusieurs fois. - [Vérification de signature](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification): Comment utiliser le secret que vous venez de révéler. - [Déclencher des événements](https://docs.wajub.com/fr/developer-tools/cli/triggers): Produire un véritable événement plutôt qu'un payload de test. - [Dépannage des webhooks](https://docs.wajub.com/fr/resources/troubleshooting/webhooks): Aucun événement n'arrive ou la signature ne correspond jamais. --- # Tests URL: https://docs.wajub.com/fr/developer-tools/testing > Déclenchez chaque résultat à la demande avant qu'un véritable payeur ne le fasse. Vous pouvez provoquer volontairement en sandbox chaque échec qu'un véritable payeur peut rencontrer : fonds insuffisants, code PIN refusé, délai dépassé, carte refusée ou échec d'un remboursement. La sandbox est la même API, avec ses propres données séparées : le code testé est donc celui que vous déployez. ## Les trois outils | Outil | Utilité | | -------------------------------------------------------------------- | --------------------------------------------------------------------------- | | [Clés de sandbox](https://docs.wajub.com/fr/developer-tools/testing/sandbox-mode) | Exécuter toute votre intégration avec de l'argent de test | | [Numéros et cartes de test](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios) | Choisir le résultat produit par la sandbox | | [La CLI](https://docs.wajub.com/fr/developer-tools/cli/listen) | Recevoir des événements live sur `localhost` et les déclencher à la demande | ## Contenu d'une série de tests complète La plupart des intégrations testent le parcours idéal, puis sont déployées. Les huit cas suivants sont ceux qui provoquent ensuite des problèmes. Chacun ne demande qu'une seule valeur d'entrée. Vos coches sont conservées dans ce navigateur. Une série de tests peut donc s'étendre sur plusieurs jours. Le test de signature est celui que presque personne n'écrit, mais c'est le seul qui protège l'argent. ## La boucle qui accélère les tests ```bash title="Deux terminaux, aucun déploiement, aucun téléphone" # 1 wajub listen --forward-to localhost:3000/webhooks/wajub # 2 wajub trigger payment.succeeded wajub trigger payment.failed wajub trigger refund.succeeded ``` Chaque déclenchement parcourt toute l'API de sandbox. Votre handler reçoit donc une véritable chaîne d'événements, pas un jeu de données figé. Vous pouvez tout vérifier dans la sandbox. Les éléments impossibles à vérifier dans cet environnement, comme les clés live, les scopes restreints et les alertes, figurent dans la [checklist de passage en live](https://docs.wajub.com/fr/getting-started/going-live), qui contient sa propre liste. > [!WARNING] > **La sandbox ne teste pas la couverture de vos prestataires** > > La sandbox accepte chaque canal pour lequel elle a des numéros de test. L'utilisation de `ci.wave` par votre compte live dépend de ce que ce compte peut débiter, pas de votre code. Vérifiez `wajub get /providers` avec le profil live avant de supposer qu'un rail est disponible. - [Mode test](https://docs.wajub.com/fr/developer-tools/testing/sandbox-mode): Ce qui est simulé, ce qui est réel et ce qui diffère volontairement. - [Scénarios de test](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios): Chaque numéro, carte et compte, avec le résultat imposé par chacun. - [Tester les webhooks](https://docs.wajub.com/fr/developer-tools/testing/webhooks): Trois niveaux, du test unitaire jusqu'à la relance d'une livraison. - [Passer en live](https://docs.wajub.com/fr/getting-started/going-live): Le changement lui-même et ses conséquences. --- # Mode test URL: https://docs.wajub.com/fr/developer-tools/testing/sandbox-mode > La même API, des données entièrement séparées et des résultats que vous choisissez. La sandbox est la même API, avec les mêmes routes et la même validation que le live, et des données entièrement séparées. Aucun argent réel ne circule : le résultat dépend du numéro, de la carte ou du compte de test utilisé. ## Sélection de l'environnement L'environnement dépend de la clé. Il n'existe aucun paramètre, en-tête ou option pour le sélectionner. | Préfixe | Environnement | | ---------------------------------- | ------------- | | `pk_test.`, `sk_test.`, `rk_test.` | Sandbox | | `pk.`, `sk.`, `rk.` | Live | Une clé de sandbox ne peut pas lire les données live, et inversement : la sandbox et le live sont entièrement séparés. C'est aussi pourquoi un paiement créé dans la sandbox n'apparaît jamais dans votre Konsole live et qu'aucun filtre n'est nécessaire. > [!CAUTION] > **Vous ne pouvez pas supprimer les données de la sandbox par erreur** > > Aucun bouton ni endpoint ne permet d'effacer un environnement. Il n'existe toutefois aucun chemin de migration : rien de ce que vous créez dans la sandbox, qu'il s'agisse de clients, de bénéficiaires ou d'endpoints, ne vous suit lors du passage en live. Recréez ces éléments volontairement. ## Ce qui est réel | Réel dans la sandbox | Signification | | ---------------------- | ----------------------------------------------------------------------------------------------------------- | | Validation | Les mêmes règles et les mêmes messages `422` | | Plafonds | Les montants minimaux et maximaux sont appliqués de la même manière | | Événements et webhooks | De vrais événements, de vraies signatures et de vraies nouvelles tentatives | | Idempotence | Le même comportement lorsqu'une clé est réutilisée | | Limites de requêtes | Les mêmes plafonds, comptés à part du live : un test de charge en sandbox ne consomme pas votre minute live | | Solde | Un solde de sandbox distinct, crédité par les paiements de sandbox | | Frais de plateforme | 2 % sont prélevés sur les paiements et transferts réussis, ce qui produit `fee.charged` | Le dernier point surprend souvent : un paiement de sandbox de 5 000 XAF crédite moins de 5 000 XAF sur votre solde de sandbox, exactement comme en mode live. ## Ce qui est simulé | Élément simulé | Méthode | | ------------------- | --------------------------------------------------------------------------------------------------------------- | | L'opérateur | Le numéro de test détermine le résultat, aucun appel n'est effectué | | Le réseau de cartes | La carte de test détermine le résultat | | 3D Secure | Le Checkout hébergé demande un code envoyé par e-mail, puis la carte de test détermine le résultat | | La banque | Les deux derniers chiffres du compte déterminent le résultat | | Les cryptomonnaies | Une adresse de dépôt est générée par résultat ; envoyer l'une d'elles comme `wallet_address` décide du résultat | | Le délai | Un court délai remplace un véritable réseau | > [!WARNING] > **Asynchrone, pas instantané** > > Un paiement de sandbox possède encore le statut `pending` au retour de l'appel. Un test qui vérifie immédiatement le statut `succeeded` après sa création échouera. Attendez le webhook ou utilisez le polling jusqu'à l'obtention d'un statut final. ## Des résultats déterministes Rien n'est aléatoire dans la sandbox. | Objet | Élément qui détermine le résultat | | ------------------------- | ------------------------------------------------------------------------------------------ | | Paiement Mobile Money | Le suffixe du numéro du payeur | | Paiement par carte | Le numéro exact de la carte | | Paiement bancaire | Les deux derniers chiffres du compte | | Paiement en cryptomonnaie | L'adresse de `crypto.deposit.scenarios` envoyée comme `wallet_address` (aucune : réussite) | | Remboursement | La carte ou le téléphone du paiement d'origine | | Transfert | Le numéro ou le compte de test du bénéficiaire | > [!NOTE] > **Les transferts sont également déterministes** > > Un transfert de sandbox vers un bénéficiaire Mobile Money exige un numéro de test reconnu. Tout autre numéro est refusé avec une erreur `422` qui liste les valeurs valides. Aucune probabilité n'intervient. ## Le solde de la sandbox Les payouts nécessitent de l'argent. Les paiements de sandbox créditent un solde de sandbox et les transferts le débitent. L'ordre de vos tests est donc important : créez et terminez un paiement avant de tester un payout. Sinon, le transfert échoue pour cause de fonds insuffisants, exactement comme en production. Un transfert échoué restitue le montant au solde et ne coûte aucun frais : les frais de plateforme de 2 % mis de côté à sa création reviennent avec le montant, comme en live. ## Les cryptomonnaies sont désactivées par défaut Le canal des cryptomonnaies est désactivé dans la sandbox tant que Wajub ne l'a pas activé. Une fois activé, une adresse de dépôt est générée pour chaque scénario, toujours la même, ce qui permet de reproduire un scénario. Personne n'envoie de fonds en sandbox : la réponse à `POST /payments/{id}` sur un canal de cryptomonnaie contient donc aussi un `simulator_url`, un lien vers une page à quatre boutons, `SUCCESS`, `FAILURE`, `TIMEOUT` et `CANCELED`. Un clic donne ce résultat au paiement, webhooks compris. Ce champ n'existe jamais en live. ## 3D Secure demande un code par e-mail Une carte de test 3D Secure des [scénarios](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios#cards) répond `202` avec `action: "confirm_3ds"`. Sur le Checkout hébergé, le payeur doit alors saisir un code à six chiffres, que Wajub envoie par e-mail à l'adresse du client et au propriétaire du compte, pour que la vérification reste possible quand le client de test a une adresse fictive. Une fois le code accepté, le numéro de carte détermine si le paiement réussit ou échoue. - [Scénarios de test](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios): Les numéros, cartes et comptes qui imposent chaque résultat. - [Environnements et API keys](https://docs.wajub.com/fr/getting-started/environments): Les quatre types de clés et leurs autorisations. - [Passer en live](https://docs.wajub.com/fr/getting-started/going-live): La checklist complète, dans l'ordre. - [Déclencher des événements](https://docs.wajub.com/fr/developer-tools/cli/triggers): Produire le paiement de sandbox sans écrire l'appel. --- # Scénarios de test URL: https://docs.wajub.com/fr/developer-tools/testing/test-scenarios > Les numéros, cartes et comptes qui imposent chaque résultat. Dans la sandbox, vous choisissez le résultat avec le numéro de téléphone, la carte, le compte bancaire ou le portefeuille utilisé pour payer. Cette page les liste tous. ## Mobile Money Un numéro de test associe un **préfixe d'opérateur** à un **suffixe de six chiffres** qui détermine le résultat. ```text title="La formule" number = operator_prefix + outcome_suffix +23767 + 000002 = +237670000002 MTN Cameroon failure a payment that always fails ``` ### Les six suffixes | Suffixe | Résultat | Ce que voit votre intégration | | -------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `000000` | Réussite | `payment.succeeded` | | `000001` | Fonds insuffisants | Un `402` sur la charge elle-même, avec `error_code: insufficient_funds`, comme un refus en live. Le paiement reste `pending` et `payment.attempt_failed` part | | `000002` | Échec | `payment.failed`, refusé par l'opérateur | | `000003` | Délai dépassé | `payment.expired`, et le paiement finit `expired` | | `000004` | Annulé | `payment.cancelled`, et le paiement finit `cancelled` | | `000009` | Réussite suivie de l'échec d'un remboursement | `payment.succeeded`, puis `refund.failed` | > [!TIP] > **Les zéros supplémentaires au début sont acceptés** > > La partie abonné peut contenir des zéros supplémentaires avant le suffixe. Ainsi, `+2376700000000` correspond également à `000000`. Tout autre caractère entre le préfixe et le suffixe empêche la correspondance, et le débit répond un `422` sur `data.phone` qui liste les numéros à utiliser, avec le préfixe de l'opérateur du canal : `Invalid sandbox test number. Use a test number of the channel's operator, e.g. +237670000000 (success), +237670000001 (insufficient funds), …`. ### Préfixes Le tableau donne un préfixe de test sandbox pour chaque canal Mobile Money annoncé par le catalogue, y compris ceux marqués bientôt disponibles : soixante-sept préfixes dans vingt-six pays. Il liste des numéros de test, pas ce qu'un paiement live peut débiter ; [Couverture](https://docs.wajub.com/fr/resources/coverage) indique les canaux réellement débitables aujourd'hui. Un portefeuille détenu quel que soit l'opérateur du payeur, comme Capitec Pay, prend aussi le numéro de test de tout autre opérateur, et son suffixe fixe toujours le résultat ; un numéro qui n'est pas un numéro de test est refusé. OPay (`ng.opay`) n'a pas de préfixe à lui : un numéro de test nigérian comme `+2348000000000` fixe son résultat. Le sandbox le règle à partir de ce seul numéro, sans l'`action: redirect` vers la page d'OPay que répond le live. Le Bénin et le Gabon ont les préfixes de leurs numéros actuels à côté des anciens : `+2290190000000` et `+24177000000` réussissent, et `00` peut remplacer le `+`. Orange Money au Burkina Faso (`bf.orange`) demande aussi le [code que le payeur génère](https://docs.wajub.com/fr/payments/direct-api#a-code-the-payer-generates) : `123456` est accepté, et tout autre code est refusé comme l'opérateur le refuserait. | Pays | Opérateur | Préfixe | | --- | --- | --- | | Cameroun | MTN MoMo | `+23767` | | Cameroun | Orange Money | `+23769` | | Cameroun | Express Union | `+23768` | | Cameroun | Yoomee | `+23766` | | Côte d'Ivoire | MTN MoMo | `+22505` | | Côte d'Ivoire | Orange Money | `+22507` | | Côte d'Ivoire | Moov | `+22501` | | Côte d'Ivoire | Wave | `+22503` | | Côte d'Ivoire | Green | `+22509` | | Nigeria | MTN | `+2348` | | Nigeria | Orange | `+2347` | | Sénégal | Orange Money | `+22177` | | Sénégal | Free | `+22176` | | Sénégal | Wave | `+22178` | | Ghana | MTN MoMo | `+23324` | | Ghana | Vodafone | `+23320` | | Ghana | Airtel | `+23326` | | Ghana | AirtelTigo | `+23327` | | Kenya | M-Pesa | `+25470` | | Kenya | M-Pesa Till | `+25471` | | Kenya | Airtel Till | `+25473` | | Kenya | Equitel | `+25476` | | Kenya | T-Kash | `+25477` | | Kenya | Airtel | `+25478` | | Tanzanie | Airtel | `+25567` | | Tanzanie | Tigo | `+25565` | | Tanzanie | Vodafone | `+25574` | | Tanzanie | HaloPesa | `+25562` | | Tanzanie | M-Pesa | `+25576` | | Ouganda | MTN | `+25677` | | Ouganda | Airtel | `+25675` | | Rwanda | MTN | `+25078` | | Rwanda | Airtel | `+25073` | | RD Congo | Airtel | `+24399` | | RD Congo | Orange | `+24389` | | RD Congo | Vodacom | `+24381` | | RD Congo | Express Union | `+24382` | | RD Congo | Africell | `+24390` | | Bénin | MTN | `+22990`, `+2290190` | | Bénin | Moov | `+22991`, `+2290191` | | Bénin | Glo | `+22997`, `+2290197` | | Burkina Faso | Orange | `+22670` | | Burkina Faso | Moov | `+22671` | | Gabon | Airtel | `+2410`, `+24174`, `+24177` | | Gabon | Express Union | `+2411` | | Gabon | Moov | `+2416`, `+24162`, `+24165`, `+24166` | | Congo | Express Union | `+24205` | | Congo | MTN | `+24206` | | Congo | Airtel | `+24204` | | Tchad | Express Union | `+23566` | | République centrafricaine | Express Union | `+23670` | | Zambie | MTN | `+26096` | | Zambie | Airtel | `+26097` | | Zambie | Zamtel | `+26095` | | Malawi | Airtel | `+26599` | | Malawi | TNM | `+26588` | | Mali | Orange | `+22370` | | Mali | Moov | `+22366` | | Togo | Moov | `+22899` | | Togo | T-Money | `+22890` | | Guinée | MTN | `+22466` | | Guinée | Orange | `+22462` | | Liberia | MTN | `+23188` | | Mozambique | M-Pesa | `+25884` | | Égypte | Vodafone Cash | `+2010` | | Sierra Leone | Orange | `+23276` | | Afrique du Sud | Capitec Pay | `+2761` | ### Exemples complets | Scénario | MTN Cameroun | Orange Côte d'Ivoire | M-Pesa Kenya | | ------------------ | --------------- | -------------------- | --------------- | | Réussite | `+237670000000` | `+225070000000` | `+254700000000` | | Fonds insuffisants | `+237670000001` | `+225070000001` | `+254700000001` | | Échec | `+237670000002` | `+225070000002` | `+254700000002` | | Délai dépassé | `+237670000003` | `+225070000003` | `+254700000003` | | Annulé | `+237670000004` | `+225070000004` | `+254700000004` | ## Cartes Seul le numéro de carte détermine le résultat. Les autres champs doivent tout de même être bien formés, sinon le débit est refusé par un `422` sur le champ : un nom de titulaire, une expiration au format `MM/AA` ou `MM/AAAA` avec une année de celle-ci à trente ans plus tard, et un CVV de trois ou quatre chiffres. La page [API directe](https://docs.wajub.com/fr/payments/direct-api#cards) montre les quatre champs d'un débit par carte en sandbox. ### Réussite sans 3D Secure | Carte | Réseau | Résultat | | --------------------- | ---------- | -------------------------------------------- | | `4242 4242 4242 4242` | Visa | Réussite | | `5555 5555 5555 4444` | Mastercard | Réussite | | `4000 0000 0000 5423` | Visa | Réussite, puis échec de chaque remboursement | ### Vérification 3D Secure obligatoire Le Checkout hébergé demande un code envoyé par e-mail, comme décrit dans [Mode sandbox](https://docs.wajub.com/fr/developer-tools/testing/sandbox-mode#3d-secure-asks-for-a-code-by-email). Ces cartes renvoient d'abord `202`. Le statut final arrive une fois la vérification terminée. | Carte | Résultat de la vérification | | --------------------- | -------------------------------------------------- | | `4000 0566 5566 5556` | Réussite de la vérification et du paiement | | `4000 0025 0000 3155` | Réussite de la vérification et du paiement | | `4000 0027 6000 3184` | Réussite de la vérification et du paiement | | `4000 0025 0000 3063` | Échec de l'authentification | | `4000 0025 0000 3089` | Échec de l'authentification | | `4000 0025 0000 3018` | Authentification réussie, puis refus de l'émetteur | | `4000 0025 0000 3026` | Authentification réussie, puis refus de l'émetteur | | `4000 0025 0000 3034` | Le payeur abandonne la vérification | | `4000 0025 0000 3042` | Le payeur abandonne la vérification | | `4000 0025 0000 3050` | Le délai de vérification est dépassé | | `4000 0025 0000 3097` | Le délai de vérification est dépassé | ### Échec sans 3D Secure | Carte | Résultat | | --------------------- | ------------------ | | `4000 0000 0000 9995` | Fonds insuffisants | | `4000 0000 0000 0002` | Refus | | `4000 0000 0000 9987` | Refus | | `4000 0000 0000 9979` | Refus | | `4000 0000 0000 0069` | Refus | | `4000 0000 0000 0127` | Refus | | `4000 0000 0000 0119` | Refus | | `4000 0000 0000 0341` | Refus | | `4000 0000 0000 6975` | Refus | | `4242 4242 4242 4241` | Refus | > [!NOTE] > **Un seul motif de refus, pas dix** > > Seule la carte `…9995` possède un motif distinct. Les neuf autres produisent le même refus générique. Utilisez celle que vous souhaitez pour tester un parcours d'échec. Une carte absente de cette page est refusée, car elle ne correspond pas à une carte de test. ## Comptes bancaires Tout numéro de compte ou IBAN d'au moins quatre caractères est accepté. Les **deux derniers chiffres** déterminent le résultat. | Se termine par | Résultat | | -------------- | ------------------ | | `00` | Réussite | | `01` | Fonds insuffisants | | `02` | Échec | | `03` | Délai dépassé | | `04` | Annulé | Toute autre valeur réussit. Un compte qui se termine par `47` fonctionne donc simplement. ## Djamo Un débit Djamo (`ci.djamo`, `sn.djamo`) ne prend aucun numéro, en sandbox comme en live. Il répond `202` avec `action: redirect`, et `action_url` ouvre une page de test Wajub à la place de celle de Djamo : choisissez **Success**, **Failure** ou **Canceled**, comme le payeur le ferait. Le paiement se termine `succeeded`, `failed` ou `cancelled` avec ses webhooks habituels, et le payeur revient à la page d'où il payait, ou à votre `callback`. La page de paiement hébergée suit cette redirection d'elle-même. ## Cryptomonnaies Quand les cryptomonnaies sont désactivées dans la sandbox, le canal n'est pas proposé. Quand elles sont actives, un débit crypto répond avec `crypto.deposit`, dont l'objet `scenarios` porte une adresse de dépôt par résultat : `success`, `insufficient_funds`, `failure`, `timeout` et `canceled`. - Sans `wallet_address` dans le débit, le paiement réussit. - Avec l'une des adresses de `scenarios` comme `wallet_address`, vous obtenez ce résultat. - Toute autre adresse est refusée par un `422` sur `data.wallet_address`. Deux exécutions du même test produisent la même adresse. Elle expire après 30 minutes. Les suffixes d'adresse `_success`, `_insufficient`, `_failure`, `_timeout` et `_canceled` choisissent le résultat d'un **payout** vers un bénéficiaire crypto, pas d'un paiement. ## Remboursements Le résultat d'un remboursement dépend du paiement d'origine, pas de l'appel de remboursement. | Moyen utilisé pour le paiement | Résultat du remboursement | | ------------------------------------------------------------------------- | ------------------------- | | `4000 0000 0000 5423` | Échec systématique | | Un numéro qui se termine par `000009` | Échec systématique | | Un numéro qui se termine par `000000` | Réussite | | Toute autre carte, un compte bancaire ou un portefeuille de cryptomonnaie | Réussite | Les numéros qui se terminent par `000001` à `000004` n'ont pas de ligne : leurs paiements n'aboutissent jamais, il n'y a donc rien à rembourser. `POST /refunds` répond `422` avec `Transaction must be completed to be refunded`. Pour tester un remboursement qui échoue, payez avec `…000009` ou avec la carte `4000 0000 0000 5423`. ## Transferts Un payout utilise les informations du bénéficiaire et les mêmes suffixes s'appliquent. Un bénéficiaire Mobile Money **doit** posséder un numéro de test reconnu. Un compte bancaire de test choisit son résultat par ses deux derniers chiffres, une adresse crypto de test par son suffixe, de la même façon. | Suffixe | Le transfert | `failure_reason` | | -------- | ------------------------------------------------------------------------------ | ------------------- | | `000000` | `succeeded` | | | `000001` | Refusé aussitôt : `422` avec `error_code: insufficient_funds`, rien n'est créé | | | `000002` | `failed` | `failure` | | `000003` | `failed` | `network_error` | | `000004` | `failed` | `invalid_recipient` | ```json title="L'erreur 422 renvoyée dans le cas contraire" { "code": 422, "status": "Unprocessable Content", "error_code": "invalid_test_number", "message": "Invalid sandbox test number. Use a recognised Mobile Money test number, e.g. +237670000000 (success), +237670000001 (insufficient funds), +237670000002 (failure), +237670000003 (timeout), +237670000004 (canceled).", "errors": { "beneficiary": [ "Invalid sandbox test number. Use a recognised Mobile Money test number, e.g. +237670000000 (success), +237670000001 (insufficient funds), +237670000002 (failure), +237670000003 (timeout), +237670000004 (canceled)." ] } } ``` Un transfert débite votre solde de sandbox. Commencez donc par réussir un paiement. Dans le cas contraire, le payout échoue pour cause de fonds insuffisants, exactement comme en mode live. ## Vérification du nom [`POST /beneficiaries/{id}/verify`](https://docs.wajub.com/fr/payouts/beneficiaries/create#checking-the-name-on-a-wallet) n'interroge aucun opérateur en sandbox : le numéro de test du bénéficiaire indique ce que l'opérateur détiendrait. Cela vaut pour `cm.mtn`, `cm.orange` et `cm.eu`, les canaux dont l'opérateur répond à la vérification en live. Tout autre canal répond `lookup_unavailable` : ceux qui n'ont pas de vérification du nom, comme en live, et un compte Wajub, qui n'est vérifié qu'en live. | Suffixe | `verification` | `registered_name` | | ------------------------- | -------------------- | --------------------------------------------------------------------- | | `000000` | `verified` | Le nom que vous avez déclaré | | `000002` | `name_mismatch` | Les initiales d'un autre nom, `S*** A*** H***`, comme pour tout écart | | Tout autre numéro de test | `lookup_unavailable` | Absent | Le bénéficiaire reste payable quel que soit le résultat, comme en live. Sur un compte dont les bénéficiaires doivent être vérifiés avant d'être payés, un compte Relay par exemple, les bénéficiaires de sandbox sont créés vérifiés et l'appel répond `verified`, quel que soit le numéro. - [Mode test](https://docs.wajub.com/fr/developer-tools/testing/sandbox-mode): Les autres différences entre les deux environnements. - [Déclencher des événements](https://docs.wajub.com/fr/developer-tools/cli/triggers): Laissez la CLI choisir le numéro correspondant au résultat souhaité. - [Tester les webhooks](https://docs.wajub.com/fr/developer-tools/testing/webhooks): Recevoir les événements produits par ces scénarios. - [Cycle de vie d'un paiement](https://docs.wajub.com/fr/payments/lifecycle): Les statuts traversés par ces résultats. --- # Tester les webhooks URL: https://docs.wajub.com/fr/developer-tools/testing/webhooks > Trois niveaux, du test unitaire jusqu'à la relance d'une livraison live. Un handler de webhook possède trois modes d'échec à tester séparément : il accepte un élément qu'il devrait refuser, refuse un élément qu'il devrait accepter ou effectue deux fois le même travail. Chacun est détecté à un niveau différent. | Niveau | Problème détecté | Prérequis | | ------------- | -------------------------------------------------------- | --------------------------------- | | Test unitaire | Un vérificateur qui accepte une signature falsifiée | Aucun, il s'agit d'un calcul pur | | La CLI | Un handler qui plante sur un véritable payload | `wajub listen` et `wajub trigger` | | Konsole | Un endpoint réellement inaccessible depuis votre serveur | Un endpoint enregistré | ## Niveau 1 : signer vous-même un payload La signature utilise `HMAC-SHA256` sur `"{timestamp}.{body}"`. Un test peut donc en produire une valide sans aucun accès réseau. Écrivez les quatre cas : signature valide, mauvais secret, corps altéré et ancien horodatage. **Producing a valid signature in a test** ```bash # The string that gets signed, for reference TIMESTAMP=1748083260 BODY='{"id":"evt_test_1","event":"payment.succeeded","data":{}}' printf '%s.%s' "$TIMESTAMP" "$BODY" \ | openssl dgst -sha256 -hmac "whsec_test_secret" -r \ | cut -d' ' -f1 ``` ```javascript import { createHmac } from 'node:crypto'; function sign(body, timestamp, secret) { return 'v1=' + createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex'); } test('rejects a tampered body', async () => { const body = JSON.stringify({ id: 'evt_test_1', event: 'payment.succeeded', data: { amount: 25000 } }); const ts = Math.floor(Date.now() / 1000).toString(); const signature = sign(body, ts, 'whsec_test_secret'); const res = await post('/webhooks/wajub', body.replace('25000', '1'), { 'x-wajub-signature': signature, 'x-wajub-timestamp': ts, }); expect(res.status).toBe(400); }); ``` ```python import hmac, hashlib, time def sign(body: bytes, timestamp: str, secret: str) -> str: mac = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256) return "v1=" + mac.hexdigest() def test_rejects_old_timestamp(client): body = b'{"id":"evt_test_1","event":"payment.succeeded","data":{}}' old = str(int(time.time()) - 400) res = client.post( "/webhooks/wajub", data=body, headers={ "X-Wajub-Signature": sign(body, old, "whsec_test_secret"), "X-Wajub-Timestamp": old, }, ) assert res.status_code == 400 ``` ```php function sign(string $body, string $timestamp, string $secret): string { return 'v1='.hash_hmac('sha256', $timestamp.'.'.$body, $secret); } public function test_it_rejects_a_wrong_secret(): void { $body = json_encode(['id' => 'evt_test_1', 'event' => 'payment.succeeded', 'data' => []]); $timestamp = (string) time(); $this->call('POST', '/webhooks/wajub', [], [], [], [ 'HTTP_X_WAJUB_SIGNATURE' => sign($body, $timestamp, 'whsec_wrong'), 'HTTP_X_WAJUB_TIMESTAMP' => $timestamp, 'CONTENT_TYPE' => 'application/json', ], $body)->assertStatus(400); } ``` ```go func sign(body []byte, timestamp, secret string) string { mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte(timestamp + ".")) mac.Write(body) return "v1=" + hex.EncodeToString(mac.Sum(nil)) } func TestRejectsForgedSignature(t *testing.T) { body := []byte(`{"id":"evt_test_1","event":"payment.succeeded","data":{}}`) ts := strconv.FormatInt(time.Now().Unix(), 10) rec := post(t, "/webhooks/wajub", body, map[string]string{ "X-Wajub-Signature": sign(body, ts, "whsec_wrong"), "X-Wajub-Timestamp": ts, }) if rec.Code != http.StatusBadRequest { t.Fatalf("expected 400, got %d", rec.Code) } } ``` > [!WARNING] > **Signez aussi les octets bruts dans le test** > > Si votre test sérialise à nouveau l'objet avant de le signer, il teste un corps différent de celui qu'il envoie et réussit pour une mauvaise raison. Construisez la chaîne du corps une seule fois, signez-la, puis envoyez-la. ## Niveau 2 : un événement réel sur votre machine Les tests unitaires vérifient le vérificateur. Ils ne prouvent pas que le handler résiste à un véritable payload, avec des champs inattendus et des types que vous n'aviez pas prévus. ```bash title="Deux terminaux" # 1 wajub listen --forward-to localhost:3000/webhooks/wajub # 2 wajub trigger payment.succeeded wajub trigger payment.failed wajub trigger refund.succeeded ``` Wajub signe ce que la CLI transfère avec un secret qui reste le même d'une exécution à l'autre. Votre vérification s'exécute donc réellement. Placez-le une seule fois dans `WAJUB_WEBHOOK_SECRET` (`wajub listen --print-secret`). Rien d'autre ne change dans votre code. Le déclenchement de `payment.succeeded` livre à lui seul cinq événements. Si votre handler n'en connaît qu'un, les quatre autres arrivent actuellement dans sa branche par défaut. ## Niveau 3 : l'endpoint déployé Deux boutons distincts dans [Konsole](https://docs.wajub.com/fr/developer-tools/konsole/webhook-tester) répondent à deux questions différentes. | Bouton | Vérification effectuée | | --------------------------- | --------------------------------------------------------------------------------------------------------- | | Envoyer un test | Wajub peut atteindre votre URL, la vérification de signature réussit et votre handler accepte l'enveloppe | | Renvoyer, sur une livraison | Votre handler traite maintenant un véritable événement qui avait auparavant échoué | > [!WARNING] > **Envoyer un test n'exerce pas vos handlers d'événements** > > Il est structuré et signé comme une vraie livraison, mais son `event` vaut `webhook.test` et son `data` est un exemple, donc aucun code derrière un vrai type ne s'exécute. Répondez-y par un `2xx`, utilisez-le pour tester la connectivité et utilisez `wajub trigger` pour tester le comportement. ## Les quatre vérifications utiles Ces quatre vérifications s'exécutent au niveau 1, dans votre propre suite et sans réseau. Chacune précise l'entrée qui produit la condition. Aucune ne nécessite donc une livraison réelle pour reproduire le résultat. | Vérification | Méthode | Condition de réussite | | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Une signature falsifiée est rejetée | Un mauvais secret, un octet modifié dans le corps ou l'absence complète de `X-Wajub-Signature` | Votre endpoint répond avec un code `4xx` et n'écrit rien | | Une livraison rejouée est rejetée | Une signature valide sur un horodatage vieux de 400 secondes | Votre endpoint répond avec un code `4xx`, car la fenêtre complète est de 300 secondes | | Deux livraisons du même événement n'effectuent le travail qu'une fois | Le même corps et les mêmes en-têtes, envoyés une deuxième fois | Une commande, un e-mail et un crédit | | Un handler occupé répond toujours à temps | Votre handler alors que la file d'attente est déjà pleine | La réponse part en moins de 30 secondes, car une réponse plus lente déclenche une nouvelle tentative | La première est votre seule protection entre le code de livraison de vos commandes et toute personne qui découvre votre URL. L'absence de la troisième vous coûte de l'argent, car chaque livraison est retentée pendant 72 heures au plus. - [Vérification de signature](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification): L'algorithme vérifié par ces tests. - [Nouvelles tentatives et ordre](https://docs.wajub.com/fr/developer-tools/webhooks/retries): Pourquoi le test des doublons compte davantage qu'il n'y paraît. - [Recevoir des webhooks en local](https://docs.wajub.com/fr/developer-tools/cli/listen): Toutes les options de `wajub listen`. - [Webhooks dans Konsole](https://docs.wajub.com/fr/developer-tools/konsole/webhook-tester): Livraisons, relances et test de connectivité. --- # Catalogue des événements URL: https://docs.wajub.com/fr/developer-tools/webhooks/events > Chaque événement émis par Wajub, ce qui le déclenche et ce qu'il transporte. Chaque événement envoyé par Wajub, regroupé par sujet, avec ce qu'il faut faire à sa réception. Tous arrivent dans l'[enveloppe des webhooks](https://docs.wajub.com/fr/developer-tools/webhooks) avec la ressource complète dans `data`, sauf les livraisons du cycle de vie Sync, qui ont [leur propre format](#sync-lifecycle-deliveries). ## Comment un endpoint décide de se déclencher La correspondance des abonnements est une simple comparaison de chaînes avec le tableau `events` que vous avez enregistré. Trois cas, pas un de plus. | Votre tableau `events` | Ce que vous recevez | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `["payment.succeeded", "refund.failed"]` | Exactement ces deux types | | `["*"]` | Tous les événements de paiement, remboursement, transfert, client, litige, facture, lien, compte, solde, frais, endpoint, conformité et prestataire, sauf les livraisons du cycle de vie Sync | | `[]` | La même chose que `["*"]` | Les jokers de préfixe n'existent pas. À partir de la version 2026-10-12 de l'API, enregistrer `payment.*`, ou tout nom qui n'est pas un type d'événement, répond `422` ; sur les versions antérieures, il est enregistré comme une chaîne littérale à laquelle aucun événement n'est jamais égal. Si vous voulez tout ce qui concerne une ressource, listez ses types, copiés depuis cette page. > [!WARNING] > **`*` ne couvre pas les livraisons du cycle de vie Sync** > > Les [livraisons du cycle de vie Sync](#sync-lifecycle-deliveries) ne font correspondre les > abonnements que sur le nom exact : un endpoint enregistré avec `["*"]`, ou avec une liste vide, n'en > reçoit aucune. Listez chaque type voulu. Les événements de conformité et de prestataires atteignent > bien `*` et une liste vide. ## Comment les noms sont construits `resource.verb`, le verbe au passé, le tout en minuscules. Les verbes sont les mêmes d'une ressource à l'autre, ce qui rend la liste plus courte à retenir qu'il n'y paraît. | Verbe | Signification | | ------------ | -------------------------------------------- | | `created` | La ressource existe désormais | | `updated` | Un champ a changé | | `deleted` | La ressource a été supprimée, ou anonymisée | | `processing` | Transmise à un prestataire, résultat inconnu | | `succeeded` | État terminal, l'opération a réussi | | `failed` | État terminal, l'opération a échoué | | `cancelled` | État terminal, arrêtée volontairement | | `expired` | État terminal, le délai est écoulé | Trois orthographes font perdre un après-midi : c'est `succeeded`, jamais `completed` ni `complete` ; c'est `cancelled` avec deux `l` ; et Sync utilise `deauthorized` avec un `z` alors que tout le reste de la plateforme suit l'orthographe britannique. ## Paiements Les six états que traverse un paiement, et la tentative qui échoue sans y mettre fin. Seul `payment.succeeded` signifie que l'argent est là. | Événement | Se déclenche quand | Que faire | | ------------------------ | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | | `payment.created` | Le paiement existe et attend le payeur | Rien, enregistrez l'id | | `payment.processing` | L'opérateur a accepté la demande de débit | Affichez un état en attente | | `payment.succeeded` | Les fonds sont capturés | **Livrez la commande ici** | | `payment.failed` | L'opérateur ou l'émetteur de la carte a refusé | Libérez la réservation, prévenez le client | | `payment.cancelled` | Vous avez appelé `DELETE /payments/{id}`, ou le payeur a cliqué sur Annuler sur la page hébergée | Libérez la réservation | | `payment.expired` | Le délai du paiement s'est écoulé avant la confirmation | Libérez la réservation | | `payment.attempt_failed` | Une tentative a été refusée sur-le-champ et le paiement est de nouveau `pending` | Laissez le payeur réessayer. Rien n'est terminé | | `payment.review_opened` | Shield a envoyé un paiement encaissé dans votre file de revue | Retenez la commande jusqu'à votre décision | | `payment.review_closed` | Vous avez tranché le paiement dans votre file de revue | Livrez la commande, ou non si vous avez bloqué le client | `payment.failed` transporte `failure_reason` dans `data`. Le champ est absent, et non null, quand il n'y a aucun motif à donner. > [!WARNING] > **Il n'existe pas de `payment.refunded`** > > Un remboursement ne produit jamais d'événement de paiement. Il produit des événements `refund.*` > sur l'objet remboursement. Le `status` du paiement lui-même affiche `refunded` ou `partially_refunded` la prochaine fois que vous le lisez, mais > aucun événement de paiement n'est émis pour ce changement. ### Une tentative refusée sur-le-champ `payment.attempt_failed` n'est pas une fin. Un fournisseur a refusé une tentative sur-le-champ, ou aucun fournisseur ne pouvait la prendre, et le paiement est revenu à `pending` : le payeur peut réessayer sur le même paiement. `payment.processing` vous est peut-être déjà parvenu pour cette tentative, et c'est ce qui le suit. Un refus qui arrive plus tard, de l'opérateur, met fin au paiement avec `payment.failed`. `data` est le paiement, avec en plus un objet `attempt` : ```json title="Ce que payment.attempt_failed ajoute au paiement" "attempt": { "failure_code": "insufficient_funds", "failure_message": "Insufficient funds.", "channel": "cm.mtn" } ``` `failure_code` est le code de refus du fournisseur quand il en donne un, `no_eligible_provider` quand aucun fournisseur ne pouvait prendre la tentative, et `payment_declined` sinon. En sandbox, un numéro qui se termine par `000001` l'envoie. Sur un canal qui demande [un code que le payeur génère](https://docs.wajub.com/fr/payments/direct-api#a-code-the-payer-generates), il est aussi envoyé quand ce code manque (`otp_required`) ou est refusé (`invalid_otp`, et `otp_attempts_exceeded` la troisième fois) ; les autres refus gardent le code du prestataire. Un refus de ce code par l'opérateur arrivé plus tard envoie aussi `payment.attempt_failed`, pas `payment.failed`. ### Bloqués jusqu'à la livraison, pour les plateformes Sync Une plateforme Sync qui crée un paiement avec `hold` est prévenue de son blocage. `data` porte l'`id` du paiement, `object` et les `holds` concernés, chacun avec son `account`, son `status`, `held` et `release_at`. [Bloquer jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds) | Événement | Se déclenche quand | Que faire | | ----------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `payment.held` | Le paiement bloqué a réussi ; pour un paiement partagé, une fois ses parts passées aux vendeurs | Expédier, puis libérer une fois livré | | `payment.released` | Vous l'avez libéré, ou son échéance l'a fait : `reason` vaut `platform` ou `auto` | Rien : le vendeur est payé à son prochain versement | | `payment.hold_expiring` | Le blocage se libère seul dans trois jours. Envoyé une fois | Libérez-le, ou remboursez l'acheteur si la marchandise n'est jamais arrivée | ## Paiements fractionnés Émis quand un même paiement est débité en plusieurs tranches, via `split_count` ou `split_amounts` sur `POST /payments/{id}/splits`. | Événement | Se déclenche quand | | -------------------------- | ---------------------------------------------------------- | | `payment.split.processing` | Une tranche a été envoyée à l'opérateur | | `payment.split.succeeded` | Cette tranche a été encaissée, et créditée sur votre solde | | `payment.split.failed` | Cette tranche a été refusée | `data` contient le paiement complet, plus un objet `split` qui indique de quelle tranche il s'agit. ```json title="L'objet split ajouté au payload du paiement" "split": { "id": "splt_9mWvL2xR7tB5nY4hC6dF", "split_number": 2, "amount": 500000, "currency": "XAF", "split_currency": "XAF", "status": "succeeded", "reference": "order-4172-2", "provider_reference": "MP260115.1032.B41209", "initiated_at": "2026-01-15T10:32:04+00:00", "succeeded_at": "2026-01-15T10:32:41+00:00" } ``` Le paiement parent n'atteint `payment.succeeded` qu'une fois toutes les tranches réussies, ou quand vous le clôturez avec [`POST /payments/{id}/close`](https://docs.wajub.com/fr/api/payments/close). Compter vous-même les `payment.split.succeeded` pour décider que la commande est complète, c'est le meilleur moyen de livrer une commande à moitié payée. Le live les envoie pour les mêmes appels, sur les canaux Mobile Money. Le paiement parent envoie aussi `payment.processing` chaque fois qu'une tranche part chez le payeur, et il est `partial` entre deux tranches. Ni le live ni la sandbox ne fractionnent un paiement d'eux-mêmes : un débit unique au-dessus du plafond par transaction indiqué dans [Plafonds et quotas](https://docs.wajub.com/fr/resources/limits) est refusé avec un `422`, et `POST /payments/{id}/splits` le règle en tranches. [Paiements fractionnés](https://docs.wajub.com/fr/sync/split-payments#what-each-call-does) décrit ce que renvoie chaque appel. ## Remboursements | Événement | Se déclenche quand | Que faire | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `refund.created` | Le remboursement a été accepté pour traitement | Enregistrez-le, ne créditez pas encore | | `refund.processing` | Le prestataire l'exécute. Live uniquement : un remboursement sandbox est créé `processing` et ne l'envoie jamais | Rien | | `refund.succeeded` | L'argent a quitté votre solde | **Créditez le client ici** | | `refund.failed` | Le prestataire l'a rejeté | Lisez `failure_reason`, décidez manuellement | | `refund.cancelled` | Wajub a arrêté le remboursement avant de l'envoyer. Il arrive en `refund.failed`, avec `status: failed` et `cancelled_by_wajub` pour `failure_reason` | Rien n'a quitté votre solde. Remboursez de nouveau si le client attend toujours son argent | | `refund.updated` | Un remboursement live a changé de voie : qui l'envoie (`execution_mode`) ou pourquoi (`manual_reason`) | Prévenez votre équipe quand il indique `merchant` : c'est à vous de l'envoyer | `data.transaction` est l'id du paiement remboursé, sous forme de chaîne, pas d'objet imbriqué. ## Transferts Les payouts depuis votre solde, que ce soit vers un portefeuille Mobile Money, un compte bancaire ou une carte. | Événement | Se déclenche quand | Que faire | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | | `transfer.created` | Le transfert a été accepté et a débité votre solde disponible | Enregistrez l'id | | `transfer.processing` | Transmis au prestataire de payout | Rien | | `transfer.succeeded` | Le bénéficiaire a été payé | Marquez le payout comme réglé | | `transfer.failed` | Le prestataire n'a pas pu payer | Lisez `failure_reason`, le montant revient sur votre solde | | `transfer.cancelled` | Le payout a été arrêté avant tout envoi : rejeté dans le Dashboard ou annulé par Wajub. Il arrive en `transfer.failed`, avec `status: failed` et `merchant_rejected` ou `cancelled_by_wajub` pour `failure_reason` | Le montant revient sur votre solde | > [!WARNING] > **Un transfert en revue envoie transfer.created, puis attend** > > `review` est un vrai statut de transfert : Wajub peut retenir un payout pour examen avant de > l'envoyer. Il envoie `transfer.created`, avec `status: review`, et rien de plus tant > qu'il attend. Approuvé, il envoie `transfer.processing` une seule fois, puis `transfer.succeeded` > ou `transfer.failed`. Refusé, il envoie `transfer.failed` avec `admin_rejected`. L'un comme > l'autre peut arriver des heures plus tard. Construisez l'état d'attente sur le statut, pas sur le > silence. ## Clients | Événement | Se déclenche quand | | ------------------ | --------------------------------------------------------------------- | | `customer.created` | Une fiche client a été créée, y compris implicitement par un paiement | | `customer.updated` | Un champ du client a changé | | `customer.deleted` | `DELETE /customers/{id}` a été exécuté, et la fiche a été anonymisée | Le payload de `customer.deleted` est le client **après** anonymisation : le nom est remplacé, et l'e-mail, le téléphone et la date de naissance ont disparu. Si vous avez besoin des valeurs d'origine pour vos propres données, vous devez les avoir conservées. ## Bénéficiaires | Événement | Se déclenche quand | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `beneficiary.created` | Une destination de payout a été enregistrée : par `POST /beneficiaries`, à la volée dans un `POST /transfers`, ou comme compte de retrait dans le Dashboard | | `beneficiary.updated` | Ses informations ont changé | | `beneficiary.deleted` | Elle a été supprimée | | `beneficiary.receivable_recorded` | Vous avez déclaré qu'un vendeur déjà payé vous doit de l'argent, avec `POST /beneficiaries/{id}/receivables` | | `beneficiary.receivable_recovered` | Une ligne de payout groupé a repris tout ou partie de cette dette | `data` contient, pour ces deux événements, la dette elle-même : `id`, `beneficiary`, `reference`, `refund`, `currency`, `amount`, `recovered`, `outstanding`, `status`, `settled_at` et `created_at`, montants en unité principale. Voir [l'endpoint des créances](https://docs.wajub.com/fr/api/beneficiaries/create-receivables). ## Liens de paiement | Événement | Se déclenche quand | | -------------- | ---------------------------------------------------------------------------------------------------------- | | `link.created` | Un lien de paiement a été créé | | `link.updated` | Son montant, son expiration ou son état a changé | | `link.deleted` | Il a été supprimé | | `link.expired` | Son `expiry_date` est passée : envoyé une fois, dans la journée, sauf si le lien a été archivé entre-temps | Un paiement effectué via un lien émet `payment.*`, pas `link.*`. Les événements de lien concernent l'objet lien lui-même. Les endpoints propres à un lien, réglés dans son onglet Webhooks, reçoivent aussi ses paiements, billets, dons, commandes et remboursements : voir [Les webhooks d'un lien](https://docs.wajub.com/fr/payments/link/tracking#webhooks-of-one-link). ## Factures | Événement | Se déclenche quand | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `invoice.created` | Une facture a été créée, en brouillon : une seule fois, avec ses lignes et ses totaux | | `invoice.updated` | Une ligne, un statut ou une date d'échéance a changé : une seule fois par `PUT /invoices/{id}`, avec les lignes et les totaux, et pas du tout pour un `PUT` qui ne change rien | | `invoice.sent` | La facture a été envoyée : son statut est devenu `sent` | | `invoice.payment_succeeded` | Un paiement effectué sur la page de la facture a réussi, chaque échéance comprise | | `invoice.paid` | La facture est réglée en totalité, en ligne ou avec `mark-paid` | | `invoice.cancelled` | Elle a été annulée | | `invoice.deleted` | Elle a été supprimée | > [!NOTE] > **Le paiement et la facture se désignent l'un l'autre** > > Quand un client paie une facture, `payment.succeeded` se déclenche pour le paiement, puis > `invoice.updated` et `invoice.payment_succeeded` pour la facture, et `invoice.paid` une fois > celle-ci réglée. Livrez à partir de `payment.succeeded` : son `data.invoice` est l'`id` de la > facture payée, et les événements de facture portent la facture elle-même. ## Litiges Rétrofacturations et réclamations. Ce sont les événements assortis des délais les plus courts. | Événement | Se déclenche quand | Que faire | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | `dispute.created` | Un litige a été ouvert sur un paiement | **Commencez à rassembler des preuves** | | `dispute.updated` | Un champ a changé, ou un message a été ajouté | Lisez `data.messages` | | `dispute.closed` | Le litige s'est terminé. Une perte l'envoie juste après `dispute.lost`, un gain ne l'envoie jamais : lisez `data.status` pour l'issue | Rien de plus, agissez sur `dispute.lost` | | `dispute.won` | La décision vous est favorable | Gardez les fonds | | `dispute.lost` | La décision vous est défavorable | Le montant est débité | | `dispute.deadline_approaching` | La `due_date` est dans deux jours et le litige est encore `open` ou `under_review`. Envoyé une seule fois | **Soumettez vos preuves maintenant** | | `dispute.deleted` | L'enregistrement du litige a été supprimé | Rien | ## Comptes, pour les plateformes Sync Ces événements décrivent un marchand connecté à une plateforme Sync, pas votre propre compte. Ceux qu'envoie l'API arrivent dans l'enveloppe habituelle : | Événement | Se déclenche quand | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `account.created` | Vous avez créé la connexion avec `POST /accounts`. Le marchand ne l'a pas encore acceptée : c'est `account.connected`, plus bas | | `account.updated` | Le compte a changé, et `data` est le compte tel que ce changement l'a laissé. Envoyé quand `PUT /accounts/{id}` modifie la connexion (son `email`, ses `metadata`, son `callback`, son `payment_status`, ses conditions de versement, ou les capacités et la tarification d'une connexion pas encore acceptée), quand `POST /accounts/{id}/token` remet une invitation annulée en `pending`, et quand Wajub envoie le versement d'un marchand Lite, ce qui avance `last_payout_at`. Un appel qui ne change rien n'envoie rien. Ni une proposition seule, qui est `account.change_requested`, ni `DELETE`, qui est `account.deauthorized`, ne l'envoient. Un changement de `payment_status` envoie aussi `account.payment_activated` ou `account.payment_suspended` | | `account.deauthorized` | Vous avez mis fin à la connexion avec `DELETE /accounts/{id}` | | `account.payment_activated` | Vous avez passé `payment_status` à `active` avec `PUT /accounts/{id}` | | `account.payout_limited` | Un versement Lite ou Relay a été retenu : par votre plafond d'exposition (`reason: exposure_cap`), parce que Wajub a retiré votre approbation (`reason: approval_withdrawn`), parce que le vendeur est nouveau (`reason: new_seller`) ou gelé (`reason: frozen`), ou à cause de votre solde (`reason: insufficient_balance`) : en Relay il ne contient pas le versement, en Lite il est sous zéro. `data` porte `account`, `reason`, `currency`, `paid`, `held` et `since`. Envoyé une fois par épisode : de nouveau seulement après un versement parti en entier | | `account.identity_required` | Un vendeur Relay a dépassé le palier du nom seul : la part de ses versements au-delà attend `POST /accounts/{id}/identity` | | `account.identity_verified` | Wajub a approuvé la pièce d'identité du vendeur Relay : les versements retenus partent au passage suivant | | `account.identity_rejected` | Wajub a refusé la pièce ; `data` porte le motif | | `account.risk_elevated` | Le niveau de risque du vendeur est passé de `normal` à `elevated`. Une fois par franchissement : renvoyé seulement après que le score est redescendu d'au moins 10 points sous le seuil. [Risque vendeur](https://docs.wajub.com/fr/sync/seller-risk#the-risk-score) | | `account.risk_high` | Il a atteint `high` ; `suggestion: "freeze"`, ou `frozen: true` quand il a gelé le vendeur automatiquement | | `account.frozen` | Vous avez gelé le vendeur avec `POST /accounts/{id}/freeze`, ou son score l'a fait : `by`, `reason` (`null` sans motif), `block_payments` (le blocage en vigueur), `frozen_at`, `still_frozen: null` | | `account.unfrozen` | Vous avez levé un gel avec `POST /accounts/{id}/unfreeze` : `by`, `reason`, `block_payments: false`, `frozen_at: null`, et `still_frozen`, le gel qui reste (`{ by, reason, block_payments, since }`) quand un seul des deux a été levé, `null` quand le vendeur n'est plus gelé. [Risque vendeur](https://docs.wajub.com/fr/sync/seller-risk#layered-freezes) | | `account.payment_suspended` | Vous l'avez passé à `suspended` | | `account.change_requested` | `PUT /accounts/{id}` a proposé une nouvelle tarification ou de nouvelles capacités, que le marchand doit approuver | | `account.commission_receivable_recorded` | Une commission n'a pas pu être prélevée à la source et le marchand la doit désormais. Live uniquement | | `account.commission_receivable_collected` | Cette commission a été prélevée sur le solde Wajub du marchand | Chacun d'eux désigne sa connexion dans `data.account` : l'identifiant `acc_…`, la valeur que vous envoyez dans `X-Sync`. Lisez la connexion à cet endroit, pas dans `data.id`, qui n'est pas toujours la connexion : | Événement | `data.account` | `data.id` | | ---------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------- | | `account.created`, `account.updated`, `account.deauthorized`, `account.payment_activated`, `account.payment_suspended` | `acc_…` | Le même `acc_…` : `data` est le compte, tel que `GET /accounts/{id}` le renvoie | | `account.change_requested` | `acc_…` | Absent. La proposition est identifiée par `change_id` | | `account.commission_receivable_recorded`, `account.commission_receivable_collected` | `acc_…` | `crv_…`, la commission due | | `account.risk_elevated`, `account.risk_high`, `account.frozen`, `account.unfrozen` | `acc_…` | Absent | Sur ces événements, `account` est l'identifiant lui-même, une chaîne. Sur la copie d'un événement de paiement, de remboursement, de transfert ou de litige que reçoit une plateforme, et sur `fee.received`, `account` est un objet et l'identifiant se trouve dans `account.id` : voir [Les plateformes Sync reçoivent une copie](#sync-platforms-receive-a-copy). Il n'existe pas de `account.deleted`. `account.created` annonce l'invitation que vous avez créée ; l'acceptation du marchand est `account.connected`, plus bas. Quand le marchand révoque lui-même la connexion, le `account.deauthorized` que vous recevez est celui au format Sync. Le reste de la vie de la connexion, ainsi que les mêmes changements quand ils sont faits depuis le Dashboard plutôt que par l'API, sont envoyés au format Sync décrit dans la section suivante : | Événement | Se déclenche quand | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account.onboarding_started` | Le marchand a ouvert votre lien d'onboarding | | `account.onboarding_email_verified` | Il a vérifié son adresse e-mail | | `account.onboarding_account_selected` | Il a choisi le compte Wajub à connecter | | `account.onboarding_kyc_submitted` | Il a soumis son dossier de vérification | | `account.onboarding_declined` | Il a refusé la connexion. Rien n'est connecté et votre lien d'invitation fonctionne toujours. `reason` contient ses mots quand il en a donné | | `account.connected` | Il a accepté la connexion. Elle est active à partir de maintenant | | `account.change_requested` | Vous avez proposé de nouvelles conditions depuis le Dashboard | | `account.change_accepted` | Le marchand les a approuvées. Elles s'appliquent à partir de maintenant | | `account.change_declined` | Le marchand les a refusées. Rien ne change | | `account.payment_activated`, `account.payment_suspended`, `account.deauthorized` | Les mêmes changements, faits depuis le Dashboard ou déclenchés par la vérification du marchand | | `account.frozen`, `account.unfrozen` | Un vendeur gelé ou dégelé depuis le Dashboard, ou par Wajub. Les mêmes champs que par l'API, `still_frozen` compris | | `account.dispute_evidence_submitted` | Un vendeur Lite a envoyé sa réponse à un litige, ou la coupure a envoyé son brouillon pour lui. [Litiges sur les ventes de vos vendeurs](https://docs.wajub.com/fr/sync/disputes#the-event) | | `platform.exposure_warning` | L'exposition d'une devise a dépassé 80 % de votre plafond de versement. En live seulement ; un envoi en échec est retenté, dédoublonnez sur `X-Idempotency-Key`. [Votre plafond d'exposition](https://docs.wajub.com/fr/sync/payouts#following-your-cap) | | `platform.exposure_reached` | Elle a atteint 100 % | | `report.ready` | Un rapport que vous avez demandé est prêt à télécharger. [Rapports](https://docs.wajub.com/fr/sync/reports#download-it) | Les trois derniers concernent votre plateforme, pas une connexion : ils ne portent pas d'`account`. ## Livraisons du cycle de vie Sync Les événements du second tableau ne voyagent pas comme les autres. Ils sont envoyés aux endpoints de la plateforme propriétaire de la connexion, dans l'environnement de cette connexion. - **Seul un abonnement exact les reçoit.** `*` et un tableau `events` vide ne correspondent pas. Listez chaque type voulu. - **Le corps est à plat**, sans l'enveloppe habituelle : `event`, `account` (l'id `acc_…` de la connexion), `sandbox`, `timestamp`, puis les champs propres à l'événement. Il n'y a pas de `data` : lisez la connexion dans `account`, la clé qu'utilisent sous `data` les événements `account.*` de l'API. Ne vous fiez qu'aux champs documentés ici. - **Les en-têtes sont différents** : `X-Sync-Event` nomme l'événement, `X-Idempotency-Key` identifie la livraison, et `X-Sync-Signature-V1` avec `X-Sync-Timestamp` portent la signature. - **Vérifiez la signature comme pour toute autre livraison.** `X-Sync-Signature-V1` est `v1=` suivi du HMAC-SHA256 en hexadécimal de `{timestamp}.{raw_body}`, avec le secret de signature de l'endpoint pour clé, et `X-Sync-Timestamp` est cet horodatage en secondes Unix. Passez les deux à `constructEvent` dans les SDK, ou vérifiez-les à la main comme dans [Vérification de signature](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification#sync-lifecycle-deliveries), et refusez une livraison dont l'horodatage s'écarte de plus de 300 secondes de votre horloge. Enregistrez ensuite chaque `X-Idempotency-Key` traité, et ignorez une livraison dont la clé a déjà été vue. - **Seul un `2xx` vaut livraison**, comme pour tout autre événement : une redirection n'est pas suivie et compte comme un échec. Chaque tentative part vers l'endpoint tel qu'il est au moment de l'envoi, signée avec son secret actuel, et un endpoint désactivé ou supprimé entre-temps ne reçoit plus rien. - **Les nouvelles livraisons ne durent que quelques minutes** : gardez l'endpoint disponible et répondez en moins de 10 secondes. Ces livraisons n'apparaissent pas dans le journal des événements de Konsole. Voici à quoi ressemble `account.connected` : ```json title="Une livraison account.connected" { "event": "account.connected", "account": "acc_7Yh2MpL4tRb3nP8sZcXv", "sandbox": false, "timestamp": "2026-09-16T10:32:41+00:00", "team_name": "Boutique Akwa", "capabilities": ["read", "payments"], "status": "active", "payment_status": "active" } ``` ## Solde et frais | Événement | Se déclenche quand | Payload | | ----------------- | -------------------------------------------------------------- | ------------------------------------- | | `balance.updated` | Votre solde a bougé | Le mouvement, pas les nouveaux totaux | | `fee.charged` | Wajub vous a débité des frais | Les frais | | `fee.received` | Une plateforme Sync a perçu ses frais sur un marchand connecté | Les frais, plus `account` | > [!WARNING] > **Un débit de frais n'est pas un `balance.updated`** > > Les débits de frais sont volontairement exclus de `balance.updated` et remontés à la place sous > forme de `fee.charged`. Si vous additionnez les mouvements `balance.updated` pour tenir un registre > local, vous dépasserez exactement du montant des frais. Abonnez-vous aux deux. `balance.updated` envoie le mouvement lui-même, c'est ce qu'il vous faut pour un registre. ```json title="Un payload balance.updated" { "currency": "XAF", "amount": 24250, "direction": "credit", "balance_type": "available", "balance_before": 1840000, "balance_after": 1864250, "reason": "payment_settlement", "sandbox": false } ``` Les totaux que renvoie `GET /balance` ne figurent pas dans ce payload. Appelez l'endpoint quand vous en avez besoin. ## Conformité Émis pendant la vérification de votre compte, puis chaque fois que votre dossier change d'état. | Événement | Se déclenche quand | | ------------------------------ | -------------------------------------------------------------- | | `compliance.submitted` | Votre dossier de vérification a été soumis pour examen | | `compliance.verified` | Le compte est vérifié, les paiements live deviennent possibles | | `compliance.rejected` | Le dossier a été refusé | | `compliance.changes_requested` | Un analyste a besoin d'autre chose de votre part | | `compliance.inquiry.created` | Une question précise a été posée sur votre dossier | | `compliance.inquiry.resolved` | Cette question a été clôturée | Pour une plateforme qui inscrit des marchands, `compliance.verified` est le signal qu'un compte connecté peut commencer à accepter des paiements live. Ne le déduisez de rien d'autre. ## Prestataires Émis quand l'ensemble des prestataires et des canaux disponibles sur votre compte change. | Événement | Se déclenche quand | | ------------------------------ | ----------------------------------------------- | | `provider.activated` | Un prestataire a été activé sur votre compte | | `provider.deactivated` | Un prestataire a été désactivé | | `provider.channel_activated` | Un canal d'un prestataire est devenu disponible | | `provider.channel_deactivated` | Un canal a été retiré | Utile si vous mettez en cache les canaux de votre compte au lieu d'appeler `GET /providers` à chaque checkout. ## Endpoints de webhook | Événement | Se déclenche quand | | -------------------------- | ----------------------------------------------- | | `webhook_endpoint.created` | Un endpoint a été enregistré | | `webhook_endpoint.updated` | Son URL, ses abonnements ou son état ont changé | | `webhook_endpoint.deleted` | Il a été supprimé | Utile sur un compte plateforme où plusieurs personnes peuvent modifier la configuration. Notez que l'endpoint qui reçoit cet événement peut être celui qui vient d'être modifié. ## Ce que contient réellement `data` `data` est la ressource telle que la renvoie son endpoint REST. Trois points sont à connaître. **Un champ sans valeur peut être absent ou `null`.** Lisez chaque champ avec une valeur par défaut, et acceptez `null`. **Un `metadata` vide arrive en `{}`**, jamais en `[]`. **Le payload est toujours dans la dernière version de l'API.** La version fixée s'applique à vos appels API, pas aux livraisons de webhooks : l'`api_version` de l'enveloppe est la version courante de la plateforme au moment où l'événement a été enregistré, et le corps est structuré pour cette version. Épingler votre compte sur `2026-08-01` ne change pas ce que reçoit votre endpoint. ```json title="Une livraison payment.succeeded complète" { "id": "evt_aio5DpN577tNU2vOxdmuZGhT", "event": "payment.succeeded", "livemode": true, "created": "2026-01-15T10:32:41+00:00", "api_version": "2026-10-11", "pending_webhooks": 1, "request": { "id": null, "idempotency_key": "idem_kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0" }, "data": { "id": "trx_CSUGajfv9xh0XQ5wu2lx", "reference": "order-4172", "amount": 25000, "amount_paid": 25000, "currency": "XAF", "status": "succeeded", "channel": "cm.mtn", "payment_method": { "channel": "cm.mtn", "account": "+237670000000" }, "customer": { "id": "cus_4tRb3nP8sZcXvK2mQ9wL", "name": "Amina Nkem", "email": "amina@example.com", "phone": "+237670000000" }, "sandbox": false, "credited_at": "2026-01-15T10:32:41+00:00", "created_at": "2026-01-15T10:30:00+00:00", "updated_at": "2026-01-15T10:32:41+00:00" } } ``` ## Les événements qu'on cherche et qui n'existent pas | Vous attendiez | Ce qui existe réellement | | ---------------------------- | --------------------------------------------------------------------------- | | `payment.refunded` | `refund.succeeded` | | `payment.partially_refunded` | `refund.succeeded`, comparez `data.amount` au paiement | | `transfer.review` | `transfer.created`, avec `status: review`. Rien d'autre jusqu'à la décision | | `payout.*` | `transfer.*`, les payouts sont des transferts dans l'API | | `subscription.*` | `invoice.*`, la facturation récurrente émet des événements de facture | | `checkout.session.completed` | `payment.succeeded` | | `account.deleted` | `account.deauthorized` | ## Sandbox et live sont deux flux séparés Un endpoint appartient à un seul environnement. Un endpoint sandbox ne reçoit que des événements sandbox, et un endpoint live que des événements live. Deux choses changent dans le payload : - `livemode` vaut `false` en sandbox et `true` en live. - Les ids d'événement sont préfixés `evt_test_` en sandbox et `evt_` en live. Un handler qui code en dur la longueur d'un id ou qui retire un préfixe cassera dès qu'il rencontrera l'autre environnement. ## Les plateformes Sync reçoivent une copie Quand un paiement, un remboursement ou un transfert appartient à un marchand connecté via Sync, ou qu'un litige est ouvert sur un tel paiement, l'événement est livré deux fois : une fois aux endpoints du marchand, et une fois à ceux de la plateforme, sous forme d'événement distinct avec son propre id. La copie de la plateforme porte un objet `account` supplémentaire pour que vous sachiez de quel marchand connecté elle provient. Les liens, factures et bénéficiaires créés par la connexion ne sont pas copiés : `GET /events` avec `X-Sync` liste leurs événements. ```json title="Ce que la copie de la plateforme ajoute à data" "account": { "id": "acc_7Yh2MpL4tRb3nP8sZcXv", "reference": "boutique-akwa" } ``` Dédupliquez sur l'id de l'événement, pas sur l'id du paiement : les deux copies décrivent le même paiement et portent volontairement deux ids d'événement différents. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks): L'enveloppe, les en-têtes et les trois règles. - [Nouvelles tentatives et ordre](https://docs.wajub.com/fr/developer-tools/webhooks/retries): Pourquoi le même événement arrive deux fois, et sur quoi vous appuyer. - [Cycle de vie d'un paiement](https://docs.wajub.com/fr/payments/lifecycle): Quels changements d'état émettent un événement, et lesquels non. - [Déclencher un événement](https://docs.wajub.com/fr/developer-tools/cli/triggers): Produisez huit de ces événements à la demande depuis votre terminal. --- # Webhooks URL: https://docs.wajub.com/fr/developer-tools/webhooks > Comment Wajub informe votre serveur de ce qui s'est passé, et comment vous fier à cette information. Un webhook informe votre serveur du résultat d'un paiement, d'un transfert ou de tout autre changement, sans que vous ayez à le demander. Trois règles rendent une intégration correcte ; le reste de cette section les détaille. | Règle | Pourquoi | | ------------------------------------------------- | ----------------------------------------------------------------- | | Vérifiez la signature avant de lire le corps | N'importe qui peut envoyer un POST à votre URL | | Répondez en moins de 30 secondes, traitez ensuite | Un handler lent déclenche une nouvelle tentative, donc un doublon | | Utilisez l'id de l'événement comme clé | Le même événement peut légitimement arriver deux fois | ## L'enveloppe Chaque livraison a la même forme. Le payload ne varie jamais selon le type d'événement, seul `data` change. ```json title="Une livraison payment.succeeded" { "id": "evt_test_aio5DpN577tNU2vOxdmuZGhT", "event": "payment.succeeded", "livemode": false, "created": "2026-05-24T10:21:09+00:00", "api_version": "2026-10-11", "pending_webhooks": 1, "request": { "id": null, "idempotency_key": "idem_kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0" }, "data": { "id": "trx_CSUGajfv9xh0XQ5wu2lx", "reference": "order-4172", "amount": 25000, "amount_paid": 25000, "currency": "XAF", "status": "succeeded", "channel": "cm.mtn", "customer": { "id": "cus_test_4tRb3nP8sZcXvK2mQ9wL", "email": "amina@example.com" } } } ``` > [!CAUTION] > **Le type d'événement est dans `event`, pas dans `type`** > > Lire `event.type` vous renvoie `undefined`, et un switch sur cette valeur tombe silencieusement > dans votre branche par défaut. Le champ s'appelle `event`. Les SDKs renvoient cette enveloppe telle > quelle, la règle s'applique donc que vous l'analysiez vous-même ou non. `data` est la ressource complète, octet pour octet ce que `GET /payments/{id}` renvoie sous `transaction`. Vous n'avez jamais besoin d'un second appel pour savoir ce qui s'est passé, même si en faire un reste un bon moyen de revérifier un paiement que vous jugez à forte valeur. Associez un événement à votre propre commande grâce à `data.reference`, la `reference` que vous avez fournie, ou `data.metadata`. | Champ | Ce qu'il contient | | ------------------ | ------------------------------------------------------------- | | `id` | L'id de l'événement, votre clé de déduplication | | `event` | Le type, par exemple `payment.succeeded` | | `livemode` | `false` en sandbox, `true` en live | | `created` | Le moment où l'événement a été enregistré, au format ISO 8601 | | `api_version` | La version selon laquelle le payload a été sérialisé | | `pending_webhooks` | Le nombre d'endpoints auxquels cet événement est destiné | | `data` | La ressource elle-même | ## Les en-têtes ```http title="Ce qui arrive avec le corps" X-Wajub-Signature: v1=8f3c1b0e4a7d... X-Wajub-Timestamp: 1748081269 X-Wajub-Event: payment.succeeded X-Wajub-Delivery-Id: whd_7Yh2MpL4tRb3nP8sZcXv Content-Type: application/json ``` Les deux premiers servent à la vérification. `X-Wajub-Event` vous permet d'aiguiller la requête avant de l'analyser, et `X-Wajub-Delivery-Id` identifie la livraison de cet événement à cet endpoint : il reste le même à chaque nouvelle tentative, et diffère d'un endpoint à l'autre. ## Ce qui se passe de bout en bout 1. **Vous enregistrez un endpoint** Une URL, dans Konsole ou via `POST /webhooks`. Un endpoint live doit utiliser `https://` ; un endpoint sandbox peut utiliser `http://`. Chaque endpoint a son propre secret de signature. 2. **Quelque chose se produit** Un paiement réussit, un transfert échoue, un litige s'ouvre. Wajub enregistre un événement. 3. **Wajub l'envoie** Signé, à chaque endpoint abonné à ce type, avec un délai de réponse de 30 secondes. 4. **Vous répondez 2xx** Pour toute autre réponse, ou sans réponse dans le délai, la livraison est retentée pendant 72 heures au plus. ## Pour aller plus loin | Vous voulez | Lisez | | --------------------------------------- | ----------------------------------------------------------------------------- | | En recevoir un sur votre ordinateur | [Démarrage rapide](https://docs.wajub.com/fr/developer-tools/webhooks/quickstart) | | Prouver qu'il vient de Wajub | [Vérification de signature](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification) | | Savoir quels événements existent | [Catalogue des événements](https://docs.wajub.com/fr/developer-tools/webhooks/events) | | Comprendre un doublon | [Nouvelles tentatives et échecs](https://docs.wajub.com/fr/developer-tools/webhooks/retries) | | Choisir de ne pas utiliser les webhooks | [Webhooks ou polling](https://docs.wajub.com/fr/developer-tools/webhooks/polling) | > [!TIP] > **Pas besoin d'URL publique pour commencer** > > `wajub listen --forward-to http://localhost:3000/webhooks` transmet les événements en temps réel à > votre machine, signés de la même façon qu'en production. Le [démarrage rapide](https://docs.wajub.com/fr/developer-tools/webhooks/quickstart) > commence par là. - [Démarrage rapide](https://docs.wajub.com/fr/developer-tools/webhooks/quickstart): Un événement signé sur votre ordinateur en cinq minutes environ. - [Vérification de signature](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification): La seule étape à ne jamais sauter. - [Nouvelles tentatives et échecs](https://docs.wajub.com/fr/developer-tools/webhooks/retries): Des tentatives pendant 72 heures, et comment rester idempotent. - [Dépannage des webhooks](https://docs.wajub.com/fr/resources/troubleshooting/webhooks): Rien n'arrive, ou la signature ne correspond jamais. --- # Webhooks ou polling URL: https://docs.wajub.com/fr/developer-tools/webhooks/polling > Pourquoi les webhooks l'emportent, quand lire l'API à la place, et ce que cela coûte. Un paiement Mobile Money n'est pas terminé quand votre requête répond : le payeur doit encore confirmer sur son téléphone. Il existe trois moyens de savoir comment il s'est terminé. | Moyen | Mécanisme | Latence | Ce que cela coûte | | ------------------------------ | -------------------------------- | --------------------------- | ------------------------------- | | Webhook | Wajub envoie un POST à votre URL | Dès que cela se produit | Un endpoint HTTPS public | | Lire un paiement | `GET /payments/{id}` | Votre intervalle de polling | Du budget de limite de requêtes | | Lire le journal des événements | `GET /events` | À chaque exécution | Une requête par page | Pour livrer la commande, la réponse, ce sont les webhooks. Les deux autres existent pour les cas que les webhooks ne couvrent vraiment pas, et cette page vous aide à les distinguer. ## Utilisez chacun pour ce qu'il fait bien | Situation | À utiliser | | ------------------------------------------------------------------------- | --------------------------------------- | | Livrer la commande, créditer le portefeuille, envoyer le reçu | **Webhook**, toujours | | Le payeur vient de revenir sur votre page de retour | **Une lecture** de `GET /payments/{id}` | | Un script, un cron, un outil de back-office sans URL publique | **Polling**, avec une échéance | | Votre endpoint a été indisponible une heure et vous devez combler le trou | **`GET /events`**, puis rejouer | | Un tableau de bord qui affiche le statut en direct à une personne | Webhook vers votre propre canal push | Le polling n'est pas une alternative plus légère aux webhooks. Il est plus lent, il consomme du budget de requêtes, et il ne voit rien de ce qui s'est passé pendant que votre processus ne tournait pas. C'est un complément. ## Ce que le polling vous coûte réellement `GET /payments/{id}` renvoie toujours le statut actuel. Il est aussi compté deux fois : une fois sur le budget global par minute de votre compte, et une fois sur le compartiment de l'endpoint `payments`, partagé avec la création de paiements. | Plan | Budget du compte, par minute | Compartiment `payments`, par minute | | ------------- | ---------------------------- | ----------------------------------- | | Pay as you go | 120 | 30 | | Growth | 360 | 90 | | Scale | 720 | 180 | | Enterprise | Illimité | Illimité | > [!WARNING] > **C'est le compartiment de l'endpoint qui vous bloque** > > Chaque appel à un endpoint de paiements compte dans le compartiment `payments`, création > comprise. Une boucle qui interroge un paiement toutes les cinq secondes en consomme 12 par minute, > et dix paiements simultanés en consomment 120, ce qui dépasse déjà le plafond sur Pay as you go et > Growth. Interrogez une file de paiements avec un seul minuteur, pas un minuteur par paiement. Au-delà du plafond, vous recevez un `429` avec un en-tête `Retry-After` en secondes, et la même valeur dans le corps. ```json title="Un 429 du compartiment payments" { "code": 429, "status": "Too Many Requests", "message": "Too many requests", "type": "endpoint", "retry_after": 37, "retry_after_human": "00:00:37" } ``` `type` vous indique quel plafond vous avez atteint : `team` pour le budget du compte, `endpoint` pour le compartiment ci-dessus, `api_key` pour la limite par clé, qui a la même valeur que le budget du compte, et `ip` pour un appel fait sans clé. ## Faire du polling correctement Quatre règles font la différence entre un polling utile et un polling qui vous fait atteindre la limite de requêtes. | Règle | Pourquoi | | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Arrêtez-vous à un statut terminal | `succeeded`, `failed`, `cancelled` et `expired` sont définitifs. `pending`, `processing` et `partial` ne le sont pas | | Donnez une échéance à la boucle | Deux minutes suffisent pour le Mobile Money. Au-delà, laissez le webhook terminer le travail et indiquez au client que vous confirmerez par e-mail | | Appliquez une attente progressive | Commencez à deux secondes et augmentez l'intervalle. Un paiement qui n'a pas bougé en trente secondes ne bougera pas dans les deux suivantes | | Ne relisez jamais ce qu'on vous a déjà transmis | Une livraison `payment.succeeded` contient déjà le paiement final. Le relire double votre trafic pour rien | **Un polling borné avec attente progressive** ```bash # One read. The status is in .transaction.status curl https://api.wajub.com/payments/trx_CSUGajfv9xh0XQ5wu2lx \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` ```javascript const TERMINAL = new Set(['succeeded', 'failed', 'cancelled', 'expired']); async function settle(id, { deadlineMs = 120_000 } = {}) { const stopAt = Date.now() + deadlineMs; let wait = 2000; while (Date.now() < stopAt) { const payment = await wajub.payments.retrieve(id); if (TERMINAL.has(payment.status)) return payment; await new Promise((r) => setTimeout(r, wait)); wait = Math.min(wait * 1.5, 15_000); } return null; // Still open. The webhook will bring the outcome. } ``` ```python TERMINAL = {"succeeded", "failed", "cancelled", "expired"} def settle(id: str, deadline: float = 120.0): stop_at = time.monotonic() + deadline wait = 2.0 while time.monotonic() < stop_at: payment = wajub.payments.retrieve(id) if payment.status in TERMINAL: return payment time.sleep(wait) wait = min(wait * 1.5, 15.0) return None # Still open. The webhook will bring the outcome. ``` ```php const TERMINAL = ['succeeded', 'failed', 'cancelled', 'expired']; function settle(Wajub\Wajub $wajub, string $id, int $deadline = 120): ?object { $stopAt = time() + $deadline; $wait = 2; while (time() < $stopAt) { $payment = $wajub->payments->retrieve($id); if (in_array($payment->status, TERMINAL, true)) { return $payment; } sleep($wait); $wait = (int) min($wait * 1.5, 15); } return null; // Still open. The webhook will bring the outcome. } ``` ```go var terminal = map[string]bool{"succeeded": true, "failed": true, "cancelled": true, "expired": true} func settle(ctx context.Context, client *wajub.Client, id string, deadline time.Duration) (*wajub.Payment, error) { ctx, cancel := context.WithTimeout(ctx, deadline) defer cancel() wait := 2 * time.Second for { payment, err := client.Payments.Retrieve(ctx, id) if err != nil { return nil, err } if terminal[payment.Status] { return &payment, nil } select { case <-ctx.Done(): return nil, nil // Still open. The webhook will bring the outcome. case <-time.After(wait): } if wait = wait * 3 / 2; wait > 15*time.Second { wait = 15 * time.Second } } } ``` Les SDKs renvoient le paiement lui-même plutôt que l'enveloppe : `retrieve` vous renvoie le paiement, pas le conteneur `{ code, status, message, transaction }` que vous voyez avec cURL. ## Rattraper le retard après une panne Si votre endpoint était injoignable, les événements existent toujours. `GET /events` liste tout ce qui a été enregistré pour votre compte dans l'environnement courant, du plus récent au plus ancien, et `POST /events/{id}/resend` en renvoie un par le circuit de livraison normal, signé comme d'habitude. Renvoyez chaque événement une fois : un même événement repart vers le même endpoint au plus une fois toutes les 5 minutes, et un second renvoi dans ce délai répond `429` (voir [Plafonds et quotas](https://docs.wajub.com/fr/resources/limits#webhook-delivery)). **Lire le journal des événements et rejouer ce que vous avez manqué** ```bash curl "https://api.wajub.com/events?type=payment.succeeded&per_page=100" \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" curl -X POST https://api.wajub.com/events/evt_aio5DpN577tNU2vOxdmuZGhT/resend \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` ```javascript const page = await wajub.events.list({ type: 'payment.succeeded', per_page: 100 }); for (const event of page.data) { if (await alreadyHandled(event.id)) continue; await wajub.events.resend(event.id); } ``` ```python page = wajub.events.list({"type": "payment.succeeded", "per_page": 100}) for event in page.data: if already_handled(event["id"]): continue wajub.events.resend(event["id"]) ``` ```php $page = $wajub->events->list(['type' => 'payment.succeeded', 'per_page' => 100]); foreach ($page->data as $event) { if (alreadyHandled($event['id'])) { continue; } $wajub->events->resend($event['id']); } ``` ```go page, err := client.Events.List(ctx, map[string]any{ "type": "payment.succeeded", "per_page": 100, }) if err != nil { return err } for _, event := range page.Data { id, _ := event["id"].(string) if handled(id) { continue } if _, err := client.Events.Resend(ctx, id, nil); err != nil { return err } } ``` Trois détails déterminent si cela fonctionne. | Détail | Ce que cela signifie | | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | | Les filtres sont `per_page`, `page` et `type` | Il n'y a pas de plage de dates. Remontez les pages jusqu'à atteindre des horodatages assez anciens | | La pagination se fait par numéro de page | `meta` contient `current_page`, `last_page`, `per_page` et `total` | | Sandbox et live sont séparés | L'environnement dépend de la clé utilisée, pas d'un paramètre | Le renvoi part vers chaque endpoint actif abonné à ce type qui n'a pas encore accepté l'événement, chacun recevant sa tentative suivante. Un endpoint qui l'a déjà accepté ne le reçoit pas une seconde fois : sur un compte avec deux endpoints, celui qui fonctionne ne reçoit pas de doublon. Quand tous l'ont accepté, l'appel répond quand même `202` et n'envoie rien. > [!NOTE] > **Le journal ne contient que ce que reçoit un endpoint** > > Les entrées de la chronologie du checkout affichées dans [Événements](https://docs.wajub.com/fr/developer-tools/konsole/event-stream) > de Konsole ne sont jamais livrées : `GET /events` ne les liste donc pas et ne peut pas les > renvoyer. ## La page de retour n'est pas une confirmation Quand un payeur revient sur votre URL `callback`, vous savez seulement qu'un navigateur a chargé une URL. Le paiement a pu réussir, échouer, ou attendre encore un code PIN. N'importe qui peut aussi ouvrir cette URL s'il la devine. > [!CAUTION] > **Ne livrez jamais sur la redirection** > > Lisez le paiement côté serveur avant d'afficher une page de succès, et livrez la commande sur le > webhook. Une page de retour qui expédie la commande est une page de retour qui expédie des > commandes gratuites à quiconque la charge deux fois. Le schéma qui fonctionne en production repose sur trois couches, et chacune couvre l'angle mort de la précédente. 1. **Le webhook livre la commande** Il arrive, que le client revienne ou non, et c'est le seul des trois dont l'arrivée est garantie. 2. **Une lecture côté serveur affiche la page de retour** Un seul `GET /payments/{id}` vous indique laquelle des trois pages afficher : réussi, toujours en attente, ou échoué. Pas de boucle. 3. **Une tâche quotidienne fait le rapprochement** Listez les paiements que votre base de données considère encore comme ouverts, lisez chacun d'eux, et comblez l'écart. Cette étape est obligatoire. Un événement peut vous parvenir en retard, et aucun n'est envoyé tant que Wajub restreint vos webhooks ([Nouvelles tentatives](https://docs.wajub.com/fr/developer-tools/webhooks/retries#what-wajub-guarantees)) : sans cette tâche, un tel paiement reste ouvert chez vous pour de bon. - [Recevoir un webhook](https://docs.wajub.com/fr/developer-tools/webhooks/quickstart): Un événement signé sur votre ordinateur, sans rien déployer. - [Nouvelles tentatives et ordre](https://docs.wajub.com/fr/developer-tools/webhooks/retries): Ce qui se passe quand c'est votre endpoint qui est en panne. - [Plafonds et quotas](https://docs.wajub.com/fr/resources/limits): Tous les plafonds appliqués par l'API, et l'erreur que chacun renvoie. - [Monitoring](https://docs.wajub.com/fr/resources/monitoring): Les signaux qui méritent une alerte, et d'où vient chacun. --- # Recevoir un webhook URL: https://docs.wajub.com/fr/developer-tools/webhooks/quickstart > Un événement signé sur votre ordinateur, sans rien déployer. Pour commencer, pas besoin d'URL publique, de service de tunnel ni d'environnement déployé. La CLI transmet les événements sandbox en temps réel à votre machine et les signe exactement comme la production : le handler que vous écrivez ici est celui que vous mettrez en production. ## Écrivez l'endpoint Il doit faire trois choses, dans cet ordre : vérifier, accuser réception, puis traiter. **La forme de tout handler** ```bash # The request your endpoint will receive POST /webhooks/wajub HTTP/1.1 X-Wajub-Signature: v1=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 X-Wajub-Timestamp: 1748083260 X-Wajub-Event: payment.succeeded Content-Type: application/json {"id":"evt_…","event":"payment.succeeded","data":{…}} ``` ```javascript app.post('/webhooks/wajub', express.raw({ type: 'application/json' }), (req, res) => { let event; try { event = wajub.webhooks.constructEvent( req.body, req.headers['x-wajub-signature'], req.headers['x-wajub-timestamp'], ); } catch { return res.sendStatus(400); } res.sendStatus(200); queue.add('wajub-event', event); }); ``` ```python @app.post("/webhooks/wajub") def wajub_webhook(): try: event = wajub.webhooks.construct_event( request.get_data(), request.headers.get("X-Wajub-Signature", ""), request.headers.get("X-Wajub-Timestamp", ""), ) except WebhookSignatureVerificationError: return "", 400 queue.enqueue(handle_event, event) return "", 200 ``` ```php Route::post('/webhooks/wajub', function (Request $request) use ($wajub) { try { $event = $wajub->webhooks->constructEvent( $request->getContent(), $request->header('X-Wajub-Signature'), $request->header('X-Wajub-Timestamp'), ); } catch (Wajub\Exception\WebhookSignatureVerificationError $e) { return response()->noContent(400); } HandleWajubEvent::dispatch($event); return response()->noContent(200); }); ``` ```go func webhookHandler(w http.ResponseWriter, r *http.Request) { body, err := io.ReadAll(r.Body) if err != nil { http.Error(w, "bad request", http.StatusBadRequest) return } event, err := client.Webhooks.ConstructEvent( body, r.Header.Get("X-Wajub-Signature"), r.Header.Get("X-Wajub-Timestamp"), 0, ) if err != nil { http.Error(w, "invalid signature", http.StatusBadRequest) return } w.WriteHeader(http.StatusOK) go handleEvent(event) } ``` > [!WARNING] > **Répondez d'abord, traitez ensuite** > > Une livraison qui prend plus de 30 secondes compte comme un échec et fait l'objet d'une nouvelle > tentative : un handler qui livre la commande avant de répondre la livre de nouveau à chaque tentative. Accusez > réception, puis mettez le travail en file d'attente. ## Branchez la CLI dessus ```bash title="Transférer les événements sandbox en temps réel vers localhost" npm install -g @wajub/cli wajub login wajub listen --forward-to localhost:3000/webhooks/wajub ``` La CLI affiche un secret de signature au démarrage, le même à chaque exécution pour ce compte et cet environnement. Placez-le une seule fois dans `WAJUB_WEBHOOK_SECRET` pendant le développement (`wajub listen --print-secret` l'affiche seul) : Wajub signe avec lui les événements transférés, votre code de vérification s'exécute donc réellement au lieu d'être ignoré en local. | Option | Ce qu'elle fait | | ---------------- | ----------------------------------------------------------- | | `--forward-to` | Où envoyer le POST. `http://` est supposé si vous l'omettez | | `--events` | Des types séparés par des virgules, au lieu de tous | | `--print-secret` | Affiche le secret de signature puis s'arrête | | `--live` | Obligatoire avec une clé live | ## Provoquez un événement `wajub trigger` pilote l'API sandbox de bout en bout et laisse le vrai événement revenir jusqu'à vous. Ce n'est pas un payload synthétique : un paiement est réellement créé et traité. ```bash title="Déclencher un événement et le voir arriver" wajub trigger --list wajub trigger payment.succeeded wajub trigger payment.failed --amount 2500 wajub trigger customer.created -d name="Acme Inc" ``` Huit événements peuvent être déclenchés ainsi, et `wajub trigger --list` les affiche. | Ressource | Événements | | -------------- | ----------------------------------------------------------------------------- | | Paiements | `payment.created`, `payment.succeeded`, `payment.failed`, `payment.cancelled` | | Remboursements | `refund.succeeded`, `refund.failed` | | Clients | `customer.created`, `customer.updated` | Tout ce qui sort de cette liste s'obtient de la manière habituelle : créez la ressource avec un [numéro de test sandbox](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios) et laissez-la suivre son cours. ## Enregistrez l'endpoint pour de bon La CLI couvre le développement. La production nécessite un endpoint HTTPS enregistré, créé dans Konsole ou via l'API. ```bash title="Créer un endpoint" curl https://api.wajub.com/webhooks \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/wajub", "events": ["payment.succeeded", "payment.failed", "refund.succeeded"] }' ``` La réponse contient un secret `whsec_`, et c'est la seule fois où il est renvoyé en entier. Enregistrez-le avant de continuer. Abonnez-vous aux événements que vous traitez plutôt qu'à tous : un endpoint qui reçoit des types qu'il ignore doit quand même y répondre, et chacun d'eux pèse sur votre budget de délai. > [!TIP] > **Vérifiez la livraison, pas seulement vos logs** > > Konsole conserve chaque tentative avec son code et son corps de réponse. Si votre handler ne s'est > jamais exécuté, la réponse se trouve dans [Webhooks](https://docs.wajub.com/fr/developer-tools/konsole/webhook-tester) : un > `404` signifie que l'URL est fausse, un délai dépassé signifie que vous avez répondu trop tard, et > l'absence de ligne signifie que l'événement ne correspondait pas à votre abonnement. - [Vérification de signature](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification): Ce que fait `constructEvent`, et comment le faire à la main. - [wajub listen](https://docs.wajub.com/fr/developer-tools/cli/listen): Toutes les options de la commande que vous venez d'utiliser. - [Catalogue des événements](https://docs.wajub.com/fr/developer-tools/webhooks/events): Tout ce à quoi vous pouvez vous abonner. - [Scénarios de test](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios): Les numéros sandbox qui produisent chaque résultat. --- # Nouvelles tentatives et ordre URL: https://docs.wajub.com/fr/developer-tools/webhooks/retries > Ce qui se passe quand votre endpoint est en panne, et pourquoi un événement arrive deux fois. Quand votre endpoint échoue, Wajub livre l'événement à nouveau : votre handler peut donc s'exécuter deux fois sur le même événement. Cette page couvre ce que Wajub garantit et la forme de handler qui résiste à un doublon. ## Ce que Wajub garantit **Au moins une fois, pas exactement une fois.** Chaque événement atteint votre endpoint au moins une fois. Certains l'atteindront plusieurs fois. Concevoir pour une livraison exactement une fois, c'est concevoir pour quelque chose qu'aucun système de webhooks ne fournit. Un cas rare fait plier cette promesse : **les livraisons s'arrêtent tant que Wajub restreint vos webhooks**, dans le cadre d'une restriction de votre compte ou de sa fermeture. Les événements sont toujours enregistrés et listés par `GET /events`, mais aucun n'est envoyé, ni à vos endpoints ni à `wajub listen`. Les événements enregistrés pendant la restriction ne sont **pas** envoyés quand elle est levée : lisez-les avec `GET /events` et rejouez ceux dont vous avez besoin avec `POST /events/{id}/resend`. C'est pourquoi un rapprochement quotidien fait partie de toute intégration : ce n'est pas un filet de sécurité facultatif. Voir [La page de retour n'est pas une confirmation](https://docs.wajub.com/fr/developer-tools/webhooks/polling#the-return-page-is-not-a-confirmation). **Aucune garantie d'ordre.** Les événements sont livrés au fur et à mesure de leur production, avec des nouvelles tentatives intercalées. Un `payment.succeeded` peut arriver avant le `payment.processing` qui l'a précédé. Ne déduisez jamais l'état d'un paiement de l'ordre d'arrivée des événements. Lisez l'état dans le corps de l'événement, ou récupérez le paiement. ## Quand une livraison compte comme un échec Une livraison réussit quand votre endpoint répond avec n'importe quel `2xx` en moins de **30 secondes**. Toute autre issue est un échec. | Votre réponse | Ce qui se passe | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `2xx` | Livré. Rien de plus. | | `5xx`, ou une erreur réseau | Nouvelle tentative | | N'importe quel `4xx` | Nouvelle tentative | | `410 Gone` | **Aucune nouvelle tentative.** Votre endpoint indique qu'il n'acceptera jamais cet événement | | Aucune réponse en 30 secondes | Nouvelle tentative | | Une redirection `3xx` | Nouvelle tentative. Les redirections ne sont jamais suivies, une redirection n'aboutit donc jamais à une livraison | > [!WARNING] > **Seul un 410 met fin à la livraison** > > Un `400` ou un `404` est retenté comme un `500` : un endpoint qui répond `404` pendant un > déploiement reçoit quand même l'événement une fois revenu. Renvoyez `410` uniquement quand vous > voulez que Wajub arrête définitivement cette livraison, et `2xx` dès que vous l'avez reçue. ## Combien de temps Wajub réessaie Wajub continue d'essayer pendant **72 heures** après la première tentative. Une fois les 72 heures écoulées, la livraison est marquée `failed` et Wajub s'arrête. Votre endpoint n'est **pas** désactivé : le prochain événement sera quand même tenté, et vous pouvez rejouer à la main celui qui a échoué depuis Konsole ou avec `POST /events/{id}/resend`. Si vous supprimez ou désactivez l'endpoint pendant qu'une livraison est encore retentée, les tentatives restantes sont abandonnées. ## Dédupliquer sur l'id de l'événement **`id` dans le corps**, une valeur `evt_…`, identifie l'**événement**. Il est identique à chaque nouvelle tentative, renvoi manuel compris, et identique pour chaque endpoint qui reçoit cet événement. Stockez-le, et ignorez un événement dont vous avez déjà traité l'`id` : expédier une commande, créditer un compte ou envoyer un reçu n'a alors lieu qu'une fois. ## La forme du handler Quatre étapes, dans cet ordre. Tout l'enjeu est dans l'ordre. **Un handler qui tolère les nouvelles tentatives** ```bash # The same event, arriving a second time after a timeout. # Its body id is the one of the first attempt. {"id":"evt_aio5DpN577tNU2vOxdmuZGhT","event":"payment.succeeded","data":{…}} ``` ```javascript app.post('/webhooks/wajub', express.raw({ type: 'application/json' }), async (req, res) => { // 1. Verify before trusting anything in the body. const event = wajub.webhooks.constructEvent( req.body, req.headers['x-wajub-signature'], req.headers['x-wajub-timestamp'], ); // 2. Acknowledge within the 30 second budget, before doing any work. res.sendStatus(200); // 3. Stop if this event was already handled. if (await alreadyHandled(event.id)) return; await markHandled(event.id); // 4. Do the work, on your own queue if it can fail. await enqueue(event); }); ``` ```python @app.post("/webhooks/wajub") def webhook(): event = wajub.webhooks.construct_event( request.get_data(), request.headers.get("X-Wajub-Signature", ""), request.headers.get("X-Wajub-Timestamp", ""), ) if already_handled(event["id"]): return "", 200 mark_handled(event["id"]) queue.enqueue(handle_event, event) return "", 200 ``` ```php $event = $wajub->webhooks->constructEvent( $request->getContent(), $request->header('X-Wajub-Signature'), $request->header('X-Wajub-Timestamp'), ); // INSERT … ON CONFLICT DO NOTHING: the unique index decides, not a read. $claimed = DB::table('processed_events') ->insertOrIgnore(['event_id' => $event['id'], 'created_at' => now()]); if ($claimed) { HandleWajubEvent::dispatch($event); } return response()->noContent(200); ``` ```go event, err := client.Webhooks.ConstructEvent( body, r.Header.Get("X-Wajub-Signature"), r.Header.Get("X-Wajub-Timestamp"), 0, ) if err != nil { http.Error(w, "invalid signature", http.StatusBadRequest) return } w.WriteHeader(http.StatusOK) id, _ := event["id"].(string) if claimed, _ := claimEvent(ctx, id); claimed { go handleEvent(event) } ``` > [!WARNING] > **200 signifie reçu, pas traité** > > Accusez réception dès l'arrivée et traitez de façon asynchrone. Si votre propre traitement peut > échouer, relancez-le depuis votre propre file de tâches. Les nouvelles livraisons de Wajub ne sont > pas un moyen de rejouer votre logique métier : elles s'arrêtent au bout de 72 heures. Marquez l'événement comme traité **avant** d'effectuer le travail, pas après. Si vous le marquez après, deux nouvelles tentatives arrivées à peu d'intervalle peuvent toutes deux passer la vérification et toutes deux s'exécuter. ## Inspecter et rejouer Chaque tentative est enregistrée avec son code de statut, son corps de réponse et sa latence dans [Konsole](https://docs.wajub.com/fr/developer-tools/konsole/webhook-tester). Une fois votre endpoint corrigé, vous pouvez rejouer une seule livraison, ou jusqu'à 100 livraisons échouées d'un coup, avec le payload d'origine et un en-tête fraîchement signé. `POST /events/{id}/resend` envoie l'événement à chaque endpoint qui ne l'a pas encore accepté. Les relances ne sont pas décomptées de votre plan, mais un même événement repart vers le même endpoint au plus une fois toutes les 5 minutes, depuis Konsole ou depuis l'API. Un endpoint encore dans ce délai est ignoré et, quand tous le sont, l'appel répond `429` avec `error_code: event_resend_cooldown` et un en-tête `Retry-After`. Ce `429` n'est pas la [limite de requêtes](https://docs.wajub.com/fr/api/rate-limits) : renvoyer avant `Retry-After` obtient la même réponse. - [Vérification de signature](https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification): Vérifiez le HMAC avant de faire confiance à un payload. - [Catalogue des événements](https://docs.wajub.com/fr/developer-tools/webhooks/events): Tous les types d'événements émis par Wajub. - [Cycle de vie d'un paiement](https://docs.wajub.com/fr/payments/lifecycle): Les états qui émettent un événement, et ceux qui n'en émettent pas. - [Tester les webhooks](https://docs.wajub.com/fr/developer-tools/testing/webhooks): Recevez des événements en local sans déployer. --- # Vérification de signature URL: https://docs.wajub.com/fr/developer-tools/webhooks/signature-verification > Prouver qu'une livraison vient bien de Wajub et n'a pas été rejouée. Votre URL de webhook est publique : n'importe qui peut y poster un `payment.succeeded` bien formé. Vérifier la signature est le seul moyen de distinguer une vraie livraison d'une imitation, et deux en-têtes la portent. | En-tête | Ce que c'est | | ------------------- | ---------------------------------------------- | | `X-Wajub-Signature` | `v1=` suivi d'un HMAC-SHA256 en hexadécimal | | `X-Wajub-Timestamp` | Secondes Unix, fait partie de ce qui est signé | ## Ce qui est signé Pas le corps seul. L'horodatage et le corps, joints par un seul point. ```text title="La chaîne signée" signed = "{timestamp}.{raw_body}" digest = hex(hmac_sha256(signed, endpoint_secret)) header = "v1=" + digest ``` L'horodatage est inclus dans le HMAC exprès : une livraison interceptée ne peut pas être rejouée un jour plus tard, car la déplacer dans le temps casse la signature. Comparer l'horodatage à l'heure actuelle constitue la seconde moitié de cette protection, et les SDKs le font pour vous avec une fenêtre de 300 secondes. ## Avec un SDK Le secret appartient au client, pas à l'appel. **Vérifier, puis agir** ```bash # What Wajub sends you POST /webhooks/wajub HTTP/1.1 X-Wajub-Signature: v1=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 X-Wajub-Timestamp: 1748083260 X-Wajub-Event: payment.succeeded X-Wajub-Delivery-Id: whd_7Yh2MpL4tRb3nP8sZcXv Content-Type: application/json {"id":"evt_…","event":"payment.succeeded","data":{…}} ``` ```javascript import { Wajub } from '@wajub/node'; const wajub = new Wajub({ secretKey: process.env.WAJUB_API_KEY, webhookSecret: process.env.WAJUB_WEBHOOK_SECRET, }); app.post('/webhooks/wajub', express.raw({ type: 'application/json' }), (req, res) => { let event; try { event = wajub.webhooks.constructEvent( req.body, req.headers['x-wajub-signature'], req.headers['x-wajub-timestamp'], ); } catch { return res.sendStatus(400); } res.sendStatus(200); queue.add(event.id, event); }); ``` ```python wajub = Wajub( api_key=os.environ["WAJUB_API_KEY"], webhook_secret=os.environ["WAJUB_WEBHOOK_SECRET"], ) @app.post("/webhooks/wajub") def wajub_webhook(): try: event = wajub.webhooks.construct_event( request.get_data(), request.headers.get("X-Wajub-Signature", ""), request.headers.get("X-Wajub-Timestamp", ""), ) except WebhookSignatureVerificationError: return "", 400 queue.enqueue(handle_event, event) return "", 200 ``` ```php $wajub = new Wajub\Wajub([ 'api_key' => env('WAJUB_API_KEY'), 'webhook_secret' => env('WAJUB_WEBHOOK_SECRET'), ]); try { $event = $wajub->webhooks->constructEvent( $request->getContent(), $request->header('X-Wajub-Signature'), $request->header('X-Wajub-Timestamp'), ); } catch (Wajub\Exception\WebhookSignatureVerificationError $e) { return response()->noContent(400); } HandleWajubEvent::dispatch($event); return response()->noContent(200); ``` ```go var client *wajub.Client func init() { c, err := wajub.New(wajub.Config{ APIKey: os.Getenv("WAJUB_API_KEY"), WebhookSecret: os.Getenv("WAJUB_WEBHOOK_SECRET"), }) if err != nil { log.Fatalf("wajub: %v", err) } client = c } func handler(w http.ResponseWriter, r *http.Request) { body, err := io.ReadAll(r.Body) if err != nil { http.Error(w, "bad request", http.StatusBadRequest) return } event, err := client.Webhooks.ConstructEvent( body, r.Header.Get("X-Wajub-Signature"), r.Header.Get("X-Wajub-Timestamp"), 0, ) if err != nil { http.Error(w, "invalid signature", http.StatusBadRequest) return } w.WriteHeader(http.StatusOK) go handleEvent(event) } ``` > [!CAUTION] > **Le secret n'est pas un quatrième argument** > > `constructEvent` prend le payload, la signature, l'horodatage, puis une **tolérance**, jamais > votre secret : le secret se passe au client que vous construisez, une seule fois. La tolérance > est en secondes, ou une `time.Duration` en Go, une `Duration` en Java et un `TimeSpan` en C#. Go et > Java exigent l'argument : passez `0` en Go, ou `null` en Java, pour la fenêtre par défaut de 300 > secondes. ## Sans SDK Trois étapes, dans cet ordre : vérifier le préfixe, recalculer le digest, comparer en temps constant. Ensuite seulement, regardez l'horodatage. **Vérifier à la main** ```bash # Reproduce a signature locally from a captured delivery TIMESTAMP=1748083260 BODY=$(cat delivery.json) printf '%s.%s' "$TIMESTAMP" "$BODY" \ | openssl dgst -sha256 -hmac "$WAJUB_WEBHOOK_SECRET" -hex ``` ```javascript import { createHmac, timingSafeEqual } from 'node:crypto'; function verify(rawBody, signatureHeader, timestampHeader, secret) { if (!signatureHeader?.startsWith('v1=')) return false; const received = signatureHeader.slice(3); const expected = createHmac('sha256', secret) .update(`${timestampHeader}.${rawBody}`) .digest('hex'); // timingSafeEqual throws on a length mismatch, which is exactly what a // forged signature looks like. if (received.length !== expected.length) return false; if (!timingSafeEqual(Buffer.from(received), Buffer.from(expected))) return false; return Math.abs(Date.now() / 1000 - Number(timestampHeader)) <= 300; } ``` ```python import hashlib, hmac, time def verify(raw_body: bytes, signature_header: str, timestamp_header: str, secret: str) -> bool: if not signature_header.startswith("v1="): return False received = signature_header[3:] signed = f"{timestamp_header}.".encode() + raw_body expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() if not hmac.compare_digest(received, expected): return False return abs(time.time() - float(timestamp_header)) <= 300 ``` ```php function verify(string $rawBody, string $signatureHeader, string $timestampHeader, string $secret): bool { if (! str_starts_with($signatureHeader, 'v1=')) { return false; } $received = substr($signatureHeader, 3); $expected = hash_hmac('sha256', $timestampHeader.'.'.$rawBody, $secret); if (! hash_equals($expected, $received)) { return false; } return abs(time() - (float) $timestampHeader) <= 300; } ``` ```go func verify(rawBody []byte, signatureHeader, timestampHeader, secret string) bool { if !strings.HasPrefix(signatureHeader, "v1=") { return false } mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte(timestampHeader + ".")) mac.Write(rawBody) expected := hex.EncodeToString(mac.Sum(nil)) if !hmac.Equal([]byte(expected), []byte(signatureHeader[3:])) { return false } ts, err := strconv.ParseFloat(timestampHeader, 64) if err != nil { return false } return math.Abs(float64(time.Now().Unix())-ts) <= 300 } ``` ## Les quatre erreurs classiques ### Le corps a été parsé avant d'être hashé C'est la cause de presque toutes les signatures qui refusent de se vérifier. Votre framework parse le JSON, vous le resérialisez pour le hasher, et les octets reviennent dans un ordre différent ou avec d'autres espaces. Le digest porte sur les octets exacts que nous avons envoyés. | Framework | Quoi utiliser | | --------------------- | ---------------------------------------------------------------------- | | Express | `express.raw({ type: 'application/json' })` sur cette route uniquement | | Flask | `request.get_data()`, jamais `request.json` | | Laravel | `$request->getContent()` | | Go | `io.ReadAll(r.Body)` avant tout décodeur | | Route handler Next.js | `await request.text()` | ### La comparaison a levé une exception au lieu de renvoyer false `crypto.timingSafeEqual` de Node lève une `RangeError` quand les deux buffers n'ont pas la même longueur, et une signature falsifiée a généralement une longueur différente. Sans vérification préalable de la longueur, votre handler plante précisément sur la requête qu'il devait rejeter. `hash_equals` et `compare_digest` gèrent ce cas eux-mêmes. ### Le type d'événement a été lu dans le mauvais champ > [!WARNING] > **Le champ s'appelle `event`** > > L'enveloppe porte `event`, pas `type`. Un switch sur `type` ne tombe dans aucun cas et rien n'est > livré. Lisez `event.event`, ou routez sur l'en-tête `X-Wajub-Event`. ### L'horloge a dérivé La vérification tolère 300 secondes d'écart entre l'horodatage signé et l'horloge de votre serveur. Un conteneur dont l'horloge a dérivé au-delà rejette toutes les livraisons, même avec une signature valide. Si tout s'est mis à échouer d'un coup sans que rien n'ait changé dans votre code, vérifiez NTP avant de vérifier le secret. ## Livraisons du cycle de vie Sync Les événements d'onboarding et de connexion que reçoit une plateforme Sync, dont `account.connected`, sont signés de la même façon, avec le même secret d'endpoint, sous leurs propres en-têtes. | En-tête | Ce que c'est | | --------------------- | --------------------------------------------------------------------- | | `X-Sync-Signature-V1` | `v1=` suivi du HMAC-SHA256 en hexadécimal de `{timestamp}.{raw_body}` | | `X-Sync-Timestamp` | Secondes Unix, fait partie de ce qui est signé | Vérifiez-les comme toute autre livraison, avec la même fenêtre de 300 secondes : passez `X-Sync-Signature-V1` et `X-Sync-Timestamp` à `constructEvent` à la place des en-têtes `X-Wajub-`, ou à la fonction `verify` de [Sans SDK](#without-an-sdk). Refusez une livraison dont l'horodatage sort de la fenêtre, même si sa signature correspond. `constructEvent` renvoie le corps tel quel, et ces livraisons ont un corps à plat plutôt que l'enveloppe habituelle, décrit dans [le catalogue des événements](https://docs.wajub.com/fr/developer-tools/webhooks/events#sync-lifecycle-deliveries). Enregistrez ensuite chaque `X-Idempotency-Key` traité, et ignorez une livraison dont la clé a déjà été vue. ```text title="Les en-têtes d'une livraison du cycle de vie Sync" X-Sync-Event: account.connected X-Sync-Timestamp: 1748083260 X-Sync-Signature-V1: v1=5d41f2a8c3e07b9a1f64d2e8b0c7a95e3f18d6b4a2c9e07f1b3d5a8c6e2f4b90 X-Idempotency-Key: 9b74c9897bac770ffc029102a200c5de35d0f7b1a8e7c3b6d4f2a1e0c9b8a7f6 ``` ## Le secret Chaque endpoint a le sien, qui commence par `whsec_`, affiché une seule fois à la création de l'endpoint puis consultable dans Konsole. Le renouveler se fait en un seul appel. ```bash title="Renouveler le secret d'un endpoint" curl -X POST https://api.wajub.com/webhooks/9d3f6a2e-4b1c-4e8a-b7d2-5c9e1f0a3b64/rotate-secret \ -H "Authorization: sk.xxxxxxxxxxxxxxxx…" ``` Wajub génère le nouveau secret : vous ne pouvez donc pas le déployer à l'avance. Il prend effet aussitôt : chaque tentative envoyée ensuite est signée avec lui, y compris les nouvelles tentatives d'événements plus anciens, car une tentative est signée au moment de son envoi. Pour basculer sans perdre de livraison : 1. Modifiez votre gestionnaire pour qu'il accepte une signature faite avec l'un ou l'autre de deux secrets, et déployez-le avec le secret actuel seul. 2. Renouvelez le secret, et ajoutez le nouveau, affiché une seule fois, comme second secret. 3. Quand plus rien n'a été refusé depuis un moment, retirez l'ancien. Une livraison refusée pendant la bascule n'est pas perdue : elle est retentée, signée avec le nouveau secret. Le renouvellement depuis le Dashboard est plus doux. Dans Konsole, ou dans l'onglet Webhooks d'un lien de paiement, vous pouvez garder l'ancien secret valide 24 heures : pendant ce temps, chaque livraison porte une seconde signature faite avec lui, dans `X-Wajub-Signature-Previous` (`X-Webhook-Signature-Previous` pour les endpoints propres à un lien de paiement). `X-Wajub-Signature` porte toujours le secret actuel : un gestionnaire qui la vérifie n'est pas affecté, et un gestionnaire encore sur l'ancien secret peut vérifier le second en-tête jusqu'à votre bascule. Un renouvellement par l'API met fin aussitôt à un tel recouvrement. - [Démarrage rapide](https://docs.wajub.com/fr/developer-tools/webhooks/quickstart): Recevez d'abord un événement signé sur votre machine. - [Nouvelles tentatives et échecs](https://docs.wajub.com/fr/developer-tools/webhooks/retries): Ce qui se passe quand vous répondez 400. - [Dépannage des webhooks](https://docs.wajub.com/fr/resources/troubleshooting/webhooks): La signature ne se vérifie jamais, symptôme par symptôme. - [Bonnes pratiques de sécurité](https://docs.wajub.com/fr/best-practices/security): La place des secrets de webhook parmi vos autres identifiants. --- # Bibliothèques URL: https://docs.wajub.com/fr/libraries > Les trois familles de packages Wajub et celle dont votre couche a besoin. Le package Wajub dont vous avez besoin dépend d'une seule question : l'endroit où s'exécute votre code. - [Wajub Components](https://docs.wajub.com/fr/libraries/components): Dans le navigateur. Checkout hébergé ou champs de paiement que vous disposez vous-même. - [SDKs](https://docs.wajub.com/fr/libraries/sdks): Sur votre serveur, dans votre application mobile ou en ligne de commande. - [Plugins](https://docs.wajub.com/fr/libraries/plugins): Aucun code à écrire pour WordPress et WooCommerce. ## Où s'exécute votre code Cette question détermine le package. Le tableau qui y répond, du navigateur à la ligne de commande, et la règle qui s'applique, la clé secrète ne quitte jamais votre serveur, figurent dans [SDKs](https://docs.wajub.com/fr/libraries/sdks#where-your-code-runs). La plupart des intégrations utilisent deux packages : un SDK serveur pour créer le paiement et un package pour navigateur ou mobile afin de l'encaisser. ## Commencez ici - [Démarrage rapide des SDKs](https://docs.wajub.com/fr/libraries/sdks/quickstart): Une clé, une commande d'installation et un appel fonctionnel. - [Choisir votre SDK](https://docs.wajub.com/fr/libraries/sdks): Les versions minimales des environnements d'exécution et les contraintes qui excluent une option. - [Choisir une intégration](https://docs.wajub.com/fr/payments/integration-paths): Redirection, intégration ou formulaire personnalisé. Découvrez quoi choisir et pourquoi. - [Sessions et sécurité](https://docs.wajub.com/fr/libraries/components/sessions): Où utiliser chaque clé et ce qu'elle permet de faire. - [SDKs mobiles](https://docs.wajub.com/fr/libraries/sdks/mobile): Une interface de paiement native, sans WebView. - [Projets d'exemple](https://docs.wajub.com/fr/libraries/sdks/examples): Du code fonctionnel et la place de chaque élément. --- # Angular URL: https://docs.wajub.com/fr/libraries/components/angular > provideWajub, le service, les composants standalone et la configuration Angular SSR associée. `@wajub/angular` vous donne `provideWajub()`, un service, des composants standalone pour le checkout et pour chacun des sept groupes de champs, et `injectConfirmPayment()`. Le rôle de chaque option est présenté dans [Afficher le checkout](https://docs.wajub.com/fr/libraries/components/hosted-checkout) et [Champs de paiement](https://docs.wajub.com/fr/libraries/components/payment-fields). Cette page traite des éléments propres à Angular. **`@wajub/angular`**: version 1.8.1, GA, npm, Angular 17+ · Angular SSR ## Installer `@wajub/js` est une dépendance homologue. Installez-la donc sur la même ligne. Le package demande Angular 17 ou une version ultérieure, `@angular/core` et `@angular/common`. ```bash npm install @wajub/angular @wajub/js ``` Il fonctionne avec zone.js comme dans une application zoneless, et avec le rendu serveur et l'hydratation. ## provideWajub et le service Ajoutez `provideWajub()` à `app.config.ts` pour toute l'application, ou aux `providers` d'une route. Sans lui, les composants fonctionnent avec les valeurs par défaut. ```typescript title="src/app/app.config.ts" import { type ApplicationConfig } from '@angular/core'; import { provideWajub } from '@wajub/angular'; export const appConfig: ApplicationConfig = { providers: [provideWajub()], }; ``` | Option | Type | Valeur par défaut | Fonction | | ------- | --------- | ----------------- | -------------------------------------------------------------------------------------------------------------- | | `defer` | `boolean` | `false` | Ne charge rien tant que vous n'appelez pas `load()` sur le service, pour un checkout qui s'ouvre après un clic | > [!CAUTION] > **getRuntime() génère une erreur pendant le chargement de Wajub.js** > > Il génère une erreur tant que Wajub.js n'est pas chargé, si le chargement échoue, et toujours sur > le serveur. Lisez `runtime()`, un signal qui vaut `null` tant que l'environnement n'est pas > chargé, sauf si vous savez qu'il l'est déjà. ```typescript title="La forme sûre" import { Component, Input, inject } from '@angular/core'; import { WajubService } from '@wajub/angular'; @Component({ selector: 'app-upgrade-button', standalone: true, template: ` `, }) export class UpgradeButtonComponent { @Input({ required: true }) sessionId!: string; readonly wajub = inject(WajubService); upgrade(): void { this.wajub.runtime()?.wajub.open({ sessionId: this.sessionId, onSuccess: () => window.location.assign('/account'), }); } } ``` Le signal vaut `null` à la création du composant et se remplit une fois Wajub.js chargé. Sur le serveur, il reste à `null`. | Membre | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------- | | `runtime` | Un signal de `{ wajub, Wajub, WajubError }`, `null` tant que l'environnement n'est pas chargé, et sur le serveur | | `runtime$` | La même valeur en observable : l'environnement actuel tout de suite, puis chaque nouveau | | `loading`, `error` | Des signaux : l'environnement est en cours de chargement, et la raison de l'échec du dernier chargement, `null` sinon | | `load()` | Charge Wajub.js, avec `defer`. Une promesse de l'environnement, `null` sur le serveur | | `getRuntime()` | L'environnement. Génère une erreur pendant le chargement, après un chargement échoué et sur le serveur | ## Intégration du checkout ``, la classe `WajubCheckoutEmbedComponent`, est le checkout hébergé dans votre propre mise en page. Ses inputs sont `sessionId`, `minHeight`, `locale`, `appearance`, `layout`, `loadingText` et `showLoading`. Ses outputs sont les onze callbacks de [EmbeddedConfig](https://docs.wajub.com/fr/libraries/components/api-reference#embeddedconfig), nommés sans `on`. ```typescript title="src/app/checkout/checkout.component.ts" import { Component, Input } from '@angular/core'; import { WajubCheckoutEmbedComponent, type WajubError } from '@wajub/angular'; @Component({ selector: 'app-checkout', standalone: true, imports: [WajubCheckoutEmbedComponent], template: ` `, }) export class CheckoutComponent { @Input({ required: true }) sessionId!: string; paid(): void { window.location.assign('/order/complete'); } failed(error: WajubError | Record): void { console.error(error.code, error.message); } } ``` | Input ou output | Type | Valeur par défaut | Fonction | | --------------- | ------------------ | ----------------- | ------------------------------------------------------------------------------- | | `sessionId` | `string` | Obligatoire | La valeur `authorization_token` de `POST /payments` | | `minHeight` | `number` | `480` | Hauteur minimale de l'hôte en pixels, jusqu'à ce que le checkout fixe la sienne | | `(ready)` | `CheckoutInstance` | aucune | Le checkout est prêt, avec l'instance à piloter ensuite | | `(resize)` | `number` | aucune | La nouvelle hauteur du checkout en pixels | Les autres outputs sont `(success)`, `(error)`, `(loadError)`, `(cancel)`, `(expired)`, `(stateChange)`, `(methodChange)`, `(breakdown)` et `(close)`. L'élément hôte est le conteneur, en `display: block` et pleine largeur : placez-y votre `class` et votre `style`. Le composant expose aussi l'instance montée sous `checkoutInstance`, `null` avant le montage, pour un `viewChild` ou une référence de template. Les inputs peuvent changer après le montage, et un nouveau `sessionId` charge un nouveau checkout. ## Champs de paiement Les sept composants affichent chacun un groupe de champs : ``, ``, ``, ``, ``, `` et ``, les classes `WajubCardComponent` à `WajubCryptoComponent`. ``, la classe `WajubComponentEmbedComponent`, est le même composant avec un input `type` obligatoire, lorsque le choix intervient pendant l'exécution. Chaque option de [ComponentConfig](https://docs.wajub.com/fr/libraries/components/payment-fields) est un input du même nom, et chaque callback un output nommé sans `on`. ```typescript title="Votre mise en page et votre bouton" import { Component, Input, signal } from '@angular/core'; import { WajubAddressComponent, WajubPaymentComponent, injectConfirmPayment, type ComponentInstance, } from '@wajub/angular'; @Component({ selector: 'app-pay-form', standalone: true, imports: [WajubAddressComponent, WajubPaymentComponent], template: ` `, }) export class PayFormComponent { @Input({ required: true }) sessionId!: string; // Une fonction, pour suivre une session qui change. readonly payment = injectConfirmPayment(() => this.sessionId); // Un signal : (instance) émet null en pleine détection des changements quand le formulaire part. readonly field = signal(null); pay(): void { const field = this.field(); if (field) this.payment.confirm(field); } } ``` | Input ou output | Type | Valeur par défaut | Fonction | | --------------- | ----------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `ComponentType` | Obligatoire | Uniquement sur `` | | `loader` | `'skeleton'` ou `'none'` | `'skeleton'` | `'skeleton'` : l'hôte garde la hauteur du formulaire dès le premier rendu, avec un squelette dans le style de vos champs. `'none'` : aucun squelette | | `minHeight` | `number` | Non définie | Hauteur minimale de l'hôte en pixels. Un `min-height` dans le `style` de l'hôte, en attribut ou en binding, compte de la même façon | | `readyTimeout` | `number` | Non définie | Millisecondes d'attente du formulaire. Au-delà, `(loadError)` reçoit une `WajubError` de code `ready_timeout`. Non définie, aucune limite | | `beforeSubmit` | `() => boolean \| Promise` | aucune | S'exécute avant le débit, pour passer votre commande : `false`, ou une erreur, ne débite rien. Définissez-le dès le premier rendu du champ. Appelé sans `this`, voir ci-dessous | | `(instance)` | `ComponentInstance \| null` | aucune | L'instance une fois montée, `null` une fois partie : un nouveau montage, ou le composant détruit | | `(ready)` | `ComponentInstance` | aucune | Le formulaire est prêt et interactif | | `(stateChange)` | `{ state, method }` | aucune | Le paiement passe à une autre étape, par exemple `APPROVAL_REQUIRED` pendant que le payeur valide sur son téléphone | | `(resize)` | `{ height }` | aucune | Le champ prend une nouvelle hauteur, en pixels | | `(redirect)` | `{ url, method }` | aucune | Le paiement continue sur la page du prestataire, et votre page va s'y rendre | Les autres outputs sont `(change)`, `(focus)`, `(blur)`, `(success)`, `(error)`, `(loadError)` et `(methodChange)`. L'élément hôte est en `display: block` et pleine largeur : placez-y votre `class` et votre `style`. Le composant expose l'instance montée sous `componentInstance`, `null` avant le montage. `(instance)` émet `null` pendant la destruction du formulaire, en pleine détection des changements. Gardez l'instance dans un signal, ou dans un champ que seul votre code lit : un simple champ lu par un binding placé plus haut dans le template déclenche `NG0100`, ExpressionChangedAfterItHasBeenChecked, en développement. > [!WARNING] > **beforeSubmit est appelé sans this** > > Comme tout callback, `beforeSubmit` est appelé seul : une simple méthode de votre classe passée en > `[beforeSubmit]="placeOrder"` n'atteint pas votre composant par `this`. Déclarez-la comme fonction > fléchée dans un champ, `readonly placeOrder = async () => …`, ou liez la méthode dans votre > classe. Si elle lève une erreur ou rejette, rien n'est débité. ## injectConfirmPayment `injectConfirmPayment(sessionId?)` envoie un composant de champ pour vous. Appelez-le dans un contexte d'injection, l'initialiseur d'un champ ou un constructeur. Il renvoie `{ confirm(instance, options?), isConfirming }`. | Membre | Fonction | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `confirm(instance, options?)` | Envoie le composant de champ qu'il reçoit et se résout avec l'issue. Il rejette avant le chargement de Wajub.js, et sans session | | `isConfirming` | Un signal : un paiement est en cours | Passez un signal ou une fonction, `() => this.sessionId`, pour suivre une session qui change, ou une simple chaîne, le type `SessionIdSource`. Un `sessionId` dans `options` l'emporte. ## Types Chaque type de `@wajub/js` est aussi exporté : un seul import sert les deux packages, et `import type { PaymentSuccess } from '@wajub/angular'` fonctionne. Les inputs et les outputs sont typés sur les classes des composants, que lit la vérification des types de templates d'Angular. Le package ajoute `WajubOptions`, ce que prend `provideWajub()`, `SessionIdSource`, la session que prend `injectConfirmPayment()`, et `WajubConfirmPayment`, ce qu'il renvoie. ## Mobile Money et carte dans votre propre checkout Votre checkout garde son formulaire, son choix de moyen de paiement et son bouton Payer, et chaque moyen n'affiche que ses champs, dans le style de votre page. Les étapes, les appels serveur et la raison de chaque option sont dans [Champs de paiement](https://docs.wajub.com/fr/libraries/components/payment-fields#mobile-money-and-card-in-your-own-checkout). Ici, votre serveur a préparé le paiement avec `deferred: true` à l'ouverture du checkout, et a transmis à la page son `authorization_token` et son `authorization_url`. ```typescript title="payment-step.component.ts" import { Component, Input, computed, signal } from '@angular/core'; import { WajubCardComponent, WajubMobileMoneyComponent, injectConfirmPayment, type ComponentInstance, type WajubError, } from '@wajub/angular'; // Le paiement est en cours, ou attend le payeur : rien ne doit changer sur la page. const RUNNING = [ 'PROCESSING', 'VERIFYING', 'PENDING', 'OTP_REQUIRED', 'PIN_REQUIRED', 'PHONE_REQUIRED', 'BIRTHDAY_REQUIRED', 'ADDRESS_REQUIRED', '3DS_REQUIRED', 'USSD_REQUIRED', 'APPROVAL_REQUIRED', ]; @Component({ selector: 'app-payment-step', standalone: true, imports: [WajubCardComponent, WajubMobileMoneyComponent], template: `
@if (fallback()) {

Vous finirez sur la page de paiement sécurisée de Wajub.

} @else if (method() === 'card') { } @else { } @if (step() === 'APPROVAL_REQUIRED') {

Validez le paiement sur votre téléphone.

} `, }) export class PaymentStepComponent { // L'authorization_token et l'authorization_url du paiement préparé, transmis par votre serveur. @Input({ required: true }) sessionId!: string; @Input({ required: true }) hostedUrl!: string; readonly method = signal<'mobileMoney' | 'card'>('mobileMoney'); readonly complete = signal(false); readonly step = signal('INITIATED'); readonly fallback = signal(false); private readonly payment = injectConfirmPayment(() => this.sessionId); readonly locked = computed(() => this.payment.isConfirming() || RUNNING.includes(this.step())); private component: ComponentInstance | null = null; // Votre serveur vérifie le panier, passe la commande et active le paiement. // Une fonction fléchée, pour que this soit votre composant quand le champ l'appelle. readonly placeOrder = async (): Promise => { const response = await fetch('/checkout/place-order', { method: 'POST' }); return response.ok; // false : rien n'est débité }; // Changer de moyen détruit un formulaire et monte l'autre : null entre les deux. mounted(instance: ComponentInstance | null): void { this.component = instance; this.complete.set(false); } loadFailed(error: WajubError | Record): void { if (error.code === 'ready_timeout') this.fallback.set(true); } async pay(): Promise { if (this.fallback()) { // Un paiement préparé n'est débité qu'une fois activé : passez d'abord la commande. if (await this.placeOrder()) window.location.assign(this.hostedUrl); return; } if (!this.component) return; try { await this.payment.confirm(this.component); window.location.assign('/thanks'); } catch { // Le formulaire affiche la raison, et le payeur peut y réessayer. } } } ``` Les champs affichent eux-mêmes un paiement refusé, et le payeur y réessaie. S'ils ne s'affichent pas dans le délai `readyTimeout`, le bouton Payer passe la commande puis envoie le payeur sur la page de Wajub : un paiement préparé n'est débité qu'une fois activé. `appearance.inherit` lit un champ texte de votre page, son libellé, votre bouton principal et le fond derrière les champs. Affichez donc les champs de votre propre formulaire avant cette étape, ou nommez-les avec `[appearance]="{ inherit: { input: '#email', button: '#pay' } }"`. Marquez la commande payée sur votre serveur, à partir du webhook `payment.succeeded`, jamais depuis le navigateur. ## Angular SSR La session est créée sur votre serveur. Aucun élément de ce package ne nécessite ni ne doit recevoir de clé secrète. ```typescript title="server.ts" import express from 'express'; import { Wajub } from '@wajub/node'; const wajub = new Wajub({ secretKey: process.env['WAJUB_API_KEY']! }); // Sur l'application Express que crée server.ts, avant le handler qui affiche Angular. app.post('/api/checkout/session', express.json(), async (req, res) => { const { cartId } = req.body; const payment = await wajub.payments.create( { amount: 25000, currency: 'XAF', description: `Cart ${cartId}`, customer: { email: 'buyer@example.com' }, metadata: { cart_id: cartId }, }, { idempotencyKey: `cart-${cartId}` }, ); res.json({ sessionId: payment.authorization_token }); }); ``` > [!CAUTION] > **src/environments est réservé à la clé publique** > > Chaque fichier `environment.ts` est compilé dans le bundle du navigateur. `pk.` peut y figurer, > jamais `sk.`. Une clé secrète envoyée depuis un navigateur reçoit une réponse `403` et son > propriétaire est alerté par e-mail. Angular SSR impose trois autres règles : - Rien à exclure. Les composants s'affichent sur le serveur et le formulaire se monte dans le navigateur : `provideClientHydration()` ne demande rien de plus, ni `ngSkipHydration`, ni `isPlatformBrowser()` autour des composants. - Placez `provideWajub()` dans `app.config.ts`, pour qu'un seul service serve tout le flux de checkout. - Récupérez la session depuis votre serveur et transmettez le jeton comme input. ## Éléments exportés par le package Les exports sont listés dans la [Référence du SDK](https://docs.wajub.com/fr/libraries/components/api-reference#framework-packages), les types que le package ajoute dans [TypeScript](https://docs.wajub.com/fr/libraries/components/typescript#framework-types). - [Afficher le checkout](https://docs.wajub.com/fr/libraries/components/hosted-checkout): Toutes les options et tous les callbacks derrière les inputs de l'intégration. - [Champs de paiement](https://docs.wajub.com/fr/libraries/components/payment-fields): Ce que collecte chaque composant de champ et ses limites. - [Sessions et sécurité](https://docs.wajub.com/fr/libraries/components/sessions): L'origine du jeton et ce qu'il permet de faire. - [Apparence](https://docs.wajub.com/fr/libraries/components/appearance): Thèmes, couleurs, locale et mise en page. --- # Référence du SDK URL: https://docs.wajub.com/fr/libraries/components/api-reference > Tous les exports, options, méthodes, types, états et codes d'erreur de @wajub/js. Tous les exports, options, méthodes, types, états et codes d'erreur de `@wajub/js`. Les guides expliquent quand utiliser chaque élément. ## Deux façons d'accéder à la même API Le runtime est un objet unique. Vous pouvez importer des helpers qui le chargent pour vous, ou le conserver vous-même. ```typescript title="Les helpers ou le runtime" import { mount, open, checkout, components, confirmPayment } from '@wajub/js'; import { loadWajub } from '@wajub/js/pure'; const rt = await loadWajub(); rt?.wajub.mount('#checkout', { sessionId }); ``` | Export de `@wajub/js` | Renvoie | Remarques | | --------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `mount(container, config)` | `Promise` | `null` sur le serveur | | `open(config)` | `Promise` | `null` sur le serveur | | `checkout(config)` | `Promise` | Redirige la page | | `components(sessionId, options?)` | `Promise` | `null` sur le serveur | | `confirmPayment(options)` | `Promise<{ status, transaction? }>` | Rejette avec `WajubError` | | `fetchSession(sessionId)` | `Promise` | Fonctionne avant tout montage | | `signals()` | `Promise` | Signaux de l'appareil pour un débit fait depuis votre serveur, voir [Shield](https://docs.wajub.com/fr/risk/shield/quickstart#if-you-run-your-own-checkout) | | `preload(sessionId, options?)` | `Promise` | Prépare le checkout avant que le payeur l'atteigne. `{ iframe: true }` charge aussi le checkout de cette session | | `appearanceFrom(container, source?)` | `Promise` | Ce que `appearance.inherit` lirait pour un composant dans `container`. `null` sur le serveur | | `componentReserveHeight(type, variant?, fields?)` | `number` | La place que tient `loader: 'skeleton'`, en px | | `componentEstimatedHeight(type, variant?, fields?)` | `number` | La même place, estimée, identique sur le serveur et dans le navigateur : à tenir dans un rendu serveur et son hydratation | | `getVersion()` | `Promise` | La version du runtime chargé | | `loadWajub()` | `Promise` | `null` sur le serveur | | `WajubError` | Déclarée dans les types seulement | Non exportée à l'exécution, lisez-la dans `loadWajub()` | ## Le runtime `WajubRuntime` La valeur résolue par `loadWajub()` et placée dans `window` par la balise script. | Membre | Description | | ------------ | ------------------------------------------------- | | `wajub` | L'objet du SDK, décrit dans le tableau ci-dessous | | `Wajub` | La fabrique de clients | | `WajubError` | La classe d'erreur | ### L'objet `wajub` | Membre | Signature | | ------------------------ | ---------------------------------------------------------------------------------------------------- | | `mount` | `(container, config) => CheckoutInstance` | | `open` | `(config) => PopupInstance` | | `checkout` | `(config) => void` | | `components` | `(sessionId, options?) => ComponentsFactory` | | `confirmPayment` | `(options) => Promise<{ status }>` | | `fetchSession` | `(sessionId) => Promise` | | `signals` | `() => Promise` | | `preload` | `(sessionId, options?) => void` | | `appearanceFrom` | `(container, source?) => AppearanceConfig`. `{}` quand il n'y a rien à lire, ne lève jamais d'erreur | | `componentReserveHeight` | `(type, variant?, fields?) => number`. La place que tient `loader: 'skeleton'`, en px | | `create` | La fabrique `Wajub`, le même objet | | `version` | La chaîne de version du runtime | Ces méthodes sont synchrones une fois le runtime en main. ## Le client `Wajub()` Un client conserve une clé publique, une session ou les deux pour éviter de les répéter. | Appel | Résultat | | -------------------------------------- | --------------------------------------------- | | `Wajub('pk_test.…')` | Un client capable d'appeler `createPayment()` | | `Wajub.session(token)` | Un client lié à une session existante | | `Wajub({ publishableKey, sessionId })` | Les deux à la fois | | Option | Rôle | | ---------------- | ----------------------------------------- | | `sessionId` | Le `authorization_token` de votre serveur | | `publishableKey` | Votre clé publique, `pk.` ou `pk_test.` | ### Membres du client | Membre | Rôle | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `publishableKey`, `sessionId`, `environment` | Les valeurs actuellement conservées par le client | | `useSession(sessionId)` | Lie une autre session et renvoie le client | | `createPayment(params)` | `POST /payments` avec la clé publique | | `initCheckout(options)` | Crée et affiche le paiement en un appel | | `fetchSession(sessionId?)` | Aperçu de la session | | `signals()` | Signaux de l'appareil pour un débit fait depuis votre serveur, voir [Shield](https://docs.wajub.com/fr/risk/shield/quickstart#if-you-run-your-own-checkout) | | `preload(sessionId?, options?)` | Prépare le checkout à l'avance | | `mount`, `open`, `checkout` | Les trois modes hébergés, avec la session déjà liée | | `components(sessionIdOrConfig?, config?)` | La fabrique de champs | | `appearanceFrom(container, source?)` | Ce que `appearance.inherit` lirait | | `confirmPayment(options?)` | Soumet un composant monté | ### Méthodes statiques de la fabrique | Membre | Rôle | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `Wajub.session(sessionId, options?)` | Un client lié à une session | | `Wajub.parsePublishableKey(key)` | `{ key, environment }`, déclenche une erreur avec une clé secrète | | `Wajub.createPayment(key, params, options?)` | Un appel unique, sans client à conserver | | `Wajub.signals()` | Signaux de l'appareil pour un débit fait depuis votre serveur, voir [Shield](https://docs.wajub.com/fr/risk/shield/quickstart#if-you-run-your-own-checkout) | ## La configuration `EmbeddedConfig` Utilisée par `mount()`, par `CheckoutEmbed` dans chaque framework et comme base de `PopupConfig`. | Option | Type | Valeur par défaut | | ------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------ | | `sessionId` | `string` | Obligatoire | | `locale` | `string` | Valeur par défaut de la session | | `layout` | `CheckoutLayout` | Valeur par défaut de la session | | `appearance` | `AppearanceConfig` | Votre image de marque du Dashboard. `inherit` est lu autour du conteneur pour `mount()`, sur toute la page pour `open()` | | `loadingText` | `string` | Vide | | `showLoading` | `boolean` | `true` | | Callback | Reçoit | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `onReady` | `CheckoutInstance` | | `onSuccess` | [`PaymentSuccess`](#paymentsuccess) | | `onError` | `WajubError`, un paiement qui a échoué, ou `nothing_to_submit` lorsque `submit()` n'avait aucun bouton sur lequel appuyer | | `onLoadError` | `WajubError`, un checkout qui n'a jamais démarré : `session_not_found`, `session_terminal_expired` ou `load_error`. Juste après, la superposition se ferme ou le checkout en ligne quitte la page, sans `onClose` | | `onCancel` | Rien | | `onExpired` | Rien | | `onStateChange` | `{ state?: CheckoutState, method?: string }` | | `onMethodChange` | `{ methodId? }` | | `onBreakdown` | `EmbedBreakdown`, `{ subtotal, discount, tax, total, currency }` en unités normales | | `onResize` | `height: number`, uniquement en ligne | | `onClose` | Rien. La superposition a été fermée, ou un checkout en ligne a été terminé par le bouton **Terminé** du payeur ou par `close()` | ## La configuration `PopupConfig` Tout le contenu de `EmbeddedConfig`, avec la fenêtre modale en plus. | Option | Type | Valeur par défaut | | ---------------- | --------- | ----------------- | | `width` | `number` | `920` | | `height` | `number` | `680` | | `closeOnOverlay` | `boolean` | `false` | | `closeOnEscape` | `boolean` | `true` | | `closeOnSuccess` | `boolean` | `true` | | `closeOnCancel` | `boolean` | `true` | | `closeOnExpired` | `boolean` | `true` | Les trois options de résultat `closeOn` s'exécutent après votre callback, jamais avant. ## Les instances `CheckoutInstance` et `PopupInstance` | Méthode | Rôle | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `mount()` | Remonte l'instance après `unmount()`. Sans effet si elle est déjà montée, ou après `destroy()` ou `close()` | | `unmount()` | Retire l'élément du DOM et conserve l'instance. En superposition, `onClose` n'est pas appelé | | `destroy()` | Détruit entièrement l'instance. `mount()` ne la ramène plus | | `update(partial)` | `locale`, `appearance`, `currency`, `layout`. `appearance` est fusionnée avec l'actuelle : une clé donnée à `undefined` ou `null` est effacée, et `appearance: undefined` ou `null` efface tout. Un nouveau preset `theme` remplace le précédent | | `getState()` | Le `CheckoutState` actuel | | `submit()` | Appuie sur le bouton de paiement du moyen en cours. S'il n'y a aucun bouton sur lequel appuyer, rien n'est pressé et `onError` reçoit `nothing_to_submit` | | `cancel()` | Annule le paiement en cours | | `retry()` | Lance une nouvelle tentative après un échec | | `selectMethod(methodId)` | Change de moyen de paiement | | `close()` | Termine le checkout, en ligne ou en superposition, et appelle `onClose`. `destroy()` le termine sans callback | | `isOpen()` | Indique si le checkout est encore ouvert, en ligne comme en superposition : `false` une fois terminé (réussite, annulation, expiration, fermeture) | `mount()` et `unmount()` se comportent de la même façon en ligne et en superposition. Quand un checkout revient, `onReady` se déclenche à nouveau, et le paiement reprend là où en est la session. [Piloter l'instance](https://docs.wajub.com/fr/libraries/components/hosted-checkout#driving-the-instance) précise quand `submit()` n'a aucun bouton sur lequel appuyer. ## La configuration `ComponentConfig` Transmise à `wajub.components(sessionId, options)` comme valeurs par défaut et à `factory.create(type, config)` pour chaque composant. | Option | Type | S'applique à | | ----------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sessionId` | `string` | Obligatoire | | `locale` | `string` | Tous | | `appearance` | `AppearanceConfig` | Tous | | `layout` | `CheckoutLayout` | `payment` | | `collectAddress` | `shipping` or `billing` | `payment` | | `addressMode` | `shipping` or `billing` | `address` | | `collectName` | `boolean` | `payment`, `address` | | `fields.phone` | `always`, `auto`, `never` | `payment`, `address` | | `fields.customer` | `auto` ou `external` | Tous sauf `address` | | `fields.country` | ISO 3166 alpha-2 | `mobileMoney`, `payment` | | `fields.operator` | `choose` ou `detect` | `mobileMoney`, `payment` | | `variant` | `default` ou `fields` | Tous sauf `address` | | `frameTitle` | `string` | Tous. Le nom du cadre pour les lecteurs d'écran, `Wajub component` par défaut | | `loader` | `none` ou `skeleton` | Tous. `none` par défaut, `skeleton` dans les packages de framework. [Charger sans décaler la page](https://docs.wajub.com/fr/libraries/components/payment-fields#loading-without-a-layout-shift) | | `readyTimeout` | `number`, en millisecondes | Tous. Sans `ready` à temps, `onLoadError` et `loaderror` reçoivent `ready_timeout`. `0` ou absent : aucune limite, et aucune erreur | | Callback | Reçoit | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `onBeforeSubmit` | Rien. Renvoyez `false`, ou levez une exception, pour arrêter le débit. Répondez en moins de 30 secondes. Tous sauf `address` | | `onReady` | `ComponentInstance` | | `onChange` | `ComponentChangeEvent` | | `onFocus`, `onBlur` | Rien | | `onLoadError` | `WajubError` : [un code envoyé par un checkout qui ne peut pas démarrer](#codes-a-checkout-sends-when-it-cannot-start), ou `ready_timeout` avec `readyTimeout` | | `onSuccess` | La transaction | | `onError` | `WajubError` | | `onMethodChange` | `{ methodId? }` | | `onStateChange` | `ComponentStateChangeEvent`, `{ state, method? }` | | `onResize` | `{ height }`. Le `onResize` du checkout hébergé reçoit le nombre lui-même | | `onRedirect` | `ComponentRedirectEvent`, `{ url, method }`. La page part juste après, même si le callback lève une erreur | Chaque callback est appelé juste avant l'événement du même nom. En passer un ne change rien d'autre. ## La fabrique `ComponentsFactory` | Membre | Description | | ----------------------- | --------------------------------------- | | `sessionId` | La session héritée par chaque composant | | `create(type, config?)` | Une nouvelle `ComponentInstance` | **Types.** `card`, `mobileMoney`, `bankTransfer`, `crypto`, `wallet`, `payment`, `address`. ## L'instance `ComponentInstance` Chaque méthode, sauf les méthodes de lecture, renvoie l'instance. Les appels peuvent donc être enchaînés. | Méthode | Renvoie | | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mount(container)` | L'instance | | `unmount()`, `destroy()` | Rien | | `on(event, fn)`, `off(event, fn)` | L'instance | | `update({ locale, appearance, layout, frameTitle })` | L'instance. `appearance` est fusionnée comme sur le checkout hébergé | | `focus()`, `blur()`, `submit()` | L'instance. `focus()` pendant que le chargeur `skeleton` est affiché place le focus dans le formulaire dès qu'il est prêt, sauf si le payeur a agi entre-temps | | `selectMethod(methodId)` | L'instance | | `getState()` | `CheckoutState` | | `isComplete()` | `boolean` | | `getError()` | `WajubError` or `null` | | `getValue()` | `ComponentAddressValue` or `null` | ### Événements | Événement | Payload | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ready` | `ComponentInstance` | | `change` | `ComponentChangeEvent` | | `focus`, `blur` | Rien | | `loaderror` | `WajubError` : [un code envoyé par un checkout qui ne peut pas démarrer](#codes-a-checkout-sends-when-it-cannot-start), ou `ready_timeout` avec `readyTimeout` | | `resize` | `{ height }` | | `success` | [`PaymentSuccess`](#paymentsuccess) | | `error` | `WajubError` | | `statechange` | `ComponentStateChangeEvent`, `{ state, method? }` | | `methodchange` | `{ methodId }` | | `redirect` | `ComponentRedirectEvent`, `{ url, method }`. Juste avant que votre page parte vers la page du prestataire | `on()` et `off()` typent la donnée de chaque événement ci-dessus avec `ComponentEventMap` : `card.on('statechange', (event) => event.state)` se passe de conversion. `update({ frameTitle })` renomme le cadre pour les lecteurs d'écran. `error` porte aussi `submission_failed` quand un envoi que vous avez demandé, avec `submit()` ou `confirmPayment()`, a été refusé avant tout débit. ## Les options `ConfirmPaymentOptions` | Option | Type | Valeur par défaut | | ------------ | ------------------- | ----------------------------------------------------------------------------------------------------- | | `sessionId` | `string` | Obligatoire | | `components` | `ComponentInstance` | Obligatoire, un composant monté | | `timeout` | `number` | `60000`, en millisecondes. `0` attend indéfiniment. Suspendu pendant que le paiement attend le payeur | Se résout avec `{ status, transaction }`, `transaction` étant un [`PaymentSuccess`](#paymentsuccess). Rejette avec une `WajubError` contenant `missing_component`, `wallet_not_supported` ou `address_not_payment` avant tout envoi. Ensuite, rejette avec `confirmation_timeout`, ou avec l'erreur du paiement lui-même : `checkout_validation`, `submission_failed`, `payment_error`, `payment_cancelled`, `session_expired`, `component_unmounted`, un code de refus, ou l'erreur de chargement du composant. Le temps ne court pas pendant que le paiement attend le payeur (`OTP_REQUIRED`, `PIN_REQUIRED`, `PHONE_REQUIRED`, `BIRTHDAY_REQUIRED`, `ADDRESS_REQUIRED`, `APPROVAL_REQUIRED`, `USSD_REQUIRED`, `3DS_REQUIRED`, `PENDING`), ni une fois que votre page est partie chez le prestataire (`redirect`). Un composant retiré de la page pendant l'attente rejette avec `component_unmounted`, comme avec `unmount()` et `destroy()`. `confirmation_timeout` ne fait qu'arrêter l'attente. Il n'annule rien : le paiement continue et peut encore réussir. Avant de proposer de payer à nouveau, écoutez `success` sur le composant ou attendez le webhook `payment.succeeded`. ## L'objet `PaymentSuccess` Ce que remettent `onSuccess`, l'événement `success` et `confirmPayment()`. C'est le résumé propre au checkout, pas l'objet paiement de l'API, et il vient du navigateur : confirmez le paiement sur votre serveur, avec `GET /payments/{id}` ou le webhook `payment.succeeded`, avant de livrer quoi que ce soit. | Champ | Type | Contenu | | ------------- | ----------- | ------------------------------------------------------------------------------------------ | | `id` | `string` | L'identifiant Wajub du paiement, celui que prend `GET /payments/{id}` | | `reference` | `string` | Votre référence, celle envoyée sur `POST /payments` | | `amount` | `number` | Ce que le payeur a payé, frais compris quand il les supporte, en unités normales | | `currency` | `string` | Code ISO 4217 | | `method` | `string` | La famille du moyen : `mobile_money`, `card`…, `unknown` quand la session était déjà payée | | `status` | `"success"` | Toujours `success` | | `timestamp` | `string` | Fin du paiement, au format ISO 8601 | | `receipt_url` | `string` | Le reçu hébergé du payeur, si vos reçus sont activés | Les montants sont en unités normales, comme dans l'API : `12.5` pour 12,50 EUR, `1500` pour 1 500 XAF. ## Les paramètres `CreatePaymentParams` Les données envoyées par `client.createPayment()`. Il s'agit des mêmes champs que [POST /payments](https://docs.wajub.com/fr/api/payments/create), limités à ceux qu'un navigateur peut définir. | Champ | Type | | ------------- | ---------------------------------------------------------------------------------------------------------- | | `amount` | `number`, obligatoire | | `currency` | `string`, obligatoire | | `reference` | `string` | | `description` | `string` | | `customer` | `{ email?, name?, phone?, country? }`, obligatoire avec un `email` ou un `phone`, sinon l'API répond `422` | | `bearer` | `merchant` ou `customer`, la personne qui paie les frais | | `callback` | URL HTTPS, uniquement pour le flux avec redirection | | `metadata` | `Record` | ### Le résultat `CreatePaymentResult` | Champ | Description | | -------------------- | ----------------------------------------------------- | | `sessionId` | Passez cette valeur à `mount`, `open` ou `components` | | `authorizationToken` | La même valeur, sous le nom utilisé par l'API | | `authorizationUrl` | La page hébergée ou `null` | | `transaction` | L'objet de transaction ou `null` | | `raw` | La réponse brute de l'API | ## Les options `InitCheckoutOptions` Crée et affiche le paiement en un seul appel. Tout le contenu de `EmbeddedConfig` s'applique aussi. | Option | Type | Rôle | | ----------- | ------------------------------- | ----------------------------------- | | `mode` | `inline`, `overlay`, `redirect` | Mode d'affichage du checkout | | `container` | `string` ou `HTMLElement` | Obligatoire pour `inline` | | `sessionId` | `string` | Ignore `createPayment()` | | `payment` | `CreatePaymentParams` | Utilisé en l'absence de `sessionId` | | `checkout` | `Partial` | Options de l'intégration elle-même | Se résout avec `{ session, instance }` et déclenche `missing_container` lorsque le mode `inline` n'a aucun emplacement de montage. ## L'aperçu `SessionPreview` La valeur résolue par `fetchSession(sessionId)`. Lisez-la avant le montage pour afficher un montant, le nom d'un marchand ou une bannière de sandbox. | Champ | Type | | ----------------- | ----------------------------------------------------------------------------------- | | `session_id` | `string` | | `status` | `string` | | `environment` | `sandbox` ou `live` | | `amount` | `number`, en unités normales comme dans l'API | | `currency` | `string` | | `merchant_name` | `string` | | `payment_methods` | `Array<{ id, type, label }>` | | `saved_methods` | `Array<{ id, type, label }>`, pour les clients existants que votre serveur a nommés | `saved_methods` liste les moyens avec lesquels un client a déjà payé, et uniquement sur un paiement dont votre serveur a nommé le client : un paiement créé avec `POST /payments` et votre clé secrète (ou une clé restreinte) avec un `customer`, un paiement activé avec `POST /payments/{id}/activate`, ou le paiement d'une facture liée à l'un de vos clients. Un lien de paiement, un paiement créé avec votre clé publique et une facture adressée à un simple nom n'en listent jamais, car l'e-mail saisi sur ces pages peut être celui de quelqu'un d'autre. Payer avec un moyen enregistré sur un tel paiement est refusé avant tout débit, avec le statut HTTP `422`, le code `saved_method_not_allowed` et le message « Saved payment methods cannot be used for this payment. » ## L'objet `ClientSignals` Ce que renvoie `signals()` : un objet opaque qui porte les signaux de l'appareil du payeur, pour un débit que vous faites depuis votre propre serveur. Ne le construisez pas, ne le modifiez pas et ne le stockez pas. La façon de le transmettre est décrite dans [Shield](https://docs.wajub.com/fr/risk/shield/quickstart#if-you-run-your-own-checkout). ## La configuration `AppearanceConfig` La liste complète des clés, les préréglages et les règles de filtrage se trouvent dans [Apparence](https://docs.wajub.com/fr/libraries/components/appearance). | Groupe | Clés | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Préréglage | `theme` : `stripe`, `night`, `flat`, `none`. `light`, `dark`, `system` ou `auto` fixe `colorScheme` quand celui-ci n'est pas donné | | Couleur | `primaryColor`, `secondaryColor`, `backgroundColor`, `buttonTextColor`, `inputBackgroundColor`, `inputBorderColor`, `textMutedColor`, `successColor`, `errorColor` | | Forme | `fontFamily`, `borderRadius`, `shadow` | | Comportement | `colorScheme`, `labels`, `disableAnimations` | | Jetons | `variables`, seize clés de jetons de design | | Sélecteurs | `rules`, uniquement `.Input` et `.Label` | | Votre page | `inherit` : `true`, ou un `InheritSource`, `{ input?, label?, button?, background? }`, chacun un sélecteur CSS ou un élément. [Reprendre le style de votre page](https://docs.wajub.com/fr/libraries/components/appearance#taking-your-pages-look) | ## États `getState()` et `onStateChange` utilisent tous deux ce vocabulaire. ```text title="CheckoutState" INITIATED → COLLECTING_DETAILS → PROCESSING → SUCCESS ↘ OTP_REQUIRED, PIN_REQUIRED, PHONE_REQUIRED ↘ BIRTHDAY_REQUIRED, ADDRESS_REQUIRED ↘ 3DS_REQUIRED, USSD_REQUIRED, APPROVAL_REQUIRED ↘ VERIFYING, PENDING ↘ FAILED, CANCELLED, EXPIRED ``` Une nouvelle instance indique `INITIATED` tant que le paiement n'avance pas. `PIN_REQUIRED`, `PHONE_REQUIRED`, `BIRTHDAY_REQUIRED` et `ADDRESS_REQUIRED` sont les étapes que certains paiements ajoutent après le premier envoi : le code PIN d'un portefeuille, un numéro à confirmer, une date de naissance, une adresse. Sur le checkout hébergé, l'issue ne passe pas par `onStateChange` : elle arrive par `onSuccess`, `onError`, `onCancel` ou `onExpired`, et `getState()` garde la dernière étape qui la précède. ## L'erreur `WajubError` Chaque rejet et chaque callback d'erreur en reçoit une. | Champ | Type | | -------------- | ------------------------------------------------------------------------------------------------- | | `message` | `string`, rédigé pour une personne | | `type` | `api_error`, `authentication_error`, `invalid_request_error`, `payment_error`, `rate_limit_error` | | `code` | `string`, le nom interprété par la machine | | `decline_code` | `string` ou `null`, la raison du refus, quand le paiement a été refusé | | `retryable` | `boolean` | | `param` | `string` ou `null`, le champ en cause | ### Codes déclenchés par le SDK Elles signalent des erreurs d'intégration. | Code | Cause | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `secret_key_in_browser` | Une clé secrète passée à `Wajub()` | | `invalid_publishable_key` | Une clé qui n'est pas publique | | `invalid_init` | `Wajub()` appelé sans clé publique ni jeton de session | | `missing_publishable_key` | `createPayment()` appelé sans clé | | `missing_session_token` | `createPayment()` a reçu une réponse sans jeton de session | | `missing_session` | Aucun `sessionId` sur le client | | `missing_container` | `initCheckout` en mode `inline` sans emplacement de montage | | `missing_component` | `confirmPayment` sans composant pouvant être soumis | | `wallet_not_supported` | `confirmPayment` sur un composant `wallet` | | `address_not_payment` | `confirmPayment` sur un composant `address` | | `confirmation_timeout` | Aucun résultat avant la fin de `timeout`. Le paiement continue et peut encore réussir | | `ready_timeout` | Un champ de paiement n'a pas envoyé `ready` avant la fin de `readyTimeout`. Arrive à `onLoadError` et à `loaderror`, et peut être retenté | | `component_unmounted` | Le composant a été démonté, détruit ou retiré de la page pendant que `confirmPayment` l'attendait | | `components_unavailable` | Le runtime des composants ne s'est pas chargé | | `load_error` | Échec du chargement du checkout | ### Codes envoyés par un checkout qui ne peut pas démarrer `onLoadError` sur le checkout hébergé, et `onLoadError` ou l'événement `loaderror` sur un champ de paiement, reçoivent l'un de ces codes. Rien n'a été payé. | Code | Cause | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `session_not_found` | Le jeton est inconnu, ou la session n'a pas pu être lue | | `session_terminal_expired` | Le paiement est terminé et son jeton n'est plus valide. Sur un champ de paiement, la session a expiré sans être payée, et le champ affiche son message | | `session_terminal_cancelled` | Champs de paiement uniquement, la session était déjà annulée. Le champ affiche son message | | `session_terminal_failed` | Champs de paiement uniquement, la session s'était déjà terminée sur un paiement échoué. Le champ affiche son message | | `component_origin_missing` | Champs de paiement uniquement, un champ qui n'a pas été monté avec Wajub.js ou un package de framework. Montez-le avec l'un d'eux | | `invalid_component` | Champs de paiement uniquement, un type de composant qui n'existe pas | | `method_unavailable` | Champs de paiement uniquement, la session ne propose aucun moyen que ce composant accepte | Avec `readyTimeout`, `onLoadError` et `loaderror` d'un champ de paiement peuvent aussi recevoir `ready_timeout`, que le SDK lève lui-même quand le champ n'est pas prêt à temps. Pour l'un des trois codes `session_terminal_`, créez un nouveau paiement et montez le champ sur son jeton. Un champ dont la session est déjà payée affiche son message et envoie `ready`, pas une erreur. ### Codes de fin d'un paiement `onError`, l'événement `error` et un rejet de `confirmPayment()` portent le code de refus quand il y en a un, `insufficient_funds` par exemple. Sinon, ils portent l'un de ces codes. | Code | Cause | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `payment_declined` | Le paiement a été refusé sans motif plus précis | | `blocked` | Refusé par Shield ou par une restriction sur votre compte | | `validation_error` | Un champ rempli par le payeur a été refusé, comme un numéro de téléphone invalide | | `rate_limited` | Trop de tentatives de paiement sur cette session. Attendez un court instant avant de proposer une nouvelle tentative | | `saved_method_not_allowed` | Un moyen enregistré a été utilisé sur un paiement qui n'en liste aucun, voir [`SessionPreview`](#sessionpreview). Rien n'a été débité, et le payeur peut toujours payer avec un moyen qu'il saisit | | `server_error` | Un échec temporaire. `retryable` indique si une nouvelle tentative vaut la peine | | `submission_failed` | Champs de paiement uniquement. Un envoi que vous avez demandé avec `submit()` ou `confirmPayment()` a été refusé avant tout débit : un formulaire qui n'est pas prêt, comme un numéro Mobile Money invalide, une carte laissée incomplète, des champs encore en chargement, un virement sans IBAN ni numéro de compte ou un paiement en crypto sans actif, un numéro de carte refusé, ou une fenêtre de paiement fermée ou qui n'a pas pu s'ouvrir. `message` indique pourquoi, dans la langue du payeur | ## Packages des frameworks `@wajub/react`, `@wajub/vue` et `@wajub/svelte` exportent ces éléments, chacun selon les conventions de son framework. | Export | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `WajubProvider` | Charge le runtime une fois pour une sous-arborescence | | `CheckoutEmbed` | Le checkout hébergé, affiché en ligne | | `CardComponent`, `MobileMoneyComponent`, `WalletComponent`, `PaymentComponent`, `AddressComponent`, `BankTransferComponent`, `CryptoComponent` | Un groupe de champs chacun | | `ComponentEmbed` | La même chose, avec `type` comme prop | | `useWajub`, `useWajubOptional`, `useLoadWajub` | Donnent accès au runtime | | `useConfirmPayment` | Soumet un composant de champs | | `WajubContext` en React, `WAJUB_INJECTION_KEY` en Vue, `getWajubContext` et `setWajubContext` en Svelte, et `useWajubContext` dans les trois | Le contexte brut, pour votre propre hook, composable ou helper | `@wajub/angular` exporte ces éléments. | Export | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `provideWajub(options?)` | Fournit Wajub à l'application ou à une route, à la place de `WajubProvider`. Avec `defer: true`, rien ne se charge avant votre appel à `WajubService.load()` | | `WajubService` | Charge le runtime une fois : les signaux `runtime`, `loading` et `error`, `runtime$`, `load()` et `getRuntime()`, à la place de `useWajub`, `useWajubOptional` et `useLoadWajub` | | `WAJUB_OPTIONS` | Le jeton d'injection que définit `provideWajub()` | | `WajubCheckoutEmbedComponent` | ``, le checkout hébergé, affiché en ligne | | `WajubCardComponent`, `WajubMobileMoneyComponent`, `WajubWalletComponent`, `WajubPaymentComponent`, `WajubAddressComponent`, `WajubBankTransferComponent`, `WajubCryptoComponent` | ``, ``, ``, ``, ``, ``, `` : un groupe de champs chacun | | `WajubComponentEmbedComponent` | ``, la même chose avec un input `type` | | `injectConfirmPayment(sessionId?)` | Soumet un composant de champs, à la place de `useConfirmPayment`. `isConfirming` est un signal | | Prop du composant | S'applique à | Valeur par défaut | | ------------------------------------------------------------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `className` dans React, `class` dans Vue et Svelte, et sur l'élément hôte en Angular | Les deux | aucune | | `style`, dans React et Vue, et sur l'élément hôte en Angular | Les deux | aucune | | `minHeight` | `CheckoutEmbed` | `480` | | `minHeight` | Composants de champs | Non définie. Avec `loader: 'none'`, passez `0` pour épouser les champs. [Dans votre propre bloc de moyen de paiement](https://docs.wajub.com/fr/libraries/components/payment-fields#inside-your-own-payment-method-box) | | `loader` | Composants de champs | `skeleton`, alors que `@wajub/js` lui-même vaut `none` par défaut | | `onInstance`, l'output `(instance)` en Angular | Composants de champs | aucune, appelée avec `null` au démontage | En Angular, les props sont des inputs et des outputs du même nom : chaque option est un input, chaque callback un output nommé sans `on`, par exemple `(loadError)` pour `onLoadError`, et `onBeforeSubmit` est l'input `beforeSubmit`, car un output ne peut pas répondre. Chaque option de `ComponentConfig` est une prop des composants de champs, callbacks compris, et un nouveau gestionnaire prend le relais sans rechargement. Un changement d'`appearance`, de `locale`, de `layout` ou de `frameTitle` s'applique au champ monté sans rechargement. Un nouveau `sessionId`, `type`, `variant`, `fields`, `loader`, `readyTimeout`, `collectAddress`, `addressMode` ou `collectName` monte un nouveau champ dans le même conteneur. `CheckoutEmbed` applique `appearance`, `locale` et `layout` de la même façon, et se recharge pour un nouveau `sessionId`. Chaque package de framework réexporte aussi tous les types de `@wajub/js` : `import type { PaymentSuccess } from '@wajub/react'` fonctionne comme depuis `@wajub/js`. `useWajubOptional()` renvoie le runtime ou `null` dans React. Il renvoie une ref dans Vue et un store dans Svelte, qui valent `null` tant que le runtime n'est pas chargé. En Angular, le signal `runtime` de `WajubService` vaut `null` jusque-là. Chaque package possède sa propre page : [React](https://docs.wajub.com/fr/libraries/components/react), [Vue](https://docs.wajub.com/fr/libraries/components/vue), [Svelte](https://docs.wajub.com/fr/libraries/components/svelte), [Angular](https://docs.wajub.com/fr/libraries/components/angular). - [TypeScript](https://docs.wajub.com/fr/libraries/components/typescript): Tous les noms de types et leur méthode d'import. - [Apparence](https://docs.wajub.com/fr/libraries/components/appearance): L'objet de style dans son intégralité. - [Dépannage](https://docs.wajub.com/fr/libraries/components/troubleshooting): La signification concrète de chaque code d'erreur. - [Wajub.js](https://docs.wajub.com/fr/libraries/components/js): Installer le package principal, l'autoriser dans votre CSP et l'appeler. --- # Apparence URL: https://docs.wajub.com/fr/libraries/components/appearance > Préréglages, couleurs, jetons de design, règles de champs, langue et mise en page. Un seul objet `appearance` stylise tout : le checkout hébergé, la superposition et chaque composant de champ de paiement. Il comprend trois couches appliquées dans cet ordre. 1. Un préréglage `theme`, si vous en indiquez un. 2. Les clés de premier niveau, comme `primaryColor`. 3. `variables` et `rules`, pour un contrôle par jeton et par sélecteur. Chaque couche remplace la précédente. Un préréglage constitue donc un point de départ, pas une contrainte. `inherit` peut placer le style de votre propre page sous les trois : voir [Reprendre le style de votre page](#taking-your-pages-look). ```typescript title="Les trois couches à la fois" await mount('#checkout', { sessionId, appearance: { theme: 'flat', primaryColor: '#6366f1', colorScheme: 'auto', labels: 'floating', variables: { colorText: '#0f172a', fontSizeBase: '16px' }, rules: { '.Input': { borderRadius: '8px' } }, }, }); ``` > [!WARNING] > **Ce que le SDK ne reconnaît pas reste sans effet** > > Une clé inconnue, un sélecteur absent de la courte liste ci-dessous ou une propriété hors de la > liste autorisée est ignoré. Aucune erreur n'est levée ni affichée dans la console. Une faute de > frappe reste simplement sans effet. ## Préréglages `theme` place un ensemble de clés de premier niveau sous les vôtres. Voici leurs valeurs exactes. | Préréglage | Valeurs définies | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `stripe` | `primaryColor: #0570de`, `borderRadius: 4px`, la stack de polices système, `shadow: low` | | `night` | `colorScheme: dark`, `primaryColor: #7c3aed`, `backgroundColor: #0f172a`, `buttonTextColor: #f8fafc`, `inputBackgroundColor: #1e293b`, `inputBorderColor: #334155`, `textMutedColor: #94a3b8`, `borderRadius: 8px`, `shadow: none` | | `flat` | `shadow: none`, `borderRadius: 0` | | `none` | Rien. Seules vos propres clés s'appliquent | `stripe` correspond à l'apparence par défaut d'un checkout Wajub. L'indiquer ne change donc rien, sauf si vous remplacez également certaines de ses valeurs. `light`, `dark`, `system` et `auto` ne sont pas des préréglages. `theme` réglé sur l'une de ces valeurs, sans `colorScheme`, fixe le schéma de couleurs, `system` valant `auto`. ## Clés de premier niveau Cette couche fournit les raccourcis. Chaque valeur est une simple chaîne CSS. | Clé | Type | Élément stylisé | | ---------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `primaryColor` | Couleur CSS | Accent, boutons principaux et liens | | `secondaryColor` | Couleur CSS | Accents secondaires | | `backgroundColor` | Couleur CSS | Surface derrière le formulaire | | `buttonTextColor` | Couleur CSS | Texte des boutons principaux | | `inputBackgroundColor` | Couleur CSS | Arrière-plan des champs seuls. La page autour garde le sien | | `inputBorderColor` | Couleur CSS | Bordure des champs seuls. Les autres bordures de la page gardent la leur | | `textMutedColor` | Couleur CSS | Texte d'aide et secondaire | | `successColor` | Couleur CSS | États de réussite et badges | | `errorColor` | Couleur CSS | Erreurs et messages de validation | | `fontFamily` | Stack de polices CSS | Tout le checkout | | `borderRadius` | Longueur CSS | Rayon par défaut des angles | | `shadow` | `low` ou `none` | Élévation | | `colorScheme` | `light`, `dark`, `auto` | `light` ou `dark` l'emporte sur l'appareil du payeur et sur le choix qu'il a enregistré sur une page hébergée. `auto` suit l'appareil. Une fois la clé définie, le payeur ne voit plus de bouton clair et sombre | | `labels` | `above` ou `floating` | Position des libellés de champs | | `disableAnimations` | `boolean` | Supprime les transitions et les mouvements | ## Variables Cette couche concerne les jetons. Chaque clé définit un jeton de design. Elle atteint ainsi chaque composant qui utilise ce jeton, pas une seule surface. | Clé | Ce qu'elle définit | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `colorPrimary` | La couleur d'accent | | `colorBackground` | La surface derrière le formulaire | | `colorText` | Le texte principal, dans les champs aussi | | `colorTextSecondary` | Le texte secondaire, libellés des champs compris | | `colorTextPlaceholder` | Le texte indicatif des champs | | `colorDanger` | Le texte d'erreur | | `colorSuccess` | Le texte de succès | | `fontFamily` | La pile de polices. Une police Google Fonts comme Poppins ou DM Sans est chargée pour vous | | `fontSizeBase` | La taille du texte saisi dans les champs, 16px au moins sur téléphone ou tablette. Les libellés et les aides sont un cran plus petits | | `fontWeightNormal` | La graisse du texte normal | | `fontWeightMedium` | La graisse moyenne | | `fontWeightBold` | La graisse du texte en gras | | `spacingUnit` | L'unité d'espacement de base | | `borderRadius` | L'arrondi des angles | | `spacingGridRow` | L'écart entre les lignes de champs | | `spacingGridColumn` | L'écart entre les colonnes de champs | Seules ces seize clés sont acceptées. Toute autre clé reste sans effet. ```typescript title="Typographie centralisée" appearance: { variables: { fontFamily: 'Inter, system-ui, sans-serif', fontSizeBase: '15px', fontWeightMedium: '600', spacingUnit: '4px', }, } ``` Si une clé de premier niveau et le jeton correspondant sont tous deux définis, la première l'emporte. Choisissez une méthode et conservez-la. ## Règles Cette couche de sélecteurs est la plus limitée. Elle sert à modifier les champs du formulaire, pas à refaire le style du checkout. **Sélecteurs.** Uniquement `.Input` et `.Label`, avec au maximum un seul parmi `:hover`, `:focus`, `:focus-within`, `:disabled`, `::placeholder`, `::selection`. `.Input` désigne la boîte d'un champ, sa bordure, son arrière-plan et ses angles, qui prend le focus avec son champ de saisie et se désactive avec lui. `.Label` désigne le libellé d'un champ. La `color` et la police d'une règle `.Input` s'appliquent aussi au texte saisi dans le champ. ```typescript title="Tous les éléments que vous pouvez cibler" appearance: { rules: { '.Input': { borderRadius: '8px', borderColor: '#cbd5e1', padding: '12px' }, '.Input:focus': { borderColor: '#6366f1', outline: '2px solid #c7d2fe' }, '.Input::placeholder': { color: '#94a3b8' }, '.Label': { fontWeight: '500', fontSize: '14px', letterSpacing: '0.01em' }, }, } ``` **Propriétés.** Trente et une propriétés, en camelCase. | Groupe | Valeurs autorisées | | ----------- | ----------------------------------------------------------------------------------------------------------------- | | Couleur | `color`, `backgroundColor`, `opacity` | | Bordure | `border`, `borderColor`, `borderWidth`, `borderStyle`, `borderRadius` | | Boîte | `padding` et ses quatre côtés, `margin` et ses quatre côtés | | Typographie | `fontFamily`, `fontSize`, `fontWeight`, `fontStyle`, `lineHeight`, `letterSpacing`, `textAlign`, `textDecoration` | | Effet | `boxShadow`, `outline`, `outlineColor`, `outlineWidth`, `outlineOffset` | **Valeurs.** Uniquement des chaînes non vides de 256 caractères au plus. Une valeur qui chargerait une ressource externe ou sortirait de sa déclaration CSS est refusée : les images d'arrière-plan et les importations de polices ne sont donc pas possibles. Les mêmes limites s'appliquent aux clés de premier niveau et à `variables`. > [!WARNING] > **Une règle non conforme ne génère aucune erreur** > > `.Tab`, `.AccordionHeader`, `display`, `position` et une image d'arrière-plan passent tous dans > `appearance` sans avertissement ni effet. Si une règle ne fait rien, comparez-la aux trois listes > ci-dessus avant toute autre vérification. ## Reprendre le style de votre page `appearance.inherit` donne à un champ de paiement ou à un checkout intégré le style de votre propre formulaire : sa police, les couleurs de ses textes et de ses champs, ses arrondis, sa couleur d'accent et son fond. ```typescript title="Trouvés près du conteneur, ou désignés" factory.create('card', { appearance: { inherit: true, labels: 'floating' } }).mount('#card-fields'); factory.create('mobileMoney', { appearance: { inherit: { input: '#billing_email', label: 'label[for=billing_email]', button: '#place-order', background: '.checkout-box', }, }, }); ``` `inherit: true` cherche votre formulaire près du conteneur. S'il choisit les mauvais éléments, désignez-les dans un `InheritSource`, par des sélecteurs CSS ou par les éléments eux-mêmes. Ceux que vous ne donnez pas sont toujours cherchés. | Élément | Ce qu'il faut désigner | Ce qu'il donne | | ------------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `input` | Un champ texte de votre formulaire | `variables.fontFamily`, `fontSizeBase`, `colorText`, `colorTextPlaceholder` et `borderRadius`, `inputBackgroundColor`, `inputBorderColor` | | `label` | Le libellé de ce champ | `variables.colorTextSecondary` | | `button` | Le bouton d'envoi de votre formulaire | `variables.colorPrimary` | | `background` | L'élément derrière le checkout | `colorScheme`, `variables.colorBackground` | - **Vos clés l'emportent.** Toute clé que vous donnez, et toute clé que fixe votre préréglage `theme`, l'emporte sur ce qui est repris de la page. - **Le schéma suit votre fond**, clair ou sombre, sauf si vous donnez `colorScheme` ou un préréglage sombre comme `night`. - **Ce qui est inutilisable est laissé de côté**, comme une couleur qui ne se lirait pas sur le fond. `inherit` ne lève jamais d'erreur. - **La lecture a lieu au montage, puis à chaque `update({ appearance })`.** La superposition de `open()` n'a pas de conteneur : elle cherche dans toute la page. Pour voir ce qui serait repris, ou l'ajuster avant de le transmettre vous-même, appelez `wajub.appearanceFrom(container, source?)`. ```typescript title="Lire, ajuster, transmettre" const look = wajub.appearanceFrom('#card-fields'); // {} quand il n'y a rien à lire factory .create('card', { appearance: { ...look, variables: { ...look.variables, fontSizeBase: '16px' } } }) .mount('#card-fields'); ``` `appearanceFrom()` renvoie `{}` quand il n'y a rien à lire et ne lève jamais d'erreur. Le client `Wajub()` l'a aussi, et `@wajub/js` l'exporte en fonction asynchrone, qui renvoie `null` sur le serveur. ## Modifier l'apparence après le montage Ce que vous transmettez au montage est fixé au chargement du checkout. `update()` modifie ce que couvre le tableau ci-dessous, et tout le reste demande un nouveau montage. Les deux types d'instances acceptent `update()`. ```typescript title="Un bouton de mode sombre sur votre page" let checkout; await mount('#checkout', { sessionId, onReady: (instance) => (checkout = instance) }); darkToggle.onchange = (event) => checkout.update({ appearance: { colorScheme: event.target.checked ? 'dark' : 'light' } }); ``` | Appel | Checkout hébergé | Champ de paiement | | ------------------------ | -------------------------------------------- | ------------------ | | `update({ appearance })` | Appliqué en direct | Appliqué en direct | | `update({ locale })` | Appliqué en direct | Appliqué en direct | | `update({ currency })` | Appliqué en direct aux sessions multidevises | Sans objet | | `update({ layout })` | Appliqué en direct | Appliqué en direct | `update({ appearance })` fusionne ce que vous donnez avec ce que le checkout ou le champ a déjà. Les clés données changent, les autres restent. Une clé donnée à `undefined` ou `null` est effacée. `appearance: undefined` ou `null` efface toute l'apparence : le checkout ou le champ reprend l'image de marque de votre Dashboard Wajub, et son prochain `mount()` part sans elle. ```typescript title="Changer une clé, en effacer une, tout effacer" card.update({ appearance: { borderRadius: '16px' } }); // les autres clés restent card.update({ appearance: { primaryColor: undefined } }); // efface cette clé card.update({ appearance: undefined }); // retour à l'image de marque du Dashboard ``` Avec `inherit`, chaque `update({ appearance })` relit la page, et effacer `inherit` efface aussi ce qu'il avait lu. `update({ appearance: {} })` ne change aucune clé. Un nouveau préréglage `theme` remplace le précédent et tout ce qu'il apportait : `update({ appearance: { theme: 'flat' } })` après `night` ne garde aucune des couleurs de `night`. Dans [React](https://docs.wajub.com/fr/libraries/components/react), [Vue](https://docs.wajub.com/fr/libraries/components/vue), [Svelte](https://docs.wajub.com/fr/libraries/components/svelte) et [Angular](https://docs.wajub.com/fr/libraries/components/angular), modifiez les props (les inputs, en Angular) plutôt que d'appeler `update()`. Un composant de champ applique en direct une nouvelle `appearance`, `locale`, `layout` ou `frameTitle`, et le checkout intégré fait de même pour `appearance`, `locale` et `layout`. La prop `appearance` remplace toute l'apparence : une clé que vous en retirez est effacée, et une `appearance` devenue `undefined` ou `{}` l'efface entièrement. ## Locale La `locale` transmise au montage est la langue dans laquelle le checkout ou le champ s'ouvre. Elle l'emporte sur la langue choisie par le payeur lors d'une visite précédente et sur la valeur par défaut de la session. Un code absent de la liste ci-dessous est ignoré. `update({ locale })` la modifie ensuite, et le payeur peut toujours changer de langue dans le checkout hébergé. ```typescript title="Lors du montage et après" await mount('#checkout', { sessionId, locale: 'fr' }); checkout.update({ locale: 'en' }); ``` Valeurs prises en charge : `fr`, `en`, `es`, `pt`, `ar`. L'arabe s'affiche de droite à gauche. Si vous omettez `locale`, le checkout s'ouvre dans la dernière langue choisie par le payeur dans ce navigateur, sinon dans la valeur par défaut de la session. Celle-ci provient de l'image de marque de votre compte ou de la préférence enregistrée du client. ## Mise en page Quatre façons de disposer les moyens de paiement. | Valeur | Affichage pour le payeur | | ----------- | ------------------------------- | | `classic` | Une liste verticale, par défaut | | `compact` | La même liste, plus dense | | `tabs` | Un onglet par catégorie | | `accordion` | Des sections repliables | ```typescript title="Configuration lors du montage" await mount('#checkout', { sessionId, layout: 'tabs' }); ``` Si vous l'omettez, la valeur par défaut de la session s'applique. Elle diffère du design de page choisi dans **Paramètres → Image de marque**, qui définit le design de la page hébergée elle-même. ## Image de marque serveur ou apparence client Ces deux options ne s'excluent pas. L'image de marque définit l'apparence par défaut de tous vos checkouts. `appearance` définit l'apparence de cette intégration précise. | Objectif | Emplacement | | ---------------------------------------------------- | -------------------------------------- | | Votre logo et vos couleurs sur chaque checkout | Image de marque du Dashboard | | Un bouton de mode sombre sur votre site | `appearance.colorScheme` et `update()` | | Une campagne sur une page | `appearance` lors de ce montage | | Une police Google Fonts, comme Poppins ou DM Sans | `appearance.variables.fontFamily` | | Votre propre police web, ou une image d'arrière-plan | Non disponible | L'apparence client se superpose à l'image de marque définie dans le Dashboard. Seules les valeurs que vous indiquez sont remplacées. Ce que vous pouvez définir dans le Dashboard figure dans [Image de marque et thème](https://docs.wajub.com/fr/libraries/components/branding). - [Image de marque et thème](https://docs.wajub.com/fr/libraries/components/branding): Valeurs par défaut du compte et sites autorisés à intégrer le checkout. - [Afficher le checkout](https://docs.wajub.com/fr/libraries/components/hosted-checkout): Où transmettre l'objet appearance. - [Champs de paiement](https://docs.wajub.com/fr/libraries/components/payment-fields): Le même objet dans votre propre mise en page. - [Référence du SDK](https://docs.wajub.com/fr/libraries/components/api-reference): Tous les types utilisés dans ces tableaux. --- # Image de marque et thème URL: https://docs.wajub.com/fr/libraries/components/branding > Valeurs par défaut du compte et interaction avec l'apparence. L'image de marque définit l'apparence de votre checkout avant l'exécution du moindre code. Vous la configurez une fois sur votre compte. Elle s'applique à la page hébergée, à la superposition et à chaque composant de champ de paiement. `appearance` constitue l'autre partie, présentée dans [Apparence](https://docs.wajub.com/fr/libraries/components/appearance). Cette page traite du côté serveur. ## Emplacement de la configuration Dans le Dashboard, sous Paramètres puis Image de marque. Aucune API ne permet de la configurer et vous ne devez rien transmettre au montage. Enregistrez-la une fois, chaque nouvelle session la contiendra. > [!NOTE] > **L'image de marque demande un plan payant** > > **Paramètres → Image de marque** est disponible à partir du plan **Growth**. Sur Pay as you go, le checkout > et les champs de paiement gardent l'apparence par défaut, et `appearance` est le seul moyen de les > styliser. La liste des sites autorisés à intégrer votre checkout ne fait pas partie de la page Image de marque : > elle a sa propre page sur tous les plans, décrite dans > [Sessions et sécurité](https://docs.wajub.com/fr/libraries/components/sessions#where-the-checkout-may-be-embedded). ## Ce que vous pouvez définir **Paramètres → Image de marque** couvre : | Réglage | Ce qu'il modifie | | -------------------- | ---------------------------------------------------------------------------------------------- | | Logo | Le logo dans l'en-tête du checkout | | Logo carré | Le logo dans les mises en page étroites | | Icône | L'icône de l'onglet du checkout dans le navigateur | | Couleurs | L'accent, l'arrière-plan, les boutons, les champs, le texte et les états de succès et d'erreur | | Police | La police de tout le checkout, Inter par défaut | | Arrondi des angles | L'arrondi des champs et des boutons, 8px par défaut | | Design de page | Le design de la page hébergée | | Langue par défaut | La langue dans laquelle le checkout s'ouvre | | Domaine personnalisé | Votre propre domaine pour la page hébergée | > [!NOTE] > **Le design de page n'est pas le layout du SDK** > > Le design de page choisit le design de la page hébergée. L'option `layout` du SDK choisit la > disposition des moyens de paiement : `classic`, `compact`, `tabs` ou `accordion`. Ces options > sont indépendantes. La configuration de l'une n'affecte jamais l'autre. ## La mention Wajub Sans logo, sans couleur principale et sans nom d'entreprise, le checkout affiche la marque Wajub. Ajoutez l'un de ces éléments et le checkout affiche votre marque, avec une petite mention Wajub. Cette mention ne peut pas être retirée. ## Ordre de priorité Trois couches sont résolues dans cet ordre. ```text title="La dernière couche l'emporte" Dashboard branding your account's default, on every session ↓ appearance at mount this one embed ↓ instance.update() this one embed, after it is running ``` Les clés client se fusionnent avec l'image de marque du Dashboard au lieu de la remplacer. `primaryColor` modifie donc l'accent sans toucher au logo, à la police ni au rayon. `locale` et `layout` transmis au montage remplacent aussi les valeurs par défaut de la session, et `update()` les modifie ensuite, comme le décrit [Apparence](https://docs.wajub.com/fr/libraries/components/appearance#changing-it-after-mount). ## Choisir une couche | Objectif | Couche | | ---------------------------------------------------- | --------------------------------------------------- | | La même apparence sur chaque checkout | Image de marque du Dashboard | | Une marque différente par marchand sur Sync | Image de marque du Dashboard propre à chaque compte | | Un bouton de mode sombre sur votre site | `appearance.colorScheme` avec `update()` | | Une campagne sur une page | `appearance` lors de ce montage | | Rayon des champs | `appearance.variables.borderRadius` | | Espacement interne des champs, graisse des libellés | `appearance.rules`, sur `.Input` et `.Label` | | Retirer la mention Wajub | Non disponible | | Une police Google Fonts, comme Poppins ou DM Sans | `appearance.variables.fontFamily` | | Votre propre police web, ou une image d'arrière-plan | Non disponible | - [Apparence](https://docs.wajub.com/fr/libraries/components/appearance): Clés, jetons et règles côté client. - [Afficher le checkout](https://docs.wajub.com/fr/libraries/components/hosted-checkout): Où apparaît l'image de marque. - [Sessions et sécurité](https://docs.wajub.com/fr/libraries/components/sessions): Le jeton de session d'où part chaque checkout. - [Créer un paiement](https://docs.wajub.com/fr/api/payments/create): Tous les champs acceptés par POST /payments. --- # Afficher le checkout URL: https://docs.wajub.com/fr/libraries/components/hosted-checkout > Trois façons d'afficher la page de paiement Wajub et les options de chacune. Le checkout hébergé est la page de paiement complète affichée par Wajub, choix du moyen de paiement, récapitulatif de commande, OTP et 3DS, en ligne, en superposition ou après une redirection, avec la même configuration. Les coupons et l'étape de livraison n'y sont pas disponibles, quel que soit le contenu de la session. > [!NOTE] > **Vous cherchez plutôt la présentation du produit ?** > > Cette page présente l'interface d'intégration. Pour découvrir les fonctionnalités de la page > hébergée destinées au payeur et savoir quand la préférer à votre propre mise en page, consultez > [Paiements, Checkout hébergé](https://docs.wajub.com/fr/payments/hosted-checkout). ## Quelle option choisir ? En ligne avec `mount(el, config)`, dans une fenêtre modale avec `open(config)`, ou sur la page de paiement hébergée avec `checkout(config)`. Les quatre modes, champs de paiement compris, sont comparés côte à côte sur la [vue d'ensemble](https://docs.wajub.com/fr/libraries/components#four-ways-to-take-a-payment). Les trois options nécessitent un `sessionId`, qui correspond à la valeur `authorization_token` de [POST /payments](https://docs.wajub.com/fr/libraries/components/sessions). Aucune ne nécessite de clé. Les modes en ligne et en superposition affichent le checkout dans un cadre de votre page. Déclarez les origines qui l'intègrent dans **Paramètres → Intégration de la page de paiement** avant d'encaisser en live : une fois la liste remplie, seules ces origines peuvent l'afficher. La page existe sur tous les plans. Voir [où le checkout peut être intégré](https://docs.wajub.com/fr/libraries/components/sessions#where-the-checkout-may-be-embedded). ## En ligne `mount` accepte un sélecteur ou un élément et renvoie l'instance que vous pouvez ensuite piloter. ```typescript title="La plus petite version fonctionnelle" import { mount } from '@wajub/js'; const checkout = await mount('#checkout', { sessionId, onSuccess: () => (window.location.href = '/order/complete'), onError: (error) => showRetry(error), }); ``` > [!TIP] > **Vous n'avez pas besoin de réserver la hauteur** > > Le checkout se dimensionne seul. Un élément vide `
` suffit. L'absence de `sessionId` ou un sélecteur qui ne correspond à aucun élément échoue aussitôt avec une simple `Error` : `window.wajub` la lève, et les helpers de `@wajub/js` sont rejetés avec elle. ### Configuration | Option | Type | Valeur par défaut | Fonction | | ------------- | ------------------ | ---------------------------------- | -------------------------------------------------------------------------- | | `sessionId` | `string` | Obligatoire | La valeur `authorization_token` de votre serveur | | `locale` | `string` | Valeur de la session | La langue dans laquelle le checkout s'ouvre : `fr`, `en`, `es`, `pt`, `ar` | | `layout` | `CheckoutLayout` | Valeur de la session | `classic`, `compact`, `tabs`, `accordion` | | `appearance` | `AppearanceConfig` | Votre image de marque du Dashboard | [Apparence](https://docs.wajub.com/fr/libraries/components/appearance) | | `loadingText` | `string` | Vide | Texte dans l'espace réservé | | `showLoading` | `boolean` | `true` | Définissez `false` pour afficher votre propre squelette | ### Callbacks ```typescript title="Callbacks à configurer dès le premier jour" await mount('#checkout', { sessionId, onReady: (instance) => (checkoutRef = instance), onSuccess: (transaction) => markPaidInTheInterface(transaction), onError: (error) => console.error(error.code, error.message), onLoadError: (error) => showSessionExpired(error), onBreakdown: (b) => (total.textContent = `${b.total.toLocaleString()} ${b.currency}`), }); ``` | Callback | Déclenchement | Valeur reçue | | ---------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `onReady` | Session chargée et formulaire visible | `CheckoutInstance` | | `onSuccess` | Paiement réussi | [`PaymentSuccess`](https://docs.wajub.com/fr/libraries/components/api-reference#paymentsuccess) : `id`, `reference`, `amount` en unités normales… | | `onError` | Échec du paiement, ou `submit()` sans bouton sur lequel appuyer (`nothing_to_submit`) | `WajubError` | | `onLoadError` | Le checkout n'a pas pu démarrer : jeton inconnu, jeton qui n'est plus valide, ou refus de chargement de l'iframe | `WajubError` | | `onCancel` | Annulation explicite par le payeur | Rien | | `onExpired` | Expiration de la session pendant le paiement | Rien | | `onBreakdown` | Modification des totaux | `{ subtotal, discount, tax, total, currency }`, en unités normales | | `onStateChange` | Passage du checkout à un autre état | `{ state, method }` | | `onMethodChange` | Choix d'un autre moyen de paiement par le payeur | `{ methodId }` | | `onResize` | Modification de la hauteur de l'iframe, uniquement en ligne | `height` en pixels | | `onClose` | Fermeture de la superposition, bouton **Terminé** de la confirmation en ligne, ou appel à `close()` | Rien | `onLoadError` contient `session_not_found` pour un jeton que Wajub ne connaît pas, `session_terminal_expired` pour un jeton dont le paiement est terminé et qui n'est plus valide, et `load_error` lorsque l'iframe elle-même n'a pas chargé. `onError` n'en reçoit aucun : il concerne un paiement qui a échoué. Juste après le callback, la superposition se ferme ou le checkout en ligne quitte la page. `onClose` n'est pas appelé : le checkout n'a jamais démarré, rien n'a donc été fermé. Affichez votre propre message depuis le callback. > [!NOTE] > **onResize est fourni à titre informatif** > > Utilisez ce callback pour déplacer un autre élément de la page, comme un récapitulatif fixe ou un > pied de page. `onSuccess` se déclenche dans un navigateur. Traitez-le comme un signal de l'interface. Livrez la commande à la réception du [webhook](https://docs.wajub.com/fr/developer-tools/webhooks/quickstart). Il reçoit le résumé du paiement par le checkout : `id` est l'identifiant Wajub du paiement, celui que prend `GET /payments/{id}`, `reference` est la vôtre, et `amount` est en unités normales comme dans l'API. En ligne, la confirmation garde un bouton **Terminé**. Quand le payeur l'utilise, `onClose` se déclenche et le checkout quitte la page : placez-y votre propre étape suivante. ### Piloter l'instance ```typescript title="CheckoutInstance" checkout.getState(); // 'COLLECTING_DETAILS', 'PROCESSING', … checkout.update({ locale: 'en' }); checkout.update({ appearance: { colorScheme: 'dark' } }); checkout.update({ currency: 'USD' }); // multi currency sessions only checkout.selectMethod('pm_momo'); checkout.submit(); // presses the checkout's own pay button checkout.retry(); checkout.cancel(); checkout.unmount(); // off the page, the instance is kept checkout.mount(); // back on the page checkout.destroy(); ``` `locale`, `appearance`, `currency` et `layout` s'appliquent en direct, en ligne comme en superposition. `appearance.inherit` donne au checkout le style de votre propre page : `mount()` le lit autour de son conteneur, `open()` sur toute la page, sous les clés que vous donnez. Voir [Reprendre le style de votre page](https://docs.wajub.com/fr/libraries/components/appearance#taking-your-pages-look). `update({ appearance })` change ensuite les clés données et garde les autres : une clé donnée à `undefined` ou `null` est effacée, et `appearance: undefined` efface tout, pour revenir à l'image de marque de votre Dashboard Wajub. Avec `inherit`, chaque appel relit la page. Un nouveau preset `theme` remplace le précédent. Voir [Modifier l'apparence après le montage](https://docs.wajub.com/fr/libraries/components/appearance#changing-it-after-mount). `submit()` appuie sur le bouton de paiement du moyen en cours. Le checkout valide le formulaire comme il le fait pour le payeur et affiche ses propres messages. Suivez donc le résultat avec `onStateChange`. S'il n'y a aucun bouton sur lequel appuyer (avant le choix d'un moyen, sur une étape d'OTP ou de confirmation, avec Apple Pay et Google Pay, qui ne répondent qu'au geste du payeur, et pendant qu'un paiement est déjà en cours), rien n'est pressé et `onError` reçoit une `WajubError` de code `nothing_to_submit`. `unmount()` retire le checkout de la page et conserve l'instance. `mount()` le remet en place, en ligne comme en superposition. À son retour, `onReady` se déclenche à nouveau, avec la locale, l'apparence et la mise en page transmises au dernier `update()`. En superposition, `unmount()` n'appelle pas `onClose`. Après `destroy()`, ou `close()` en superposition, `mount()` n'a plus d'effet. ## Superposition Même configuration, mêmes callbacks et même instance, avec la fenêtre modale en plus. ```typescript title="Payer sans quitter la page" import { open } from '@wajub/js'; const popup = await open({ sessionId, width: 960, closeOnOverlay: true, onSuccess: (transaction) => fulfillOrder(transaction), onClose: () => console.log('dismissed'), }); popup.isOpen(); ``` | Option | Valeur par défaut | Fonction | | ---------------- | ----------------- | ----------------------------------------------- | | `width` | `920` | Largeur maximale de la fenêtre modale en pixels | | `height` | `680` | Hauteur de la fenêtre modale en pixels | | `closeOnOverlay` | `false` | Ferme lors d'un clic sur l'arrière-plan | | `closeOnEscape` | `true` | Ferme avec la touche Échap | | `closeOnSuccess` | `true` | Ferme peu après l'exécution de `onSuccess` | | `closeOnCancel` | `true` | Ferme peu après l'exécution de `onCancel` | | `closeOnExpired` | `true` | Ferme peu après l'exécution de `onExpired` | La fermeture de la fenêtre modale masque uniquement l'interface. La session reste ouverte jusqu'à sa réussite, son expiration ou son annulation dans le checkout. Le même jeton permet donc encore de la monter. `onResize` ne se déclenche jamais en mode superposition, car la fenêtre modale possède une hauteur fixe. ## Redirection Ce mode demande le moins de code et constitue le seul où `callback` est utile. ```typescript title="Deux façons de quitter la page" // The URL your server already received from POST /payments window.location.href = authorizationUrl; // Or, when the browser only has the token import { checkout } from '@wajub/js'; await checkout({ sessionId }); ``` Le payeur revient sur l'URL de `callback` définie lors de la création du paiement, avec `?status=succeeded|cancelled|failed|expired`, `reference`, l'identifiant Wajub du paiement, et `trxref`, votre propre référence, quelle que soit l'issue. Lisez le paiement avec ce `reference` sur votre serveur : ces paramètres d'URL sont une indication. Le [webhook](https://docs.wajub.com/fr/developer-tools/webhooks/quickstart) fournit la confirmation. Consultez [Sessions et sécurité](https://docs.wajub.com/fr/libraries/components/sessions#the-callback-url) pour le détail. ## Avec un framework Dans `@wajub/react`, `@wajub/vue` et `@wajub/svelte`, le checkout en ligne est le composant `CheckoutEmbed`, et dans `@wajub/angular` c'est ``. Ses options sont des props, des inputs en Angular, à côté de celles du composant : la session, une classe, un style dans React et Vue, sur l'élément hôte en Angular, et la hauteur réservée pendant le chargement du checkout, 480 pixels par défaut. React et Svelte acceptent toutes les options de [EmbeddedConfig](https://docs.wajub.com/fr/libraries/components/api-reference#embeddedconfig) ; Vue et Angular en acceptent une liste fermée, donnée sur [Vue](https://docs.wajub.com/fr/libraries/components/vue#checkoutembed) et [Angular](https://docs.wajub.com/fr/libraries/components/angular#checkout-embed). En Angular, les callbacks sont des outputs. L'intégration suit ses props. Un changement d'`appearance`, `appearance.inherit` compris, de `locale` ou de `layout` s'applique au checkout monté sans rechargement : un objet `appearance` écrit en ligne convient donc. Une clé de premier niveau d'`appearance` retirée depuis le dernier rendu est effacée, et une `appearance` devenue `undefined` ou `{}` revient à votre image de marque. Une nouvelle session charge un nouveau checkout dans le même conteneur. `loadingText` et `showLoading` sont lus au chargement du checkout, et un nouveau handler prend le relais sans rechargement. **Changer de thème après le montage** ```tsx title="react" // Une nouvelle valeur s'applique sans rechargement. ; ``` ```vue title="vue" ``` ```svelte title="svelte" ``` ```typescript title="angular" import { Component, Input } from '@angular/core'; import { WajubCheckoutEmbedComponent } from '@wajub/angular'; @Component({ selector: 'app-checkout', standalone: true, imports: [WajubCheckoutEmbedComponent], template: ` `, }) export class CheckoutComponent { @Input({ required: true }) sessionId!: string; @Input() dark = false; } ``` Le provider, les props exactes et le câblage côté serveur sont sur [React](https://docs.wajub.com/fr/libraries/components/react), [Vue](https://docs.wajub.com/fr/libraries/components/vue), [Svelte](https://docs.wajub.com/fr/libraries/components/svelte) et [Angular](https://docs.wajub.com/fr/libraries/components/angular). ## Style Le checkout utilise déjà l'image de marque de votre compte, configurée une fois dans le Dashboard. Transmettez `appearance` uniquement pour modifier cette intégration précise, par exemple pour un bouton de mode sombre ou la couleur d'une campagne. ```typescript title="Remplacement propre à une intégration" await mount('#checkout', { sessionId, layout: 'tabs', appearance: { theme: 'night', primaryColor: '#6366f1', labels: 'floating' }, }); ``` La liste complète des clés figure dans [Apparence](https://docs.wajub.com/fr/libraries/components/appearance). Les valeurs par défaut du compte sont présentées dans [Image de marque et thème](https://docs.wajub.com/fr/libraries/components/branding). - [Apparence](https://docs.wajub.com/fr/libraries/components/appearance): Toutes les clés de style et celles que le SDK ignore. - [Champs de paiement](https://docs.wajub.com/fr/libraries/components/payment-fields): Lorsque la page hébergée dépasse vos besoins. - [Référence du SDK](https://docs.wajub.com/fr/libraries/components/api-reference): La liste complète des méthodes, types et états. - [Webhooks](https://docs.wajub.com/fr/developer-tools/webhooks/quickstart): Confirmez le paiement sur votre serveur. --- # Wajub Components URL: https://docs.wajub.com/fr/libraries/components > Des packages pour navigateur qui intègrent le checkout Wajub ou permettent de composer vos propres champs de paiement. Wajub Components intègrent l'interface de paiement Wajub à votre site : `@wajub/js` sur n'importe quelle page, et `@wajub/react`, `@wajub/vue`, `@wajub/svelte` et `@wajub/angular` dans ces frameworks. Ils sont distribués uniquement sous forme de modules ES. ## Quatre façons d'encaisser un paiement Ils se distinguent par une question : qui affiche le bouton de paiement ? | Mode | Appel | Qui affiche le bouton de paiement | Résultat | À choisir lorsque | | -------------------- | -------------- | --------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------- | | Redirection | `checkout()` | Wajub | La page hébergée sur une URL Wajub | Vous souhaitez écrire un minimum de code front-end | | Intégration en ligne | `mount()` | Wajub | La page hébergée dans votre propre mise en page | Le checkout constitue la page | | Superposition | `open()` | Wajub | La même page dans une fenêtre modale au-dessus de votre page | Le checkout interrompt une autre action | | Champs de paiement | `components()` | Vous | Des champs individuels que vous placez vous-même, puis `confirmPayment()` | La mise en page elle-même est l'exigence | Les trois premiers modes gèrent tout le checkout, y compris les OTP et 3D Secure. Les coupons et l'étape de livraison n'y sont pas disponibles. Les champs de paiement vous laissent gérer la mise en page et confient à Wajub les parties qui doivent lui appartenir, avec les [limites correspondantes](https://docs.wajub.com/fr/libraries/components/payment-fields#what-you-give-up). > [!TIP] > **Commencez par l'intégration en ligne** > > `mount()` garde le client sur votre page sans limiter les fonctionnalités : le checkout gère toujours > tous les moyens de paiement, toutes les vérifications et tous les cas particuliers. Passez aux champs > de paiement lorsque la mise en page constitue votre exigence principale. Il existe sept types de champs : `card`, `mobileMoney`, `wallet`, `bankTransfer`, `crypto`, `payment` et `address`. Chacun a son propre composant, de `CardComponent` à `CryptoComponent` dans React, Vue et Svelte, de `` à `` en Angular, et `ComponentEmbed`, `` en Angular, monte n'importe lequel d'entre eux selon son `type`. ## Une session est nécessaire avant tout Rien ne s'affiche sans jeton de session. Vous pouvez en obtenir un de deux façons, mais elles n'offrent pas le même niveau de sécurité. | Lieu de création | Avec | Conséquence | | ---------------- | ------------------------------------- | ---------------------------------------------------------------- | | Votre serveur | Une clé secrète, `sk.` | Le montant est défini par du code auquel le client n'a pas accès | | Le navigateur | Une clé publique, `pk.` ou `pk_test.` | Un seul appel, sans backend, et le montant provient de la page | `POST /payments` renvoie `authorization_url`, `authorization_token` et `transaction`. Le jeton est ce que le navigateur utilise comme `sessionId`. > [!CAUTION] > **Une clé secrète dans un navigateur est refusée et signalée** > > Une clé secrète ne doit jamais être utilisée depuis un navigateur : elle est refusée avec une > réponse `403`, et le propriétaire de la clé est prévenu par e-mail. Ce blocage est volontaire. Utilisez une clé publique dans le navigateur, ou créez la session sur votre serveur et > envoyez uniquement le jeton. ## Packages [`@wajub/js`](https://docs.wajub.com/fr/libraries/components/js) fonctionne sur n'importe quelle page, avec ou sans framework. ```bash npm install @wajub/js ``` Un package de framework nécessite `@wajub/js` installé à côté de lui, comme dépendance homologue. React, Vue et Svelte vous donnent un `WajubProvider`, un `CheckoutEmbed` et un composant par type de champ. Angular vous donne `provideWajub()`, un service, et un composant standalone pour le checkout et pour chaque type de champ. ```bash title="react" npm install @wajub/react @wajub/js ``` ```bash title="vue" npm install @wajub/vue @wajub/js ``` ```bash title="svelte" npm install @wajub/svelte @wajub/js ``` ```bash title="angular" npm install @wajub/angular @wajub/js ``` **Installation, configuration et liste des props** - [React](https://docs.wajub.com/fr/libraries/components/react): Provider, hooks et routes Next.js. - [Vue 3](https://docs.wajub.com/fr/libraries/components/vue): Provider, composables et routes Nuxt. - [Svelte](https://docs.wajub.com/fr/libraries/components/svelte): Provider, contexte et endpoints SvelteKit. - [Angular](https://docs.wajub.com/fr/libraries/components/angular): provideWajub, le service et les routes Angular SSR. Sans bundler, chargez directement le script, ou importez la version module. ```html title="Depuis le CDN" ``` ## La plus petite intégration fonctionnelle Créez la session sur votre serveur, transmettez le jeton à la page, puis montez le checkout. ```bash title="Sur votre serveur" curl https://api.wajub.com/payments \ -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \ -H "Content-Type: application/json" \ -d '{ "amount": 25000, "currency": "XAF", "email": "buyer@example.com", "callback": "https://shop.example.com/return" }' ``` Envoyez `authorization_token` au navigateur, et rien d'autre. Le jeton est limité à ce paiement, vous pouvez donc l'utiliser en toute sécurité dans le navigateur. ```typescript title="Dans le navigateur" import { mount } from '@wajub/js'; await mount('#checkout', { sessionId: authorizationToken, onSuccess: () => (window.location.href = '/thanks'), onError: (error) => showRetry(error), }); ``` Pour choisir le moment où Wajub.js se charge, appelez plutôt `loadWajub()` : il renvoie `{ wajub, Wajub, WajubError }`, et vous appelez `rt.wajub.mount(…)` dessus. > [!WARNING] > **Tout renvoie null sur le serveur** > > `loadWajub()` et les helpers renvoient `null` en l'absence de `window`. Le rendu serveur ne génère > donc jamais d'erreur. L'importation de `@wajub/js` charge Wajub.js comme effet de bord : pour > l'éviter, importez `@wajub/js/pure` et appelez `loadWajub()` au moment voulu. ## Où trouver le reste de la documentation | Votre objectif | Documentation à lire | | ----------------------------------------------------------- | ---------------------------------------------------------------------- | | Voir une intégration fonctionner de bout en bout | [Démarrage rapide](https://docs.wajub.com/fr/libraries/components/quickstart) | | Créer et sécuriser la session | [Sessions et sécurité](https://docs.wajub.com/fr/libraries/components/sessions) | | Monter, ouvrir ou rediriger avec tous les callbacks | [Afficher le checkout](https://docs.wajub.com/fr/libraries/components/hosted-checkout) | | Créer votre propre mise en page autour des champs | [Champs de paiement](https://docs.wajub.com/fr/libraries/components/payment-fields) | | Modifier les couleurs, le thème et la locale depuis la page | [Apparence](https://docs.wajub.com/fr/libraries/components/appearance) | | Modifier le logo et la palette pour toutes les sessions | [Image de marque et thème](https://docs.wajub.com/fr/libraries/components/branding) | | Consulter la liste complète des méthodes et des types | [Référence du SDK](https://docs.wajub.com/fr/libraries/components/api-reference) | | Utiliser les bons types | [TypeScript](https://docs.wajub.com/fr/libraries/components/typescript) | | Copier une structure complète | [Cas d'utilisation](https://docs.wajub.com/fr/libraries/components/use-cases) | | Comprendre pourquoi rien ne s'affiche | [Dépannage de Wajub Components](https://docs.wajub.com/fr/libraries/components/troubleshooting) | - [Démarrage rapide](https://docs.wajub.com/fr/libraries/components/quickstart): Une session serveur et un checkout monté de bout en bout. - [Afficher le checkout](https://docs.wajub.com/fr/libraries/components/hosted-checkout): Toutes les options et tous les callbacks de mount, open et checkout. - [Créer un paiement](https://docs.wajub.com/fr/api/payments/create): L'appel qui génère le jeton de session. - [Recevoir un webhook](https://docs.wajub.com/fr/developer-tools/webhooks/quickstart): Le seul endroit où un paiement est réellement confirmé. --- # Wajub.js URL: https://docs.wajub.com/fr/libraries/components/js > Le package principal pour navigateur, comment l'installer, l'autoriser dans votre CSP et l'appeler. `@wajub/js` place le checkout et les champs de paiement Wajub sur n'importe quelle page. Cette page présente son installation, la Content Security Policy qu'il demande et les trois façons de l'appeler. **`@wajub/js`**: version 1.8.1, GA, npm + CDN, Any modern browser (ES2020+) ## Aucun build hors ligne Que vous installiez le package npm ou utilisiez la balise script, Wajub.js se charge depuis `https://js.wajub.com`. Il n'existe aucun build hors ligne ni auto-hébergé : un navigateur qui ne peut pas accéder à `js.wajub.com` ne dispose d'aucun checkout. Prenez cette origine en compte comme vous le faites pour l'API. ## Content Security Policy Une page qui applique une `Content-Security-Policy` stricte doit autoriser ces hôtes. Sans eux, le navigateur bloque le checkout et signale la violation dans la console. | Directive | Hôte | Raison | | ------------- | ----------------------- | ----------------------------------------------------------------- | | `script-src` | `https://js.wajub.com` | Wajub.js, depuis npm ou la balise script | | `frame-src` | `https://pay.wajub.com` | Le checkout hébergé, la superposition et chaque champ de paiement | | `connect-src` | `https://pay.wajub.com` | `fetchSession()`, `signals()` et le préchargement du checkout | | `connect-src` | `https://api.wajub.com` | `createPayment()` et `initCheckout()` avec une clé publique | | `img-src` | `https://pay.wajub.com` | Le logo Wajub dans le pied de la superposition | ```text title="Les directives à ajouter à votre propre politique" script-src https://js.wajub.com; frame-src https://pay.wajub.com; connect-src https://pay.wajub.com https://api.wajub.com; img-src https://pay.wajub.com; ``` Si vous servez le checkout depuis votre propre domaine vérifié, utilisez cet hôte partout où `pay.wajub.com` apparaît. La page du checkout définit elle-même sa politique ; la vôtre ne régit que la page qui l'entoure. Un champ de paiement dont le paiement se poursuit sur la page du prestataire, un paiement en crypto par exemple, y emmène toute votre page, parfois avec un formulaire envoyé en `POST`. Si votre politique définit `form-action`, elle doit autoriser cet envoi. Un champ de paiement avec `loader: 'skeleton'` ajoute un élément `