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.xxxxxxxxxxxxxxxx…" \
  -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 le canal de l'opérateur : ke.mpesa, eg.vodafone, cm.mtn, cm.orange. Le Cameroun est la seule exception : quand vous avez un numéro camerounais sans son opérateur, transmettez cm.mobile, et l'opérateur, cm.mtn ou cm.orange, est déterminé à partir du numéro. En live, il vient du plan de numérotation du pays, comme pour un paiement ; en sandbox, des préfixes de test. Aucun autre pays n'a de canal générique : ke.mobile ou tout autre {country}.mobile est refusé comme un canal inconnu.

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. cm.mobile sert lorsque vous n'avez qu'un numéro camerounais.

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, car 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.

Vérifier le nom d'un portefeuille

L'appel ne prend aucun corps. Il demande à l'opérateur sous quel nom le portefeuille est enregistré et le compare au nom que vous avez déclaré. La comparaison ignore l'ordre des mots, les accents et la ponctuation, et tolère de petites différences d'orthographe.

Sur vos propres bénéficiaires, la réponse est une information. Le bénéficiaire reste payable quel que soit le résultat, l'appel répond 200, et registered_name porte le nom que détient l'opérateur quand il correspond : vous pouvez le montrer à la personne qui s'apprête à envoyer l'argent. En cas d'écart, il n'en porte que les initiales, P*** N*** : la vérification confirme un bénéficiaire, elle ne dit pas à qui appartient un numéro.

Les opérateurs qui répondent aujourd'hui sont MTN, Orange Money et Express Union au Cameroun, cm.mtn, cm.orange et cm.eu, ainsi qu'un compte Wajub, wajub. Tout autre canal renvoie lookup_unavailable.

Le bénéficiaire conserve le dernier résultat : verification le porte à chaque lecture, et il est absent tant qu'aucune vérification n'a eu lieu. verified est autre chose. Il indique si Wajub paiera le bénéficiaire en live, et ici un name_mismatch ne le change pas. Une exception : un bénéficiaire resté non vérifié, par exemple un vendeur que l'opérateur n'a pas pu confirmer quand votre compte était sur Relay, devient payable si les noms correspondent, et il est alors payé sous le nom que détient l'opérateur. Une différence de nom ou un opérateur injoignable le laisse impayable.

L'appel a son propre plafond, quel que soit votre plan : 10 vérifications par minute et 200 par jour et par compte en live, 10 par minute en sandbox. Au-delà, la réponse est 429. Il sert à vérifier vos propres bénéficiaires à mesure que vous les ajoutez, pas à interroger des numéros en masse.