Solde et règlements

Wajub ne détient pas votre argent. Les encaissements sont réglés par un partenaire de paiement agréé qui conserve les fonds pour votre compte. Le solde représente cette position consultée via l'API.

Un seul montant permet de payer quelqu'un : available. Tout le reste correspond à de l'argent que vous détenez, mais ne pouvez pas encore dépenser. La plupart des questions des marchands sur les payouts concernent en réalité l'écart entre ces deux montants.

Un seul appel

La clé secrète est obligatoire. Comme toutes les autres routes de payout, une clé publique renvoie 406 Private Key Required. Il n'existe aucun autre endpoint de solde : aucun historique, aucune consultation par portefeuille et aucun ajustement.

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

La réponse live contient dix champs. Six décrivent votre argent. Les quatre autres existent pour des raisons sans rapport avec celui-ci.

Voici les six champs à lire. Les quatre premiers répondent à des questions différentes sur les mêmes fonds. Les deux derniers indiquent comment les montants sont exprimés.

Les quatre champs absents de ce tableau le sont volontairement.

Les montants utilisent l'unité principale, comme pour un transfert. 1250000 en XAF signifie un million deux cent cinquante mille francs, et non douze mille cinq cents.

Il ne s'agit pas d'un portefeuille, mais de leur ensemble

Wajub conserve un portefeuille par devise. GET /balance n'en renvoie pas un seul. Il lit tous vos portefeuilles, convertit chacun dans une même devise, puis les additionne.

currency est donc une unité d'affichage, pas un filtre. ?currency=XOF n'affiche pas votre portefeuille XOF, mais tous vos fonds exprimés en XOF. Les fonds sous-jacents ne bougent pas et aucun portefeuille n'est exclu.

curl "https://api.wajub.com/balance?currency=USD"   -H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…"

Seul cURL est présenté, car les SDK n'acceptent ici aucun argument. balance.retrieve() ne possède aucun paramètre dans les différents SDK. Omettez le paramètre d'URL pour obtenir la devise définie sur votre compte. Il s'agit de XAF jusqu'à sa modification, quel que soit votre pays d'activité.

Pourquoi available est inférieur à total

Un encaissement n'arrive pas sous forme de fonds utilisables. Il est crédité dans pending et y reste pendant une durée fixe avant son transfert. Cette rétention protège la plateforme contre un paiement contesté après que vous l'avez déjà retiré.

La durée est calculée pour chaque paiement selon son canal d'origine.

Cette base est ensuite multipliée par le niveau de risque de votre compte. Le résultat est encadré pour éviter toute valeur extrême.

Un nouveau compte reçoit un score intermédiaire. Attendez-vous donc au niveau medium, soit 24 heures pour Mobile Money. Quel que soit le résultat du calcul, la rétention ne descend jamais sous 6 heures et ne dépasse jamais 168 heures, soit sept jours. Votre plan ou un accord avec Wajub peut remplacer directement cette durée de base.

À l'expiration d'une rétention, les fonds ne sont pas déplacés immédiatement. Une tâche traite les rétentions expirées toutes les cinq minutes. Un décalage de quelques minutes est donc normal et ne signifie pas que le solde est bloqué.

Signification de reserved

reserved correspond aux fonds engagés dans des payouts qui ne sont pas terminés. La création d'un transfert retire le montant et une estimation des frais de available, puis les place dans reserved avant même de contacter l'opérateur.

Ces fonds quittent reserved au résultat du transfert. Ce résultat détermine leur destination. Avec transfer.succeeded, ils sont réellement débités et total diminue. Avec transfer.failed, ils reviennent dans available et aucuns frais ne sont prélevés. Un payout retenu pour examen conserve ses fonds réservés pendant toute la rétention. C'est le seul cas où reserved peut rester inchangé pendant des heures.

Le montant consulté peut dater de trois minutes

La réponse est mise en cache pendant trois minutes, pour chaque compte et devise demandée. Un payout créé il y a une minute peut ne pas avoir encore modifié available.

Le solde ne convient donc pas au suivi d'une boucle. Consultez-le une fois avant un lot pour estimer votre position, puis laissez les appels de transfert faire foi. Un payout impossible à financer est refusé à la création avec sa propre erreur 422, sans créer de découvert.

Solde simplifié dans la sandbox

La sandbox répète un seul montant. total et available contiennent la même valeur. pending, reserved et les autres restent à zéro. Il n'existe aucune rétention, réservation ou règlement à reproduire.

Le solde commence aussi à zéro. Il n'existe aucun endpoint de recharge ni aucun bouton dans la Konsole. Seul un paiement sandbox réussi crédite ce solde. C'est pourquoi le Démarrage rapide Transferts commence par encaisser des fonds avant d'en envoyer.

Suivre les changements

Au lieu d'utiliser le polling, abonnez-vous à balance.updated. Cet événement est émis à chaque mouvement. Son payload décrit le mouvement lui-même, et non le nouvel objet solde.

balance_type indique le solde modifié, pending ou available. Vous pouvez ainsi distinguer un nouvel encaissement d'une rétention qui vient d'expirer. direction vaut credit ou debit.

Aucun endpoint de registre

Aucun endpoint de l'API ne renvoie la liste des mouvements d'un solde. Pour rapprocher une période, listez les ressources à l'origine des mouvements avec GET /payments, GET /transfers et GET /refunds, puis ajoutez les frais provenant de vos événements fee.charged. La Konsole exporte les mêmes données pour la comptabilité.