Paiements
Initialisez, récupérez, listez et annulez des paiements avec l'API Payments.
L'objet Payment (transaction) représente une tentative d'encaissement. Son cycle de vie va de
pending à succeeded (ou failed). Toutes les routes partagent la base https://api.wajub.com.
Avant de commencer
Créez un paiement depuis votre serveur avec votre clé privée (sk. ou sk_test.), ou depuis un
navigateur avec votre clé publique (pk. ou pk_test.). Les deux se trouvent dans le
dashboard Wajub.
Marketplaces : agir pour le compte d'un sous-compte
Une plateforme peut attribuer un paiement à un sous-compte connecté en envoyant un en-tête
X-Sync avec sa propre clé. Consultez Sous-comptes pour les règles
et les cas d'erreur.
Endpoints
| Méthode | Chemin | Description |
|---|---|---|
POST | /payments | Initialiser un paiement |
POST | /payments/{id} | Débiter un paiement depuis votre serveur |
POST | /payments/{id}/confirm | Confirmer une étape d'un débit (code, PIN, fenêtre du prestataire) |
POST | /payments/{id}/splits | Débiter la tranche suivante (Mobile Money en live) |
POST | /payments/{id}/close | Clôturer un paiement réglé en partie en tranches |
GET | /payments/{id} | Récupérer un paiement |
GET | /payments | Lister les paiements |
DELETE | /payments/{id} | Annuler un paiement |
GET | /payments/{id}/refunds | Lister les remboursements d'un paiement |
PATCH | /payments/{id} | Changer le montant d'un paiement préparé |
POST | /payments/{id}/activate | Créer un paiement préparé une fois la commande passée |
Paiements préparés
Un paiement créé avec deferred: true est seulement préparé. Il existe pour les
champs de paiement montés sur votre
page de commande avant que la commande existe, et il reste à l'écart de tout le reste jusqu'à ce que
vous l'activiez.
| Préparé | Activé | |
|---|---|---|
Dans GET /payments et le dashboard | Non | Oui |
GET /payments/{id} | Se lit pending, puis expired ou cancelled ; répond 404 une heure après son expiration ou son annulation | Le paiement |
payment.created | Non envoyé | Envoyé à l'activation |
| Montant et devise | PATCH /payments/{id} | Fixés |
| Peut être débité | Non | Oui |
DELETE /payments/{id} | Met fin à la session, sans webhook | Annule, envoie payment.cancelled |
L'activation conserve l'id et le jeton de session que vous avez déjà transmis au navigateur. Un
paiement préparé jamais activé expire avec sa session, et rien n'en parvient à vos paiements ni à
votre endpoint de webhook, tant que vous n'avez envoyé aucun client en le préparant : ce client-là
est créé, avec son customer.created.
L'objet Payment
Réponse de création ou réponse de lecture
La réponse de POST /payments (création) contient deux champs de plus, authorization_url et
authorization_token, absents des réponses de lecture suivantes. Ce sont les deux champs les
plus importants de la réponse de création.
Un champ sans valeur est absent de la réponse au lieu d'être envoyé à null.
idstringfacultatiftrx_ suivi de 20 caractères, trx_test_ en sandbox. C'est l'identifiant à utiliser dans chaque appel d'API (GET /payments/{id}, corps de POST /refunds, etc.).authorization_urlstringfacultatifPOST /payments uniquement.** L'URL de la page de paiement hébergée vers laquelle rediriger votre client. Une URL de session opaque : ne l'analysez pas et ne la construisez pas vous-même.authorization_tokenstringfacultatifPOST /payments uniquement.** Jeton de session utilisable dans le navigateur, limité à ce paiement. Passez-le comme sessionId aux Wajub Components pour un checkout intégré.referencestringfacultatifreference envoyée sur POST /payments : votre propre référence de commande, enregistrée et renvoyée telle quelle. Ce n'est pas un identifiant d'API, et Wajub ne vérifie jamais qu'elle est unique.statusenumfacultatifpending, processing, succeeded, failed, cancelled, expired, partial, refunded, partially_refunded.amountnumberfacultatifamount_paidnumberfacultatifamount tant qu'un paiement réglé en tranches est partial, et sur un tel paiement clôturé avant sa dernière tranche (POST /payments/{id}/close).currencystringfacultatifSLL.channelstring?facultatifcm.mtn, cm.orange, sn.wave).payment_methodobject?facultatif{ channel, account }.descriptionstring?facultatifitemsarray?facultatifname, description et quantity. Affichées sur la page de paiement, elles ne portent aucun prix et ne changent jamais amount. Sur un paiement fait sur la page d'une facture, ce sont les lignes de la facture, chacune avec son unit_price et son total, net de sa remise et taxe comprise ; à partir de la version 2026-10-12 de l'API, une remise sur toute la facture termine la liste, sous la forme d'un élément avec kind: discount, name: Discount, un total négatif, et quantity et unit_price à null.taxobject?facultatif{ amount, taxable_amount, rate, name, country, inclusive }. Jamais présent en sandbox.failure_reasonstring?facultatifstatus=failed.failure_messagestring?facultatiffailure_reason, pour vos journaux et votre support. Présent uniquement quand status=failed.receipt_urlstring?facultatifcustomerobject?facultatif{ id, name, email, phone }.shipping_addressobject?facultatif{ address_line1, address_line2, city, state, postal_code, country }.billing_addressobject?facultatifmetadataobject?facultatifinvoicestring?facultatifid de la facture que ce paiement règle, quand il a été fait sur la page d'une facture. Absent sinon.linkstring?facultatifid du [lien de paiement](/api/payment-links) par lequel ce paiement a été fait. Absent sinon.clientobject?facultatif{ name, version, platform, os_version }. name vaut hosted-checkout, wajub-js, wajub-android, wajub-ios, wajub-flutter, wajub-react-native ou le nom que déclare une autre application, et platform l'une des valeurs android, ios, web, macos, windows ou linux. version, platform et os_version peuvent valoir null. Renseigné par la première tentative du payeur, jamais par un débit depuis votre serveur, et donné à titre indicatif. Non renvoyé à une clé publique.callbackstring?facultatifbearerstringfacultatifmerchant, ou customer quand le payeur les paie en plus de amount.expires_atdatetime?facultatifexpires.in à la création. Passé ce délai, le paiement devient expired, sauf si un débit est en cours : le paiement attend alors l'issue de ce débit. Voir [Expiration](/payments/lifecycle#expiry).sandboxbooleanfacultatiftrue pour les transactions du mode test.credited_atdatetime?facultatifcreated_atdatetimefacultatif+00:00).updated_atdatetimefacultatifCycle de vie
Événements
| Événement | Déclencheur |
|---|---|
payment.created | Paiement initialisé, ou paiement préparé activé |
payment.processing | Paiement soumis au prestataire |
payment.succeeded | Paiement validé avec succès |
payment.failed | Paiement échoué (voir failure_reason) |
payment.attempt_failed | Une tentative a été refusée sur-le-champ et le paiement est de nouveau pending |
payment.expired | L'échéance du paiement (expires_at) est passée avant qu'il soit payé |
payment.cancelled | Paiement annulé avec DELETE /payments/{id} ou le bouton Annuler de la page hébergée |
payment.split.processing | Une tranche a été envoyée au payeur |
payment.split.succeeded | Une tranche a été payée, et créditée sur votre solde |
payment.split.failed | Une tranche a été refusée ; l'appel suivant la débite de nouveau |
Consultez le catalogue complet des événements pour les
événements propres aux remboursements. Un remboursement sur un paiement ne réémet pas d'événement
payment.* : il émet des événements refund.*.