Transferts et payouts

Envoyez de l'argent, comprenez d'où il vient et les conditions à remplir au préalable.

Toutes les autres sections de cette documentation parlent d'argent qui entre. Celle-ci traite de l'argent qui part vers un fournisseur, un livreur, un vendeur de votre marketplace ou votre propre compte.

Un payout n'est pas le miroir d'un paiement. Un paiement réussit ou ne vous coûte rien. Un payout dépense des fonds que vous détenez déjà. C'est pourquoi il passe plus de contrôles que toute autre opération de l'API.

1Seul available peut sortir
Pending est encaissé mais pas réglé, reserved est déjà engagé. Un payout ne puise dans aucun des deux.
2Douze contrôles d'abord
Chacun répond avec son propre 422. Rien n'est réservé tant qu'ils ne sont pas tous passés, un refus ne laisse donc aucune trace.
3Les frais sont aussi retenus
Envoyer 10 000 XAF en réserve 10 100. Le 1 % est prélevé à la fin, mais il est retenu dès le départ.

Un payout prélève un solde que vous détenez déjà. Douze contrôles sont d'abord exécutés. Ce n'est qu'après leur réussite que le montant et ses frais quittent le solde disponible pour passer dans le solde réservé. Le bénéficiaire reçoit le montant, et les frais restent acquis au circuit.

Fonctionnalités disponibles aujourd'hui

Besoin	Solution
Payer une personne ou une entreprise	Transferts
Conserver une liste des personnes que vous payez souvent	Bénéficiaires
Connaître le montant disponible et celui déjà réglé	Solde et règlements
Payer plusieurs personnes à la fois	Aucun endpoint de lot, parcourez `POST /transfers`

Il n'existe aucun payout groupé ou par CSV dans l'API ou le Dashboard. Aucun plan ni aucune demande au support ne peut l'activer. Payer cinquante personnes nécessite cinquante appels, chacun avec sa propre valeur Idempotency-Key, afin qu'une nouvelle tentative de votre boucle ne paie personne en double.

Origine des fonds

Wajub conserve un solde par devise pour votre compte. Les encaissements l'alimentent, les payouts y puisent, et aucun destinataire ne reçoit de fonds qui n'ont pas d'abord été couverts par le solde.

GEThttps://api.wajub.com/balance

Un appel renvoie le solde de l'environnement associé à votre clé. Il répartit l'argent entre cinq montants qui n'ont pas la même signification.

Réponse · 200 OK

{

"code": 200,

"status": "OK",

"message": "Balance retrieved",

"balance": {

"total": 1325000,

"available": 1250000,

"pending": 75000,

"reserved": 0,

"credit": 0,

"currency": "XAF",

"environment": "live"

}

available est le seul montant utilisable pour un payout. pending correspond aux fonds encaissés mais pas encore réglés en votre faveur. reserved correspond aux fonds déjà engagés dans des payouts en cours. Ajoutez ?currency= pour consulter le même solde converti dans une autre devise.

Le solde est mis en cache pendant trois minutes

L'endpoint renvoie un agrégat mis en cache. Un payout créé il y a une minute peut donc ne pas encore avoir modifié available. Ne l'utilisez pas comme total actualisé dans une boucle. Vérifiez-le une fois avant un lot, puis fiez-vous aux appels de transfert eux-mêmes. Ils échouent en cas de fonds insuffisants au lieu de créer un découvert. Dans la sandbox, la réponse est plus simple : total et available contiennent le même montant, tandis que pending et reserved restent à zéro.

Coût d'un payout

Sur le circuit Wajub, un payout est facturé 1 % fixe par défaut. Votre plan peut définir un taux différent par canal. Les frais sont débités à la fin du transfert, mais ils sont réservés avec le principal dès sa création. Envoyer 10 000 XAF réserve donc 10 100 XAF, et non 10 000 XAF.

Le routage vers votre propre compte prestataire change ce fonctionnement. Un payout qui passe par un prestataire que vous avez apporté ne touche pas le registre Wajub. Il n'entraîne donc aucuns frais Wajub et ne réserve rien. Le prestataire vous facture directement selon ses propres conditions.

Conditions d'exécution d'un payout

Cette partie mérite d'être lue avant votre premier transfert live. La création exécute une série de contrôles. Chacun renvoie une réponse 422 avec son propre message plutôt qu'un échec générique.

Contrôle	Élément vérifié
Plafonds du montant	Le minimum et le maximum configurés pour cette devise
Bénéficiaire	Sa résolution sur votre compte et la présence d'un moyen de paiement
Canal	Un canal de payout. Vos propres bénéficiaires acceptent uniquement Mobile Money
Interrupteur général de la plateforme	La suspension des payouts sur tout Wajub, pour tous les comptes
Restrictions du compte	Une restriction `transfers` active sur votre compte
Vérification de la destination	La vérification du moyen de paiement
Votre propre plafond quotidien	Le nombre et le montant définis dans Transfer security settings
Plafond de la plateforme	Une limite stricte selon le palier KYC, que vous ne pouvez pas augmenter vous-même
Vélocité	Une activité inhabituelle et soudaine pendant l'heure écoulée
Plafond du canal	La limite par transfert de cet opérateur
Disponibilité du prestataire	L'existence d'une route de payout pour ce canal et cette devise
Fonds	Sur une route Wajub, `available` couvre le montant et les frais

L'ordre importe moins que le principe : rien n'est réservé avant la réussite de tous les contrôles. Un transfert qui échoue à l'un d'eux n'a jamais existé. Il n'y a donc rien à nettoyer.

Votre premier payout live n'est pas exécuté immédiatement

Un payout est retenu pour examen au lieu d'être envoyé dans chacun des cas suivants : il serait le premier payout réussi de votre compte dans cette devise, son montant dépasse le seuil d'examen de la plateforme ou un seuil que vous avez vous-même défini, votre compte exige la confirmation manuelle de ses payouts, ou le montant atteint au moins cinq fois votre moyenne récente. Le transfert retenu est créé avec le statut review, ses fonds sont réservés et il attend la décision de Wajub. Planifiez le premier et ne réalisez pas un lancement dans une boucle sans surveillance.

Créer un transfert

POSThttps://api.wajub.com/transfers

Un transfert nécessite un montant, une devise et un destinataire. Le destinataire peut être un bénéficiaire déjà enregistré, transmis par son id, ou ses coordonnées complètes. Dans ce dernier cas, le bénéficiaire est créé pendant l'appel.

curl https://api.wajub.com/transfers   -H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…"   -H "Content-Type: application/json"   -H "Idempotency-Key: payout-892"   -d '{
    "beneficiary": "ben_7Kq2mX9vL4tRb3nP8sZc",
    "amount": 10000,
    "currency": "XAF",
    "description": "Supplier payment #892"
  }'

La réponse est 201 Created et le transfert revient avec le statut processing, alors qu'il est déjà en cours d'acheminement. Les deux environnements se comportent de la même façon. Un transfert dans la sandbox puise dans votre solde sandbox, puis se règle tout seul quelques secondes plus tard. Le résultat dépend du numéro de test du destinataire.

Aucune annulation possible

L'API permet de créer, lister et récupérer des transferts. Elle ne permet pas de les annuler. Une fois créé, un transfert évolue vers succeeded ou failed. Seul un examen peut le suspendre, et vous ne contrôlez pas cet examen. Considérez POST /transfers comme irréversible et effectuez vos contrôles avant l'appel, pas après.

Ressources

Méthode	Endpoint	Usage
`POST` `GET`	`/transfers`	Créer, lister et récupérer un payout
`POST` `GET` `PUT` `DELETE`	`/beneficiaries`	Conserver les personnes que vous payez
`GET`	`/balance`	Connaître le montant disponible
`POST`	`/identity/resolve`	Vérifier qu'un numéro appartient bien à la personne attendue

Toutes ces ressources nécessitent la clé secrète. Une clé publique est refusée, tout comme un navigateur. Les routes de payout sont les plus strictement protégées de l'API. Si vous effectuez un payout pour le compte d'un compte connecté, l'en-tête X-Sync permet de le sélectionner. La page Sync détaille ce fonctionnement.

Pages associées