Glossaire

Les termes utilisés dans cette documentation, définis une seule fois avec leurs pièges.

Le vocabulaire des paiements contient de nombreux termes dont le sens varie légèrement selon les entreprises. Les paiements africains ajoutent encore une couche. Cette page définit les termes tels que Wajub les utilise et signale ceux pour lesquels une habitude acquise sur une autre plateforme peut vous coûter cher.

Si vous consultez cette documentation pour la première fois, commencez par les six entrées signalées comme des pièges. Vous pourrez revenir aux autres plus tard.

Paiements et encaissement

Terme	Signification dans cette documentation
Paiement	Une tentative d'encaissement avec un identifiant et un statut. L'API l'appelle aussi transaction. Les deux termes désignent le même objet. Voir Paiements.
Canal	Le moyen de paiement concret, au format `country.operator`, comme `cm.mtn` ou `sn.wave`. Voir Moyens de paiement et canaux.
URL d'autorisation	Le lien à usage unique vers la page hébergée où le payeur termine le paiement. Il expire avec le paiement.
Jeton de session	`authorization_token`, la même session sous forme de jeton. Il peut être utilisé dans un navigateur, car sa portée se limite à un seul paiement.
Client	Un payeur réutilisable, identifié par son e-mail ou son téléphone. Voir Clients.
Remboursement	Des fonds renvoyés après la réussite d'un paiement. Il possède son propre objet, son propre statut et ses propres webhooks. Voir Remboursements.
Litige	La contestation d'un paiement par le payeur. Voir Litiges.
Payeur des frais	La partie qui paie les frais d'un paiement, `merchant` ou `customer`. Avec `customer`, les frais sont ajoutés au montant demandé au payeur.

Piège : `reference` vous appartient, `id` appartient à Wajub

reference est une chaîne libre associée au paiement pour le reconnaître dans votre système. Elle n'est soumise à aucune règle d'unicité et deux paiements peuvent partager la même valeur. id est l'identifiant Wajub et la seule valeur acceptée par GET /payments/{id}. Rechercher un paiement à partir de votre propre référence renvoie 404.

Mobile Money

Terme	Signification dans cette documentation
Mobile Money	Un compte de monnaie électronique associé à un numéro de téléphone, comme MTN MoMo, Orange Money ou Wave. C'est le principal moyen de transférer de l'argent sur la plupart des marchés couverts par Wajub.
Portefeuille	Le compte Mobile Money d'un payeur, identifié par son numéro au format E.164.
USSD	Le menu `*…#` composé par un payeur pour autoriser un paiement sans connexion de données.
Demande push	La confirmation envoyée par l'opérateur au téléphone du payeur. L'opérateur l'envoie, pas Wajub. Son délai échappe donc au contrôle de Wajub.
Transfert	Des fonds envoyés vers un portefeuille ou un compte. Aussi appelé payout. Voir Transferts.
Bénéficiaire	Le destinataire enregistré d'un transfert, réutilisable sans ressaisir ses informations. Voir Bénéficiaires.

Piège : un paiement Mobile Money attend une personne

Une machine décide du résultat d'une carte en environ deux secondes. Une personne qui tient un téléphone décide du résultat d'un paiement Mobile Money. Le statut pending est donc normal et peut durer plusieurs minutes. Le webhook, et non la réponse de l'API, vous indique le résultat.

Fonds et règlements

Terme	Signification dans cette documentation
Solde	Les fonds détenus pour vous par le partenaire agréé, répartis entre `available` et `pending`. Seul `available` peut financer un transfert. Voir Solde et règlements.
Règlement	L'étape qui transforme un encaissement réussi en solde utilisable. Un paiement peut afficher `succeeded` alors que ses fonds restent `pending`.
Frais	Le coût d'une transaction. Voir Frais et tarification.
Rapprochement	La comparaison, généralement quotidienne, des données enregistrées par Wajub avec celles de votre système.
Partiel	Un paiement dont une partie seulement du montant a été encaissée. Pour le Mobile Money au-dessus de 500 000 XAF ou XOF, la page hébergée encaisse par tranches et le paiement conserve cet état jusqu'à la dernière. Ce n'est pas un signal de livraison.

Plateforme et marketplaces

Terme	Signification dans cette documentation
Sync	Agir au nom d'un autre marchand après son autorisation de votre plateforme. Voir Sync.
Connexion	Un lien autorisé entre votre plateforme et un marchand, avec le préfixe `acc_`. Vous le créez et le marchand l'accepte.
`X-Sync`	L'en-tête qui attribue un appel à une connexion. Le paiement appartient alors au marchand et votre commission vous est créditée.
Paiement fractionné	Deux fonctionnalités distinctes partagent ce terme. Le paiement par tranches permet à un payeur de régler un paiement en plusieurs fois. La tarification par connexion représente votre part du paiement d'un marchand connecté. Voir Paiements fractionnés.

