Alternative Payment Methods (API)

Country codes

(For ISO2A format, refer to the “Country 2-Letter” column below)

 

Country 2-Letter Country 3-Letter Country 3-Digit Country Name
AD AND 020 Andorra
AE ARE 784 United Arab Emirates
AF AFG 004 Afghanistan
AG ATG 028 Antigua And Barbuda
AI AIA 660 Anguilla
AL ALB 008 Albania
AM ARM 051 Armenia
AN ANT 530 Netherlands Antilles
AO AGO 024 Angola
AQ ATA 010 Antarctica
AR ARG 032 Argentina
AS ASM 016 American Samoa
AT AUT 040 Austria
AU AUS 036 Australia
AW ABW 533 Aruba
AX ALA 248 Åland Islands
AZ AZE 031 Azerbaijan
BA BIH 070 Bosnia And Herzegowina
BB BRB 052 Barbados
BD BGD 050 Bangladesh
BE BEL 056 Belgium
BF BFA 854 Burkina Faso
BG BGR 100 Bulgaria
BH BHR 048 Bahrain
BI BDI 108 Burundi
BJ BEN 204 Benin
BL BLM 652 Saint Barthélemy
BM BMU 060 Bermuda
BN BRN 096 Brunei Darussalam
BO BOL 068 Bolivia
BQ BES 535 Bonaire, Saint Eustatius and Saba
BR BRA 076 Brazil
BS BHS 044 Bahamas
BT BTN 064 Bhutan
BV BVT 074 Bouvet Island
BW BWA 072 Botswana
BY BLR 112 Belarus
BZ BLZ 084 Belize
CA CAN 124 Canada
CC CCK 166 Cocos (Keeling) Islands
CD COD 180 Congo, Democratic Republic of
CF CAF 140 Central African Republic
CG COG 178 Congo
CH CHE 756 Switzerland
CI CIV 384 Cote D’ivoire
CK COK 184 Cook Islands
CL CHL 152 Chile
CM CMR 120 Cameroon
CN CHN 156 China
CO COL 170 Colombia
CR CRI 188 Costa Rica
CS SCG 891 Serbia and Montenegro
CU CUB 192 Cuba
CV CPV 132 Cape Verde
CW CUW 531 Curaçao
CX CXR 162 Christmas Island
CY CYP 196 Cyprus
CZ CZE 203 Czech Republic
DE DEU 276 Germany
DJ DJI 262 Djibouti
DK DNK 208 Denmark
DM DMA 212 Dominica
DO DOM 214 Dominican Republic
DZ DZA 012 Algeria
EC ECU 218 Ecuador
EE EST 233 Estonia
EG EGY 818 Egypt
EH ESH 732 Western Sahara
ER ERI 232 Eritrea
ES ESP 724 Spain
ET ETH 231 Ethiopia
FI FIN 246 Finland
FJ FJI 242 Fiji
FK FLK 238 Falkland Islands (Malvinas)
FM FSM 583 Micronesia, Federated States Of
FO FRO 234 Faroe Islands
FR FRA 250 France
GA GAB 266 Gabon
GB GBR 826 United Kingdom
GD GRD 308 Grenada
GE GEO 268 Georgia
GF GUF 254 French Guiana
GG GGY 831 Guernsey
GH GHA 288 Ghana
GI GIB 292 Gibraltar
GL GRL 304 Greenland
GM GMB 270 Gambia
GN GIN 324 Guinea
GP GLP 312 Guadeloupe
GQ GNQ 226 Equatorial Guinea
GR GRC 300 Greece
GS SGS 239 South Georgia And The South Sandwich Islands
GT GTM 320 Guatemala
GU GUM 316 Guam
GW GNB 624 Guinea-Bissau
GY GUY 328 Guyana
HK HKG 344 Hong Kong
HM HMD 334 Heard And Mc Donald Islands
HN HND 340 Honduras
HR HRV 191 Croatia (Local Name: Hrvatska)
HT HTI 332 Haiti
HU HUN 348 Hungary
ID IDN 360 Indonesia
IE IRL 372 Ireland
IL ISR 376 Israel
IM IMN 833 Isle of Man
IN IND 356 India
IO IOT 086 British Indian Ocean Territory
IQ IRQ 368 Iraq
IR IRN 364 Iran (Islamic Republic Of)
IS ISL 352 Iceland
IT ITA 380 Italy
JE JEY 832 Jersey
JM JAM 388 Jamaica
JO JOR 400 Jordan
JP JPN 392 Japan
KE KEN 404 Kenya
KG KGZ 417 Kyrgyzstan
KH KHM 116 Cambodia
KI KIR 296 Kiribati
KM COM 174 Comoros
KN KNA 659 Saint Kitts And Nevis
KP PRK 408 Korea, Democratic People’s Republic Of
KR KOR 410 Korea, Republic Of
KW KWT 414 Kuwait
KY CYM 136 Cayman Islands
KZ KAZ 398 Kazakhstan
LA LAO 418 Lao People’s Democratic Republic
LB LBN 422 Lebanon
LC LCA 662 Saint Lucia
LI LIE 438 Liechtenstein
LK LKA 144 Sri Lanka
LR LBR 430 Liberia
LS LSO 426 Lesotho
LT LTU 440 Lithuania
LU LUX 442 Luxembourg
LV LVA 428 Latvia
LY LBY 434 Libyan Arab Jamahiriya
MA MAR 504 Morocco
MC MCO 492 Monaco
MD MDA 498 Moldova, Republic Of
ME MNE 499 Montenegro
MF MAF 663 Saint Martin
MG MDG 450 Madagascar
MH MHL 584 Marshall Islands
MK MKD 807 Macedonia, The Former Yugoslav Republic Of
ML MLI 466 Mali
MM MMR 104 Myanmar
MN MNG 496 Mongolia
MO MAC 446 Macau
MP MNP 580 Northern Mariana Islands
MQ MTQ 474 Martinique
MR MRT 478 Mauritania
MS MSR 500 Montserrat
MT MLT 470 Malta
MU MUS 480 Mauritius
MV MDV 462 Maldives
MW MWI 454 Malawi
MX MEX 484 Mexico
MY MYS 458 Malaysia
MZ MOZ 508 Mozambique
NA NAM 516 Namibia
NC NCL 540 New Caledonia
NE NER 562 Niger
NF NFK 574 Norfolk Island
NG NGA 566 Nigeria
NI NIC 558 Nicaragua
NL NLD 528 Netherlands
NO NOR 578 Norway
NP NPL 524 Nepal
NR NRU 520 Nauru
NU NIU 570 Niue
NZ NZL 554 New Zealand
OM OMN 512 Oman
PA PAN 591 Panama
PE PER 604 Peru
PF PYF 258 French Polynesia
PG PNG 598 Papua New Guinea
PH PHL 608 Philippines
PK PAK 586 Pakistan
PL POL 616 Poland
PM SPM 666 St. Pierre And Miquelon
PN PCN 612 Pitcairn
PR PRI 630 Puerto Rico
PS PSE 275 Palestinian Territory, Occupied
PT PRT 620 Portugal
PW PLW 585 Palau
PY PRY 600 Paraguay
QA QAT 634 Qatar
RE REU 638 Reunion
RO ROU 642 Romania
RS SRB 688 Serbia
RU RUS 643 Russian Federation
RW RWA 646 Rwanda
SA SAU 682 Saudi Arabia
SB SLB 090 Solomon Islands
SC SYC 690 Seychelles
SD SDN 729 Sudan
SE SWE 752 Sweden
SG SGP 702 Singapore
SH SHN 654 St. Helena
SI SVN 705 Slovenia
SJ SJM 744 Svalbard And Jan Mayen Islands
SK SVK 703 Slovakia (Slovak Republic)
SL SLE 694 Sierra Leone
SM SMR 674 San Marino
SN SEN 686 Senegal
SO SOM 706 Somalia
SR SUR 740 Suriname
SS SSD 728 South Sudan
ST STP 678 Sao Tome And Principe
SV SLV 222 El Salvador
SX SXM 534 Sint Maarten (Dutch part)
SY SYR 760 Syrian Arab Republic
SZ SWZ 748 Swaziland
TC TCA 796 Turks And Caicos Islands
TD TCD 148 Chad
TF ATF 260 French Southern Territories
TG TGO 768 Togo
TH THA 764 Thailand
TJ TJK 762 Tajikistan
TK TKL 772 Tokelau
TL TLS 626 Timor-Leste, Democratic Republic of
TM TKM 795 Turkmenistan
TN TUN 788 Tunisia
TO TON 776 Tonga
TR TUR 792 Turkey
TT TTO 780 Trinidad And Tobago
TV TUV 798 Tuvalu
TW TWN 158 Taiwan
TZ TZA 834 Tanzania, United Republic Of
UA UKR 804 Ukraine
UG UGA 800 Uganda
UM UMI 581 United States Minor Outlying Islands
US USA 840 United States
UY URY 858 Uruguay
UZ UZB 860 Uzbekistan
VA VAT 336 Vatican City State (Holy See)
VC VCT 670 Saint Vincent And The Grenadines
VE VEN 862 Venezuela
VG VGB 092 Virgin Islands (British)
VI VIR 850 Virgin Islands (U.S.)
VN VNM 704 Viet Nam
VU VUT 548 Vanuatu
WF WLF 876 Wallis And Futuna Islands
WS WSM 882 Samoa
YE YEM 887 Yemen
YT MYT 175 Mayotte
ZA ZAF 710 South Africa
ZM ZMB 894 Zambia
ZW ZWE 716 Zimbabwe
ZZ ZZZ 999 Unknown

