> ## Documentation Index
> Fetch the complete documentation index at: https://developer.runa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Paying for an order using another currency

> Use Runa Embedded FX to pay for an order using your funds in another currency

<Note>
  By default, this feature applies standard FX fees in production. If you
  haven't negotiated custom rates, those standard fees will apply. To learn more
  or discuss custom pricing, [talk to an
  expert](https://runa.io/products/runa-fx) or contact your account manager
</Note>

## What is Runa FX?

Runa FX allows you to top up your balance in your preferred currency and seamlessly pay for orders across different countries.

Runa Embedded FX handles currency exchanges in real-time at the point of payment, offering a smooth, cost-effective, and efficient solution for hassle-free international spending.

## Placing an Embedded FX order

Placing an Embedded FX order follows the same request schema as the existing method for placing orders via the `/v2/order` endpoint. You can refer to the [ordering guides](/getting-started/first-order/sync) or [create order reference](/reference/2024-02-05/endpoint/orders/create) for detailed instructions.

To use embedded FX you should specify the desired billing currency in the `payment_method` object.

### Requirements

1. You must have sufficient funds in your `payment_method` balance to cover the entire order amount. For example, if purchasing a \$10 payout link using your GBP account balance, you must have at least \$10 worth of GBP available.
2. All order items must still be from the same country, ensuring they are in the same currency.
3. This feature currently supports **only** single item orders.
4. This feature currently supports **only** synchronous orders.

### Example

Here's an example of a basic request and response for an order with embedded FX.

* The `payment_method.currency` has been set to `GBP`.
* The products specified in the `items.products` array are US products priced in USD.

<CodeGroup>
  ```json Request {4} theme={null}
  {
    "payment_method": {
      "type": "ACCOUNT_BALANCE",
      "currency": "GBP"
    },
    "items": [
      {
        "face_value": 10,
        "distribution_method": {
          "type": "EMAIL",
          "email_address": "fred@bloggs.com"
        },
        "products": {
          "type": "MULTIPLE",
          "values": ["AMZ-US", "AMC-US"]
        }
      }
    ]
  }
  ```

  ```json Response {37-49} theme={null}
  {
    "id": "O-01234567890ABCDEFGHIJK",
    "status": "COMPLETED",
    "created_at": "2023-11-14T14:37:54.093824+00:00",
    "completed_at": "2023-11-14T15:25:07.728788+00:00",
    "description": "My first order.",
    "payment_method": {
      "type": "ACCOUNT_BALANCE",
      "currency": "GBP"
    },
    "currency": "GBP",
    "total_discount": "0.00",
    "total_price": "8.49",
    "items": [
      {
        "id": "E-0123456789ABCDEFG",
        "distribution_method": {
          "type": "EMAIL",
          "email_address": "fred@bloggs.com"
        },
        "products": {
          "type": "MULTIPLE",
          "values": ["AMZ-US", "AMC-US"]
        },
        "currency": "USD",
        "face_value": "10.00",
        "price": "10.00",
        "redemption_url": "https://payout.runa.io/ej99mjdmf958324d2f38",
        "payout": {
          "status": "ACTIVE",
          "status_updated_at": "2023-11-23T08:29:15.940064+00:00",
          "url": "https://example-test.spend.runa.io/055306f2-466b-4fc4-8b59-9538eaf1be92",
          "expiry_date": null
        }
      }
    ],
    "transaction_detail": {
      "USD": {
        "value": "10.00",
        "fx": {
          "rate": "1.2",
          "rate_symbol": "GBPUSD",
          "fee": {
            "value": "0.16",
            "currency": "GBP"
          }
        }
      }
    }
  }
  ```
</CodeGroup>

In the above example, a \$10 USD payout link has been purchased using a `GBP` balance.

To help you understand the costs involved in making this embedded FX order, we provide a `transaction_detail` object that breaks down each component:

1. You purchased \$10.00 USD, as shown in the `transaction_detail` value.
2. An exchange rate (`fx.rate`) of 1.2 was applied for converting GBP to USD. (See below for more details on how our rates work.)
3. A `fee` of £0.16 GBP was charged for the currency conversion. This fee is included in the `total_price` of the order and is always charged in the currency specified for the `payment_method`.

## Getting the price estimate for an Embedded FX order

You can get an estimate of how much an Embedded FX order will cost by using the `/v2/order/estimate` endpoint. Detailed guidance on how to use it can be found in the [order estimate reference](/reference/2024-02-05/endpoint/orders/estimate).

### Example

Here's an example of a basic request and response for getting the estimate of an order with embedded FX.

<CodeGroup>
  ```json Request {4} theme={null}
  {
    "payment_method": {
      "type": "ACCOUNT_BALANCE",
      "currency": "GBP"
    },
    "items": [
      {
        "face_value": 10,
        "distribution_method": {
          "type": "EMAIL",
          "email_address": "fred@bloggs.com"
        },
        "products": {
          "type": "MULTIPLE",
          "values": ["AMZ-US", "AMC-US"]
        }
      }
    ]
  }
  ```

  ```json Response {21-33} theme={null}
  {
    "payment_method": {
      "type": "ACCOUNT_BALANCE",
      "currency": "GBP"
    },
    "currency": "GBP",
    "total_discount": "0.00",
    "total_price": "8.49",
    "items": [
      {
        "products": {
          "type": "MULTIPLE",
          "values": ["AMZ-US", "AMC-US"]
        },
        "currency": "USD",
        "face_value": "10.00",
        "price": "10.00",
        "discount_multiplier": "0.05"
      }
    ],
    "transaction_detail": {
      "USD": {
        "value": "10.00",
        "fx": {
          "rate": "1.2",
          "rate_symbol": "GBPUSD",
          "fee": {
            "value": "0.16",
            "currency": "GBP"
          }
        }
      }
    }
  }
  ```
</CodeGroup>

## Rates and Fees

### FX Rates

The fx\_rate provided by our API reflects the exchange rate applied for the Embedded FX conversion at the time of placing the order.

You can use the `fx.rate_symbol` to determine the equivalent amount in the other currency within the currency pair.

<Card>
  For example, if the `fx.rate` is 1.2 and the `fx.rate_symbol` is `GBPUSD`:

  * When converting GBP to USD: If your `payment_method` currency is GBP and you're purchasing an item priced at \$10 USD, the calculation is: `$10 ÷ 1.2 = £8.33`
  * When converting USD to GBP: If your `payment_method` currency is USD and you're purchasing an item priced at £10 GBP, the calculation is: `£10 × 1.2 = $12`
</Card>

### FX Fees

The fee is always calculated and included in the billing currency, so that you can operate in one currency.

The fee amount depends on the transaction value, the currency of the order, and the fee rate agreed with us. If you're already using our FX platform with custom fees, those same rates will apply.

If you haven't set up custom fees, **a standard fee rate of 1.9%** will be applied to the conversion. For more information on custom FX fee rates, please contact your Account Manager.

## Currencies

Embedded FX support varies by currency. Check the [currencies page](/reference/currencies) for detail on what is supported today. We are actively working to expand support for more combinations.

<Card title="Currencies" icon="coins" href="/reference/currencies" horizonal={true} arrow={true}>
  View the list of currencies supported by the Runa API.
</Card>