The FX Quotes API公開プレビュー

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:

• 決済前にサイトに表示する適切な外貨額。
• 取引に適用される現在の為替レートと外貨為替 (FX) 手数料。
• ご利用通貨で Stripe 残高に入金される金額。
• 為替レートの変更回数と現地価格への更新タイミング。

The FX Quotes API provides the following currency conversion capabilities:

• 現在の為替レート: 特定の通貨ペアを対象とする Stripe の現在の為替レート。
• 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.

利用規約

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

最適な現地価格を設定する

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.

見積もり期間と料金の変更

FX Quotes API によって提供される為替レート情報を使用して価格をローカライズする場合、特定のレートが有効な期間について確実性が必要な場合があります。FX Quotes API は、lock_duration に five_minutes、hour、day の 3 つの期間を提供します。この期間は、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

補助単位の処理

すべての API リクエストは、通貨の補助単位の amount 値を想定しています。FX Quotes API で提供されたレートを使用した後、換算後の金額を Stripe の補助単位に変換します。詳細については、API 金額の補助単位および小数点以下なしの通貨を参照してください。

見積もりの有効期限を処理する

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.

仲値レートのフォールバック

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.

料金体系

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: