Private preview

Create a multi-currency Financial Account Private preview

Learn how to hold multiple currencies, convert funds and send local payouts.

This example use case shows an integration using a SaaS platform that supports wholesalers using Connect and Treasury for platforms. One of its US wholesalers wants to set up a multi-currency financial account that can hold GBP so it can convert funds and send EUR payments to suppliers in Europe.

Availability

Multi-currency financial accounts are available in the following countries:

Country	Supported currencies
Australia	AUD, EUR, GBP, USD
United Kingdom	EUR, GBP, USD
United States	EUR, GBP, USD

The example integration requires the following steps:

Create and onboard a connected account for Treasury for platforms.
Create a multi-currency financial account .
Create a financial address so the wholesaler can bank-transfer funds into a financial account.
Get an exchange rate quote for currency conversion and then convert the funds.
Create a cross-border payout from the wholesaler to its supplier.

Develop in a sandbox

Begin in a sandbox with access to Treasury for platforms and use that sandbox’s test API keys for all requests.

Create the connected account

The platform creates the connected account for the wholesaler with the merchant and money_manager configurations and requests the associated capabilities.

Note

A connected account can only hold currencies that the platform also holds.

Command Line

cURL

Example response

{
 "id": "{{CONNECTED_ACCOUNT_ID}}",
 "object": "v2.core.account",
 "applied_configurations": ["merchant","money_manager"],
 "configuration": {
 "money_manager": {
 "capabilities": {
 "business_storage": { "inbound": { "gbp": { "requested": true, "status": "restricted" }, "eur": { "requested": true, "status": "restricted" }, "usd": { "requested": true, "status": "restricted" } }, "outbound": { "gbp": { "requested": true, "status": "restricted" }, "eur": { "requested": true, "status": "restricted" }, "usd": { "requested": true, "status": "restricted" } } }
 }
 }
 },
 "display_name": "Euro Supplies Inc",
 "dashboard": "none",
 "livemode": false
}

Onboard the wholesaler

The platform then onboards the connected account by:

Retrieving the requirements generated for the requested capabilities.
Providing a form to collect the information required from your connected account.
Updating the Account with the collected information, specifying the connected account in the Stripe-Context header: {{the related setting}} to identify the connected account as the account to update.

Alternatively, the platform might create an account link specifying the type as the merchant and money_manager configurations, then send the returned URL to the connected account before it expires so they can provide the required information in a Stripe-hosted interface.

The platform listens for the v2.core.account[configuration.money_manager].capability_status_updated webhook to confirm the capabilities are active for its connected account.

Create a multi-currency financial account

The platform creates a storage financial account that can store funds in EUR, USD and GBP, specifying the wholesaler’s account ID in the Stripe-Context header to associate the financial account with the wholesaler.

Command Line

cURL

The response includes the financial account ID:

Example response

{
 "id": "{{FINANCIAL_ACCOUNT_ID}}",
 "object": "v2.money_management.financial_account",
 "balance": {
 "available": {
 "gbp": { "value": 0, "currency": "gbp" },
 "eur": { "value": 0, "currency": "eur" },
 "usd": { "value": 0, "currency": "usd" }
 },
 "inbound_pending": {
 "gbp": { "value": 0, "currency": "gbp" },
 "eur": { "value": 0, "currency": "eur" },
 "usd": { "value": 0, "currency": "usd" }
 },
 "outbound_pending": {
 "gbp": { "value": 0, "currency": "gbp" },
 "eur": { "value": 0, "currency": "eur" },
 "usd": { "value": 0, "currency": "usd" }
 }
 },
 "country": "US",
 "created": "2025-11-17T11:05:27.930Z",
 "status": "pending",
 "status_details": null,
 "storage": { "holds_currencies": ["gbp", "eur", "usd"] },
 "type": "storage",
 "livemode": false
}

Create financial addresses

To allow the wholesaler to add funds through bank transfers, the platform creates a GBP financial address for the wholesaler’s financial account.

Command Line

