Tools/
Foreign Exchange as a Service/
Integration

Get StartedAnchorIcon

Braintree Foreign Exchange as a Service (FXaaS) is available to eligible merchants in the UK and EU. To get started, contact your Braintree Account Manager, who will guide you through eligibility, contracting, and account setup. Once your account is activated and your FXaaS contract is signed, your Account Manager will provide the credentials and integration details needed to proceed.

To integrate BT FXaaS:

  1. Obtain an exchange rate quote
  2. Create a transaction using the quote, and submit it for settlement
  3. Handle market-moving events

PrerequisiteAnchorIcon

  • Ensure your FXaaS contract is signed and your merchant account is activated by your Braintree account Manager.
  • Review your contract for key parameters: rate expiration interval, rate refresh time, FX fees, and other relevant terms.

Server-Side ImplementationAnchorIcon

Creating a transactionAnchorIcon

When creating a transaction, pass the exchangeRateQuoteId obtained from the SDK's Exchange Rate Quote API. The Exchange Rate Quote API is a GraphQL API; the server-side implementation converts a client-passed request into the API call, retrieves the quote's id from the response, and passes that id into the transaction sale.

Request an exchange rate quote:
  1. Ruby
result = gateway.exchange_rate_quote.generate(
  quotes: [
    { baseCurrency: "USD", quoteCurrency: "EUR", baseAmount: "12.19", markup: "12.14" }
  ]
)
quote_id = result[:quotes][0][:id]
Create the transaction using the returned quote id:
  1. Ruby
result = gateway.transaction.sale(
  amount: "12.19",
  payment_method_nonce: nonce_from_the_client,
  exchange_rate_quote_id: quote_id,
  device_data: device_data_from_the_client,
  options: { submit_for_settlement: true }
)
Note: An exchange rate quote is not tied to a single transaction. Request a quote once, then pass the same exchange_rate_quote_id to as many transactions as you need until the quote is due for a refresh. You don’t need to request a new quote for every checkout.

Handle market-moving events (Force majeure)AnchorIcon

Market-moving events, such as natural disasters or political unrest, can lead to high volatility in currency markets, and the FXaaS exchange rate lock guarantee may be suspended. In response to these events, exchange rates may be refreshed outside of the normal daily schedule.

If a market-moving event occurs after you’ve obtained a quote but before your transaction settles, the transaction will be processed at the current market rate at settlement rather than your originally quoted rate. You’ll be notified if any of your transactions are affected.

Buyers are not impacted. They will pay the amount you quoted. Any difference between the quoted rate and the settlement rate affects only your settlement amount, not what your buyer is charged.

To minimize your exposure to market-moving events, we recommend requesting a new exchange rate quote at least every 2 hours rather than relying on a single quote for its full validity window.

Test your integrationAnchorIcon

You can use the Braintree sandbox to test your integration with the Exchange Rate Quote API and to create test transactions that pass an exchange_rate_quote_id.

What to expect in the sandbox

  • The sandbox doesn't support end-to-end money movement, so currency conversion and payout to your merchant account are not simulated.
  • Test transactions don't progress beyond the sandbox, so you won't see status changes or updates to the transaction response as a result of FX processing.

  • In the sandbox: Confirm that you can request quotes and pass the returned quote ID into transaction.sale.
  • In production: Validate end-to-end behavior, including conversion and payout, with your Account Manager as part of go-live.