Transferts et payouts

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

Cette section traite de l'argent qui part vers un fournisseur, un livreur, un vendeur de votre marketplace ou votre propre compte. 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.
2Les 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à. Une série de contrôles est d'abord exécutée. 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

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	`POST /transfers/batch`, jusqu'à 500 lignes par appel
Payer la même personne selon un calendrier	Paramètres, Transferts, Automatisation, à partir du plan Growth

Un lot accepte jusqu'à 500 payouts en un seul appel, sur tous les plans. Son en-tête Idempotency-Key est obligatoire, et chaque ligne porte une reference unique dans le lot. Chaque ligne passe les mêmes contrôles qu'un payout seul, bornes de la devise comprises, et désigne son bénéficiaire par son id seulement : un numéro de téléphone ou un e-mail est refusé avec beneficiary_not_found. Chaque ligne réussit ou échoue indépendamment : un vendeur sans destination vérifiée ne bloque pas les autres.

Deux choses refusent un lot entier, avant qu'aucune ligne ne parte. Une ligne mal formée, par exemple un champ manquant, une currency qui ne fait pas trois lettres ou une reference répétée dans le lot, répond 422 pour tout l'appel, avec la ligne fautive nommée dans errors (transfers.3.amount). L'autre est un en-tête Idempotency-Key absent ou vide. Limitez cette clé aux lettres, chiffres et . _ : -.

Un transfert récurrent paie à un bénéficiaire un montant fixe chaque heure, jour, semaine ou mois. Chaque exécution crée un payout ordinaire, soumis à tous les contrôles ci-dessous, et un calendrier mis en pause peut reprendre.

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 des 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 n'est pas en temps réel

Un payout créé il y a une minute peut 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.

Coût d'un payout

Sur le circuit Wajub, un payout est facturé à partir de 1 %, selon le pays et le canal. Votre plan peut réduire ce taux. Un payout vers un autre compte Wajub (wajub) est gratuit, et un virement bancaire (wire) porte des frais fixes au lieu d'un taux, voir Frais et tarification. 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é n'est pas financé par votre solde 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 et son propre error_code plutôt qu'un échec générique. Aiguillez votre code sur ce code ; la liste complète figure dans Erreurs.

Contrôle	Élément vérifié	`error_code`
Plafonds du montant	Le minimum et le maximum configurés pour cette devise	`amount_out_of_range`
Bénéficiaire	Sa résolution sur votre compte, son activation et la présence d'un moyen de paiement	`beneficiary_not_found`, `beneficiary_inactive`, `beneficiary_missing_payment_method`
Canal	Un canal de payout : Mobile Money, un portefeuille Djamo ou un autre compte Wajub par l'API, et un compte bancaire via un compte de versement	`channel_not_supported`
Payouts suspendus sur toute la plateforme	La suspension des payouts sur tout Wajub, pour tous les comptes	`payouts_suspended`
Restrictions du compte	Une restriction `transfers` active sur votre compte	`merchant_restricted`
Solde négatif	Aucun payout ne part tant que `available` est sous zéro, quelle que soit la devise	`negative_balance`
Réserve Sync Lite	Le payout d'un marchand Lite ne peut pas entamer la part retenue pour les remboursements	`reserve_held`
Vérification de la destination	La vérification du moyen de paiement	`beneficiary_not_verified`
Délai de carence de la destination	Une destination ajoutée ou modifiée à l'instant ne peut être payée qu'après son `payout_allowed_after`	`beneficiary_cooling_off`
Votre propre plafond quotidien	Le nombre et le montant définis dans Transfer security settings. Les payouts échoués ou annulés ne comptent pas	`daily_count_limit_exceeded`, `daily_amount_limit_exceeded`
Plafond de la plateforme	Une limite stricte selon le palier KYC, que vous ne pouvez pas augmenter vous-même	`single_payout_limit_exceeded`, `daily_payout_limit_exceeded`, `monthly_payout_limit_exceeded`, `payouts_not_enabled`
Vélocité	Trop de payouts, ou un montant versé trop élevé, en peu de temps	`too_many_payouts`, `hourly_payout_amount_exceeded`
Plafond du canal	La limite par transfert de cet opérateur	`amount_above_channel_limit`
Disponibilité du canal	Les payouts vers ce canal ne sont pas temporairement indisponibles	`channel_unavailable`
Disponibilité du prestataire	L'existence d'une route de payout pour ce canal et cette devise	`no_provider`
Fonds	Sur une route Wajub, `available` couvre le montant et les frais	`insufficient_balance`

L'ordre importe moins que le principe : rien n'est réservé avant la réussite de tous les contrôles, et un transfert qui échoue à l'un d'eux n'a jamais existé. Une chose survit pourtant au refus : un bénéficiaire passé en ligne, sous forme d'objet, est créé avant les contrôles. Il reste sur votre compte et dans GET /beneficiaries, et beneficiary.created est envoyé pour lui. Une nouvelle tentative avec le même canal et le même numéro paie ce même bénéficiaire, sous le nom de sa création, au lieu d'en créer un second.

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

Un payout est retenu pour examen au lieu d'être envoyé lorsqu'il fait partie des premiers payouts live de votre compte, lorsque son montant dépasse un seuil que vous avez vous-même défini, ou lorsque votre compte exige la confirmation manuelle de ses payouts. Wajub peut aussi retenir un payout pour ses propres contrôles. 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.

Les deux seuils qui vous appartiennent se trouvent sous Paramètres, Transferts : la confirmation manuelle, avec un montant facultatif en dessous duquel elle ne s'applique pas, dans l'onglet Général, et le montant d'examen ainsi que les plafonds quotidiens en nombre et en montant dans l'onglet Sécurité. Une retenue qu'ils déclenchent reste levée par Wajub, pas depuis votre propre Dashboard.

Le même onglet Sécurité porte deux interrupteurs qui s'appliquent aux payouts lancés depuis le Dashboard, sur tous les plans. Pour protéger les payouts faits par l'API, utilisez des clés restreintes et une liste d'IP autorisées pour l'API. Require 2FA refuse un payout tant que le membre n'a pas saisi de code de vérification de sécurité et validé son second facteur dans les 30 dernières minutes. IP whitelist refuse tous les payouts tant que l'équipe n'a pas de liste d'IP pour le Dashboard : la liste elle-même se règle dans la sécurité de l'équipe, cet interrupteur vérifie seulement qu'elle existe. Les deux réglages se modifient en mode live, par le propriétaire ou un membre qui a manage_settings.

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.xxxxxxxxxxxxxxxx…" \
  -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. Seuls un examen, que vous ne contrôlez pas, et un moyen de paiement temporairement indisponible peuvent le suspendre. Considérez POST /transfers comme irréversible et effectuez vos contrôles avant l'appel, pas après.

Quand un moyen de paiement est temporairement indisponible

Un opérateur peut être indisponible du côté de Wajub pendant un moment. Si vous avez connecté votre propre prestataire pour ce canal, c'est lui qui verse le payout. Sinon, Wajub fait l'une de deux choses avec un nouveau payout :

Il le garde. Le transfert est créé comme d'habitude, processing, son montant réservé, et metadata.rail_queue.queued_at indique depuis quand il attend. Il part de lui-même dès le retour de l'opérateur (metadata.rail_queue.released_at), et les webhooks habituels suivent. D'ici là, vous pouvez l'annuler depuis le Dashboard, ce qui rend son montant de nouveau disponible ; votre délai d'expiration des transferts s'applique toujours.
Il le refuse avec 422 et error_code: channel_unavailable. Rien n'est réservé : réessayez plus tard, ou utilisez un autre canal.

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`	`/transfers/batch`	Payer jusqu'à 500 personnes en un appel
`POST`	`/beneficiaries/{id}/verify`	Vérifier qu'un portefeuille appartient bien à la personne attendue

Pour vérifier le nom d'un portefeuille, utilisez POST /beneficiaries/{id}/verify : il interroge l'opérateur en live et renvoie ce qu'il détient, à titre d'information. Vérifier le nom d'un portefeuille

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