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. PHP
$variables = [
    "quotes" => [
        "baseCurrency" => "USD",
        "quoteCurrency" => "EUR",
        "baseAmount" => "12.19",
        "markup" => "12.14",
    ],
];
$request = ExchangeRateQuoteRequest::factory($variables);
$response = $gateway->exchangeRateQuote()->generate($request);
$quoteId = $response->quotes[0]->id;
Create the transaction using the returned quote id:
  1. PHP
$result = $gateway->transaction()->sale([
    'amount' => '12.19',
    'paymentMethodNonce' => $nonceFromTheClient,
    'deviceData' => $deviceDataFromTheClient,
    'exchangeRateQuoteId' => $quoteId,
    'options' => ['submitForSettlement' => 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 eventsAnchorIcon

Exchange rates refresh daily. On occasion, significant movement in the FX market may cause a rate to be refreshed outside of the normal daily schedule. This is known as a market-moving event.

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

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. This keeps the rate you're quoting to your buyers closer to the current market rate at all times.

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.

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