---
title: "Payment With FX"
source_url: https://docs.rapyd.net/en/payment-with-fx.html
lang: en
---

# Payment With FX

Enable customers to pay in their local currency.

The Payment with FX feature allows your customers to make transactions in the currency of their choice — even if that currency is different from what is supported by their payment method. The FX process is transparent to the customer.

You can accept a payment with [FX](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_fx "Foreign exchange") from thousands of payment methods (card, bank transfer, [eWallet](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_ewallet "eWallet"), with different currencies).

Common use cases may include:

- You are selling merchandise on your online store, and accept [various payment methods](https://docs.rapyd.net/en/integrate-payment-methods.md "Integrate Payment Methods") from international customers who use a different local currency.
- You are an independent contractor who accepts payments from international clients.

Your business based in Europe sells merchandise on your online store. A customer from the United States wants to purchase a product from you that costs 370 EUR (Euros). But the customer uses a payment method that only supports USD (U.S. Dollars).

Rapyd makes the transition seamless for both the merchant and the customer through the Payment with FX feature.

> **Note:**
>
> Only clients with [PCI-DSS](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_dss "Payment Card Industry Data Security Standard") certification can handle personal identifying information for cards. This method is available to merchants who have signed a special agreement with Rapyd.

### Payment With FX Workflow

You can accept a payment with FX from thousands of payment methods (card, bank transfer, eWallet, with different currencies).

How it Works describes how to find the specific payment methods you'll accept and their required fields.

### Step 1: Customer Purchase

![fx-pmt.jpg](image/img-ce03f4c39e37202bb7bb2da20c57f8bc.jpg)

1. A customer adds an item on your website that costs 370 EUR (Euros) to the shopping cart. The customer wants to pay in USD (U.S. Dollars). The customer presses the checkout button and arrives on the payment page. The customer selects the payment method of their choice (card, bank transfer, eWallet, with different currencies).
2. You ask Rapyd for the required fields of the payment method and present them to the customer.
3. The customer fills in the required details and confirms the payment by pressing **Pay**.

### Step 2: Processing Payment

> **Note:**
>
> Check whether the payment method type currency is different from the website currency.

![process-fx-pmt.jpg](image/img-f4e887803fdc8ed802acfb2d92ba2c91.jpg)

1. Your website back end asks Rapyd to process the payment with FX in the receiver's currency (EUR).
2. Rapyd processes the payment and sends a response to the website back end.
3. Your website displays a page that tells your customer that the purchase succeeded.

### How Payment With FX Works

Find out how to choose the payment methods you'll accept and find their required fields. The customer must fill out these fields for the payment method.

### Processing the Payment With FX

On your payment page, you let the customer choose a payment method. In order to process the payment with FX you need to:

1. Decide which payment methods you will accept.
2. For the accepted payment methods, use [List Payment Methods by Country](https://docs.rapyd.net/en/list-payment-methods-by-country.md "List Payment Methods by Country") with the following parameters:

Description of Path Parameters

| Path Parameter | Description |
| --- | --- |
| country | Enter **US** as the country abbreviation. |
| currency | Enter **USD** as the currency code. |

### List Payment Methods by Country Request

You ask for the list of all available US payment methods that support USD.

- - Request

    - ```
      // Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=US&currency=USD

      // Message body absent
      ```
- - .NET Core

    - ```
      using System;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {
                      string country = "US";
                      string currency = "USD";

                      string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payment_methods/country?country={country}&currency={currency}");

                      Console.WriteLine(result);
                  }
                  catch (Exception e)
                  {
                      Console.WriteLine("Error completing request: " + e.Message);
                  }
              }
          }
      }
      ```
- - JavaScript

    - ```
      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

      async function main() {
        try {
          const result = await makeRequest('GET', '/v1/payment_methods/country?country=US&currency=USD');

          console.log(result);
        } catch (error) {
          console.error('Error completing request', error);
        }
      }
      ```
- - PHP

    - ```
      <?php
      $path = $_SERVER['DOCUMENT_ROOT'];
      $path .= "/<path-to-your-utility-file>/utilities.php";
      include($path);

      try {
          $object = make_request('get', '/v1/payment_methods/country?country=US&currency=USD');
          var_dump($object);
      } catch (Exception $e) {
          echo "Error: $e";
      }
      ?>
      ```
- - Python

    - ```
      from pprint import pprint

      from utilities import make_request

      country = 'US'
      currency = 'USD'
      results = make_request(method='get',
                             path=f'/v1/payment_methods/country?country={country}&currency={currency}')
      pprint(results)
      ```

### List Payment Methods by Country Response

- - Response

    - ```
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "2ae2817f-a9ff-464c-a5e9-e6dfb04d4ea3"
          },
          "data": [

                // ...
                
              {
                  "type": "us_debit_mastercard_card",
                  "name": "Mastercard",
                  "category": "card",
                  "image": "https://iconslib.rapyd.net/checkout/us_mastercard_card.png",
                  "country": "US",
                  "payment_flow_type": "card",
                  "currencies": [
                      "USD"
                  ],
                  "status": 1,
                  "is_cancelable": false,
                  "payment_options": [
                      {
                          "name": "customer",
                          "type": "customer",
                          "regex": "",
                          "description": "make sure a customer was created with first_name, last_name and email",
                          "is_required": true,
                          "is_updatable": false
                      }
                  ],
                  "is_expirable": false,
                  "is_online": false,
                  "minimum_expiration_seconds": null,
                  "maximum_expiration_seconds": null
              },

                // ...        
          ]
      }
      ```

The `data` section of this response shows that Mastercard is an acceptable payment method.

### Finding the Required Fields for the Payment Method

You need to find which fields the customer must fill in for the payment method.

You will use the [Get Payment Method Required Fields](https://docs.rapyd.net/en/get-payment-method-required-fields.md "Get Payment Method Required Fields") with the following parameter:

Description of Path Parameters

| Path Parameter | Description |
| --- | --- |
| type | Enter  **us_debit_mastercard_card** as the payment method type. |

### Get Payment Method Required Fields Request

You ask for the set of required fields:

- - Request

    - ```
      // Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/us_debit_mastercard_card/required_fields

      // Message body absent
      ```
- - .NET Core

    - ```
      using System;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {
                      string type = "us_mastercard_card";

                      string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payment_methods/{type}/required_fields");

                      Console.WriteLine(result);
                  }
                  catch (Exception e)
                  {
                      Console.WriteLine("Error completing request: " + e.Message);
                  }
              }
          }
      }
      ```
- - JavaScript

    - ```
      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

      async function main() {
        try {
          const result = await makeRequest('GET', '/v1/payment_methods/us_mastercard_card/required_fields');

          console.log(result);
        } catch (error) {
          console.error('Error completing request', error);
        }
      }
      ```
- - PHP

    - ```
      <?php
      $path = $_SERVER['DOCUMENT_ROOT'];
      $path .= "/<path-to-your-utility-file>/utilities.php";
      include($path);

      try {
          $object = make_request('get', '/v1/payment_methods/us_mastercard_card/required_fields');
          var_dump($object);
      } catch (Exception $e) {
          echo "Error: $e";
      }
      ?>
      ```
- - Python

    - ```
      from pprint import pprint

      from utilities import make_request

      payment_method = 'us_mastercard_card'
      results = make_request(method='get',
                             path=f'/v1/payment_methods/{payment_method}/required_fields')
      pprint(results)
      ```

### Get Payment Method Required Fields Response

- - Response

    - ```
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "25bdf361-e575-4baf-a180-6cd4602201e8"
          },
          "data": {
              "type": "us_debit_mastercard_card",
              "fields": [
                  {
                      "name": "number",
                      "type": "string",
                      "regex": "",
                      "is_required": true,
                      "instructions": "card number"
                  },
                  {
                      "name": "expiration_month",
                      "type": "string",
                      "regex": "",
                      "is_required": true,
                      "instructions": "expiration month as string, 01-12"
                  },
                  {
                      "name": "expiration_year",
                      "type": "string",
                      "regex": "",
                      "is_required": true,
                      "instructions": "expiration year in to digits as string, 18-99"
                  },
                  {
                      "name": "cvv",
                      "type": "string",
                      "regex": "",
                      "is_required": true,
                      "instructions": "card cvv"
                  },
                  {
                      "name": "name",
                      "type": "string",
                      "regex": "",
                      "is_required": false,
                      "instructions": "card holder name"
                  },
                  {
                      "name": "address",
                      "type": "Address",
                      "regex": "",
                      "is_required": false,
                      "instructions": "card billing address. see Address object for more details"
                  }
              ],
                
       // ...
                
              "minimum_expiration_seconds": null,
              "maximum_expiration_seconds": null
          }
      }
      ```

The response shows that the required fields for **us_debit_mastercard_card** are:

- `number` - The credit card number.
- `expiration_month` - The expiration month of the credit card.
- `expiration_year` - The expiration year of the credit card.
- `cvv` - The card verification number.

**Note**: The response shows that the `name` and `address` fields are NOT required.

### Asking Rapyd to Process the Customer's Payment

> **Note:**
>
> You can check the current currency exchange rate with [Get FX Rate](https://docs.rapyd.net/en/get-fx-rate.md "Get FX Rate").

When the customer checks out on your website, you ask Rapyd to process the customer's card payment and to convert the currency from USD to EUR.

You will use [Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment") with the following parameters:

Description of Body Parameters

| Body Parameter | Description |
| --- | --- |
| amount | Enter **370** as the amount of EUR to be paid out. |
| currency | Enter **EUR** as the currency that the seller will receive. |
| expiration | Enter the expiration of the transaction, in Unix time. |
| requested_currency | Enter **USD** as the currency supported by the payment method. |
| payment_method | Enter an object with the following fields:  - `type` - **us_debit_mastercard** - **card** `fields` - (object)  - `number` - **4111111111111111** as the card number   - .`expiration_month` - **10**   - `expiration_year` - **20**   - `cvv` - **123** |

### Create Payment Request

You ask Rapyd to process the customer's 370 EUR (Euros) payment and to collect the payment for you right away.

- - Request

    - ```
      // Request URL: POST https://sandboxapi.rapyd.net/v1/payments

      // Message body:
      {
         "amount": 370,
         "currency": "EUR",
         "expiration": 1591173527,
         "fixed_side": "buy",
         "payment_method": {
             "type": "us_debit_mastercard_card",
             "fields": {
                 "number": "4111111111111111",
                 "expiration_month": "10",
                 "expiration_year": "20",
                 "cvv": "123"
             }
         },
         "requested_currency": "USD"
      }
      ```
- - .NET Core

    - ```
      using System;
      using System.Text.Json;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {
                      var requestObj = new
                      {
                          amount = 370,
                          currency = "EUR",
                          expiration = 1591173527,
                          fixed_side = "buy",
                          payment_method = new
                          {
                              type = "us_mastercard_card",
                              fields = new
                              {
                                  number = "4111111111111111",
                                  expiration_month = "10",
                                  expiration_year = "20",
                                  cvv = "123",
                              }
                          },
                          requested_currency = "USD"
                      };

                      string request = JsonSerializer.Serialize(requestObj);

                      string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payments", request);

                      Console.WriteLine(result);
                  }
                  catch (Exception e)
                  {
                      Console.WriteLine("Error completing request: " + e.Message);
                  }
              }
          }
      }
      ```
- - JavaScript

    - ```
      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

      async function main() {
        try {
          const body = {
            amount: 370,
            currency: 'EUR',
            requested_currency: 'USD',
            fixed_side: 'buy',
            payment_method: {
              type: 'us_visa_card',
              fields: {
                number: '4111111111111111',
                expiration_month: '10',
                expiration_year: '20',
                cvv: '123'
              }
            },
            expiration: 1601173527
          };
          const result = await makeRequest('POST', '/v1/payments', body);

          console.log(result);
        } catch (error) {
          console.error('Error completing request', error);
        }
      }
      ```
- - Python

    - ```
      from pprint import pprint

      from utilities import make_request

      payment_body = {
          "amount": 370,
          "currency": "EUR",
          "expiration": 1591173527,
          "fixed_side": "buy",
          "payment_method": {
              "type": "us_mastercard_card",
              "fields": {
                  "number": "4111111111111111",
                  "expiration_month": "10",
                  "expiration_year": "20",
                  "cvv": "123"
              }
          },
          "requested_currency": "USD"
      }

      create_payment_response = make_request(method='post',
                                             path='/v1/payments',
                                             body=payment_body)
      pprint(create_payment_response)
      ```

### Payment With Foreign Exchange Response

- - Response

    - ```
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "4b257ecb-2775-4a3d-a829-978ead4d6dff"
          },
          "data": {
              "id": "payment_02e2ce0763a6473ef7788109ae5d0479",
              "amount": 426.13,
              "original_amount": 426.13,
              "is_partial": false,
              "currency_code": "USD",
              "country_code": "US",
              "status": "CLO",
                
       // ...
                
              "paid": true,
              "paid_at": 1583308522,
                
       // ...
                
              "payment_method_type": "us_debit_mastercard_card",
              "payment_method_type_category": "card",
              "fx_rate": "1.151688",
              "merchant_requested_currency": "EUR",
              "merchant_requested_amount": 370,
              "fixed_side": "buy",
              "payment_fees": null,
              "invoice": "",
              "escrow": null,
              "group_payment": ""
          }
      }
      ```

The `data` section of this response shows:

- The `amount` is  **426.13**, which is the equivalent amount of  **USD** required for the **370 EUR** payment.
- The `merchant_requested_amount` is **370.00**, which is the amount of **EUR** that is paid out.
- The `fx_rate` is the **EUR** to **USD** exchange rate of 1.151688.
- The `paid_at` field indicates the time of completion of the payment operation, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time").