Localize pricesPublic preview

When selling in a foreign market, using the customer’s local currency improves customer conversion, and payment authorization rates. However, this approach requires that you consider several factors:

• The appropriate foreign currency amounts to display on your site before checkout.
• The current exchange rates and foreign exchange (FX) fees for transactions.
• The amount of money credited to your Stripe balance in your currency.
• The frequency of exchange rate changes and when to update localized prices.

Stripe’s FX Quotes API addresses these considerations by providing:

• Current exchange rates: Stripe’s current exchange rate for any given currency pair.
• Extended exchange rate quotes: Rate quotes are valid for 5 minutes, 1 hour and 24 hour periods, reducing the uncertainty from FX fluctuations.
• FX fee information: Details on Stripe’s FX fees for your transactions, helping you estimate settlement amounts before payment costs.

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.

Available in 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")

Set the optimal localized price

You might want to set your localized prices for other countries based on what you’d charge a domestic customer. You can use the rates FX Quotes provides to convert your domestic pricing to other countries’ local currency. Consider rounding of prices and local market prices when deciding on your localized prices.

To ensure that the funds you receive for a transaction stay consistent across all markets, you can choose to pass Stripe’s FX fee to the customer. For example, consider a US-based merchant that wants to sell their 100 USD product in France. To calculate the equivalent price in Euros, use the exchange_rate parameter to pass on the FX fee to the customer. If you don’t want to pass on this fee, use the base_rate parameter. The following FX Quotes example response shows an FX Quote created to convert prices presented in the local currency, EUR, to your settlement currency, 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"
  }
}

Using this example, to pass on the FX fee to the customer, take the product price 100 USD divided by the exchange rate (1.0791) to get the rate in Euros 92.67 EUR. If you don’t want to pass on the FX fee, take the product price 100 USD and divide it by the base rate (1.09) for the Euro rate 91.74 EUR. Note that cross-border transactions also carry an international payment method fee, depending on the geography and payment method. See Stripe’s pricing page for more details.

Quote durations and rate changes

When you localize your pricing using exchange rate information provided by the FX Quotes API, you might want certainty around how long a given rate is valid. The FX Quotes API offers three time periods for lock_duration: five_minutes, hour, and day. This duration indicates that your transaction will be converted at the quoted exchange rate as long as you use the provided rate before it expires, as indicated by lock_expires_at.

The FX Quotes API also provides exchange rate information for the current live Stripe exchange rate. For this, choose lock_duration = none. When a lock_duration that isn’t none is used to create a quote, the base_rate field includes a premium for the extended rate. To determine the right extended rate quote period, consider the local price refresh cadence and checkout duration.

Currency markets might experience volatility which affects our ability to honor a given quote. FX Quotes created for payments have a 3.5% rate threshold, and those for transfers have a 1% rate threshold. Any quotes that drift beyond these thresholds are invalidated, with lock_status changing to 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.

Use localized prices to make payments

Assume you’re a UK-based merchant that sells to US customers, and you want to guarantee that you’ll receive 100 GBP even when selling to a US customer and regardless of changes in the exchange rate. In this scenario, we recommend fetching an FX Quote with a lock_duration of 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

Use the latest FX Quote to localize prices at any point during your customer journey knowing that you have a locked exchange rate for the next hour. Knowing that you want to recieve 100 GBP, if the exchange rate field for USD is 0.8, divide the GBP price 100 GBP by the exchange rate to give an amount of 125 USD.

This amount of 125 USD can be passed into the Payment Intents API to make the payment using the fx_quote parameter:

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

Handle minor units

All API requests expect amount values in the currency’s minor unit. After using the rates provided by the FX Quotes API, convert the resulting converted amount into Stripe’s minor units. See Minor units in API amounts and Zero-decimal currenciesfor more details.

Conversions on disputes and refunds

If currency-converted payment that used an FX Quote is disputed or refunded, the amount you received is converted back to the presentment currency at the current exchange rate. Exchange rates fluctuate with the market, so the rate used during the payment often differs from the rate used when a dispute or refund occurs. The amount deducted from your merchant balance depends on the current rate and this amount might be more or less than the original payment. The customer is always refunded the exact amount they paid and in the currency they paid in, regardless of any rate fluctuations.

Handle quote expiry

Stripe sends an fx_quote.expired webhook when a quote becomes invalid due to expiry or significant rate drifts. Attaching an already expired FX Quote object to the PaymentIntent API or Transfer API results in a 400 response. We recommend subscribing to the fx_quote.expired webhook event and creating a new FX Quote upon receipt of the event so that localized prices can be updated based on the new FX Quote object.

Mid-market rate fallback

Some non-card payment methods take longer to process payments than a 24-hour locking period covers. For these payments, the FX Quote might expire or become unusable due to significant mid-market rate changes. In these cases, we use the mid-market rate to process the payment.

Premium

We don’t charge for using FX Quotes with a lock duration of none. Stripe charges a premium for using extended rate quotes. This premium lets us cover the risk and cost incurred by offering extended rate quotes. The exact cost is determined by the lock_duration, and the currency pair in the currency conversion.

For a given currency pair, the higher premium of the two is used if the currencies have different premiums. For example, a USD-KRW currency pair with a 1-hour duration will have a 0.15% premium. If both currencies fall under the same group, the FX fee for that group is applied.

FX Quote only supports the currencies in the following two groups: