API directe

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 application recueille le numéro de téléphone, votre serveur débite le paiement sur le canal que vous avez choisi, et vous affichez vous-même l'attente et le résultat. Wajub envoie la demande de confirmation sur le téléphone du payeur et vous communique le résultat.

Il faut deux appels. POST /payments enregistre le paiement, exactement comme dans les autres modes, et POST /payments/{id} le débite. Cette page traite du second.

Cet appel a sa place sur votre serveur

Envoyez-le avec votre clé privée, depuis votre backend. Une requête qui porte un en-tête Origin ou Referer avec une clé sk.… est refusée avec un 403. Si votre écran de paiement vit dans un navigateur, utilisez plutôt les Composants intégrés.

1. Créez le paiement

Créez le paiement comme le montre le guide de démarrage des paiements. Conservez transaction.id dans la réponse. Vous n'utiliserez ni authorization_url ni authorization_token : ils servent à la page hébergée et aux composants.

Le paiement est pending, et personne n'a encore été débité.

2. Débitez-le

POSThttps://api.wajub.com/payments/{id}

channelstringobligatoire

Où débiter : un identifiant de canal renvoyé par GET /channels, comme cm.mtn ou cm.orange. Envoyez mobile ou un agrégat de pays comme cm.mobile pour laisser Wajub trouver l'opérateur à partir du numéro.

data.phonestringfacultatif

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.operatorstringfacultatif

Avec un agrégat de pays comme 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.ibanstringfacultatif

Pour un canal bancaire. data.account_number est accepté à la place.

data.wallet_addressstringfacultatif

Pour un canal crypto.

data.save_payment_methodbooleanfacultatif

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.

curl https://api.wajub.com/payments/trx_test_CSUGajfv9xh0XQ5wu2lx \
  -H "Authorization: sk_test.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: charge-order-4172-1" \
  -d '{
    "channel": "cm.mtn",
    "data": { "phone": "+237670000000" }
  }'

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 :

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 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`, attendez le webhook
`400`	Le paiement ne peut plus être débité : il a déjà réussi, expiré ou été annulé	Créez un nouveau paiement si besoin
`402`	L'opérateur ou l'émetteur de la carte a refusé. Le paiement repasse en `pending`	Laissez le payeur réessayer, voir plus bas
`403`	Refusé par une restriction sur votre compte, ou par Shield. Un blocage Shield porte une référence `BLK-…`	Ne relancez pas la même tentative
`404`	Aucun paiement avec cet id, dans cet environnement	Vérifiez l'id et la clé
`422`	Le canal n'est pas accepté, le numéro ne correspond pas à l'opérateur, ou le montant dépasse le plafond du canal	Corrigez la requête

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é

Le Mobile Money n'attend rien de plus de votre part : action est absent et vous attendez le webhook. Deux autres valeurs existent.

confirm_3ds signifie que l'émetteur de la carte veut authentifier le payeur. Cette étape se passe dans la page de paiement ou les composants, une raison de plus d'y traiter les cartes.
confirm signifie que le payeur doit agir de son côté. Pour la crypto, crypto.deposit donne l'adresse et le montant à envoyer.

Laisser Wajub trouver l'opérateur

Avec channel à mobile, ou à un agrégat de pays comme cm.mobile, Wajub lit l'opérateur à partir du numéro et débite dessus : +23767… part sur cm.mtn. 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 un agrégat de pays, 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.

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é, les Composants intégrés ou un SDK mobile, qui les transmettent aux champs sécurisés du prestataire de paiement.

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.

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 avec un 422 sur data.phone, et le paiement reste pending. Le tableau complet est dans Scénarios de test.

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, ne fonctionne qu'en sandbox pour l'instant.

Pages associées