Refunds

 

For customers that have completed a payment using DCC, it is possible to process refunds by manually submitting a REFUND request using our Webservices API.

 

Info
Remember!

  • The customer’s currency is the currency associated with their card.
  • The merchant’s currency is the local currency associated with your account.

 

DCC refunds have a similar structure to standard REFUND requests, but are subject to additional requirements that are outlined below. There are four DCC refund options available:

 

Warning
It is your responsibility to ensure that all DCC field values you include in any DCC REFUND requests are correct and agreed with your conversion rate provider.

Your conversion rate provider will specify the required process to handle refunds on your account. We recommend that you review the options available and contact our Support Team for further information.


 

Option 1: Refund using original rate

 

Request

The request has the same structure as a standard REFUND request, except your system will also need to resubmit either the customer currency fields OR the merchant currency fields, as shown below:

 

Either submit the following two customer currency fields in the request:

currencyiso3a The customer’s currency.
baseamount The amount in the customer’s currency.

 

Or, if you prefer to submit the merchant currency fields in the request:

dcccurrencyiso3a The merchant’s currency.
dccbaseamount The amount in the merchant’s currency.

 

Info
As with standard REFUND requests, the submitted parenttransactionreference field must refer to the parent AUTH request being refunded (not the CURRENCYRATE request).

