Use the FX Quotes API in Connect

Select which currencies to localize, lock in exchange rates, and decide whether to pass along fees to your customers.

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.

Multi-currency settlement

If the connected account has enabled the presentment currency through multi-currency settlement, Stripe converts to that currency instead of the default currency described in the following examples.

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

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

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 a destination charge without on_behalf_of, Stripe first converts the charge from the presentment currency to the platform’s settlement currency. Stripe then converts the amount transferred to the connected account into the connected account’s settlement currency.

The currency of the platform’s earnings depends on how the platform collects them:

• If you use application _ fee _ amount , Stripe deducts the application fee after converting the transferred funds. The platform receives the application fee in the connected account’s settlement currency.
• If you use transfer _ data[amount] , the amount not transferred remains with the platform in the platform’s settlement currency.

Note

This charge flow is subject to Stripe’s regional and cross-border policies.

For example, if a charge has a presentment currency of EUR, the platform settles in USD, and the connected account settles in GBP. An application fee is credited to the platform in GBP. An amount retained using transfer_data[amount] remains with the platform in USD.

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

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Destination charges with on_behalf_of

When processing a destination charge with on_behalf_of, the connected account is the settlement merchant. Stripe converts the charge from the presentment currency to the connected account’s settlement currency.

Stripe credits both forms of platform earnings in the connected account’s settlement currency:

• If you use application _ fee _ amount , the platform receives the application fee in the connected account’s settlement currency.
• If you use transfer _ data[amount] , the amount not transferred remains with the platform in the connected account’s settlement currency.

For example, if a charge has a presentment currency of USD and the connected account settles in EUR, Stripe credits the platform in EUR for both an application fee and an amount retained using 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 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

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

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:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

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.

Note

This charge flow is subject to Stripe’s regional and cross-border policies.

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

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

FX quote for the transfer

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

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.

Note

This charge flow is subject to Stripe’s regional and cross-border policies.

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

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Note

This charge flow is subject to Stripe’s regional and cross-border policies.

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: