Localiser les prixVersion bêta publique

Lorsque vous vendez sur un marché étranger, utiliser la devise locale du client améliore le taux de conversion et les taux d’autorisation de paiement. Toutefois, cette approche nécessite que vous preniez en compte plusieurs facteurs :

• 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 de Stripe répond à ces considérations en fournissant les éléments suivants :

• 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 : cotations de change valables pour des périodes de 5 minutes, 1 heure et 24 heures, ce qui réduit l’incertitude liée aux fluctuations des taux de change.
• Informations sur les frais de change : détails sur les frais de change de Stripe pour vos transactions, ce qui vous aide à estimer les montants de règlement avant les coûts de paiement.

Terms of use

By using the FX Quotes service, you agree to these Terms of Service.

As part of using FX Quotes you agree and understand:

• FX Quotes is currently offered as a preview service. This means Stripe offers the service “as is” and disclaims all expressed or implied warranties and guarantees around this service. You’re relying on a preview service at your own risk and Stripe isn’t liable for losses, damages, or costs arising that relate to the accuracy of the preview service.
• FX Quotes might provide you with a quote for a specific currency pair that’s valid for a time in the future. This is called an Extended Rate Quote. This quote isn’t an offer to enter into foreign exchange, and we can withdraw it at any time.
• Use of FX Quotes and Extended Rate Quotes must be used as part of a commercial transaction of goods and services you sell on Stripe.
• Extended Rate Quotes can help you manage general uncertainty in foreign exchange (FX) rates. You’re not permitted to use Extended Rate Quotes only in instances where the market FX rate is less favorable than the Extended Rate Quote.
• Stripe might add or remove supported currencies from FX Quotes at any time, without notice.

Disponible en Preview

Setup to use FX Quotes

If you’re using the SDK, refer to SDK versioning to add configurations to access preview features. If you’re not using the SDK and calling the API endpoints directly, specify a beta header along with your API version in the API call

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

Fixer le prix localisé optimal

Vous pouvez définir vos tarifs localisés pour d’autres pays en fonction de ce que vous factureriez à un client national. Vous pouvez utiliser les taux proposés par FX Quotes pour convertir vos tarifs nationaux dans la devise locale d’autres pays. Tenez compte de l’arrondissement des tarifs et des prix du marché local lorsque vous prenez une décision concernant vos tarifs localisés.

Pour que les fonds que vous recevez en contrepartie d’une transaction restent les mêmes sur tous les marchés, vous pouvez choisir de transférer les frais de change Stripe au client. Prenons l’exemple d’un marchand établi aux États-Unis qui souhaite vendre son produit à 100 USD en France. Pour calculer le prix équivalent en euros, utilisez le paramètre exchange_rate pour 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 les tarifs présentés dans la 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 cet exemple, pour répercuter les frais de change sur le client, divisez le prix du produit 100 USD par le taux de change (1,0791) pour obtenir le taux en euros 92.67 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,09) pour le taux en euros 91.74 EUR. Veuillez noter que les transactions transfrontalières entraînent également des frais associés aux moyens de paiement internationaux, en fonction du pays et du moyen de paiement. Pour en savoir plus, consultez la page de tarification 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, choisissez lock_duration = none. Lorsqu’une valeur de lock_duration autre que none est utilisée pour créer une cotation, le champ base_rate inclut un supplément pour le prolongement du taux. Pour déterminer la période de cotation prolongée qui vous convient, tenez compte de la cadence d’actualisation des tarifs locaux et la durée du processus de paiement.

Les marchés des changes peuvent connaître une volatilité qui affecte notre capacité à honorer une cotation donnée. Les objets FX Quote créés pour les paiements ont un seuil de taux de 3,5 % et ceux créés pour les transferts ont un seuil de taux de 1 %. Toutes les cotations qui dépassent ces seuils sont invalidées, et lock_status passera à expired.

Lorsque vous utilisez des cotations de change expirées pour un PaymentIntent ou un transfert, vous recevez le error.code payment_intent_fx_quote_invalid ou transfers_fx_quote_invalid. Vous pouvez utiliser ces codes d’erreur pour gérer les cotations de change expirées.

Utiliser des tarifs localisés pour effectuer des paiements

Supposons que vous soyez un marchand établi au Royaume-Uni, que vous réalisiez des ventes à des clients aux États-Unis et que vous vouliez avoir la garantie de recevoir 100 GBP même lorsque vous vendez à un client américain, et quelles que soient les variations du taux de change. Dans ce cas, nous vous recommandons de récupérer un objet FX Quote avec une durée de validité lock_duration de hour :

curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-03-31.basil; fx_quote_preview=v1" \
  -d to_currency=gbp \
  -d "from_currencies[]"=eur \
  -d lock_duration=day

Utilisez la dernière cotation de change pour localiser les tarifs à n’importe quel moment du parcours client, en sachant que votre taux de change est bloqué durant une heure. Étant donné que vous souhaitez recevoir 100 GBP, si le champ taux de change USD est de 0,8, divisez le tarif 100 GBP en GBP par le taux de change pour obtenir un montant de 125 USD.

Vous pouvez transmettre ce montant de 125 USD à 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-03-31.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.

Conversions pour les litiges et remboursements

En cas de contestation ou de remboursement d’un paiement converti en devises utilisant une cotation de change, le montant reçu est reconverti dans la devise de présentation au taux de change en vigueur. Les taux de change fluctuent en fonction du marché, de sorte que le taux utilisé lors du paiement diffère souvent du taux utilisé en cas de litige ou de remboursement. Le montant déduit du solde du marchand dépend du taux en vigueur, et ce montant peut être supérieur ou inférieur au paiement initial. Le client est toujours remboursé du montant exact qu’il a payé et dans la devise dans laquelle il a payé, quelles que soient les fluctuations de taux.

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 génère une réponse 400. Nous vous recommandons de vous abonner à l’événement de webhook fx_quote.expired et de créer une nouvelle cotation de change à la réception de l’événement afin que les prix localisés puissent être mis à jour en fonction du nouvel objet FX Quote.

Utilisation des taux moyens du marché comme solution de repli

Le traitement de certains moyens de paiement autres que les cartes prend plus de temps qu’une période de verrouillage de 24 heures. Pour ces paiements, la cotation de change peut expirer ou devenir inutilisable en raison de variations importantes des taux interbancaires. Dans ce cas, nous utilisons le taux interbancaire pour traiter le paiement.

Supplément

Nous ne facturons pas l’utilisation des cotations de change dont la durée de verrouillage est none. Stripe facture des suppléments pour l’utilisation de cotations étendues. Ce supplément nous permet de couvrir les risques et les coûts encourus en offrant des cotations prolongées. Le coût exact est déterminé par l’attribut lock_duration et la paire de devises de la conversion.

Pour une paire de devises donnée, le supplément le plus élevé des deux est utilisé si les devises ont des suppléments différents. Par exemple, une paire de devises USD-KRW d’une durée de 1 heure aura un supplément de 0,15 %. Si les deux devises appartiennent au même groupe, les frais de change de ce groupe sont appliqués.

FX Quote ne prend en charge que les devises des deux groupes suivants :