#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
refund= {
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "currencyiso3a": "USD",
  "baseamount": "1641"
}
  
strequest = securetrading.Request()
strequest.update(refund)
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' => '[email protected]',
  'password' => 'Password1^',
);

$requestData = array(
  'requesttypedescriptions' => array('REFUND'),
  'sitereference' => 'test_site12345',
  'parenttransactionreference' => '1-2-345678',
  'currencyiso3a' => 'USD',
  'baseamount' => '1641'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "currencyiso3a": "USD",
  "baseamount": "1641"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["REFUND"],"sitereference":"test_site12345","parenttransactionreference":"1-2-345678","currencyiso3a":"USD","baseamount":"1641"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="REFUND">
    <billing>
      <amount currencycode="USD">1641</amount>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Field specification

Field Format Description

Submit one of these amounts

baseamount
XPath: /billing/amount
Numeric (13) The amount to be refunded in the customer’s currency (this includes the fee added as part of the Margin Rate Percentage calculation). This should be in base units with no commas or decimal points, so £10 would be 1000.

Note: When submitting the baseamount, you must also submit the associated currencyiso3a field.

dccbaseamount
XPath: /billing/dcc/amount
Numeric (13) The amount to be refunded in the merchant’s currency. This should be in base units with no commas or decimal points, so £10 would be 1000.

Note: When submitting the dccbaseamount, you must also submit the associated dcccurrencyiso3a field.

Submit one of these currencies

currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3) The customer’s currency in iso3a format. Click here for a full list of available currencies.

Required if the baseamount is submitted.

