Introduction
This article discusses the functionality of First Data's Dynamic Currency Conversion (“DCC”), Dynamic Pricing (“DP”), and Global ePricing features in the Gateway.
First Data’s Dynamic Currency Conversion service (also known as GlobalChoice) is a payment solution that allows international customers to pay in either their credit card currency or the base currency of the Merchant. The DCC service authorizes and settles transactions in major global currencies while still being funded in the Merchant's Base Currency. Both the customer and merchant will know precisely the amount of the sale in both currencies.
With Dynamic Pricing, a consumer is offered the choice of payment currencies upon entering the merchant’s website. After selecting the preferred currency, the merchant’s website will display pricing in the chosen currency (i.e. the cardholder’s issuing bank’s currency) only. When the cardholder arrives at the checkout page, the transaction will continue to be represented in the chosen currency, through to the receipt/confirmation page. The final transaction amount will be displayed as a single currency amount in the cardholder’s selected currency.
Global ePricing (GEP) requires one merchant processing account per each unique currency. Merchants using GEP with Payeezy Gateway will be able to process one currency type through each outlet. Multiple currencies types will require multiple outlets.
Gateway Support
- DCC is available through the RPM’s (Real Time Payment Manager’s) POS and Recurring Transaction Screens for Retail and MOTO (Mail Order/Telephone Order) Transactions, as well as via the Hosted Checkout and Web Services API.
- DP is only available through the Hosted Checkout Page and Web Services API.
Supported card types
- Visa
- Master Card
DCC feature description
For the RPM's VPOS (Virtual Terminal), Recurring transactions (MOTO and Retail), Hosted Checkout and Web Service API, the following functionality applies:
- The Client Base Currency is the default currency on the outlet.
- If the user’s credit card is eligible for DCC, the website displays a pop-up message offering the DCC choice to the cardholder.
- If the cardholder chooses to pay in the Client’s Base Currency, the system authorizes and settles the transaction in typical domestic fashion as is (without DCC).
- If the cardholder chooses to pay in their local currency (DCC opt in), the system authorizes the transaction as a DCC transaction in accordance with the First Data authorization specification.
- System produces a confirmation page / receipt.
Credits / Returns
If the original transaction was converted using DCC, then the credit or return must be conducted in the currency of the original sale using the prevailing rate of exchange of the date of the credit or return.
Referrals
First Data does not provide DCC authorizations via its voice authorization center; therefore a DCC transaction that has been referred must be manually authorized in the Client’s Base Currency.
DCC - Transaction Types supported
- Purchase
- Pre-Authorizations
- Pre-Auth Completion
- Partial Auth (Transaction API Only)
- Refund
- Tagged Void
- Tagged Purchase
- Tagged Refund
- Tagged Completion
Point of Sale (POS)
The Gateway provides the ability to offer DCC via the Virtual Terminal (VPOS). This would be considered a MOTO transaction, whereby the merchant offers DCC to the cardholder over the phone. The POS will display the DCC choice to the merchant, who in turn relays the DCC choice to the customer. The merchant is prompted with all of the required DCC elements in order to make the DCC offer in a compliant manner.
Currency selection pop up
These elements are:
- Cardholder’s billing currency
- Applicable exchange rate
- Amount in the cardholder’s currency
- International margin when making the DCC offer to the cardholder
The merchant must disclose all of the following to the cardholder:
- Amount of the transaction in the Client’s Base Currency
- Amount of the transaction in the cardholder’s billing currency
- The Exchange rate used
- International margin (typically 3%, note this is dynamic and checked on every DCC request processed by the Gateway; this rate is displayed on all screens and receipts
Once the cardholder has made their currency choice, the merchant will display a Confirmation page which confirms the payment details for the cardholder. This page shows The Total Amount in the Client’s base currency and the total amount in the cardholder’s currency.
Cardholder will select the desired currency button to proceed with order. Advancing from this page initiates the authorization process.
Selecting the Cancel option will return the cardholder to the currency choice display.
This screen isn't displayed if the cardholder selects to pay in the Clients Base Currency.
Note: This is the case when the “x_currency_code” property is sent by the merchant and it is different from the Terminal’s.
Receipt
The DCC transaction receipt will show the following:
- The Transaction amount of the goods or services in the merchant’s local Currency, also know as base currency (including the currency symbol or ISO acronym)
- The Exchange Rate used to communicate the markup applied to the DCC transaction, including any commission
- Any additional markup, commission or fee for the DCC service
- Total price in the transaction currency
- Disclosure (see example receipts below)
Example of a receipt for Visa
Example of a receipt for Master Card
Recurring Billing
For merchants that support recurring billing, This option can be enabled when the transaction is created, establishing a user profile in advance that indicates if a cardholder transaction should be converted for DCC on every recurring transaction.
This setting is determined by a onetime DCC opt-in by the customer. The merchant must notify the cardholder that they can select to have all of their transactions converted into their card billing currency, using the exchange rate applicable at the time of the transaction. If the cardholder agrees, then a flag will be set on the system that indicates this choice and drives the automatic conversion of each recurring transaction into the cardholder’s agreed billing currency.
Note: Recurring billing is not supported for Dynamic Pricing merchants.
Recurring - Manual transaction entry
Once a card number is entered, it is checked for DCC eligibility. If it is eligible, elements are added to the form (displayed) and the merchant has to select Dcc-Opt-In vs. DCC-Opt-out (based on the cardholders preference).
This selection (and the card's currency) are stored with this transaction.
It should be noted that the Gateway, does not store the actual credit card number, these will always be masked or tokenized (preference).
Recurring - CSV File upload
The merchant can indicate DCC-Opt-In, vs. DCC-Opt-out in an additional column in the CSV files. Please note that this column only has an effect for Visa / MasterCard numbers. See CSV Format Specifications: Recurring and Quick Key article, for additional details.
The Gateway maintains compatibility with prior versions of the CSV file format, older files (without DCC) will continue to work properly with the Gateway.
For CSV file upload, the “DCC Opt-In” field must have “Y” or “N” indicator. If the merchant uploads a CSV File with the “DCC Opt-In” field set to “Y” and DCC has not been enabled on their account then the transactions will be rejected.
DCC with QuickKey
Manual transaction entry
When the merchant selects a terminal with DCC enabled, a checkbox becomes active that allows for the selection of either the DCC Opt-In or Opt-Out (as specified by the cardholder). Transactions are processed accordingly.
CSV File upload
As explained in the Recurring section, the merchant can indicate DCC-Opt-In vs. DCC-Opt-out in an additional column in the CSV files. Click here, to review.
Note: The DCC indicator field only impacts Visa and MasterCard transactions.
DCC and the HCO (Hosted Checkout Page)
DCC in the HCO can support either a onetime payment or processed and added as a Recurring billing transaction.
The standard DCC use case is for the payment to be entered through the HCO, using the HCO credit card form. Card numbers are checked for DCC eligibility once entered, if they are not found to be eligible, the transaction is processed as usual. The customer sees no difference.
If the Cardnumber does qualify for DCC, the customer is presented with a "DCC-opt-in" form with two options:
- "Cardholder chooses to pay in own currency" and
- "Cardholder chooses to pay in ABC," where ABC is the terminal's currency.
The former constitutes an Opt-In, the latter constitutes an Opt-Out.
In the Opt-Out case, the transaction is processed as usual.
In the Opt-In case, the customer is presented with a confirmation page, and if they confirm, the transaction is processed as a DCC-Opt-In transaction.
In this case the receipt will indicate the exchange rate, the amount in the terminal's currency (Client’s base currency), and the amount in the customer's local currency. This information will also be visible to the merchant in the DCC section f transaction details.
The merchant will see few differences when using a payment page with a terminal that has DCC enabled:
- Transaction details in Transaction Search will have a DCC section at the bottom. Only when the DCC currency conversion has been performed.
- In the Closed Batch reports of the RPM, DCC transactions(where the customer opted-in) will be included in the DCC/DP total amount for the terminals.
- Under Transaction Search, when searching by Currency, DCC-Opt-In all transactions in that foreign currency will be included.
- The relay response/silent post (if configured and used) will include extra fields, when payment was made with Visa or MasterCard
- dcc_indicator: one of the following values 1,2,3
If the dcc_indicator is 1 or 3:
- dcc_foreign_amount
- dcc_foreign_currency_code
- dcc_exchange_rate
- dcc_margin_rate
- dcc_exchange_rate_source
DCC Indicator Values
The DCC Indicator appears in the Web Service API responses and the RPM interface, in the Transaction Details (Transaction Search).
If the DCC indicator is empty, the transaction was processed without DCC and DP.
Otherwise the DCC indicator will have one of the values 1,2,3,4 or 6.
These are the descriptions for the DCC indicator values.
DCC Transactions
DCC Indicator |
Description |
1 |
Customer opted-in to DCC, exchange rate was applied |
2 |
Card number is in BIN file, but no exchange rate request is available |
3 |
Customer did not opt in to DCC, exchange rate was not applied |
If the HCO is used for Pre-Authorizations, and the merchant completes a DCC-Opt-In payment through Transaction Search or API, the prevailing exchange rate will be automatically looked up and applied to the completion .
When refunding DCC-Opt-In transactions, through Transaction Search or API, the customer will be refunded in their card's currency, using the prevailing rate.
Important: If the currency of the transaction request is different from what is set in the terminal, any Dynamic Currency data will be ignored.
Screenshot DCC currency selection (Opt-In/Out) page
DCC using the API
Please refer to the Gateway Web Service API reference guide for DCC/DP transactions and to the DCC-DP Merchant Rate and Card Rate API Reference Guide for additional information on using DCC with the API.
Dynamic Pricing “DP” feature description
DP is only available via HCO or API
Transaction Types Supported:
- Purchase
- Pre-Authorizations
- Pre-Auth Completion
- Partial Auth (WS-API Only)
- Refund
- Tagged Void
- Tagged Purchase
- Tagged Refund
- Tagged Completion
DP via the HCO
When the cardholder lands on a merchant’s website, the merchant will either:
- Provide the customer with a pull-down list of currencies from which to choose (default should be client’s base currency)
- Force the customer to choose a currency before they can proceed to shop
- Using IP location detection, dynamically change the pricing from the Client Base Currency into the cardholder’s native currency
For any of the above methods, the merchant must generate a currency rate request to the gateway. The gateway will respond with the prevailing exchange rate for the chosen currency.
This rate will be used by the merchant to dynamically convert the Client Base Currency pricing into the chosen currency. The cardholder will only see pricing in the chosen currency.
The confirmation page shows the total transaction amount in the chosen currency or client based currency, accompanied by the ISO currency symbol. (E.g. EUR, MXN JPY)
The receipt page will show the total transaction amount in the chosen currency, accompanied by the ISO currency symbol. (E.g. EUR, MXN JPY) as well as the client’s base (or local) currency
Selection of the currency at the Merchant’s website represents Defacto opt-in as the cardholder has requested this currency specifically.
Dynamic Pricing can only be conducted on Visa and MasterCard cards. If a customer is using another card type (such as Amex, Diners, etc.), the interface will inform the cardholder by showing the message in Figure 1: “Currency Options”. Their transaction can be processed in the Merchant’s Base Currency (USD in the example below), and a new tender can be provided (one that supports the selected currency) or the transaction can be cancelled in which case the cardholder is returned to the merchants website.
Figure 1
The general DP use case is when the merchant obtains an exchange rate for a given currency (chosen by the customer), then shows all prices in their shopping cart or Ecommerce site in that currency.
The merchant includes a reference to the exchange rate record in their redirect to the HCO, together with the total amount in the terminal's base currency and in the foreign currency.
These total amounts and the foreign currency are verified against the exchange rate in the exchange rate record.
In order to use the HCO with DP, the merchant's web site will perform a Merchant Rate Request with the foreign currency that the customer has chosen.
The response for the rate request will include the exchange rate and the rate response identifier
This merchant rate will have a field, "valid_until", which indicates for how long the rate will remain valid.
When redirecting the customer to the HCO, two additional fields must be included:
- x_dp_rate_response_id
- x_dp_foreign_currency_amount
It is important to note that the "x_fp_hash value" is computed with using a different string when compared to a non-DP HCO request:
x_login^x_fp_sequence^x_fp_timestamp^x_amount^x_dp_foreign_currency_amount^x_currency_code^x_dp_rate_response_id |
The fields "x_dp_foreign_currency_amount" and "x_dp_rate_response_id" have been included
Example:
Field Name |
Sample Value |
x_login |
WSP-FDATA-10 |
x_fp_sequence |
123456 |
x_fp_timestamp |
1424480303 |
x_amount |
12.24 |
x_foreign_currency_amount |
1210.0 |
x_currency_code |
USD |
x_dp_rate_response_id |
2-620aff334cbd3f3ede6c64722bbef295971b986a488f07e6b1c47dbcf8802eb6 |
Then the hash will be computed as shown:
WSP-FDATA-10^123456^1424480303^12.24^1210.0^USD^2-620aff334cbd3f3ede6c64722bbef295971b986a488f07e6b1c47dbcf8802eb6 |
These are the valid values for x_fp_hash
Hash Algorithm |
Valid x_fp_hash Value |
MD5 |
83b2586a388579ada6e9fe6d1de2a5c9 |
SHA-1 |
9cf265e3f67095b9f8ff4da3a4e1c83fca02a439 |
Important notes:
- The x_currency_codeparameter is required for DP / HCO.
2. The x_currency_codeparameter must be equal the terminal's currency code.
3. The foreign currency amount will be validated against the amount multiplied by the exchange rate of the merchant rate obtained under 1.
4. The exchange rate response must be valid for at least 15 minutes from the time the customer is sent to HCO.
DP using API
Please refer to the Gateway Web Service API Reference Guide for DCC/DP transactions and to the DCC-DP Merchant Rate and Card Rate API Reference Guide for additional information on using DCC with the API..
Merchants can include DCC fields in the transaction requests, indicating DCC-Opt-In and referencing a rate response obtained in a previous merchant rate request.
This will be applied to the transaction; transaction types include partial auth's in addition to those mentioned above.
Currencies Table
Country Name |
Currency Name |
Alphabetic Currency Code |
Numeric Currency Code |
Minor Currency Unit |
Afghanistan |
Afghani |
AFN |
971 |
2 |
Albania |
Lek |
ALL |
008 |
2 |
Algeria |
Algerian Dinar |
DZD |
012 |
2 |
Argentina |
Argentine Peso |
ARS |
032 |
2 |
Australia |
Australian Dollar |
AUD |
036 |
2 |
Azerbaijan |
Azerbaijanian Manat |
AZN |
944 |
2 |
Bahamas |
Bahamian Dollar |
BSD |
044 |
2 |
Bahrain |
Bahraini Dinar |
BHD |
048 |
3 |
Bangladesh |
Taka |
BDT |
050 |
2 |
Barbados |
Barbados Dollar |
BBD |
052 |
2 |
Belize |
Belize Dollar |
BZD |
084 |
2 |
Bermuda |
Bermudian Dollar |
BMD |
060 |
2 |
Bolivia |
Boliviano |
BOB |
068 |
2 |
Botswana |
Pula |
BWP |
072 |
2 |
Brazil |
Brazilian Real |
BRL |
986 |
2 |
Brunei Darussalam |
Brunei Dollar |
BND |
096 |
2 |
Bulgaria |
Bulgarian Lev |
BGN |
975 |
2 |
Canada |
Canadian Dollar |
CAD |
124 |
2 |
Chile |
Chilean Peso |
CLP |
152 |
2 |
China |
Yuan Renminbi |
CNY |
156 |
2 |
Colombia |
Colombian Peso |
COP |
170 |
2 |
Costa Rica |
Costa Rican Colon |
CRC |
188 |
2 |
Croatia |
Croatian Kuna |
HRK |
191 |
2 |
Czech Republic |
Czech Koruna |
CZK |
203 |
2 |
Denmark |
Danish Kroner |
DKK |
208 |
2 |
Dominican Republic |
Dominican Peso |
DOP |
214 |
2 |
Egypt |
Egyptian Pound |
EGP |
818 |
2 |
Europe |
Euro |
EUR |
978 |
2 |
Guatemala |
Quetzal |
GTQ |
320 |
2 |
Honduras |
Lempira |
HNL |
340 |
2 |
Hong Kong |
Hong Kong Dollar |
HKD |
344 |
2 |
Hungary |
Forint |
HUF |
348 |
2 |
Iceland |
Iceland Krona |
ISK |
352 |
2 |
India |
Indian Rupee |
INR |
356 |
2 |
Israel |
New Israeli Sheqel |
ILS |
376 |
2 |
Jamaica |
Jamaican Dollar |
JMD |
388 |
2 |
Japan |
Japanese Yen |
JPY |
392 |
0 |
Jordan |
Jordanian Dinar |
JOD |
400 |
3 |
Kazakhstan |
Tenge |
KZT |
398 |
2 |
Kenya |
Kenyan Shilling |
KES |
404 |
2 |
Korea Republic of |
Won |
KRW |
410 |
0 |
Kuwait |
Kuwait Dinar |
KWD |
414 |
3 |
Latvia |
Latvian Lats |
LVL |
428 |
2 |
Lebanon |
Lebanese Pound |
LBP |
422 |
2 |
Liberia |
Liberian Dollar |
LRD |
430 |
2 |
Lithuania |
Lithuanian Litas |
LTL |
440 |
2 |
Macao |
Pataca |
MOP |
446 |
2 |
Malaysia |
Malaysian Ringitt |
MYR |
458 |
2 |
Mauritius |
Mauritius Rupee |
MUR |
480 |
2 |
Mexico |
Mexican Peso |
MXN |
484 |
2 |
Morocco |
Moroccan Dirham |
MAD |
504 |
2 |
New Zealand |
New Zealand Dollar |
NZD |
554 |
2 |
Nigeria |
Naira |
NGN |
566 |
2 |
Norway |
Norwegian Krone |
NOK |
578 |
2 |
Oman |
Omani Rial |
OMR |
512 |
3 |
Organisation of Eastern Caribbean States |
East Caribbean Dollar |
XCD |
951 |
2 |
Pakistan |
Pakistan Rupee |
PKR |
586 |
2 |
Panama |
Balboa |
PAB |
590 |
2 |
Peru |
Nuevo Sol |
PEN |
604 |
2 |
Philippines |
Philippine Peso |
PHP |
608 |
2 |
Poland |
Polish New Zloty |
PLN |
985 |
2 |
Qatar |
Qatari Rial |
QAR |
634 |
2 |
Romania |
Romanian New Leu |
RON |
946 |
2 |
Russian Federation |
Russian Ruble |
RUB |
643 |
2 |
Saudi Arabia |
Saudi Riyal |
SAR |
682 |
2 |
Seychelles |
Seychelles Rupee |
SCR |
690 |
2 |
Singapore |
Singapore Dollar |
SGD |
702 |
2 |
South Africa |
South African Rand |
ZAR |
710 |
2 |
Sri Lanka |
Sri Lanka Rupee |
LKR |
144 |
2 |
Sweden |
Swedish Kroner |
SEK |
752 |
2 |
Switzerland |
Swiss Franc |
CHF |
756 |
2 |
Taiwan Province of China |
New Taiwan Dollar |
TWD |
901 |
2 |
Thailand |
Baht |
THB |
764 |
2 |
Trinidad and Tobago |
Trinidad and Tobago Dollar |
TTD |
780 |
2 |
Turkey |
New Turkish Lira |
TRY |
949 |
2 |
Ukraine |
Hryvnia |
UAH |
980 |
2 |
United Arab Emirates |
United Arab Emirates Dirham |
AED |
784 |
2 |
United Kingdom |
British Pound |
GBP |
826 |
2 |
United States |
US Dollar |
USD |
840 |
2 |
Venezuela |
Venezuelan Bolivar new 2008 |
VEF |
937 |
2 |
Yemen |
Yemeni Rial |
YER |
886 |
2 |
DCC and DP Support in the Demo Environment
The URL's for the Demo environment are:
- RPM: https://demo.globalgatewaye4.firstdata.com
- API Endpoint: https://api.demo.globalgatewaye4.firstdata.com/transaction
- API WSDL: https://api.demo.globalgatewaye4.firstdata.com/transaction/wsdl
- Payment Page Checkout URL - https://demo.globalgatewaye4.firstdata.com/payment
Card numbers supported:
- In the Demo environment the numbers shown in the table below can be used to simulate DCC and DP.
- Two merchant base foreign currencies are supported, USD and CAD. The exchange rates will not change in the Demo Environment.
The following two card numbers are simulated, they appear to be in the BIN file, but DCC is not offered. These numbers will generate transactions with a DCC indicator value 2.
Visa |
4000000000000002 |
MasterCard |
5100000000000008 |
Notes:
- The CAD test card numbers don't have an "Exchange Rate CAD" because no currency exchange is necessary.
- The 5200000000000007 number can be for testing Verified-by-Visa / 3D-Secure.
- OMR is Omani Rial and has 3 rounding digits.
- AUD has currency code 036, the 0 is to be included
DCC Indicator Values
The DCC Indicator appears in the Transaction API response, and in the RPM interface as well as the Transaction Details (Transaction Search).
If the DCC indicator is empty, the transaction was processed without DCC and/or DP.
Otherwise the DCC indicator will have one of the values 1,2,3,4 or 6.
These are the descriptions for the DCC indicator values.
DCC Transactions
DCC Indicator |
Description |
1 |
Customer opted-in to DCC, exchange rate was applied |
2 |
Card number is in BIN file, but no exchange rate request is available |
3 |
Customer did not opt in to DCC, exchange rate was not applied |
DP Transactions
DCC Indicator |
Description |
4 |
Customer opted-in to DCC, exchange rate was applied |
6 |
Customer did not opt in to DCC, exchange rate was not applied |