L’API FX QuotesVersion bêta publique

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

En utilisant l’API FX Quotes, vous acceptez les Conditions d’utilisation 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 à la section Gestion des versions du SDK pour ajouter des configurations permettant d’accéder aux fonctionnalités en version bêta. Si vous appelez directement les endpoints de l’API plutôt que d’utiliser le SDK, indiquez un en-tête bêta avec la version de votre API dans l’appel à l’API.

require 'stripe'
Stripe.api_key = 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
Stripe.api_version = '2025-05-28.basil'
Stripe.add_beta_version("fx_quote_preview", "v1")

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

{
  "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 de Stripe.

Durées des cotations de change et évolutions des taux

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.

When lock_duration is set to 5 minutes, 1 hour, or 1 day, the duration_premium field includes the fee charged for the extended rate quote. To determine the right lock duration, consider how regularly local prices are refreshed and how long a checkout session lasts.

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.

When you use an expired quote for a PaymentIntent or Transfer, you receive an error.code of either payment_intent_fx_quote_invalid or transfers_fx_quote_invalid. You can use these error codes to handle expired quotes.

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 https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-05-28.basil; fx_quote_preview=v1" \
  -d to_currency=gbp \
  -d "from_currencies[]"=usd \
  -d lock_duration=day

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 https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-05-28.basil; fx_quote_preview=v1" \
  -d amount=125 \
  -d currency=usd \
  -d fx_quote=fxq_1QBck4FTKRd55CNDdboZYz9g

Gérer les unités mineures

Toutes les requêtes à l’API attendent des valeurs amount dans l’unité mineure de la devise. Après avoir utilisé les taux indiqués par l’API FX Quotes, convertissez le montant converti obtenu en unités mineures de Stripe. Pour plus d’informations, consultez la page Unités mineures dans les montants de l’API et Devises à zéro décimale.

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

Disponibilité Preview

L’API FX Quotes est actuellement disponible dans les pays suivants :