
Standards et fiabilité
Montants et devises : contrôler les unités mineures des API
Un montant entier peut représenter des euros, des centimes ou une autre unité selon l’interface. La devise et la convention de l’opération doivent accompagner chaque valeur, de l’offre au remboursement.
La règle se lit dans l’API qui reçoit le montant
SIX maintient les codes monétaires ISO 4217. Ce référentiel permet d’identifier la devise ; il ne suffit pas à connaître le format exigé par chaque API. La documentation Adyen indique des montants en unités mineures pour la plupart de ses API et signale des conventions qui diffèrent du standard pour certaines devises. Conservez donc une règle par prestataire et opération, avec sa source et sa version.
La première question d’une intégration est simple : la valeur est-elle un entier en unité mineure, un décimal en unité principale ou une chaîne de caractères ? Ne déduisez pas la réponse de la taille du nombre. Une mauvaise conversion peut multiplier ou diviser le montant sans provoquer d’erreur technique.
Trois exemples arithmétiques à tester
| Devise | Décimales indiquées | Montant affiché | Entier correspondant |
|---|---|---|---|
| EUR | 2 | 12,34 EUR | 1234 |
| JPY | 0 | 1234 JPY | 1234 |
| KWD | 3 | 12,345 KWD | 12345 |
Ces valeurs servent à tester une conversion d’unité, pas à donner des prix de voyage. Pour une autre interface, relisez la convention. Ne remplacez jamais une devise absente par EUR : placez l’opération en attente de qualification. Un nombre et sa devise forment un objet indivisible.
Conserver les arrondis à l’endroit où ils naissent
Dans votre propre modèle, utilisez des entiers ou des décimaux exacts selon les besoins ; évitez de laisser des approximations binaires déterminer les sommes à encaisser. Définissez qui arrondit et à quelle étape : composant, taxe, remise, total ou conversion. Une somme de lignes déjà arrondies peut différer d’un total calculé avant arrondi. Conservez cet écart et sa règle, au lieu de le masquer dans les frais.
Pour une conversion de devise, gardez montant et devise source, valeur du taux retenu, date, origine du taux, marge éventuelle et total proposé au client. Ne recalculez pas silencieusement un remboursement à partir du taux du jour si la règle contractuelle impose une autre méthode. Le rapprochement doit pouvoir expliquer pourquoi deux écritures ne portent pas le même nombre.
Une recette sur tout le cycle financier
- Lire une offre et son prix total avec taxes et frais.
- Transmettre exactement le montant attendu par l’opération de paiement.
- Rapprocher la valeur affichée, la valeur envoyée et la transaction retournée.
- Tester remise, acompte, solde et deux remboursements partiels.
- Tester une devise sans décimale et une devise à trois décimales.
- Rejeter ou isoler une devise absente, une précision excessive et une convention non reconnue.
Demandez des cas de test propres à votre prestataire : les moyens de paiement peuvent ajouter des contraintes différentes de celles du catalogue. Mesurez les écarts de rapprochement par devise et par opération. Un test uniquement en EUR laisse passer une conversion erronée dans d’autres marchés.
Un dictionnaire partagé avec la finance
Publiez pour l’équipe un dictionnaire de montants : champ, opération, devise, unité, précision autorisée, règle d’arrondi et source. Versionnez-le avec l’intégration et le jeu de recette. Le support doit pouvoir lire le montant facturé sans reconstruire la conversion ; la finance doit pouvoir comparer vente, capture, règlement et remboursement.
Le modèle de dictionnaire des montants sert à préparer cette revue. Un nouveau prestataire ou une nouvelle devise déclenche une vérification de la règle, même lorsque le format JSON paraît identique.
Approfondir le parcours : Précision des nombres : quantités, identifiants et valeurs conservées
Les unités mineures ne résolvent pas seules tous les écarts numériques. Gardez type, précision et moment de conversion pour le champ concerné. Une valeur affichée peut avoir une convention différente de celle utilisée dans le calcul.
Précision des nombres : quantités, identifiants et valeurs conservées · Rapprocher les preuves du parcours
Adyen : les décimales de l’API peuvent différer de la devise ISO
Adyen demande généralement un montant entier en unités mineures. Sa documentation exclut explicitement Terminal API de cette règle générale.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| Exceptions | CLP, CVE, IDR et ISK ont un nombre de décimales Adyen différent de la référence ISO 4217. | Appliquer la table de l’API et conserver aussi le code monétaire. |
| ISK | Pour l’ISK, la référence ISO indique zéro décimale, tandis qu’Adyen en demande deux pour le montant transmis. | Un montant de 10 ISK s’écrit 1000 selon cette convention Adyen ; ce calcul n’est pas un taux de change. |
| Périmètre | Les règles présentées concernent les API soumises à la convention en unités mineures, hors Terminal API. | Relire le contrat de l’opération avant de transposer un encodage utilisé ailleurs. |
La table technique ne confirme ni l’activation d’une devise sur le compte ni les conditions de règlement, les frais ou un taux de change.
Adyen — Currency codes and minor units · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
OCTO Pricing : distinguer prix par unité et prix par réservation
Le nombre de participants ne suffit pas à calculer le prix d’une activité privée. Le mode de tarification se lit avant la multiplication.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| Unité ou réservation | pricingPer vaut UNIT ou BOOKING. En mode BOOKING, le prix s’applique une fois à la réservation plutôt qu’à chaque unité achetée. | Ne pas multiplier un prix de privatisation par le nombre de participants. |
| Prix indicatif | Le suffixe From, comme pricingFrom, indique un prix indicatif et non final. | Conserver cette nuance dans le calendrier et vérifier le prix de la sélection. |
| Vente et achat | retail est le prix de vente au client ; net est le montant de gros facturé par le fournisseur. | Distinguer prix public, coût fournisseur et marge après les autres charges. |
| Précision | Le montant entier se divise par 10 à la puissance currencyPrecision pour obtenir le montant décimal. | Exemple de lecture : 12500 avec une précision de 2 donne 125,00 dans la devise indiquée. |
Capacité optionnelle pricing, à demander dans Octo-Capabilities. Le standard ne prouve pas son activation chez chaque fournisseur.
OCTO — Pricing capability · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Lire les montants Adyen pour 26 devises
Le code ISO identifie la monnaie ; la documentation de l’opération fixe la représentation du montant. Quatre devises de cette sélection ont des décimales Adyen différentes de leur référence ISO : CLP, CVE, IDR et ISK.
Exemple de lecture : 12,34 EUR correspond à une valeur technique de 1234 avec deux décimales. Pour un montant de 10 ISK, la convention Adyen donne 1000, alors que la référence ISO possède zéro décimale.
Chaque case part de 10 unités de sa propre devise ; ces montants n’ont pas la même valeur économique. L’entier affiché suit la convention Adyen, hors Terminal API.
- CLPISO : 0 · Adyen : 2 décimale(s)10 CLP → 1000
- CVEISO : 2 · Adyen : 0 décimale(s)10 CVE → 10
- IDRISO : 2 · Adyen : 0 décimale(s)10 IDR → 10
- ISKISO : 0 · Adyen : 2 décimale(s)10 ISK → 1000
Virgule ou point décimal, sans séparateur de milliers. Le calcul refuse les décimales supplémentaires non nulles et ne pratique aucun arrondi. Il n’effectue ni conversion de devise ni paiement.
EUR : deux décimales ISO et deux décimales Adyen. Exemple de valeur technique : 1234.
Comparer les 26 devises et leurs codes numériques
| Devise | Code numérique ISO | Décimales ISO | Décimales Adyen |
|---|---|---|---|
| EUR — Euro | 978 | 2 | 2 |
| USD — Dollar des États-Unis | 840 | 2 | 2 |
| GBP — Livre sterling | 826 | 2 | 2 |
| CHF — Franc suisse | 756 | 2 | 2 |
| JPY — Yen | 392 | 0 | 0 |
| KRW — Won sud-coréen | 410 | 0 | 0 |
| BHD — Dinar bahreïni | 048 | 3 | 3 |
| KWD — Dinar koweïtien | 414 | 3 | 3 |
| TND — Dinar tunisien | 788 | 3 | 3 |
| CLP — Peso chilien | 152 | 0 | 2 — écart avec ISO |
| CVE — Escudo cap-verdien | 132 | 2 | 0 — écart avec ISO |
| IDR — Roupie indonésienne | 360 | 2 | 0 — écart avec ISO |
| ISK — Couronne islandaise | 352 | 0 | 2 — écart avec ISO |
| HUF — Forint | 348 | 2 | 2 |
| TWD — Nouveau dollar de Taïwan | 901 | 2 | 2 |
| SGD — Dollar de Singapour | 702 | 2 | 2 |
| AUD — Dollar australien | 036 | 2 | 2 |
| CAD — Dollar canadien | 124 | 2 | 2 |
| CNY — Yuan renminbi | 156 | 2 | 2 |
| INR — Roupie indienne | 356 | 2 | 2 |
| AED — Dirham des Émirats arabes unis | 784 | 2 | 2 |
| SAR — Riyal saoudien | 682 | 2 | 2 |
| NOK — Couronne norvégienne | 578 | 2 | 2 |
| SEK — Couronne suédoise | 752 | 2 | 2 |
| NZD — Dollar néo-zélandais | 554 | 2 | 2 |
| THB — Baht thaïlandais | 764 | 2 | 2 |
SIX, agence de maintenance ISO 4217 : liste publiée le 17/09/2026. Adyen, codes monétaires et unités mineures. Sources consultées le .
Ce module traite la convention en unités mineures, hors Terminal API. Il ne vérifie pas les fractions facturables, l’éligibilité du compte, les frais ou la devise de règlement. Les règles Stripe de versement HUF et TWD, notamment, doivent être lues séparément.
Sources et périmètre des faits documentés
La date de consultation figure avec chaque référence. Les méthodes d’essai et recommandations de ce guide sont éditoriales ; les conditions d’accès et d’usage se vérifient dans la documentation actuelle.
- SIX — liste courante ISO 4217 : Codes et unités mineures, sélection de 26 devises ; liste publiée le 17 septembre 2026. (consultée le )
- Adyen : Currency codes and minor units : Convention des montants, précisions EUR, JPY et KWD, et divergences signalées avec ISO 4217. (consultée le )
- Adyen — Currency codes and minor units : La table technique ne confirme ni l’activation d’une devise sur le compte ni les conditions de règlement, les frais ou un taux de change. (consultée le )
- OCTO — Pricing capability : Capacité optionnelle pricing, à demander dans Octo-Capabilities. Le standard ne prouve pas son activation chez chaque fournisseur. (consultée le )
Questions fréquentes
Questions utiles avant de décider
Faut-il toujours multiplier par 100 ?
Non. La précision dépend de la devise et de la convention de l’API. Les exemples EUR, JPY et KWD montrent trois conversions différentes.
Un code ISO 4217 décrit-il le taux de change ?
Non. Il identifie la devise. Le taux, sa date et les frais éventuels doivent être documentés séparément.
Comment traiter une devise inconnue ?
Conservez le montant reçu et bloquez la conversion automatique jusqu’à qualification. Une valeur par défaut pourrait modifier la somme à encaisser.




