Frais et devises

Les commissions dépendent de l'opérateur et, le cas échéant, du canal ou du terminal. Le total payé par le client est toujours calculé par CashChap : en XOF, il est arrondi au multiple de 5 F supérieur. Si votre service est réglé dans une autre devise (l'euro, par exemple), vos clients voient prix, frais et total dans cette devise, et vous la voyez en premier dans le portail, le XOF en second (Devise du service). Les valeurs ci-dessous sont celles de la plateforme, relevées le 12 octobre 2026 ; votre portail et la grille tarifaire publique font foi pour votre compte.

Commissions d'encaissement par opérateur

Les minimums et maximums s'entendent dans la devise de l'opérateur ; une demande hors plafonds reçoit amount_too_small ou amount_too_large, avec la limite dans le message. Les commissions, plafonds et moyens réellement ouverts à votre service sont donnés par GET /v2/payment-methods (fees_preview, min_amount, max_amount). Depuis l'API 2.2.0, les mêmes plafonds sont aussi donnés dans la devise du service (display_currency, display_min_amount arrondi au supérieur, display_max_amount arrondi à l'inférieur : 0,16 EUR et 7 622,45 EUR pour MTN Bénin sur un service en euros), et le message d'erreur rappelle la limite dans cette devise : c'est elle que voit le client.

Qui paie les frais ?

Dans Compte › Préférences, bloc Frais d'opération, vous choisissez, opérateur par opérateur, qui paie la commission. Case cochée, vous prenez les frais à votre charge : la commission est déduite de votre encaissement, le client paie le prix et votre solde reçoit le prix moins la commission. Case décochée (« Frais supportés par le client »), les frais sont payés par le client : le widget, la boutique et les liens de paiement affichent alors le total à payer, et votre solde reçoit le prix entier.

Les frais de change d'un prix fixé dans une autre devise que celle de l'opérateur, et la marge de change d'un prix dans une devise à taux variable, suivent la même règle : ajoutés au total du client quand il paie les frais, retenus sur votre net sinon.

Dans l'API v2, fees.payer vaut merchant ou customer ; amount_charged est le total débité au client, fees.amount la commission de CashChap, exchange.fee les frais de change éventuels (et exchange.fee_payer qui les paie), exchange.margin la marge de change éventuelle (et exchange.margin_payer) et net_amount ce que reçoit votre solde. Un montant qui ne couvrirait pas les frais est refusé (amount_below_fees).

Total arrondi au 5 F supérieur (XOF)

En XOF, la plus petite pièce est de 5 F : le total payé par le client (prix + frais à sa charge) est arrondi au multiple de 5 F supérieur, quel que soit le payeur des frais et même quand la commission est nulle. L'appoint (0 à 4 F) est payé par le client et s'ajoute à la commission de CashChap ; votre crédit ne change pas : il ne supporte jamais que votre propre commission. Exemples avec MTN Mobile Money Bénin (1,7 %) :

Dans les autres devises, le total est arrondi à l'unité supérieure de la devise prélevée (au centime supérieur en EUR ou USD). Ne recalculez pas ce total vous-même : prenez celui de CashChap, dans le devis avant le paiement ou dans la transaction après.

Devis avant le paiement

POST /v2/quotes calcule le total exact qu'un encaissement coûtera au client, avec les frais de votre canal (et de votre terminal), l'arrondi et le change éventuel. Le devis n'engage rien et reste indicatif 10 minutes (expires_at).

curl -X POST https://api.cashchap.com/v2/quotes \
  -H "Authorization: Bearer VOTRE_CLE_PUBLIQUE" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1000, "currency": "XOF", "provider": "mtn-benin" }'

{
  "data": {
    "object": "quote",
    "operation": "collection",
    "channel": "widget",
    "amount": 1000,
    "currency": "XOF",
    "fees": {
      "amount": 20,
      "currency": "XOF",
      "payer": "customer",
      "rule": { "kind": "percentage", "value": 1.7, "level": "platform", "channel": null, "terminal": null }
    },
    "amount_charged": 1020,
    "charged_currency": "XOF",
    "net_amount": 1000,
    "net_currency": "XOF",
    "exchange": null,
    "display": {
      "currency": "XOF", "amount": 1000, "fees": 20, "amount_charged": 1020, "net_amount": 1000, "fees_under_minimum": false,
      "rate": { "value": 1, "per_unit": 1, "at": null, "source": "origin" }
    },
    "summary": "Vous paierez 1 020 XOF, dont 20 XOF de frais.",
    "expires_at": "2026-10-11T09:24:00Z"
  },
  "meta": { "request_id": "req_01JA2Q8X3T9Z0F6V4M2K7C1B5N" }
}

Sur un service réglé en euros, le même appel avec "amount": 25, "currency": "EUR" rend les montants prélevés en XOF, inchangés, et le bloc display dans la devise du service : c'est lui que votre page doit montrer au client.

{
  "data": {
    "object": "quote",
    "amount": 25,
    "currency": "EUR",
    "fees": { "amount": 282, "currency": "XOF", "payer": "customer", "rule": { "kind": "percentage", "value": 1.7, "level": "platform", "channel": null, "terminal": null } },
    "amount_charged": 16845,
    "charged_currency": "XOF",
    "net_amount": 16399,
    "net_currency": "XOF",
    "exchange": { "from": "EUR", "to": "XOF", "amount": 16399, "fee": 164, "fee_currency": "XOF", "fee_payer": "customer" },
    "display": {
      "currency": "EUR", "amount": 25, "fees": 0.68, "amount_charged": 25.68, "net_amount": 25, "fees_under_minimum": false, "exchange_fee": 0.25,
      "rate": { "value": 0.001524490172374, "per_unit": 655.957, "at": "2026-10-09T22:12:28Z", "source": "fixed" }
    },
    "summary": "Vous paierez 25,68 EUR, dont 0,68 EUR de frais (frais de change de 0,25 EUR compris).",
    "expires_at": "2026-10-12T05:53:51Z"
  },
  "meta": { "request_id": "req_01JA2Q8X3T9Z0F6V4M2K7C1B5N" }
}

Les 16 845 XOF prélevés se décomposent en 16 399 XOF de prix, 164 XOF de frais de change (1 %) et 282 XOF de commission (279 XOF, plus 3 F d'arrondi au 5 F supérieur) : amount_charged = prix + fees.amount + exchange.fee quand le client paie les frais. summary est une phrase prête à afficher, rédigée dans la devise du service (« Vous paierez 25,68 EUR, dont 0,68 EUR de frais (frais de change de 0,25 EUR compris). »). operation vaut collection (par défaut) ou payout (retrait, clé secrète seulement). Le montant final reste celui calculé au moment de l'encaissement : si les conditions ont changé entre-temps, c'est le nouveau total qui s'applique et il figure dans la transaction.

Frais par canal et par terminal

CashChap peut appliquer des frais différents selon le canal de la transaction (API, widget, lien de paiement, boutique, TPE) et même selon le terminal. Les règles se cherchent du plus précis au plus général : d'abord celles de votre service, puis de votre compte, puis de la plateforme ; à chaque niveau, une règle propre au terminal passe avant celle du canal, qui passe avant la règle générale. Sans règle particulière, ce sont les frais habituels de l'opérateur.

• La règle appliquée est toujours indiquée dans fees.rule : kind (percentage ou fixed), value, level (service, account ou platform), channel et terminal.
• Un terminal de paiement que CashChap n'a pas encore validé paie le tarif du canal api, pas celui des terminaux.
• Le canal n'est jamais choisi par l'appelant : il est déduit de la clé. Le devis donne donc les frais réellement applicables à la clé utilisée.

Frais de retrait

Les retraits se font en XOF uniquement (payout_currency_not_supported). Le frais d'un virement bancaire, à votre charge, s'ajoute au montant viré ; le barème en vigueur figure dans la page Tarifs du portail.

Devises acceptées

Le franc CFA (XOF) est la devise pivot : tous les soldes sont tenus en XOF. Vous pouvez demander un encaissement dans une autre devise active ; CashChap convertit au taux en vigueur au moment de la demande et le mémorise dans la transaction (exchange). Le montant doit respecter le nombre de décimales de la devise (amount_too_many_decimals) : aucune décimale en XOF ou XAF. Dans l'API v2, les montants sont des nombres JSON (1000, 12.5), jamais des chaînes.

Frais de change : 1 %

L'opérateur prélève toujours dans sa devise (XOF pour MTN et Moov Bénin, XAF au Cameroun, CDF en RD Congo…), même quand le client voit les montants dans la devise du service. Des frais de change de 1 % de l'équivalent XOF du prix (arrondis au franc supérieur) s'appliquent une seule fois dans deux cas :

• Prix dans une autre devise que celle prélevée (depuis le 12 octobre 2026) : prix d'un service, d'un CashChap Link, du SDK, d'un QR de caisse ou d'un appel à l'API fixé par exemple en EUR ou en USD et prélevé en XOF. Les frais de change sont payés comme la commission CashChap du service : si le client paie les frais, ils s'ajoutent à son total (affichés dans la devise du service, jamais en XOF, et le total reste arrondi au 5 F supérieur en XOF) ; si vous prenez les frais à votre charge, ils sont retenus sur votre net.
• Opérateur dans une autre devise que le XOF, prix dans la devise de l'opérateur (par exemple 10 000 NGN prélevés en NGN) : la conversion vers votre solde en XOF comporte ces frais, à votre charge, déduits de votre crédit (règle inchangée).

Un prix en XOF prélevé en XOF n'a jamais de frais de change, même sur un service réglé en euros (le client voit alors simplement le prix converti). Le taux de 1 % est un réglage de la plateforme ; le devis, la transaction et le reçu donnent les montants appliqués.

Par l'API, le devis et la transaction donnent les frais de change dans exchange.fee (devise pivot, exchange.fee_currency) et leur payeur dans exchange.fee_payer (customer : compris dans amount_charged ; merchant : retenus sur net_amount) ; le bloc display donne la part de change payée par le client dans la devise du service (exchange_fee, version 2.3.0), comprise dans fees.

La transaction donne toujours la conversion appliquée dans exchange (from, to, rate, amount), ou null sans conversion. Un taux indisponible ou trop ancien renvoie exchange_rate_unavailable.

Marge de change : devises à taux variable

Le taux des devises à taux variable (USD, NGN, GHS, CAD, CDF) est mis à jour chaque jour à partir d'un fournisseur de cours, et les banques n'appliquent pas toujours ce cours. Depuis le 12 octobre 2026, un prix fixé dans l'une de ces devises et prélevé dans une autre devise (par exemple 10 USD prélevés en XOF par MTN Bénin) porte une marge de change : le cours du jour est dégradé de 10 %, réglé devise par devise par CashChap. L'équivalent XOF du prix au cours du jour est divisé par (1 − marge), soit par 0,9 pour 10 % ; la marge est la différence, arrondie au franc supérieur (environ 11,1 % de l'équivalent XOF pour 10 %).

• Elle est payée comme la commission du service : comprise dans les frais du client quand il paie les frais (le total reste arrondi au 5 F supérieur en XOF), retenue sur votre net sinon.
• Elle s'ajoute à la commission et aux frais de change de 1 % ; les trois montants sont calculés sur le même équivalent XOF du prix et enregistrés séparément.
• Jamais de marge : prix en XOF, en XAF ou en euros (parité fixe) ; prix dans la devise de l'opérateur (10 000 NGN prélevés en NGN) ; retraits et remboursements. Les montants que vous voyez dans le portail dans la devise de votre service sont toujours convertis au cours réel, sans marge.
• Votre client ne voit pas de ligne « marge » : elle est comprise dans les frais affichés dans la devise de votre service. Vous la voyez dans le détail de chaque paiement (« Marge de change (cours − 10 %) »), dans les exports CSV (marge_change_xof, marge_change_taux, marge_change_payee_par) et dans l'API (exchange.margin).

Exemple au cours de 1 USD = 585,48 XOF (1 XOF = 0,001708 USD), commission de 1,7 %, prix de 10,00 USD = 5 855 XOF ; avec la marge de 10 %, il vaut 5 855 ÷ 0,9 = 6 505,56 XOF, soit une marge de 651 XOF :

Avec une marge réglée à 5 % pour l'USD (5 855 ÷ 0,95), la marge serait de 309 XOF : 6 325 XOF prélevés quand le client paie les frais, 5 387 XOF nets quand vous les prenez à votre charge. Un prix au plafond (8 540,00 USD = 5 000 000 XOF) reste accepté : le plafond porte sur le prix, frais, frais de change et marge en plus.

Par l'API, avec votre clé secrète, le devis et la transaction donnent la marge dans exchange.margin (devise pivot, exchange.margin_currency), son taux dans exchange.margin_percent et son payeur dans exchange.margin_payer (customer : comprise dans amount_charged ; merchant : retenue sur net_amount), depuis la version 2.4.0. Ces champs n'apparaissent pas dans les réponses destinées au payeur (lien de paiement public, clé publique) ; le bloc display comprend la marge dans fees.

Devise du service : partout, pour vous et pour vos clients

Quand un compte ou un service est réglé sur une devise (par exemple l'euro), toute la chaîne de paiement s'affiche dans cette devise. Le moteur, lui, ne change pas : l'opérateur prélève dans sa devise (XOF au Bénin) et votre solde est tenu en XOF. Aucun montant enregistré n'est recalculé. La devise se règle dans Compte › Préférences (devise du compte, ou devise de préférence du service, qui l'emporte).

Un exemple complet : une robe à 25 EUR

Le service « Boutique en ligne » est réglé en euros. Son CashChap Link « Robe en wax sur mesure » est à 25,00 EUR, les frais (1,7 % chez MTN Bénin, plus 1 % de frais de change puisque le prix est en euros et prélevé en XOF) sont payés par le client, et 1 EUR = 655,957 XOF (parité fixe).

Le prix est converti une fois en XOF (au F supérieur : 16 399 XOF), le moteur calcule la commission (279 XOF) et les frais de change (164 XOF), puis le total arrondi au 5 F supérieur (16 845 XOF, l'appoint de 3 F va à la commission), et le total est reconverti une seule fois pour le client (25,68 EUR) ; les frais affichés sont la différence total − prix (0,68 EUR, dont 0,25 EUR de frais de change), si bien que prix + frais = total au centime près. Si vous preniez les frais à votre charge, le client paierait 25,00 EUR (16 400 XOF prélevés) et votre net serait de 15 956 XOF (24,32 EUR).

Ce que voit votre client

• Page du produit, montant libre, frais, total, bouton de paiement, écran d'attente, écran final, reçu (écran, image et reçu imprimé de la caisse), facture PDF, e-mail de reçu, page de vérification, QR code de la boutique et QR code de caisse : tout est dans la devise du service. Le client ne voit jamais le XOF sur les pages CashChap.
• Seule la demande de confirmation de l'opérateur (USSD ou SMS), que CashChap ne contrôle pas, annonce le montant prélevé dans la monnaie du compte Mobile Money du client (16 845 XOF dans l'exemple). L'écran d'attente le prévient : « Le montant peut s'afficher dans la monnaie de votre compte Mobile Money. »
• Un prix fixé dans une autre devise que celle du service (lien ancien, SDK, API) est montré converti au taux du moment ; un montant libre se saisit dans la devise du service. Les plafonds de l'opérateur sont rappelés dans cette devise (minimum arrondi au supérieur, maximum à l'inférieur). Des frais réels inférieurs au centime s'affichent « moins de 0,01 EUR ».
• Ce que le client a vu est enregistré avec le paiement (devise, taux, prix, frais, total) : son reçu et sa facture ne changent jamais, même si vous changez ensuite la devise du service.

Ce que vous voyez dans le portail

• La devise du compte est la devise d'affichage par défaut de tous vos services ; un service peut avoir la sienne (Compte › Préférences).
• Chaque opération (paiement, reversement, remboursement, ajustement, dépôt) est affichée dans la devise du service, au taux de sa date, puis le montant enregistré en XOF en second (« 25,00 EUR · 16 399 XOF »). C'est vrai aussi des opérations faites avant le passage du service à l'euro : un paiement de 32 000 XOF s'affiche « 48,78 EUR · 32 000 XOF ».
• Le détail d'un paiement donne le prix, le total payé par le client, les frais payés par le client, la commission CashChap, les frais de change (« payés par le client » ou « retenus sur le net »), le net crédité et le taux de conversion (« 1 EUR = 655,957 XOF (parité fixe) »). Si la devise du service a changé depuis, une ligne « Vu par le client » rappelle ce que le payeur a vu.
• Les totaux, soldes et chiffres clés sont la somme en XOF convertie une seule fois, avec le montant XOF en petit dessous. La mention « au taux du jour » n'apparaît que pour une devise à taux variable : l'euro et le franc CFA d'Afrique centrale sont à parité fixe.
• Le tableau de bord d'un service dans une autre devise que le XOF n'affiche que cette devise : soldes, transactions récentes (« 0,30 EUR »), graphiques, activités récentes et notifications de la cloche, sans le montant XOF en second. Le XOF reste affiché dans le détail des opérations, les listes et les exports. Les ajustements de solde se consultent dans Argent › Ajustements.
• Les filtres « Montant » des listes se saisissent dans la devise du service et portent sur la valeur XOF enregistrée ; le tri par montant aussi.
• Les retraits se saisissent en XOF (l'argent réellement versé), avec l'équivalent dans la devise du service en direct (« 50 000 XOF (≈ 76,22 EUR) ») ; le minimum de 10 000 XOF est aussi rappelé dans cette devise. Voir Fonds et retraits.
• Les nouveaux CashChap Link sont toujours dans la devise du service ; un lien plus ancien à prix fixe dans une autre devise garde son prix et est signalé par une pastille « Prix en XOF, service en EUR » (voir CashChap Link). Ma boutique et les QR codes de caisse encaissent dans la devise du service.
• Les exports CSV gardent leurs 7 colonnes de devise (dont montant_affiche, au taux de l'opération, et taux_origine, le taux de la devise demandée) et ajoutent à la fin taux_affiche, source_taux, frais_xof, net_xof, net_affiche, total_preleve, devise_prelevee, frais_change_xof et frais_change_payes_par (client ou marchand). La colonne mode vaut désormais toujours UNIQUE.
• Les e-mails « Paiement reçu » et « Fonds disponibles », les notifications du portail et les e-mails de remboursement et de retrait donnent le montant dans la devise du service, puis le XOF.

Par l'API, le bloc display (version 2.2.0, exchange_fee depuis 2.3.0) donne les mêmes montants : aucun champ existant ne change.

Consulter un taux par l'API

curl "https://api.cashchap.com/v2/exchange-rates?from=XOF&to=EUR" \
  -H "Authorization: Bearer VOTRE_CLE_PUBLIQUE"

{
  "data": { "object": "exchange_rate", "from": "XOF", "to": "EUR", "rate": 0.0015244902, "as_of": "2026-10-10T00:00:00Z" },
  "meta": { "request_id": "req_01JA2Q8X3T9Z0F6V4M2K7C1B5N" }
}

GET /v2/currencies donne la liste des devises actives (code, nom, symbole, décimales, devise pivot).