Démarrage rapide

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.

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 détaille correctement cet appel. Ici, il sert uniquement à alimenter le solde.

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"
  }'

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.

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.

curl https://api.wajub.com/balance \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…"

La réponse contient cinq montants.

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

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.

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"
    }
  }'

Wajub répond 201 Created et le payout possède déjà le statut processing. Aucune confirmation de votre part n'est attendue.

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.

Statuts et webhooks détaille l'enregistrement, les signatures et le contenu de chaque handler. Pendant vos premiers essais, récupérez plutôt le payout.

curl https://api.wajub.com/transfers/po_test_CSUGajfv9xh0XQ5wu2lx \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…"

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.

{
  "amount": 5000,
  "currency": "XAF",
  "beneficiary": {
    "name": "Aminata Diallo",
    "channel": "cm.mtn",
    "phone": "+237670000000"
  }
}

{
  "code": 201,
  "status": "Created",
  "transfer": {
    "id": "po_test_CSUGajfv9xh0XQ5wu2lx",
    "status": "processing"
  }
}

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.

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

Passer ensuite en live

Remplacez sk_test. par sk.. Quatre éléments changent, mais aucun ne concerne votre code.

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 liste tous les contrôles d'un payout live. Transferts décrit l'objet complet.