cURL

The response includes the ID of the financial address:

Example response

{
 "id": "{{FINANCIAL_ADDRESS_ID}}",
 "object": "v2.money_management.financial_address",
 "created": "2025-06-19T19:17:54.607Z",
 "credentials": null,
 "currency": "gbp",
 "financial_account": "fa_12345",
 "settlement_currency": "gbp",
 "status": "pending",
 "livemode": false
}

The platform simulates receiving funds through the financial address using the Credit a FinancialAddress object test helper in a sandbox instead of funding in live mode using an external bank account.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

The response indicates if the transfer of virtual funds was successful.

The platform listens for the v2.money_management.received_credit.created webhook to learn when the money movement has started.

Retrieve an exchange rate quote

The platform obtains an FX quote to display an indicative rate to its wholesaler. This quote represents the current exchange rate, but isn’t lockable for currency conversion, which calculates its own rate at execution and might differ from the quote rate.

Command Line

cURL

Example response

{
 "id": "fxq_123",
 "object": "fx_quote",
 "created": 1731498806.6424642,
 "lock_duration": "none",
 "rates": {
 "gbp": {
 "exchange_rate": 1.10167,
 "rate_details": {
 "base_rate": 1.12415,
 "fx_fee_rate": 0.02,
 "reference_rate": 1.12437,
 "reference_rate_provider": "ecb"
 }
 }
 },
 "to_currency": "eur",
 "usage": {
 "payment": null,
 "transfer": null,
 "type": "payment"
 }
}

Convert GBP funds to EUR

The platform converts the financial account funds from GBP to EUR on behalf of the wholesaler. Stripe charges the platform’s financial account for the FX fee, and the platform can create an OutboundPayment from the wholesaler to its own financial account to recover the fee.

Command Line

cURL

Example response

{
 "id": "cnvr_test_123",
 "object": "v2.money_management.currency_conversion",
 "created": "2025-11-17T14:28:48.000Z",
 "exchange_rate": "1.1324",
 "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
 "from": {
 "amount": {
 "value": 2500,
 "currency": "gbp"
 }
 },
 "to": {
 "amount": {
 "value": 2831,
 "currency": "eur"
 }
 },
 "livemode": false
}

The platform verifies that the wholesaler’s financial account has enough EUR to pay their supplier.

Command Line

cURL

Example response

{
 "id": "{{FINANCIAL_ACCOUNT_ID}}",
 "object": "v2.money_management.financial_account",
 "balance": {
 "available": {
 "gbp": {
 "value": 2500,
 "currency": "gbp"
 },
 "eur": {
 "value": 2831,
 "currency": "eur"
 },
 "usd": {
 "value": 0,
 "currency": "usd"
 }
 },
 "inbound_pending": {
 "gbp": {
 "value": 0,
 "currency": "gbp"
 },
 "eur": {
 "value": 0,
 "currency": "eur"
 },
 "usd": {
 "value": 0,
 "currency": "usd"
 }
 },
 "outbound_pending": {
 "gbp": {
 "value": 0,
 "currency": "gbp"
 },
 "eur": {
 "value": 0,
 "currency": "eur"
 },
 "usd": {
 "value": 0,
 "currency": "usd"
 }
 }
 },
 "country": "US",
 "created": "2025-11-17T16:20:14.943Z",
 "display_name": null,
 "metadata": null,
 "other": null,
 "status": "open",
 "status_details": null,
 "storage": {
 "holds_currencies": ["gbp", "eur", "usd"]
 },
 "type": "storage",
 "livemode": false
}

Create a cross-border outbound payment

Follow the instructions in the Cross-border payouts use case to:

Create a recipient-configured connected account for the supplier under the wholesaler’s account.
Onboard the supplier.
Add a payout method for the supplier.
Create an outbound payment quote.
Create the cross-border outbound payment to the supplier.

Stripe charges the platform’s financial account for all FX fees, and the platform can create an OutboundPayment from the wholesaler to its own financial account to recover the fee.