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.

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

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).
You ask Rapyd for the required fields of the payment method and present them to the customer.
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.

Your website back end asks Rapyd to process the payment with FX in the receiver's currency (EUR).
Rapyd processes the payment and sends a response to the website back end.
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:

Decide which payment methods you will accept.
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.

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

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.

In this section:

Documentation

Payment With FX

PCI Certification

Payment With FX Workflow

Step 1: Customer Purchase

Step 2: Processing Payment

Note

How Payment With FX Works

Processing the Payment With FX

List Payment Methods by Country Request

List Payment Methods by Country Response

Finding the Required Fields for the Payment Method

Get Payment Method Required Fields Request

Get Payment Method Required Fields Response

Asking Rapyd to Process the Customer's Payment

Get FX Rate Call

Create Payment Request

Payment With Foreign Exchange Response

Search results