Payment with FX

Enable customers to pay in their local currency.

Rapyd enables your customers to purchase products with a different currency than the currency supported by the customer's chosen payment method. The foreign exchange (FX) process is transparent to the customer.

A client based in Europe sells merchandise on their website in euros (EUR). The customer is based in the United States, and the customer wants to pay with a card that supports only United States dollars (USD). Rapyd makes the transaction seamless for both the merchant and the customer.

A one-time unregistered customer purchases an item on your website. The customer needs to pay 30 EUR for the item with a card that supports only USD.

🚧

PCI Certification

Only clients with PCI certification can handle personal identifying information for cards.

Card Payment with FX Workflow

Finding the specific card transfer payment methods you'll accept and corresponding required fields that customers fill out is described under How it Works.

Step 1 - Customer Purchase

  1. A customer with a card in USD adds an item on your website that costs 370 EUR to the shopping cart. The customer presses the checkout button and arrives on the payment page. The customer selects the option to pay with a card.
  2. You ask the Rapyd for the card details required fields and present to customer.
  3. The customer fills in the card details and confirms the payment by pressing Pay.

Step 2 - Processing Payment

  • Note: Check whether the payment method type currency is different from the web site currency.
  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 it Works

Processing the Payment with FX

On your payment page, you let the customer choose a payment method. First, you need to decide which payment methods you will accept.

For that, you'll use List Payment Methods by Country with the following 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 URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=US&currency=USD

// Message body absent
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);
            }
        }
    }
}
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
$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";
}
?>
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

Let's take a look at the response. Payment Method Type Object describes the fields in the response.

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

          // ...
          
        {
            "type": "us_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 us_mastercard_card 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.

For that, you will use the Get Payment Method Required Fields with the following parameter:

Path Parameter

Description

type

Enter us_mastercard_card as the payment method type.

Get Payment Method Required Fields request

You ask for the set of required fields:

// Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/required_fields/us_mastercard_card

// Message body absent
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/required_fields/{type}");

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}
const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

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

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}
<?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

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

from utilities import make_request

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

Get Payment Method Required Fields response

Let's take a look at the response. Payment Method Type Object describes the fields in the response.

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "25bdf361-e575-4baf-a180-6cd4602201e8"
    },
    "data": {
        "type": "us_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_mastercard_card are:

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

Asking Rapyd to Process the Customer's Payment

📘

Note: Get Daily Rate Call

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

For that, you'll use Create Payment with the following 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_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 payment and to collect the payment for you right away.

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

// Message 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"
}
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);
            }
        }
    }
}
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);
  }
}
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

Let's take a look at the response. Payment Object describes the fields in the 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_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 amount of USD that is required for the payment of 370 EUR.
  • The merchant_requested_amount is 370.00, which is the amount of EUR that is paid out.
  • The fx_rate is the exchange rate of 1.151688.
  • The paid_at field indicates the time of completion of the payment operation, in Unix time.

📘

Looking for more in-depth technical information?

Want to see the Rapyd API methods and objects that you'll use?
Visit the Rapyd API Reference Documentation for more technical details.


Updated 4 months ago


Payment with FX


Enable customers to pay in their local currency.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.