The following process requires the implementation of a solution that utilises our Webservices API to perform the currency conversion and our JavaScript Library to process the payment.
Utilising Webservices API involves the direct handling of sensitive cardholder data on your server and, as such, is subject to stricter PCI compliance standards. Please ensure you have obtained the necessary certification before proceeding.
If you are unsure, contact our Support Team for assistance.
Before proceeding, please ensure you have met all requirements for processing DCC
Click here to open this information in a new tab
Dynamic Currency Conversion (DCC) is a feature that allows customers to complete the payment in their currency or your local currency. The amounts are calculated using a third-party conversion rate provider with up-to-date conversion rates.
Process overview
In our DCC documentation, we refer to the customer’s currency and the merchant’s currency. These are defined as follows:
- The customer’s currency – the currency associated with their card.
- The merchant’s currency – the local currency associated with your account.
The DCC payment flow can be split into three main parts, as shown below:
1. Submit CURRENCYRATE request
Your checkout form will need to prompt the customer for their card and billing details (this process follows the standard payment flow). Submit these details, along with the transaction amount, in a CURRENCYRATE request, using our Webservices API.
2. Receive CURRENCYRATE response
We will contact your conversion rate provider to obtain the latest conversion rate between the customer’s currency and the merchant’s currency. We will return a CURRENCYRATE response that contains the amount in both the customer’s currency and merchant’s currency.
3. Process transaction
You must then offer the customer a choice between using either the customer’s currency or the merchant’s currency to complete the payment. You will need to ensure your checkout form has been modified to reference our JavaScript Library, and that the payload submitted within the JWT includes additional fields regarding the currency conversion performed.
To eliminate the need to ask the customer to click "Pay" when the JavaScript Library is initialised and the card st.Components method is called, you can pass the method a config of {startOnLoad:true}, which triggers the payment process immediately.
Click here for further information regarding capturing card details using your own custom form.
Please be aware of the following distinctions:
- When we discuss the customer’s currency, we are referring to the currency associated with their card. This often correlates to the country the card was issued in, and as such, you may find customers are more accustomed to processing payments in this currency.
- When we discuss the merchant’s currency, this is the local currency assigned to your account with us. Local customers to your business may be more accustomed to processing payments in this currency.
- As part of the DCC process, you will need to provide the customer with a choice between the customer’s currency and your local merchant currency, prior to processing the payment. We refer to the currency chosen by the customer as the final currency.
1. Submit CURRENCYRATE request
The CURRENCYRATE request is used to determine both the customer’s currency and the amount in the customer’s currency.
Example request
The following is an example of a CURRENCYRATE request.
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
currencyrate = {
"sitereference": "test_site12345",
"requesttypedescriptions": ["CURRENCYRATE"],
"accounttypedescription": "CURRENCYRATE",
"dcctype": "DCC",
"dccbaseamount": "1050",
"dcccurrencyiso3a": "GBP",
"orderreference": "My_Order_123",
"pan": "4111111111111111"
}
strequest = securetrading.Request()
strequest.update(currencyrate)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php
if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);
$configData = array(
'username' => 'webservices@example.com',
'password' => 'Password1^',
);
$requestData = array(
'sitereference' => 'test_site12345',
'requesttypedescriptions' => array('CURRENCYRATE'),
'accounttypedescription' => 'CURRENCYRATE',
'dcctype' => 'DCC',
'dccbaseamount' => '1050',
'dcccurrencyiso3a' => 'GBP',
'orderreference' => 'My_Order_123',
'pan' => '4111111111111111'
);
$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());
?>
curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"webservices@example.com",
"version": "1.00",
"request": [{
"sitereference": "test_site12345",
"requesttypedescriptions": ["CURRENCYRATE"],
"accounttypedescription": "CURRENCYRATE",
"dcctype": "DCC",
"dccbaseamount": "1050",
"dcccurrencyiso3a": "GBP",
"orderreference": "My_Order_123",
"pan": "4111111111111111"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"sitereference":"test_site12345",
"requesttypedescriptions":["CURRENCYRATE"],
"accounttypedescription":"CURRENCYRATE",
"dcctype":"DCC",
"dccbaseamount":"1050",
"dcccurrencyiso3a":"GBP",
"orderreference":"My_Order_123",
"pan":"4111111111111111"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="CURRENCYRATE">
<operation>
<sitereference>test_site12345</sitereference>
<accounttypedescription>CURRENCYRATE</accounttypedescription>
</operation>
<merchant>
<orderreference>My_Order_123</orderreference>
</merchant>
<billing>
<dcc type="DCC">
<amount currencycode="GBP">1050</amount>
</dcc>
<payment>
<pan>4111111111111111</pan>
</payment>
</billing>
</request>
</requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Field specification
| Field | Format | Description | |
| accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | This must be submitted as “CURRENCYRATE”. | |
| dccbaseamount XPath: /billing/dcc/amount |
Numeric (13) | The amount in the merchant’s currency. This should be in base units with no commas or decimal points, so £10 would be 1000. | |
| dcccurrencyiso3a XPath: /billing/dcc/amount/@currencycode |
Alpha (3) |
The merchant’s currency in iso3a format. |
|
| dcctype XPath: /billing/dcc/dcctype |
Alpha (3) | The value submitted must be “DCC”. | |
| orderreference XPath: /merchant/orderreference |
Alphanumeric including symbols (25) Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction. |
Your unique order reference that can be stored on the Trust Payments system. | |
| pan XPath: /billing/payment/pan |
Numeric (12-19) | This is the long number printed on the front of the customer’s card. | |
| requesttypedescriptions XPath: /@type |
Alpha (20) | You must submit “CURRENCYRATE”, as shown in the request example. | |
| sitereference XPath: /operation/sitereference |
Alphanumeric & underscore (50) |
The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support Team. |
2. Receive CURRENCYRATE response
This response contains the customer’s currency and converted amount, calculated using the latest conversion rate.
Example response
{
u 'requestreference': u 'A0bxh87wt',
u 'version': u '1.00',
u 'responses': [{
u 'transactionstartedtimestamp': u '2017-04-21 09:26:46',
u 'dcccurrencyiso3a': u 'GBP',
u 'livestatus': u '0',
u 'englishacquirertypedescription': u 'Acquirer',
u 'iin': u '411111111',
u 'dcctype': u 'DCC',
u 'dccbaseamount': u '1050',
u 'errorcode': u '0',
u 'orderreference': u 'My_Order_123',
u 'dccconversionratesource': u 'Conversion rate source',
u 'merchantnumber': u '00000000',
u 'dccexpirytimestamp': u '2017-04-25 14:26:00',
u 'transactionreference': u '23-71-101',
u 'paymenttypedescription': u 'VISA',
u 'baseamount': u '1641',
u 'dccmarginratepercentage': u '2.5000',
u 'accounttypedescription': u 'CURRENCYRATE',
u 'acquirerresponsecode': u '0',
u 'requesttypedescription': u 'CURRENCYRATE',
u 'acquirerresponsemessage': u 'Success',
u 'currencyiso3a': u 'USD',
u 'maskedpan': u '411111######1111',
u 'errormessage': u 'Ok',
u 'issuercountryiso2a': u 'ZZ',
u 'dccconversionrate': u '1.5626',
u 'operatorname': u 'webservices@example.com'
}]
}
array(3) {
["requestreference"] => string(9) "A3579dkvx"
["version"] => string(4) "1.00"
["responses"] => array(1) {
[0] => array(26) {
["transactionstartedtimestamp"] => string(19) "2017-04-21 09:26:46"
["dcccurrencyiso3a"] => string(3) "GBP"
["livestatus"] => string(1) "0"
["englishacquirertypedescription"] => string(8) "Acquirer"
["iin"] => string(9) "411111111"
["dcctype"] => string(3) "DCC"
["dccbaseamount"] => string(4) "1050"
["errorcode"] => string(1) "0"
["orderreference"] => string(12) "My_Order_123"
["dccconversionratesource"] => string(22) "Conversion rate source"
["merchantnumber"] => string(8) "00000000"
["dccexpirytimestamp"] => string(19) "2017-04-25 14:26:00"
["transactionreference"] => string(9) "23-71-101"
["paymenttypedescription"] => string(4) "VISA"
["baseamount"] => string(4) "1641"
["dccmarginratepercentage"] => string(6) "2.5000"
["accounttypedescription"] => string(12) "CURRENCYRATE"
["acquirerresponsecode"] => string(1) "0"
["requesttypedescription"] => string(12) "CURRENCYRATE"
["acquirerresponsemessage"] => string(7) "Success"
["currencyiso3a"] => string(3) "USD"
["maskedpan"] => string(16) "411111######1111"
["errormessage"] => string(2) "Ok"
["issuercountryiso2a"] => string(2) "ZZ"
["dccconversionrate"] => string(6) "1.5626"
["operatorname"] => string(23) "webservices@example.com"
}
}
}
{
"requestreference":"W23-fjgvn3d8",
"version":"1.00",
"response":[{
"transactionstartedtimestamp":"2017-04-21 09:26:46",
"dcccurrencyiso3a":"GBP",
"livestatus":"0",
"englishacquirertypedescription":"Acquirer",
"iin":"411111111",
"dcctype":"DCC",
"dccbaseamount":"1050",
"errorcode":"0",
"orderreference":"My_Order_123",
"dccconversionratesource":"Conversion rate source",
"merchantnumber":"00000000",
"dccexpirytimestamp":"2017-04-25 14:26:00",
"transactionreference":"23-71-101",
"paymenttypedescription":"VISA",
"baseamount":"1641",
"dccmarginratepercentage":"2.5000",
"accounttypedescription":"CURRENCYRATE",
"acquirerresponsecode":"0",
"requesttypedescription":"CURRENCYRATE",
"acquirerresponsemessage":"Success",
"currencyiso3a":"USD",
"errormessage":"Ok",
"issuer":"Test Issuer",
"issuercountryiso2a":"ZZ",
"dccconversionrate":"1.5626",
"operatorname":"webservices@example.com"
}],
"secrand":"zO9"
}
<responseblock version="3.67">
<requestreference>X881587174</requestreference>
<response type="CURRENCYRATE">
<merchant>
<orderreference>My_Order_123</orderreference>
<merchantnumber>00000000</merchantnumber>
<operatorname>webservices@example.com</operatorname>
</merchant>
<transactionreference>23-71-101</transactionreference>
<billing>
<amount currencycode="USD">1641</amount>
<payment type="VISA">
<iin>411111111</iin>
<issuercountry>ZZ</issuercountry>
<issuer>Test Issuer</issuer>
</payment>
<dcc>
<marginratepercentage>2.5000</marginratepercentage>
<amount currencycode="GBP">1050</amount>
<dcctype>DCC</dcctype>
<conversionrate>1.5626</conversionrate>
<conversionratesource>Conversion rate source</conversionratesource>
<expirytimestamp>2013-06-09 18:45:00</expirytimestamp>
<dccproviderdata>01020304120021250373330603INR0803356200513800210875190000300124306MBB015</dccproviderdata>
</dcc>
</billing>
<timestamp>2013-06-05 14:45:56</timestamp>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<acquirerresponsecode>0</acquirerresponsecode>
<operation>
<processor>Test DCC Provider</processor>
<accounttypedescription>CURRENCYRATE</accounttypedescription>
</operation>
<acquirerresponsemessage>Success</acquirerresponsemessage>
</response>
<secrand>1Enh1O0h</secrand>
</responseblock>
After you have received the CURRENCYRATE response, check if the currency returned in the currencyiso3a field is different to that in the dcccurrencyiso3a field.
| If currencies differ: | If currencies are the same: |
|
Offer the customer a choice between processing the payment in the customer’s currency or the merchant’s currency. Note: Select acquirers may require certain information to be displayed to the customer on the currency choice page, such as the conversion rate used and the name of the conversion rate provider. Please be sure to check with your acquiring bank that you are displaying all the information required. |
Prompt the customer to confirm they would like to proceed before processing the payment. |
Field specification
It is imperative that all transactions, which use the currency conversions provided by the conversion rate provider, are settled before the dccexpirytimestamp (returned in the CURRENCYRATE response).
Failing to do so, by deferring the settlement date, may result in the customer paying an incorrect amount and invalidate your agreement with the conversion rate provider or acquirer.
| Field | Format | Description | |
| accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | This is returned as “CURRENCYRATE”. | |
| acquirerresponsecode XPath: /acquirerresponsecode |
Alphanumeric (255) |
Used by the DCC provider to indicate the outcome of the request. This will vary depending on your acquiring bank. Please contact your bank for further information. |
|
| acquirerresponsemessage XPath: /acquirerresponsemessage |
Alphanumeric (255) | ||
| baseamount XPath: /billing/amount |
Numeric (13) | The total amount in the customer’s currency. This value includes the conversion fee applied to cover the cost of converting the amount to their local currency. The amount is in base units with no commas or decimal points, so £10 would be 1000. | |
| currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) |
The customer’s currency in iso3a format. This is determined by analysing the card details submitted in the request. |
|
| dccbaseamount XPath: /billing/amount |
Numeric (13) | The amount in the merchant’s currency. This should be in base units with no commas or decimal points, so £10 would be 1000. The value returned in the response will match the value submitted in the request. | |
| dccconversionrate XPath: /billing/dcc/conversionrate |
Numeric (255) | The conversion rate used to calculate the amount in the customer’s currency. | |
| dccconversionratesource XPath: /billing/dcc/conversionratesource |
Alphanumeric (255) | The source of the conversion rate returned from the DCC provider. | |
| dcccurrencyiso3a XPath: /billing/dcc/amount/@currencycode |
Alpha (3) |
The merchant’s currency in iso3a format. |
|
| dccexpirytimestamp XPath: /billing/dcc/expirytimestamp |
Date Time “YYYY-MM-DD HH:MM:SS” |
The expiry date of the CURRENCYRATE look-up. Payments using the CURRENCYRATE as a parent must settle before this date and time. Format: YYYY-MM-DD HH:MM:SS |
|
| dccmarginratepercentage XPath: /billing/dcc/marginratepercentage |
Numeric (11) | The percentage used to calculate the currency conversion fee (4 decimal places), automatically added to the amount in the customer’s currency by the DCC provider. | |
| dccprovider XPath: /billing/dcc/provider |
Alphanumeric (255) |
The name of the third-party DCC provider that has provided the conversion rate used in the payment. This field is returned when the data has been provided by the conversion rate provider. |
|
| dccproviderdata XPath: /billing/dcc/dccproviderdata |
Alphanumeric (255) |
A unique string that contains information on the calculated conversion rate, returned directly from certain conversion rate providers. This field is returned when the data has been provided by the conversion rate provider. |
|
| dcctype XPath: /billing/dcc/dcctype |
Alpha (3) | This is returned as “DCC”. | |
| englishacquirertypedescription XPath: /operation/processor |
Alphanumeric (255) | The name of the third-party DCC provider that has provided the conversion rate used in the payment. This is an English description of the provider that can be displayed on your pages. | |
| iin XPath: /billing/payment/iin |
Numeric (9) | Issuer Identification Number (IIN) – This is the first 9 digits from the start of the customer’s card number. | |
| issuercountryiso2a XPath: /billing/payment/issuercountry |
Alpha (2) |
The country for the customer’s card issuer. |
|
| maskedpan XPath: /billing/payment/pan |
Alphanumeric including “#” (12-19) | The customer’s card number. This is masked in the response. Part of the number is intentionally obscured by “#” characters, e.g. 411111######0211. | |
| paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | Payment method (e.g. “VISA” or “MASTERCARD”). | |
| requesttypedescription XPath: /@type |
Alpha (20) | This is returned as “CURRENCYRATE”. | |
| transactionreference XPath: /transactionreference |
Alphanumeric including hyphens (25) |
A unique reference for the transaction assigned by Trust Payments. |
3. Process transaction
After you have received the CURRENCYRATE response and prompted the customer to choose the final currency, the customer will need to click “Pay” on your checkout form in order to complete the payment. You will need to ensure your checkout form has been updated to reference our JavaScript Library, and that the payload submitted as part of the JWT has been updated to include additional fields regarding the currency conversion (as shown below).
It is imperative that all transactions, which use the currency conversions provided by the conversion rate provider, are settled before the dccexpirytimestamp (returned in the CURRENCYRATE response). Failing to do so, by deferring the settlement date, may result in the customer paying an incorrect amount and invalidate your agreement with the conversion rate provider or acquirer.
(Payload example:)
{
"payload":{
"accounttypedescription":"ECOM",
"baseamount":"1641",
"currencyiso3a":"USD",
"sitereference":"test_site12345",
"parenttransactionreference":"23-71-101",
"pan":"4111111111111111",
"expirydate":"12/2037",
"securitycode":"123",
"dcctype":"DCC",
"dccoffered":"1",
"dccconversionrate":"1.5626",
"dcccurrencyiso3a":"GBP",
"dccbaseamount":"1050",
"requesttypedescriptions":["THREEDQUERY","AUTH"]
},
"iat":1559033849,
"iss":"jwt.user"
}
You will need to check the response JWT to confirm that the payment was successful. As with a standard payment, you will need to pay particular attention to the errorcode and settlestatus fields.
Receipt text
Select acquirers may require certain information to be displayed to the customer in a receipt, following a transaction, such as the conversion rate used and the name of the conversion rate provider. Please be sure to check with your acquiring bank that you are displaying all the information required.
Field specification
| Field | Format | Description | |
| accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | This must be submitted as “ECOM” (e-commerce). | |
| baseamount XPath: /billing/amount |
Numeric (13) | The amount in the final currency. This should be in base units with no commas or decimal points, so £10 would be 1000. | |
| currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) |
The final currency. |
|
| dccbaseamount XPath: /billing/dcc/amount |
Numeric (13) | The amount in the merchant’s currency. This should be in base units with no commas or decimal points, so £10 would be 1000. | |
| dccconversionrate XPath: /billing/dcc/conversionrate |
Numeric (255) | The conversion rate used to calculate the amount in the customer’s currency. | |
| dccconversionratesource XPath: /billing/dcc/conversionratesource |
Alphanumeric (255) | The source of the conversion rate returned from the DCC provider. | |
| dcccurrencyiso3a XPath: /billing/dcc/amount/@currencycode |
Alpha (3) |
The merchant’s currency in iso3a format. |
|
| dccmarginratepercentage XPath: /billing/dcc/marginratepercentage |
Numeric (11) | The percentage used to calculate the currency conversion fee (4 decimal places), automatically added to the amount in the customer’s currency by the DCC provider. | |
| dccoffered XPath: /billing/dcc/offered |
Numeric (1) |
Please use one of the following values:
|
|
| dccprovider XPath: /billing/dcc/provider |
Alphanumeric (255) | The name of the third-party DCC provider that has provided the conversion rate used in the payment. | |
| dccproviderdata XPath: /billing/dcc/dccproviderdata |
Alphanumeric (255) | A unique string that contains information on the calculated conversion rate, returned directly from certain conversion rate providers. | |
| dcctype XPath: /billing/dcc/dcctype |
Alpha (3) | The value submitted must be “DCC”. | |
| expirydate XPath: /billing/payment/expirydate |
Date MM/YYYY | The expiry date printed on the card. | |
| pan XPath: /billing/payment/pan |
Numeric (12-19) | This is the long number printed on the front of the customer’s card. | |
| parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
Retrieve the transactionreference value from the CURRENCYRATE response, and submit this in the parenttransactionreference field in the payload of the JWT.
Note: We support the ability to perform currency conversion using your own DCC provider. In such a case, the parenttransactionreference field is not required. Click here for further information. |
|
| requesttypedescriptions | List | This must be set to [“THREEDQUERY”,”AUTH”]. | |
| securitycode XPath: /billing/payment/securitycode |
Numeric (3-4) |
This is the three digit security code printed on the back of the card.
(For AMEX cards, this is a 4 digit code found on the front of the card) This field is not strictly required by Trust Payments, but it is highly recommended for the processing of security code checks. Additionally, some banks may decline the payment if the security code is not present. |
|
| sitereference XPath: /operation/sitereference |
Alphanumeric & underscore (50) |
Unique reference that identifies your Trust Payments site. |
Testing
We recommend that you thoroughly test your solution before processing live payments.
Click here for test card details that you can submit when testing.