dcccurrencyiso3a
XPath: /billing/dcc/amount/@currencycode
Alpha (3) The merchant’s currency in iso3a format. Click here for a full list of available currencies.

Required if the dccbaseamount is submitted.

dccconversionrate
XPath: /billing/dcc/conversionrate
Numeric (255) The conversion rate originally used to calculate the amount in the customer’s currency (returned in the original CURRENCYRATE response).
dccconversionratesource
XPath: /billing/dcc/conversionratesource
Alphanumeric (255) The source of the original conversion rate returned from the DCC provider (returned in the original CURRENCYRATE response).
dccmarginratepercentage
XPath: /billing/dcc/marginratepercentage
Numeric (11) The percentage (4 decimal places) used as part of the CURRENCYRATE request to calculate the currency conversion fee, which is automatically appended to the amount in the customer’s currency, following calculation.
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 (returned in the original CURRENCYRATE response).
dccproviderdata
XPath: /billing/dcc/dccproviderdata
Alphanumeric (255) A unique string that contains information on the calculated conversion rate, returned directly from participating conversion rate providers (returned in the original CURRENCYRATE response).
dcctype
XPath: /billing/dcc/dcctype
Alpha (3) If submitted, this must be “DCC”.
parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
This field must contain the transaction reference of the AUTH request that you would like to refund.
requesttypedescriptions
XPath: /@type
Alpha (20) You must submit “REFUND”.
sitereference
XPath: /operation/sitereference
Alphanumeric
& underscore (50)
Identifies your site on the Trust Payments system.

If you do not know your site reference, please contact our Support Team.

 

Request REFUND
Partial refund

By submitting a baseamount OR dccbaseamount with a lower value than originally authorised, your system can process partial refunds. We will automatically recalculate the amount in the other currency and this will be returned in the response.

 

Response

The response returned will follow a similar structure to a standard REFUND response, with the addition of DCC-specific fields, as described below.

The DCC-specific fields returned will have the same values as in the initial CURRENCYRATE and AUTH requests, reflecting that the same conversion data has been applied.

Info
The dccratio value is calculated using the refund amount in the customer and merchant currencies. Because this value is calculated after the conversion has taken place, and the converted amount is rounded, the dccratio returned in the response may differ slightly from that used in the initial payment.

 

Field specification

Field Format Description
baseamount
XPath: /billing/amount
Numeric (13) The amount refunded in the customer’s currency (this includes the fee added as part of the Margin Rate Percentage calculation). This is in base units with no commas or decimal points, so £10 would be 1000.
dccbaseamount
XPath: /billing/dcc/amount
Numeric (13) The amount refunded in the merchant’s currency. This 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. Click here for a full list of available currencies.
dcccurrencyiso3a
XPath: /billing/dcc/amount/@currencycode
Alpha (3) The merchant’s currency in iso3a format. Click here for a full list of available currencies.
dccconversionrate
XPath: /billing/dcc/conversionrate
Numeric (255) The conversion rate originally used to calculate the amount in the customer’s currency.
dccconversionratesource
XPath: /billing/dcc/conversionratesource
Alphanumeric (255) The source of the original conversion rate returned from the DCC provider.
dccenabled
XPath: /billing/dcc/@enabled
Numeric (1) The value returned will be “1”, indicating the account used for processing this payment is enabled for DCC.
dccmarginratepercentage
XPath: /billing/dcc/marginratepercentage
Numeric (11) The percentage (4 decimal places) used as part of the CURRENCYRATE request to calculate the currency conversion fee, which is automatically appended to the amount in the customer’s currency, following calculation.
dccoffered
XPath: /billing/dcc/offered
Numeric (1) This value represents whether the REFUND was processed in the customer’s currency or the merchant’s currency:

1 – The customer was refunded in the customer’s currency.

3 – The customer was refunded in the merchant’s currency.

dccproviderdata
XPath: /billing/dcc/dccproviderdata
Alphanumeric (255) A unique string that contains information on the calculated conversion rate, returned directly from participating conversion rate providers.
dccratio
XPath: /billing/dcc/ratio
Numeric (255) The ratio between both amounts processed in the request in main units.
dcctype
XPath: /billing/dcc/dcctype
Alpha (3) This is returned as “DCC”.
parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
The transaction reference of the AUTH request refunded.
requesttypedescription
XPath: /@type
Alpha (20) This is returned as “REFUND”.

 


 

Option 2: Refund using new rate

 

Process overview

1
Perform a new CURRENCYRATE request.

Note: When performing a partial refund, you will need to submit a lower dccbaseamount in the request.

2
Perform a REFUND request, ensuring all DCC-specific fields returned in the new CURRENCYRATE response are submitted (see list below).
Info
As with standard REFUND requests, the submitted parenttransactionreference field must refer to the parent AUTH request being refunded (not the CURRENCYRATE request).

 

Request

The following is an example of a request to process a REFUND using a new conversion rate. This presumes you have already performed a new CURRENCYRATE request and are including the new data in the REFUND request (Refer to the field specification below for further information on these fields)


#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
refund= {
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "currencyiso3a": "USD",
  "baseamount": "1260",
  "dcctype": "DCC",
  "dccconversionrate": "1.2",
  "dccconversionratesource": "Rate Source",
  "dccmarginratepercentage": "2.5000",
  "dcccurrencyiso3a": "GBP",
  "dccbaseamount": "1050",
  "dccprovider": "Test Provider",
 
 "dccproviderdata": "01020304120021250373330603INR0803356200513800210875190000300124306MBB01"
}
  
strequest = securetrading.Request()
strequest.update(refund)
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' => '[email protected]',
  'password' => 'Password1^',
);

$requestData = array(
  'requesttypedescriptions' => array('REFUND'),
  'sitereference' => 'test_site12345',
  'parenttransactionreference' => '1-2-345678',
  'currencyiso3a' => 'USD',
  'baseamount' => '1260',
  'dcctype' => 'DCC',
  'dccconversionrate' => '1.2',
  'dccmarginratepercentage' => '2.5000',
  'dcccurrencyiso3a' => 'GBP',
  'dccbaseamount' => '1050'

  'requesttypedescriptions' => array('REFUND'),
  'sitereference' => 'test_site12345',
  'parenttransactionreference' => '1-2-345678',
  'currencyiso3a' => 'USD',
  'baseamount' => '1260',
  'dcctype' => 'DCC',
  'dccconversionrate' => '1.2',
  'dccconversionratesource' => 'Rate Source',
  'dccmarginratepercentage' => '2.5000',
  'dcccurrencyiso3a' => 'GBP',
  'dccbaseamount' => '1050',
  'dccprovider' => 'Test Provider',
 
 'dccproviderdata' => '01020304120021250373330603INR0803356200513800210875190000300124306MBB01'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "currencyiso3a": "USD",
  "baseamount": "1260",
  "dcctype": "DCC",
  "dccconversionrate": "1.2",
  "dccconversionratesource": "Rate Source",
  "dccmarginratepercentage": "2.5000",
  "dcccurrencyiso3a": "GBP",
  "dccbaseamount": "1050",
  "dccprovider": "Test Provider",
 
 "dccproviderdata": "01020304120021250373330603INR0803356200513800210875190000300124306MBB01"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["REFUND"],"sitereference":"test_site12345","parenttransactionreference":"1-2-345678","currencyiso3a":"USD","baseamount":"1260","dcctype":"DCC","dccconversionrate":"1.2","dccconversionratesource":"Rate Source","dccmarginratepercentage":"2.5000","dcccurrencyiso3a":"GBP","dccbaseamount":"1050","dccprovider":"Test Provider","dccproviderdata":"01020304120021250373330603INR0803356200513800210875190000300124306MBB01"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="REFUND">
    <billing>
      <amount currencycode="USD">1260</amount>
      <dcc type="DCC">
        <amount currencycode="GBP">1050</amount>
        <conversionrate>1.2</conversionrate>
        <conversionratesource>Rate Source</conversionratesource>
        <provider>Test Provider</provider>
<dccproviderdata>01020304120021250373330603INR0803356200513800210875190000300124306MBB015</dccproviderdata>
        <marginratepercentage>2.5000</marginratepercentage>
      </dcc>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Field specification

Field Format Description
baseamount
XPath: /billing/amount
Numeric (13) The amount to be refunded in the customer’s currency (this includes the fee added as part of the Margin Rate Percentage calculation). This should be in base units with no commas or decimal points, so £10 would be 1000.

dccbaseamount
XPath: /billing/dcc/amount
Numeric (13) The amount to be refunded in the merchant’s 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 customer’s currency in iso3a format. Click here for a full list of available currencies.
dcccurrencyiso3a
XPath: /billing/dcc/amount/@currencycode
Alpha (3) The merchant’s currency in iso3a format. Click here for a full list of available currencies.
dccconversionrate
XPath: /billing/dcc/conversionrate
Numeric (255) The conversion rate used to calculate the new amounts (returned in the new CURRENCYRATE response).
dccconversionratesource
XPath: /billing/dcc/conversionratesource
Alphanumeric (255) The source of the new conversion rate returned from the DCC provider (returned in the new CURRENCYRATE response).
dccmarginratepercentage
XPath: /billing/dcc/marginratepercentage
Numeric (11) The percentage used as part of the new CURRENCYRATE request, 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 (returned in the new CURRENCYRATE response).
dccproviderdata
XPath: /billing/dcc/dccproviderdata
Alphanumeric (255) A unique string that contains information on the calculated conversion rate, returned directly from participating conversion rate providers (returned in the new CURRENCYRATE response).
dcctype
XPath: /billing/dcc/dcctype
Alpha (3) You must submit “DCC”.
parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
This field must contain the transaction reference of the AUTH request that you would like to refund.
requesttypedescriptions
XPath: /@type
Alpha (20) You must submit “REFUND”.
sitereference
XPath: /operation/sitereference
Alphanumeric
& underscore (50)
Identifies your site on the Trust Payments system.

If you do not know your site reference, please contact our Support Team.

 

Response

The response returned will follow a similar structure to a standard REFUND response, with the addition of DCC-specific fields, as described below.

The DCC-specific fields returned will have the same values as in the new CURRENCYRATE request, reflecting that the new conversion data has been applied.

Field specification

Field Format Description
baseamount
XPath: /billing/amount
Numeric (13) The amount refunded in the customer’s currency (this includes the fee added as part of the Margin Rate Percentage calculation). This is in base units with no commas or decimal points, so £10 would be 1000.
dccbaseamount
XPath: /billing/dcc/amount
Numeric (13) The amount refunded in the merchant’s currency. This 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. Click here for a full list of available currencies.
dcccurrencyiso3a
XPath: /billing/dcc/amount/@currencycode
Alpha (3) The merchant’s currency in iso3a format. Click here for a full list of available currencies.
dccconversionrate
XPath: /billing/dcc/conversionrate
Numeric (255) The conversion rate used to calculate the new amounts (returned in the new CURRENCYRATE response).
dccconversionratesource
XPath: /billing/dcc/conversionratesource
Alphanumeric (255) The source of the new conversion rate returned from the DCC provider (returned in the new CURRENCYRATE response).
dccenabled
XPath: /billing/dcc/@enabled
Numeric (1) The value returned will be “1”, indicating the account used for processing this payment is enabled for DCC.
dccmarginratepercentage
XPath: /billing/dcc/marginratepercentage
Numeric (11) The percentage used as part of the new CURRENCYRATE request, 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) This value represents whether the REFUND was processed in the customer’s currency or the merchant’s currency:

1 – The customer was refunded in the customer’s currency.

3 – The customer was refunded in the merchant’s currency.

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 participating conversion rate providers.
dccratio
XPath: /billing/dcc/ratio
Numeric (255) The ratio between both amounts processed in the request in main units.
dcctype
XPath: /billing/dcc/dcctype
Alpha (3) This is returned as “DCC”.
parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
The transaction reference of the AUTH request refunded.
requesttypedescription
XPath: /@type
Alpha (20) This is returned as “REFUND”.

 


 

Option 3: Refund using custom rule

 

Process overview

Your conversion rate provider may require you to use a new conversion rate when performing a DCC refund after a pre-specified number of days have passed since the parent AUTH was processed (we’ll refer to this as x days). To address this, our Support team can configure your account to behave in the following way:

To have this configured for your account or to find out further information, please contact our Support Team.

 

Request

The request has the same structure as a standard REFUND request, except your system will also need to resubmit either the customer currency fields OR the merchant currency fields, as shown below:

 

Either submit the following two customer currency fields in the request:

currencyiso3a The customer’s currency.
baseamount The amount in the customer’s currency.

 

Or, if you prefer to submit the merchant currency fields in the request:

dcccurrencyiso3a The merchant’s currency.
dccbaseamount The amount in the merchant’s currency.

 

Info
As with standard REFUND requests, the submitted parenttransactionreference field must refer to the parent AUTH request being refunded (not the CURRENCYRATE request).
Info
This implementation supports both partial refunds and full refunds. Simply submit a lower baseamount OR dccbaseamount and we will calculate the value in the other currency.

 


#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
refund= {
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "currencyiso3a": "USD",
  "baseamount": "1641"
}
  
strequest = securetrading.Request()
strequest.update(refund)
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' => '[email protected]ample.com',
  'password' => 'Password1^',
);

$requestData = array(
  'requesttypedescriptions' => array('REFUND'),
  'sitereference' => 'test_site12345',
  'parenttransactionreference' => '1-2-345678',
  'currencyiso3a' => 'USD',
  'baseamount' => '1641'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "currencyiso3a": "USD",
  "baseamount": "1641"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["REFUND"],"sitereference":"test_site12345","parenttransactionreference":"1-2-345678","currencyiso3a":"USD","baseamount":"1641"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="REFUND">
    <billing>
      <amount currencycode="USD">1641</amount>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

 


Option 4: Refund using MyST

 

It is also possible to refund DCC payments by using MyST. If the payment was processed using the customer’s currency (shown within MyST as dccoffered = 1), we automatically perform a new CURRENCYRATE request in order to refund the customer using an up-to-date conversion rate. MyST also supports the ability to process partial refunds.

User
The ability to refund transactions using MyST is limited to users with certain user roles (Click here for information on different user roles).

 

Additional notes

 

Updating DCC authorisations

It is possible to perform updates on DCC payments prior to settlement, by submitting a TRANSACTIONUPDATE request.

It is not possible to change the currency of the payment after it has been authorised by the acquiring bank.

Warning
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 (e.g. by updating the settlement date) may result in the customer paying the wrong amount and may invalidate your agreement with the conversion rate provider or acquirer.

 

Partial settlement

You can use a TRANSACTIONUPDATE request to update the settle amount of an authorised DCC payment. This can be used to settle a transaction for a lower value than was initially authorised. The remaining funds will be released by the card issuer once the authorisation code has expired (usually approx. 7 days).

The new settle amount is specified in the settlebaseamount field (this represents the amount in the customer’s currency). It must be lower than the total amount authorised in the customer’s currency.

If a partial settlement request has been processed and the customer has made the payment in the customer’s currency, the original conversion rate of the transaction is used to calculate the respective settle amount in the merchant’s currency.


#!/usr/bin/python
import securetrading
   
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
   
update = {
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
   },
   "updates":{"settlebaseamount":"960"}
}
   
strequest = securetrading.Request()
strequest.update(update)
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' => '[email protected]',
  'password' => 'Password1^',
);
 
$requestData = array(
'requesttypedescriptions' => array('TRANSACTIONUPDATE'),
'filter' => array(
  'sitereference' => array(array('value' => 'test_site12345')),
  'transactionreference' => array(array('value' => '1-2-3'))
),
'updates' => array('settlebaseamount' => '960')
);
 
$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());
 
?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
},
"updates":{"settlebaseamount":"960"}
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["TRANSACTIONUPDATE"],"filter":{"sitereference":[{"value":"test_site12345"}],"transactionreference":[{"value":"1-2-3"}]},"updates":{"settlebaseamount":"960"}}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="TRANSACTIONUPDATE">
    <filter>
      <transactionreference>1-2-3</transactionreference>
      <sitereference>test_site12345</sitereference>
    </filter>
    <updates>
      <settlement>
        <settlebaseamount>960</settlebaseamount>
      </settlement>
    </updates>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Using your own DCC provider

If preferred, you can perform your own currency conversion without performing a CURRENCYRATE request or refer to a pre-existing parent CURRENCYRATE request. To do this, submit an AUTH request (as outlined on this page), while ensuring all the required fields are submitted using valid conversion rate details from your DCC provider.

Warning
It is your responsibility to calculate the amounts based on the conversion rates from your DCC provider, and to ensure the amounts and currencies you submit in the AUTH request are valid.
URL
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.

 

