> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caurisflux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-devises

> Comment vos soldes, vos limites et vos débits fonctionnent devise par devise

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 :

| Catégorie | Rôle                           |
| --------- | ------------------------------ |
| `collect` | Encaissements reçus            |
| `payout`  | Fonds dédiés aux décaissements |
| `credit`  | Ligne de crédit, si activée    |

[`GET /payments/balance`](/api-reference/balance/get) renvoie l'ensemble, groupé par devise.

<Warning>
  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.
</Warning>

## Mode de solde

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

<CardGroup cols={2}>
  <Card title="separate" icon="table-columns">
    `collect` et `payout` sont cloisonnés. Les payouts débitent `payout`, que vous alimentez
    séparément.
  </Card>

  <Card title="unified" icon="layer-group">
    `collect` finance directement les payouts. La catégorie `payout` reste à zéro **par
    construction** — ce n'est pas une anomalie.
  </Card>
</CardGroup>

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` :

```json theme={null}
{
  "amount": 600,
  "currency": "XOF",
  "destinationCountry": "SN",
  "method": "wave",
  "allowFxFrom": "CDF"
}
```

Sans ce champ, le devis échoue plutôt que de convertir dans votre dos.

<Info>
  Quand la parité et la paire flottante sont toutes deux possibles, la parité l'emporte : elle
  ne vous coûte rien.
</Info>

### 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 :

```json theme={null}
{
  "code": "INSUFFICIENT_BALANCE",
  "balanceCategory": "collect",
  "attempts": [{ "currency": "XOF", "required": 632, "available": 130 }],
  "convertibleFrom": [{ "currency": "CDF", "available": 99180 }]
}
```

`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`](/api-reference/balance/get).

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Lisez payoutSourceCategory">
    Ne déduisez pas `payout` : en mode `unified` c'est `collect` qui porte les fonds.
  </Step>

  <Step title="Passez currency aux méthodes de paiement">
    Dans les pays multi-devises comme la RDC, c'est la devise qui départage les canaux.
  </Step>

  <Step title="Traitez INSUFFICIENT_BALANCE">
    Exploitez `convertibleFrom` pour proposer une conversion, plutôt que d'afficher un échec sec.
  </Step>
</Steps>