The FX Quotes APIVersion bêta publique

Available in Preview

Displaying prices in a customer’s local currency improves conversion rates and payment authorization rates. To convert currencies in an accurate and cost-effective way, you must account for:

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

The FX Quotes API provides the following currency conversion capabilities:

• Current exchange rates: Stripe’s current exchange rate for any given currency pair.
• Extended exchange rate quotes: A 5 minute, 1 hour or 24 hour rate quote can be created to reduce the uncertainty from FX fluctuations.
• FX fee information: Details about Stripe’s FX fees for your transactions, helping you estimate settlement amounts before payment costs.

Terms of use

By using the FX Quotes API, you agree to the following Terms of Service:

• The FX Quotes API 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.
• The FX Quotes API might provide you with a quote for a specific currency pair that’s valid for a period of 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 the FX Quotes API 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 selectively use Extended Rate Quotes in certain situations but not others. For example, you cannot only use Extended Rate Quotes in instances where the market FX rate is less favorable than the Extended Rate Quote.
• Stripe might add or remove supported currencies from the FX Quotes API at any time, without notice.

Set up to use the FX Quotes API

If you’re using the SDK, refer to SDK versioning to add configurations to access preview features. If you call the API endpoints directly instead of using the SDK, 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-04-30.basil'
Stripe.add_beta_version("fx_quote_preview", "v1")

Set the optimal localized price

Using the rates from the FX Quotes API, you can set your localized prices for other countries based on the price you charge customers in your home country. When finalizing your localized prices, consider any local market pricing nuances and whether you want to round prices to the nearest whole number.

To ensure that you receive the same amount regardless of the currency your customer pays in, you can choose to pass Stripe’s FX fee to the customer. For example, imagine you’re a US-based merchant who wants to sell your 100 USD product in France. To calculate the equivalent price in EUR, use the exchange_rate parameter to pass the FX fee to the customer. If you don’t want to pass on this fee, use the base_rate parameter. The following example response shows a 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 the above example, to pass on the FX fee to the customer, divide the product price (100 USD) by the exchange rate (1.06053) to get the price for your customers in France inclusive of the FX fee: 94.29 EUR. If you don’t want to pass on the FX fee, divide the product price (100 USD) by the base rate (1.08295) for the price excluding the FX fee: 92.34 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, set lock_duration to none.

When lock_duration is set to 5 minutes, an hour, or a 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.

Currency markets might experience volatility, affecting our ability to honor a given quote. An extended rate quote created for payments has a 3.5% rate threshold, and an extended rate quote for transfers has a 1% rate threshold. If an exchange rate exceeds these thresholds, the extended rate quote is 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 locked exchange rates to localize prices

As an example, if you’re a UK-based merchant that localizes prices for US customers, and you want to receive 100 GBP regardless of changes in the USD-GBP exchange rate. In this scenario, we recommend fetching an extended rate quote with a lock_duration of hour:

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

If the latest exchange rate for USD is, for example, 0.8, divide your price (100 GBP) by the exchange rate (0.8) to calculate your localized price: 125 USD. Because this exchange rate is locked for the next hour, you can show 125 USD to your US customers, from your site to the checkout page.

You can pass your US price 125 USD 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-04-30.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.

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 returns a 400 status code. We recommend subscribing to the fx_quote.expired webhook event and creating a new extended rate quote after receiving 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 extended rate 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.

Pricing

We don’t charge for extended rate quotes with a lock duration of none. When lock_duration is set to five_minutes, hour, or day, Stripe charges a fee to cover the risk and cost incurred. This fee is shown in the duration_premium field and is added to the base_rate to calculate the exchange_rate.

The exact fee depends on the lock_duration, and the currency pair used for the currency conversion. Refer to the table below to calculate the fee for an extended rate quote. If you’re converting from a currency in Group 2 to a currency in Group 1 (or vice versa), the fee listed for Group 2 will be used. For example, a USD-KRW currency pair with a 1-hour duration will have a 0.15% fee because KRW is in Group 2. If both currencies are in the same group, the fee for that group is applied.

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