Skip to main content
CaurisFlux ne tient pas un solde unique converti dans votre devise de règlement. Vous détenez un portefeuille par devise et par catégorie, et chacun vit sa propre vie. Un encaissement en XAF crédite votre portefeuille XAF. Il n’est ni converti, ni fondu dans un total. C’est ce qui permet de payer en XAF sans passer deux fois par le marché des changes.

​
Portefeuilles et catégories

Chaque devise porte les mêmes catégories : GET /payments/balance renvoie l’ensemble, groupé par devise.
Les totaux ne sont jamais agrégés entre devises. Additionner des XOF et des CDF n’a pas de sens, et un total unique masquerait l’une des deux. Si vous voulez une valeur consolidée, convertissez-la vous-même, en assumant le taux que vous choisissez.

​
Mode de solde

Le champ balanceMode détermine quel portefeuille finance vos payouts.

separate

collect et payout sont cloisonnés. Les payouts débitent payout, que vous alimentez séparément.

unified

collect finance directement les payouts. La catégorie payout reste à zéro par construction — ce n’est pas une anomalie.
Plutôt que de déduire la règle, lisez payoutSourceCategory : il nomme directement la catégorie débitée.

​
Quel portefeuille est débité

Pour un payout, le devis retient :
  1. le portefeuille dans la devise du payout, s’il existe et qu’il couvre ;
  2. sinon, le portefeuille dans votre devise de règlement.
totalDebit.currency vous dit lequel a été retenu. Ne présumez pas qu’il s’agit de votre devise de règlement.

​
Les frais suivent une autre règle

Le barème de frais est toujours libellé en XOF, quelle que soit la devise du payout. Il est ensuite converti dans la devise du portefeuille débité. L’objet fees.billed conserve le montant d’origine et le taux, pour que vous puissiez refaire le calcul.

​
Compléter un portefeuille

Quand aucun portefeuille ne couvre seul le débit, CaurisFlux peut compléter le manque depuis une autre devise. Seul le manque est converti, jamais le portefeuille entier. Deux régimes, selon ce que la conversion vous coûte.

​
Parité fixe — automatique

Les paires à parité 1:1, comme XOF ↔ XAF, sont converties sans que vous ayez à le demander. Sans spread, l’opération est sans perte : exiger un consentement n’apporterait rien.

​
Paire flottante — consentement explicite

Les paires soumises à un taux du jour — XOF ↔ CDF, USD ↔ XOF — coûtent un spread. Elles ne sont jamais converties implicitement. Il faut passer allowFxFrom :
Sans ce champ, le devis échoue plutôt que de convertir dans votre dos.
Quand la parité et la paire flottante sont toutes deux possibles, la parité l’emporte : elle ne vous coûte rien.

​
L’erreur vous dit quoi faire

Un solde insuffisant ne renvoie pas un message opaque. Il nomme les devises que vous détenez et pouvez autoriser :
convertibleFrom vous donne directement la valeur à mettre dans allowFxFrom. Une liste vide signifie qu’aucun de vos portefeuilles ne couvre le manque : il faut approvisionner le compte.

​
Limites par devise

Les plafonds sont définis par devise, jamais convertis. Un plafond journalier de 50 000 000 XOF ne dit rien de votre plafond en CDF ou en GHS. Ne cumulez pas les consommations de deux devises. Les bornes applicables à un payout vous sont renvoyées par le devis lui-même : un montant hors limites échoue en 400 avec le seuil et sa devise. Pour le solde disponible, interrogez GET /payments/balance.

​
Devises sans centimes

Le franc CFA (XOF, XAF), le franc rwandais (RWF) et le shilling ougandais (UGX) n’ont pas de subdivision. Envoyez des montants entiers : 1500, pas 1500.75. Les autres devises couvertes acceptent deux décimales.

​
À vérifier dans votre intégration

1

Ne lisez plus un solde racine

GET /payments/balance ne renvoie plus data.currency ni data.categories. Parcourez data.balances et sélectionnez la devise voulue.
2

Lisez payoutSourceCategory

Ne déduisez pas payout : en mode unified c’est collect qui porte les fonds.
3

Passez currency aux méthodes de paiement

Dans les pays multi-devises comme la RDC, c’est la devise qui départage les canaux.
4

Traitez INSUFFICIENT_BALANCE

Exploitez convertibleFrom pour proposer une conversion, plutôt que d’afficher un échec sec.