Skip to main content

Documentation

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 from thousands of payment methods (card, bank transfer, eWallet, with different currencies).

Common use cases may include:

  • You are selling merchandise on your online store, and accept various 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.

PCI Certification

Only clients with PCI-DSS certification can handle personal identifying information for cards. This method is available to merchants who have signed a special agreement with Rapyd.

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
  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
  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.

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.

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 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.

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

You will use the 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.

Get FX Rate Call

You can check the current currency exchange rate with 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 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.