Bénéficiaires

Un bénéficiaire est une destination enregistrée : un nom, un numéro Mobile Money et l'opérateur qui le dessert. Vous le créez une fois, puis le payez par son id. Le numéro reste ainsi absent de chaque appel de payout et des logs produits par ces appels.

C'est aussi le seul moyen de payer deux fois la même personne sans ressaisir la destination des fonds. Une ressaisie est souvent la cause d'un envoi vers le mauvais téléphone.

Créer un bénéficiaire

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. Ajouter une destination représente en effet la moitié de ce dont un attaquant a besoin pour déplacer des fonds.

curl https://api.wajub.com/beneficiaries   -H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…"   -H "Content-Type: application/json"   -H "Idempotency-Key: beneficiary-amina"   -d '{
    "channel": "cm.mtn",
    "name": "Amina Traoré",
    "phone": "+237670000000"
  }'

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.

Le canal détermine l'opérateur

Indiquez directement l'opérateur lorsque vous le connaissez, avec cm.mtn ou cm.orange. Sinon, transmettez le canal générique du pays, comme cm.mobile. L'opérateur est alors déterminé à partir du numéro.

Cette résolution peut échouer. Elle renvoie alors une erreur claire au lieu de choisir un opérateur au hasard.

Si vous connaissez déjà l'opérateur, indiquez-le. La forme générique sert lorsque vous ne disposez que d'un numéro.

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 ne quitte jamais Wajub : un solde est débité, l'autre crédité, sans réseau intermédiaire et sans attente.

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 — il n'y a aucun réseau à payer entre deux comptes Wajub. Sur un compte dont Wajub vérifie les bénéficiaires, le nom est comparé à la fiche de conformité du destinataire plutôt qu'aux données d'un opérateur.

Payer un bénéficiaire

Transmettez l'id à l'emplacement où un payout attend un destinataire. Le reste du transfert ne change pas.

Le corps correspond à celui décrit dans Transferts, avec une chaîne à la place de l'objet inline.

Éléments modifiables ou non

La mise à jour accepte cinq champs. La destination n'en fait pas partie.

Récupérer un bénéficiaire

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.

curl https://api.wajub.com/beneficiaries/ben_7Kq2mX9vL4tRb3nP8sZc   -H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…"

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

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.

search ne fonctionne pas de la même manière dans les deux environnements. Dans la sandbox, la recherche porte directement sur le nom, l'e-mail, le téléphone et l'id. En live, elle utilise l'index de recherche, qui couvre aussi le code pays et le type. Une recherche live peut donc renvoyer des résultats absents dans la sandbox.

is_active filtre selon l'indicateur correspondant. Le filtre type mérite une explication.

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.

Supprimer un bénéficiaire

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.

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.

Événements envoyés à votre webhook