Use the FX Quotes API in Connect

Use the FX Quotes API to localize prices in your customers’ currencies and reduce any uncertainty around changing exchange rates. You can specify an FX quote when creating a PaymentIntent with your customer’s presentment currency. You can also specify an FX quote when creating a transfer to confirm the settlement amount on the connected account. For details, see FX quotes.

Example FX scenarios

Across different Connect charge types, FX occurs in the following different ways.

Direct charges

Direct charges are always converted to the connected account’s default currency from the presentment currency. The application fee is converted to the platform’s default currency.

For example, say you accept a charge for a connected account in USD. The connected account receives funds in EUR. The funds sent to the connected account convert to EUR and the application fee converts back to your platform in USD from EUR.

You can use extended rate quotes from the FX Quotes API to reduce FX uncertainty on direct charges. When creating a direct charge, pass the FX quote ID into the PaymentIntent. Specify the end customer’s currency as the from_currency. Specify your connected account’s default settlement currency as the to_currency.

Create an FX quote

curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d to_currency=gbp \
  -d "from_currencies[]"=usd \
  -d "from_currencies[]"=eur \
  -d lock_duration=hour \
  -d "usage[type]"=payment

Although direct charges are in the connected account’s default currency, your platform receives the application fees for direct charges in your platform’s default currency. Using the extended rate quotes on direct charges in the FX Quotes API doesn’t affect the FX rate at which application fees convert.

If your platform doesn’t use application fees and retains a portion of the charges instead, those funds are paid out the same way as other charges on the platform account.

Destination charges without on_behalf_of

When processing destination charges without on_behalf_of, Stripe first converts them from the presentment currency to the platform’s default currency. The funds sent to the connected account then convert to the connected account’s default currency.

• If you use application_fee_amount, we collect the application fee after the conversion to the connected account’s default currency. The fee remains in that currency when added to the platform.
• If you use transfer_data[amount], we collect the fee after the first currency conversion and it remains in the platform’s default currency.

For example, say you accept a destination charge for a connected account in EUR. The connected account settles in GBP, and your platform settles in USD. The charge converts from EUR to USD, and the funds sent to the connected account convert to GBP.

• If you use application_fee_amount, the application fee amount converts from EUR to GBP and we take it from the amount that settles on the connected account.
• If you use transfer_data[amount], the fee is retained in USD after converting it from the initial presentment currency.

You can use extended rate quotes from the FX Quotes API to reduce FX uncertainty on destination charges without on_behalf_of. When creating a charge, pass the FX quote ID into the PaymentIntent. In the above example, this gives you certainty about the FX rate used for the conversion from EUR (the end customer currency) to USD (the platform currency). In FX quotes, specify the end customer’s currency as the from_currency. Specify your platform’s default settlement currency as the to_currency. You can’t use FX quotes for any conversion occurring on the transfer from the platform to the connected account, or on any conversion of the application fees.

Creating an FX quote

curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d to_currency=gbp \
  -d "from_currencies[]"=usd \
  -d "from_currencies[]"=eur \
  -d lock_duration=hour \
  -d "usage[type]"=payment \
  -d "usage[payment][destination]"=
{{CONNECTED_ACCOUNT_ID}}

We don’t convert application fees collected using the application_fee_amount parameter again for destination charges. Platforms always receive application fees in the connected account’s settlement currency. Use the transfer_data[amount] parameter to transfer less of the transaction amount and collect fees in the platform’s default settlement currency.

Destination charges with on_behalf_of

When processing destination charges with on_behalf_of, Stripe first converts them from the presentment currency to the connected account’s default currency. The application fee remains in the connected account’s currency, regardless of whether you use application_fee_amount or transfer_data[amount].

For example, the connected account accepts a charge in USD but settles in EUR. The charge converts to EUR and we send it to the connected account in EUR. We collect the fee in EUR, regardless of whether you use application_fee_amount or transfer_data[amount].

You can use extended rate quotes from the FX Quotes API to reduce FX uncertainty on destination charges with on_behalf_of. When creating a charge, pass the FX Quote ID into the PaymentIntent. In the above example, this gives you certainty of the FX rate used for the conversion from USD (the end customer currency) to EUR (the the connected account currency). In FX quotes, specify the end customer’s currency as the from_currency. Specify your connected account’s default settlement currency as the to_currency.

Creating an FX quote

curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d to_currency=gbp \
  -d "from_currencies[]"=usd \
  -d "from_currencies[]"=eur \
  -d lock_duration=hour \
  -d "usage[type]"=payment \
  -d "usage[payment][on_behalf_of]"=
{{CONNECTED_ACCOUNT_ID}} \
  -d "usage[payment][destination]"=
{{CONNECTED_ACCOUNT_ID}}

We don’t convert application fees collected using the application_fee_amount parameter again for destination charges. Platforms always receive application fees in the connected account’s settlement currency. Use the transfer_data[amount] parameter to transfer less of the transaction amount and collect fees in the platform’s default settlement currency.

If you create charges on the platform using the destination or on_behalf_of parameters, you might accumulate balances in multiple currencies. If you don’t have bank accounts for these other currencies, Stripe provides a way to pay out balances in non-default currencies to your platform’s default bank account.

Stripe converts the currencies and they’re represented as manual payouts with currency set as the currency of the source balance:

curl https://api.stripe.com/v1/payouts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1000 \
  -d currency=xaf

If there are sufficient funds in the balance for the specified currency, Stripe automatically converts the funds to the default bank account’s currency. We don’t support using FX quotes on payouts.

Separate charges and transfers without on_behalf_of

We convert separate charges to the platform’s default currency from the presentment currency and the platform later transfers the funds to the connected account. The application_fee_amount and transfer_data[amount] parameters aren’t used to collect fees, because the platform can choose the appropriate amount to send at transfer time.

Take a USD charge as an example. The platform account’s default currency is GBP. Currency conversion from USD to GBP occurs as part of the charge. When the platform transfers these funds to a connected account with EUR as their default currency, another currency conversion occurs, this time from GBP to EUR.

You can use extended rate quotes from the FX Quotes API to reduce FX uncertainty when using separate charges and transfers without on_behalf_of. This applies on both the charge and the stand-alone transfer.

FX quote for the payment

curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d to_currency=gbp \
  -d "from_currencies[]"=usd \
  -d "from_currencies[]"=cad \
  -d lock_duration=hour \
  -d "usage[type]"=payment

FX quote for the transfer

curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d to_currency=eur \
  -d "from_currencies[]"=gbp \
  -d lock_duration=five_minutes \
  -d "usage[type]"=transfer \
  -d "usage[transfer][destination]"=
{{CONNECTED_ACCOUNT_ID}}

When creating a charge, pass the FX quote ID into the PaymentIntent. In the above example, this gives you certainty of the FX rate used for the conversion from USD (the end customer currency) to GBP (the Connect Platform currency). In FX quotes, specify the end customer’s currency as the from_currency. Specify your platform’s default settlement currency as the to_currency.

When creating a transfer, pass the FX quote ID into the transfer. In the above example, this gives you certainty of the FX rate used for the conversion from GBP (the Connect platform currency) to EUR (the connected account currency). In FX quotes, specify the Connect platform’s currency as the from_currency. Specify your connected account’s default currency as the to_currency.

Separate charges and transfers with on_behalf_of

We convert separate charges to the connected account’s default currency from the presentment currency, and the platform later transfers the funds to the connected account. We don’t use the application_fee_amount and transfer_data[amount] parameters to collect fees, because the platform can choose the appropriate amount to send at transfer time.

Take a USD charge as an example. The connected account’s default currency is EUR. Currency conversion from USD to EUR occurs as part of the charge. There is no currency conversion during the transfer because the funds are already in the connected account’s currency.

You can use extended rate quotes from the FX Quotes API to reduce FX uncertainty when using separate charges and transfers with on_behalf_of.

FX quote for the charge

curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d to_currency=gbp \
  -d "from_currencies[]"=usd \
  -d lock_duration=hour \
  -d "usage[type]"=payment \
  -d "usage[payment][on_behalf_of]"=
{{CONNECTED_ACCOUNT_ID}}

FX on refunds

When you refund a payment that was originally converted to another currency, we use the live FX rate at the time of the refund. This is true regardless of whether you used FX quotes to set your FX rate on the original payment. Stripe doesn’t charge an FX fee for any conversion on the refund. Stripe doesn’t refund the FX fee charged on the original transaction.

FX on payouts

The settlement currency is the currency that you can receive payouts in. See the supported settlement currencies.

Depending on bank account or debit card availability, the following occurs when paying out a balance: