# L’API FX Quotes Sélectionnez les devises à localiser, verrouillez les taux de change et choisissez de répercuter ou non les frais sur vos clients. L’affichage des prix dans la devise locale d’un client peut améliorer les taux de conversion et les taux d’autorisation de paiement. Pour convertir des devises, vous devez prendre en compte les éléments suivants : - Les montants en devise appropriés à afficher sur votre site avant le paiement. - Les taux de change actuels et les frais de change pour les transactions. - Le montant des fonds crédités sur votre solde Stripe dans votre devise. - La fréquence des fluctuations des taux de change et des mises à jour nécessaires des prix localisés. L’[API FX Quotes](https://docs.stripe.com/api/fx_quotes.md?api-version=2025-07-30.preview) offre les fonctionnalités de conversion de devises suivantes : - **Taux de change actuels** : le taux de change actuel de Stripe pour toute paire de devises donnée. - **Cotations de change à durée prolongée** : créez une cotation de change à 5 minutes, 1 heure ou 24 heures pour réduire l’incertitude liée aux fluctuations des taux de change. - **Informations sur les frais de change** : détails sur les frais de change Stripe applicables à vos transactions, pour vous aider à estimer les montants de règlement avant les coûts de paiement. ## Conditions d’utilisation Stripe ne prend pas en charge l’API FX Quotes pour certains MCC. Utilisez le formulaire au bas de cette page pour demander un accès. En utilisant l’API FX Quotes, vous acceptez les [Conditions d’utilisation](https://www.stripe.com/legal/fxquotes) suivantes : - L’API FX Quotes est actuellement proposé en tant que *service en version bêta*. Cela signifie que Stripe offre le service « en l’état » et décline toute garantie, expresse ou implicite, concernant ce service. Vous utilisez un service en version bêta à vos propres risques, et Stripe n’est pas responsable des pertes, dommages ou coûts liés à la précision de ce service. - L’API FX Quotes peut vous fournir une cotation pour une paire de devises spécifique valable pour une certaine durée. C’est ce qu’on appelle une cotation à durée prolongée. Cette cotation ne constitue pas une offre de change et nous pouvons la retirer à tout moment. - L’API FX Quotes et les cotations de change prolongées doivent être utilisées dans le cadre de transactions commerciales de biens et de services que vous vendez sur Stripe. - Les cotations à taux prolongé peuvent vous aider à gérer la volatilité générale entourant les taux de change. Vous ne pouvez pas utiliser les cotations de change prolongées de manière sélective dans certaines situations, et en exclure d’autres. Par exemple, vous ne pouvez pas limiter l’utilisation des cotations à durée prolongée aux cas où le taux de change du marché est moins favorable que la cotation à durée prolongée. - Stripe peut ajouter ou supprimer des devises prises en charge de l’API FX Quotes à tout moment et sans préavis. ## Configurer l’API FX Quotes Si vous utilisez le SDK, reportez-vous au [contrôle des versions](https://docs.stripe.com/sdks/versioning.md#stripe-sdk-versions) du SDK pour ajouter des configurations permettant d’accéder aux fonctionnalités de prévisualisation. Si vous appelez directement les endpoints de l’API au lieu d’utiliser le SDK, assurez-vous d’utiliser une version bêta de l’API dans l’appel à l’API. #### Utiliser le SDK Stripe Vous trouverez ci-dessous un exemple pour Ruby. Vous pouvez exécuter la commande équivalente pour [tous les SDK](https://docs.stripe.com/sdks.md) dans d’autres langues. ```bash gem install stripe -v 14.0.0-beta.1 ``` ```ruby require 'stripe' Stripe.api_key = <> Stripe.api_version = '2025-07-30.preview' ``` #### Appeler directement l’API ```curl curl https://api.stripe.com/v1/fx_quotes \ -u "<>:" \ -H "Stripe-Version: 2025-03-31.preview" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d to_currency=gbp \ -d "from_currencies[]=eur" \ -d lock_duration=day ``` ## Fixer le prix localisé optimal En utilisant les taux de l’API FX Quotes, vous pouvez définir vos prix localisés pour d’autres pays d’après le tarif que vous facturez aux clients dans votre pays d’origine. Lorsque vous finalisez vos prix localisés, tenez compte des nuances de prix du marché local, et décidez si vous souhaitez ou non arrondir les prix au nombre entier le plus proche. Pour vous assurer de recevoir le même montant, quelle que soit la devise dans laquelle votre client paie, vous pouvez répercuter les frais de change Stripe sur le client. Par exemple, imaginez que vous êtes un marchand établi aux États-Unis et que vous souhaitez vendre votre produit au tarif de 100 USD en France. Pour calculer le tarif équivalent en EUR, utilisez le paramètre `exchange_rate` afin de répercuter les frais de change sur le client. Si vous ne souhaitez pas répercuter ces frais, utilisez le paramètre `base_rate`. L’exemple de réponse suivant montre une cotation de change créée pour convertir des tarifs présentés en devise locale (EUR) vers votre devise de règlement (USD) : ```json { "id": "fxq_1R6BWhL05bA97JHQELB5EROs", "object": "fx_quote", "created": 1742824731, "lock_duration": "five_minutes", "lock_expires_at": 1742825031, "lock_status": "active", "to_currency": "usd", "rates": { "eur": { "exchange_rate": 1.06053, "rate_details": { "base_rate": 1.08295, "duration_premium": 0.0007, "fx_fee_rate": 0.02, "reference_rate": 1.0827, "reference_rate_provider": "ecb" } } }, "usage": { "payment": { "destination": null, "on_behalf_of": null }, "transfer": null, "type": "payment" } } ``` Dans l’exemple ci-dessus, pour répercuter les frais de change sur le client, divisez le prix du produit (100 USD) par le taux de change (1,06053) afin d’obtenir le tarif pour vos clients français, frais de change compris : 94.29 EUR. Si vous ne souhaitez pas répercuter les frais de change, divisez le prix du produit (100 USD) par le taux de base (1,08295) pour le prix, hors frais de change : 92.34 EUR. Les transactions transfrontalières comportent également des frais de moyen de paiement international, en fonction de la zone géographique et du moyen de paiement. Pour en savoir plus, consultez la [page des tarifs](https://stripe.com/pricing) de Stripe. ## Durées des cotations de change et évolutions des taux Si vous avez besoin d’une durée `lock_duration` de cotation de change plus longue, contactez-nous à l’aide du formulaire disponible en bas de cette page. Lorsque vous localisez votre tarification à l’aide des informations sur les taux de change fournies par l’API FX Quotes, vous pouvez avoir besoin de certitude quant à la durée de validité d’un taux donné. L’API FX Quotes propose trois périodes pour `lock_duration` : `five_minutes`, `hour` et `day`. Cette durée indique que votre transaction sera convertie au taux de change indiqué, à condition que vous utilisiez le taux fourni avant son expiration, tel qu’indiqué par `lock_expires_at`. L’API FX Quotes fournit également des informations sur le taux de change Stripe en temps réel. Pour cela, définissez `lock_duration` sur `none`. Lorsque la durée `lock_duration` est définie sur 5 minutes, une heure ou un jour, le champ `duration_premium` inclut [les frais facturés pour la cotation de change à durée prolongée](https://docs.stripe.com/payments/currencies/localize-prices/fx-quotes-api.md#pricing). Pour déterminer la durée de verrouillage appropriée, tenez compte de la fréquence à laquelle les prix locaux sont actualisés et de la durée d’une session de paiement. Les marchés des changes peuvent connaître une volatilité qui affecte notre capacité à honorer une cotation donnée. Une cotation à durée prolongée créée pour les paiements a un seuil de taux de 3,5 %, tandis qu’une cotation à durée prolongée pour les transferts a un seuil de taux de 1 %. Si un taux de change dépasse ces seuils, la cotation à durée prolongée est annulée, et l’état `lock_status` passe à `expired`. Lorsque vous utilisez des cotations de change expirées pour un PaymentIntent ou un transfert, vous recevez un `error.code` [payment_intent_fx_quote_invalid](https://docs.stripe.com/error-codes.md#payment-intent-fx-quote-invalid) ou [transfers_fx_quote_invalid](https://docs.stripe.com/error-codes.md#transfers-fx-quote-invalid). Vous pouvez utiliser ces codes d’erreur pour [gérer les cotations de change expirées](https://docs.stripe.com/payments/currencies/localize-prices/fx-quotes-api.md#webhook-integration). ## Utiliser des taux de change bloqués pour localiser les tarifs Par exemple, si vous êtes un marchand établi au Royaume-Uni qui localise ses tarifs pour des clients américains et que vous souhaitez recevoir 100 GBP, indépendamment des variations du taux de change USD/GBP. Dans ce cas, nous vous recommandons de récupérer une cotation de change à durée prolongée avec une durée `lock_duration` de `hour` : ```curl curl https://api.stripe.com/v1/fx_quotes \ -u "<>:" \ -d to_currency=gbp \ -d "from_currencies[]=usd" \ -d lock_duration=day ``` Si vous souhaitez afficher les taux de change de la Banque centrale européenne à titre de référence, l’objet [FX Quotes](https://docs.stripe.com/api/fx_quotes/object.md?api-version=2025-07-30.preview#fx_quote_object-rates-%3Cfrom_currency%3E.rate_details-reference_rate_provider) contient l’ensemble des taux que [la Banque centrale européenne prend en charge](https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html). Par exemple, si le dernier taux de change pour l’USD est de 0,8, divisez votre tarif (100 GBP) par le taux de change (0,8) pour calculer votre tarif localisé : 125 USD. Ce taux de change étant bloqué pendant une heure, vous pouvez afficher 125 USD à vos clients américains, depuis votre site vers la page de paiement. Vous pouvez transmettre votre tarif américain 125 USD dans l’API Payment Intents pour effectuer le paiement à l’aide du paramètre `fx_quote` : ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=125 \ -d currency=usd \ -d fx_quote=fxq_1QBck4FTKRd55CNDdboZYz9g ``` ### Gérer les unités mineures Stripe [convertit les paiements litigieux ou remboursés](https://docs.stripe.com/payments/currencies/localize-prices.md) dans la devise de présentation au taux de change actuel, au lieu du taux précédent. Toutes les requêtes API attendent des valeurs `amount` exprimées dans l’unité monétaire minimale de la devise. Après utilisation des taux fournis par l’[API FX Quotes](https://docs.stripe.com/api/fx_quotes.md?api-version=2025-07-30.preview), convertissez le montant obtenu dans l’unité minimale Stripe. Consultez [Unités minimales pour les montants API](https://docs.stripe.com/currencies.md#minor-units) et [Devises sans décimales](https://docs.stripe.com/currencies.md#zero-decimal) pour plus de détails. ## Gérer l’expiration des cotations Stripe envoie un webhook `fx_quote.expired` lorsqu’une cotation n’est plus valide en raison d’une expiration ou d’une évolution importante du taux. L’association d’un objet `FX Quote` déjà expiré à l’API PaymentIntent ou à l’API Transfer renvoie un code d’état `400`. Nous vous recommandons de vous abonner à l’événement de webhook `fx_quote.expired` et de créer une nouvelle cotation de change prolongée après réception de l’événement afin que les prix localisés puissent être mis à jour d’après le nouvel objet `FX Quote`. ### Utilisation des taux moyens du marché comme solution de repli Certains [moyens de paiement autres que les cartes](https://stripe.com/guides/payment-methods-guide#2-choosing-the-right-payment-methods-for-your-business) nécessitent un temps de traitement plus long qu’une période de verrouillage de 24 heures. Pour ces paiements, la cotation à durée prolongée peut expirer ou devenir inutilisable en raison de variations importantes des taux moyens du marché. Dans ce cas, nous utilisons le taux interbancaire pour traiter le paiement. ## Tarifs Nous ne facturons pas les cotations de change prolongées dont la durée de blocage est `none`. Lorsque `lock_duration` est défini sur `five_minutes`, `hour` ou `day`, Stripe facture des frais pour couvrir le risque et les coûts encourus. Vous pouvez définir ces frais dans le champ `duration_premium`. Ils seront ajoutés au `base_rate` pour calculer le `exchange_rate`. Le montant exact des frais dépend de la durée `lock_duration` et de la paire de devises utilisée pour la conversion de devises. Reportez-vous au tableau ci-dessous pour calculer les frais d’une cotation à durée prolongée. Si vous effectuez une conversion d’une devise du groupe 2 vers une devise du groupe 1 (ou vice-versa), les frais indiqués pour le groupe 2 s’appliquent. Par exemple, une paire de devises USD/KRW d’une durée de 1 heure a des frais de 0,15 %, car les KRW appartiennent au groupe 2. Si les deux devises appartiennent au même groupe, les frais pour ce groupe s’appliquent. L’API FX Quote prend uniquement en charge les devises des deux groupes suivants : | Groupe | 5 minutes | 1 heure | 24 heures | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------ | -------------- | | **Groupe 1 :** aed, aud, awg, bbd, bhd, bmd, bsd, cad, chf, dkk, eur, gbp, hkd, idr, inr, jod, jpy, kwd, myr, nzd, omr, pab, ron, sar, sek, sgd, thb, usd, xcd, yer | 0,07 % | 0,10 % | 0,20 % | | **Groupe 2 :** afn, all, amd, ang, aoa, azn, bam, bdt, bif, bnd, bob, brl, bwp, bzd, clp, cny, cop, crc, cve, czk, djf, dop, dzd, fkp, gel, gip, gmd, gnf, gtq, gyd, hnl, htg, huf, ils, isk, jmd, kes, kgs, khr, krw, kyd, kzt, lkr, lrd, mad, mdl, mga, mkd, mnt, mop, mur, mvr, mxn, mzn, nad, nok, npr, pen, php, pkr, pln, pyg, qar, rsd, rwf, shp, std, tjs, tnd, try, ttd, twd, tzs, uah, ugx, uyu, uzs, vnd, xaf, xof, xpf, zar, zmw | 0,12 % | 0,15 % | 0,30 % | ## Disponibilité (Preview) L’API FX Quotes est disponible dans les pays suivants, et vous pouvez l’utiliser pour afficher des tarifs localisés dans les [devises prises en charge](https://docs.stripe.com/currencies.md#presentment-currencies) : - AT - BE - BG - CA - CH - CY - CZ - DE - DK - EE - ES - FI - FR - GB - GI - GR - HR - HU - IE - IT - LT - LU - LV - MT - NL - NO - PL - PT - RO - SE - SI - SK - US