Gérer les bénéficiaires
Ce qui est modifiable, récupérer, lister et supprimer un bénéficiaire, et ses relevés.
Éléments modifiables ou non
https://api.wajub.com/beneficiaries/{id}La mise à jour accepte cinq champs. La destination n'en fait pas partie.
| Champ | Modifiable |
|---|---|
name, email, country_code, metadata | Oui |
phone | Oui, uniquement comme coordonnée de contact |
channel, account_number, la destination du payout | Non |
Modifier phone ne change pas la destination des fonds
La destination est fixée dans le moyen de paiement associé lors de la création du bénéficiaire.
Aucun endpoint de l'API ne la modifie ensuite. Mettre à jour phone change le numéro de contact
dans l'enregistrement, mais le payout continue d'être envoyé au numéro d'origine, sans
avertissement ni différence dans la réponse. Pour payer un autre numéro, créez un second
bénéficiaire et utilisez son id.
Récupérer un bénéficiaire
https://api.wajub.com/beneficiaries/{id}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.xxxxxxxxxxxxxxxx…"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
https://api.wajub.com/beneficiariesLes 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, la recherche
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.
| Type | Créé par | Vérifié |
|---|---|---|
standard | Vos propres appels API | À la création, sauf sur un compte Relay |
privileged | Vous, dans le Dashboard, comme compte de versement | Seulement après votre vérification sur la même page |
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. Sur un compte Relay, le portefeuille du vendeur est d'abord comparé au nom enregistré par son opérateur, et Payer les vendeurs couvre ce cas.
Relevés et dettes
Trois autres routes dépendent d'un bénéficiaire.
| Route | Rôle |
|---|---|
GET /beneficiaries/{id}/statement | Tout ce qui lui a été versé sur une période d'un an au plus, réparti entre payé, en cours et échoué |
POST /beneficiaries/{id}/receivables | Enregistrer ce qu'il vous doit après un remboursement. GET sur le même chemin liste ces dettes |
POST /beneficiaries/{id}/receivables/{receivable}/settle | Marquer une dette comme recouvrée hors de Wajub |
Une dette enregistrée envoie beneficiary.receivable_recorded. Si la compensation est activée sur
votre compte, le prochain payout groupé vers ce bénéficiaire en est réduit et envoie
beneficiary.receivable_recovered. Payer les vendeurs détaille les deux cas.
Supprimer un bénéficiaire
https://api.wajub.com/beneficiaries/{id}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 : leur beneficiary porte deleted: true, et GET /beneficiaries/{id}/statement
répond toujours pour lui.
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.