Processing payments

Warning
The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.

If you are unsure, please contact our Support Team for assistance.

 

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

This page explains how to utilise DCC to provide the customer a choice between two currencies prior to completing the payment:

 

What will the customer see?

  • During the checkout process, your website prompts the customer for their address and card details.
  • On the next page, your checkout displays a choice of two currencies, with which the customer can choose to complete the payment.
  • Once the customer chooses their preferred currency, they can click “Pay” and complete the payment.

 

How does it work behind the scenes?

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.

 

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

 

Requirements

Before you get started, please be aware of the following restrictions:

We support DCC for Visa and Mastercard-branded payment methods.
(The customer’s card must support DCC payments)

 


 

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 = "[email protected]"
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",
  "expirydate": "12/2020",
  "securitycode": "123"
}

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' => '[email protected]',
  'password' => 'Password1^',
);

$requestData = array(
  'sitereference' => 'test_site12345', 
  'requesttypedescriptions' => array('CURRENCYRATE'),
  'accounttypedescription' => 'CURRENCYRATE',
  'dcctype' => 'DCC',
  'dccbaseamount' => '1050',
  'dcccurrencyiso3a' => 'GBP',
  'orderreference' => 'My_Order_123',
  'pan' => '4111111111111111',
  'expirydate' => '12/2020',
  'securitycode' => '123'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"[email protected]",
"version": "1.00",
"request": [{
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["CURRENCYRATE"],
  "accounttypedescription": "CURRENCYRATE",
  "dcctype": "DCC",
  "dccbaseamount": "1050",
  "dcccurrencyiso3a": "GBP",
  "orderreference": "My_Order_123",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"sitereference":"test_site12345","requesttypedescriptions":["CURRENCYRATE"],"accounttypedescription":"CURRENCYRATE","dcctype":"DCC","dccbaseamount":"1050","dcccurrencyiso3a":"GBP","orderreference":"My_Order_123","pan":"4111111111111111","expirydate":"12\/2020","securitycode":"123"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</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>
	  <expirydate>12/2020</expirydate>
	  <securitycode>123</securitycode>
	</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. Click here for a full list of available currencies.
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.
orderreference
XPath: /merchant/orderreference
Alphanumeric including
symbols (255)
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.
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)
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 'response': [{
            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 '[email protected]'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A3579dkvx"
  ["version"] => string(4) "1.00"
  ["response"] => 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) "[email protected]"
    }
  }
}
{"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":"[email protected]"}],"secrand":"zO9"}
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
  <requestreference>X881587174</requestreference>
  <response type="CURRENCYRATE">
    <merchant>
      <orderreference>My_Order_123</orderreference>
      <merchantnumber>00000000</merchantnumber>
      <operatorname>[email protected]</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

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

Click here for a full list of available currencies.

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. Click here for a full list of available currencies.
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.
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) 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.
This will be in ISO2A format. Click here for a full list of country codes.
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).

Warning
It is imperative that all transactions, which use the currency conversions provided by the conversion rate provider, are settled before the expirytimestamp (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":
  {
    "accounttypedescription":"ECOM",
    "baseamount":"1050",
    "currencyiso3a":"GBP",
    "sitereference":"test_site12345",
    "parenttransactionreference": "23-71-101",
    "dcctype": "DCC",
    "dccoffered": "1",
    "dccconversionrate": "1.5626",
    "dcccurrencyiso3a": "GBP",
    "dccbaseamount": "1050",
  },
  "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.

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

Click here for a full list of available currencies.

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.

Click here for a full list of available currencies.

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) This value represents whether the customer has chosen to pay in the customer’s currency or the merchant’s currency.

1 – Customer has chosen to pay in the customer’s currency.

2 – Customer will pay using the merchant’s currency because DCC was not offered (e.g. the merchant did not provide the customer the choice between currencies and/or the CURRENCYRATE request encountered an error).

3 – The customer has chosen to pay in the merchant’s currency.

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

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.

 

investors in people logo   pci - security standards council logo

TRUST Payments LTD, No.1 Royal Exchange, London, EC3V 3DG.
A company registered in England and Wales with Company Number 04591066. VAT Number 756265116