Dynamic Currency Conversion ("DCC") and Dynamic Pricing ("DP") Merchant Rate and Card Rate API – Payeezy Knowledge Base

This article outlines the API requirements for processing Dynamic Currency Conversion (“DCC”) and Dynamic Pricing (“DP”) requests via the gateway. Please see “Dynamic Currency Conversion (DCC) and Dynamic Pricing (DP) Feature Guide" for additional information relative to these features.

First Data’s Dynamic Currency Conversion (“DCC”) service, also known as GlobalChoice, is a payment solution that allows international customers to pay in their credit card currency, providing convenience and a sense a confidence. The DCC service allows merchants to authorize and settle transactions in major global currencies while still being funded in US dollars (or their base currency). Both merchants and their customers will know precisely the amount of the sale in the cardholders’ currency, which means no more waiting or guessing at conversion rates or fees.

First Data’s Dynamic Pricing (“DP”) provides merchants with the ability to offer their international cardholders the choice to view and pay for goods and services in their own currency. The customer sees all pricing in their home currency as opposed to US dollars (or the client’s base currency). Upon checkout they will pay in their home currency and the transactions will be submitted to the associations in the selected currency.

NOTE: This article should be used with the First Data Payeezy Gateway Web Services API Reference Guide and Hosted Payment Pages Integration Pages Manual.

It should be noted that Dynamic Pricing utilizes the same process for authorizations and settlement as is used for DCC transactions

As stated above, these requests are made available for two purposes, to obtain:

The response for a card rate request which contains the field rate_response_id which is to be used in DCC Transaction API requests.
The response for a merchant rate request contains the field rate_response_id which is to be used in HCO for DP payments.

Two formats are supported: JSON and XML.

A card rate request specifies a BIN number and an optional amount. (BIN - Bank Identification Number, first 6 digits of the card number)

A merchant rate request specifies a foreign currency code, and an optional amount.

The Gateway Webservice API Reference Guide has been expanded with two paths:

POST /exchange_rates/v1/card_rate
POST /exchange_rates/v1/merchant_rate

Both are authenticated with Gateway ID and Gateway Password as HTTP Basic Authentication. No HMAC calculations are required.

Merchant Rate Requests

The URL's are:

* Production system: https://api.globalgatewaye4.firstdata.com/exchange_rates/v1/merchant_rate

* Demo system: https://api.demo.globalgatewaye4.firstdata.com/exchange_rates/v1/merchant_rate

All requests are to be sent as HTTP POST requests.

Responses are encoded in UTF-8.

Sample JSON requests:

Without amount:

{"merchant_rate": {"foreign_currency_code": "124"} }

With amount:

{"merchant_rate": {"foreign_currency_code": "124", "amount": "12.34"} }

Sample XML requests:

Without amount:

<?xml version="1.0" encoding="UTF-8"?>

</MerchantRate>

With amount:

<?xml version="1.0" encoding="UTF-8"?>

</MerchantRate>

Merchant Rate Responses

Sample JSON response where “DP” is not available:

HTTP Status is 201.

The body of the response has:

{

"merchant_rate": {

"dcc_offered": false

}

Sample JSON response where DP is available, including amount (the amount fields are base_amount and foreign_amount):

HTTP Status is 200. The body of the response has:

{

"merchant_rate": {

"dcc_offered": true,

"details": {

"rate_response_id": "825-98c34d0dfc0dbcfb3eb0ded8feca20cf879a8c3cdb048bd6a626d57b3a84531b",

"margin_rate_percentage": "3.0",

"exchange_rate": "1.197264",

"base_amount": "133",

"foreign_amount": "159.24",

"foreign_currency_alphabetic_code": "CAD",

"foreign_currency_code": "124",

"foreign_currency_minor_unit": 2,

"foreign_currency_symbol_html": "$",

"terminal_currency_alphabetic_code": "USD",

"terminal_currency_code": "840",

"terminal_currency_minor_unit": 2,

"terminal_currency_symbol_html": "$",

"created_at": "2015-02-20T22:24:53Z",

"valid_until": "2015-02-21T10:24:53Z"

}

Sample XML response where “DP” is not available:

HTTP Status is 201. The body of the response has:

<?xml version="1.0" encoding="UTF-8"?>

<DccOffered>false</DccOffered>

</MerchantRate>

Sample XML response where DP is available, including amount. The amount fields are BaseAmount and ForeignAmount, these are the only two fields that are added when the optional amount is included in the request.

HTTP Status is 200. The body of the response has:

<?xml version="1.0" encoding="UTF-8"?>

</Details>

</MerchantRate>

The response, when a rate is available, has these fields (values shown are examples only, when amount was given):

Field Name	Sample Value
dcc_offered	true
rate_response_id	14-19b71932a3c5323fa336d0c50e50f30de8f79fdb1858e661e833dd29965f695d
margin_rate_percentage	3.0
exchange_rate	12.34
base_amount	123.45
foreign_currency_alphabetic_code	JPY
foreign_currency_code	392
foreign_currency_minor_unit	0
foreign_currency_symbol_html	¥
terminal_currency_alphabetic_code	CAD
terminal_currency_code	124
terminal_currency_minor_unit	2
terminal_currency_symbol_html	$
created_at	2015-02-02T23:13:27Z
valid_until	2015-02-03T11:13:27Z

Sample error responses for merchant rate requests

When the authentication headers are missing or invalid, the response will have a status of 401, and the body will be as shown below:

Unauthorized Request. Bad or missing credentials.

When a HTTP method other than POST is used, the response will have a status of 301, and redirect with the body as shown below:

<html><body>You are being <a href="https://support.payeezy.com/forums/328586>redirected</a>.</body></html>

When the request authenticated successfully, the response will be

JSON for JSON requests, and
XML for XML requests.

For example if the terminal does not have DP enabled, the response will have a status of 400, and the XML error message will be as follows:

<?xml version="1.0" encoding="UTF-8"?>

<ErrorMessage>Terminal does not have DP enabled</ErrorMessage>

</Errors>

When the request has authenticated successfully, but the request data is invalid in other ways, the response will have a status of 400, and a JSON error message will be returned similar to the following:

{"errors":["Foreign currency code is too long (maximum is 3 characters)"]}

{"errors":["Amount is not a number"]}

{"errors":["Foreign currency code is too long (maximum is 3 characters)","Amount is not a number"]}

Card Rate Requests

A card rate request specifies a card BIN, and an optional amount.

The URL's are:

* Production system:

https://api.globalgatewaye4.firstdata.com/exchange_rates/v1/card_rate

* Demo system:

https://api.demo.globalgatewaye4.firstdata.com/exchange_rates/v1/card_rate

All requests are to be sent as HTTP POST requests.

Responses are encoded in UTF-8.

Sample JSON requests:

Without amount:

{"card_rate": {"bin": "123456"} }

With amount:

{"card_rate": {"bin": "123456", "amount": "12.34"} }

Sample XML requests:

Without amount:

<?xml version="1.0" encoding="UTF-8"?>

</CardRate>

With amount:

<?xml version="1.0" encoding="UTF-8"?>

</CardRate>

Card Rate Responses

Sample JSON response where DCC is not available:

Case 1, BIN does not qualify:

HTTP Status is 201. The body of the response has:

{

"card_rate": {

"bin_qualifies": false

}

Case 2, BIN qualifies, DCC is not offered:

HTTP Status is 201. The body of the response has:

{

"card_rate": {

"bin_qualifies": false,

"dcc_offered": false

}

Sample JSON response where DCC is available, including amount (the amount fields are base_amount and foreign_amount):

HTTP Status is 200. The body of the response has:

{

"card_rate": {

"bin_qualifies": true,

"dcc_offered": true,

"details": {

"rate_response_id": "825-99befde89250857f83d7e7af582f3ed037c8e9261da2150d3d355e5a4e0cd853",

"credit_card_type": 0,

"margin_rate_percentage": "3.0",

"exchange_rate": "118.323547",

"base_amount": 12.34,

"foreign_amount": "1460",

"foreign_currency_alphabetic_code": "JPY",

"foreign_currency_code": "392",

"foreign_currency_minor_unit": 0,

"foreign_currency_symbol_html": "¥",

"terminal_currency_alphabetic_code": "USD",

"terminal_currency_code": "840",

"terminal_currency_minor_unit": 2,

"terminal_currency_symbol_html": "$",

"created_at": "2015-02-20T22:05:17Z",

"valid_until": "2015-02-21T10:05:17Z"

}

Sample XML response where DCC is not available:

Case 1, BIN does not qualify:

HTTP Status is 201. The body of the response has:

<?xml version="1.0" encoding="UTF-8"?>

<BinQualifies>false</BinQualifies>

</CardRate>

Case 2, BIN does not qualify and DCC is not offered :

HTTP Status is 201. The body of the response has:

<?xml version="1.0" encoding="UTF-8"?>

<BinQualifies>true</BinQualifies>

<DccOffered>false</DccOffered>

</CardRate>

Sample XML response, DCC is available, including amount. The amount fields are BaseAmount and ForeignAmount, these are the only two fields that are added when the optional amount is included in the request.

HTTP Status is 200. The body of the response has:

<?xml version="1.0" encoding="UTF-8"?>

</Details>

</CardRate>

The response has these fields (Sample values are examples only, when amount is given)

Field Name	Sample Value
bin_qualifies	true
dcc_offered	true
rate_response_id	123-19b71932a3c5323fa336d0c50e50f30de8f79fdb1858e661e833dd29965f695d
credit_card_type	0
margin_rate_percentage	3.0
exchange_rate	12.34
base_amount	123.45
foreign_amount	1523.37
foreign_currency_alphabetic_code	MXN
foreign_currency_code	484
foreign_currency_minor_unit	2
foreign_currency_symbol_html	$
terminal_currency_alphabetic_code	CAD
terminal_currency_code	124
terminal_currency_minor_unit	2
terminal_currency_symbol_html	$
created_at	2015-02-02T23:16:59Z
valid_until	2015-02-03T11:16:59Z

Valid Credit Card Types (field credit_card_type):

MasterCard: 0

Visa: 1

Note that the foreign_amount is formatted with the minor currency units of the foreign currency (e.g. in JPY, only integers are used)

Sample error responses for card rate requests

When the authentication headers are missing or invalid, the response will have a status of 401, and the body as shown below:

Unauthorized Request. Bad or missing credentials.

When a HTTP method other than POST is used, the response will have a status of 301, and redirect with a body as shown below:

<html><body>You are being <a href="https://support.payeezy.com/forums/328586">redirected</a>.</body></html>

When the request authenticated successfully, but the terminal does not have DCC enabled, the response will have a status of 400, and an XML / JSON message as follows:

<?xml version="1.0" encoding="UTF-8"?>

<ErrorMessage>Terminal does not have DCC enabled</ErrorMessage>

</Errors>

When the request authenticated successfully, but the request data is invalid in other ways, the response will have a status of 400, and an XML / JSON message as follows:

Example 1. {"errors":["Bin needs to be 6 digits"]}

Example 2. {"errors":["Amount is not a number"]}