Montants et devises : contrôler les unités mineures des API

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

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

1. Lire une offre et son prix total avec taxes et frais.
2. Transmettre exactement le montant attendu par l’opération de paiement.
3. Rapprocher la valeur affichée, la valeur envoyée et la transaction retournée.
4. Tester remise, acompte, solde et deux remboursements partiels.
5. Tester une devise sans décimale et une devise à trois décimales.
6. 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.

Sources et périmètre des faits documentés

Sources officielles consultées le 05/10/2026. 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 : codes monétaires — Agence de maintenance des codes ISO 4217.
• Adyen : Currency codes and minor units — Convention des montants, précisions EUR, JPY et KWD, et divergences signalées avec ISO 4217.