Piège : aucun paiement n'est partagé entre plusieurs marchands

Aucun plan ne permet de répartir le produit d'un paiement entre plusieurs comptes. Un panier avec plusieurs vendeurs nécessite plusieurs paiements, un par vendeur, chacun avec son propre X-Sync.

Termes techniques

Terme	Signification dans cette documentation
Orchestration	Choisir le prestataire vers lequel une transaction est routée et passer au suivant en cas d'échec. Voir Orchestration des paiements.
Cascade	La nouvelle tentative automatique auprès d'un prestataire de secours après un échec. Voir Cascade et repli.
Palier de priorité	Un entier associé à un prestataire qui domine le routage. Un palier inférieur n'est jamais essayé avant un palier supérieur, quels que soient le coût ou le score.
Shield	Le filtrage de la fraude fondé sur des règles : listes de blocage et score de risque. Disponible uniquement en mode live. Voir Shield.
Webhook	Un appel HTTP signé que Wajub envoie à votre serveur lorsqu'un élément change d'état. Voir Webhooks.
Événement	Une action survenue, avec le préfixe `evt_`, livrée par un webhook. Son nom se trouve dans le champ `event`, jamais dans `type`.
Clé d'idempotence	Une chaîne associée à une écriture pour qu'une nouvelle tentative renvoie le résultat initial au lieu de répéter l'opération. Voir Idempotence.
Motif d'échec	Le code stable d'un paiement, transfert ou remboursement échoué. Adaptez le traitement à ce code, jamais au message qui l'accompagne. Voir Motifs d'échec.
`X-Request-Id`	L'identifiant d'un appel d'API, renvoyé dans chaque réponse. Si vous fournissez le vôtre, il est repris dans la réponse et accélère le traitement d'un ticket de support.
Sandbox	L'environnement de test accessible avec une clé `pk_test.` ou `sk_test.`. Il utilise une base de données distincte sans argent réel. Voir Environnements et API keys.
Konsole	L'inspecteur de requêtes : données envoyées, réponse reçue, prestataire utilisé et état de la livraison du webhook. Voir Konsole.
KYC	La vérification d'identité exigée par un régulateur avant que vos clés live puissent encaisser de l'argent réel. Voir Passer en live.

Identifiants

Chaque objet créé par Wajub possède un identifiant opaque : un préfixe, test_ si l'objet a été créé dans la sandbox, puis 20 ou 24 caractères aléatoires.

Le même objet dans chaque environnement

trx_CSUGajfv9xh0XQ5wu2lx        # live
trx_test_CSUGajfv9xh0XQ5wu2lx   # sandbox

La partie aléatoire ne contient aucune structure. Ce n'est pas un horodatage, elle ne permet pas un tri chronologique et ne contient aucune information à analyser. Enregistrez-la sans la construire ni en déduire quoi que ce soit.

Préfixe	Objet
`trx_`	Paiement
`fdg_`	Approvisionnement de votre propre solde
`splt_`	Tranche d'un paiement fractionné
`po_`	Transfert
`rfd_`	Remboursement
`dsp_`	Litige
`cus_`	Client
`pm_`	Moyen de paiement
`ben_`	Bénéficiaire
`acc_`	Connexion Sync
`evt_`	Événement

Le préfixe `test_` accélère immédiatement le diagnostic

Une clé live ne peut pas trouver un identifiant qui contient test_. Une clé de la sandbox ne peut pas trouver un identifiant qui ne le contient pas. Dans les deux cas, la réponse est 404, pas une erreur d'autorisation, car les environnements utilisent des bases de données différentes. Si un identifiant valide renvoie 404, commencez par lire son préfixe.

Termes absents de cette documentation

Nommer ce qui n'existe pas fait gagner autant de temps que définir ce qui existe.

Vous pourriez chercher	Fonctionnement réel
Transferts groupés ou par lots	Aucun. Envoyez un `POST /transfers` par destinataire. Voir Transferts groupés (à venir).
Comptes Standard, Express ou Custom	Sync possède trois modes — `direct`, `lite`, `relay` — qui disent où se trouve l'argent, pas ce qu'une connexion a le droit de faire.
`invoice.paid`	`invoice.created`, `invoice.updated`, `invoice.deleted`. Les résultats des paiements arrivent sous la forme `payment.*`.
Montants en centimes	Toutes les valeurs utilisent les unités principales. `5000` signifie cinq mille francs.
Une réponse `409 Conflict`	Les conflits d'idempotence renvoient `422`, avec le détail dans `errors.idempotency_key`.

Pages associées