Rapyd Docs and API Reference

Payment With FX

Enable customers to pay in their local currency.

Suggest Edits

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

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

1536
  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

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 with the following parameters:
Path ParameterDescription
countryEnter US as the country abbreviation.
currencyEnter 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

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

Path ParameterDescription
typeEnter us_debit_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_debit_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

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

You will use Create Payment with the following parameters:

Body ParameterDescription
amountEnter 370 as the amount of EUR to be paid out.
currencyEnter EUR as the currency that the seller will receive.
expirationEnter the expiration of the transaction, in Unix time.
requested_currencyEnter USD as the currency supported by the payment method.
payment_methodEnter 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 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"
}

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

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

Updated 6 months ago

What's Next

Split Payment by Amount

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.