Contents

Processing payments

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

 

Our Javascript library handles the card details without them being passed to your server.

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 AUTH

You must then offer the customer a choice between using either the customer’s currency or the merchant’s currency to complete the payment. Submit an AUTH request for the amount and currency chosen by the customer (we call this the final currency).

 

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. In order to achieve this, it is crucial that the following three fields are submitted in every CURRENCYRATE request:

dcccurrencyiso3a The merchant’s currency.
dccbaseamount The amount in the merchant’s currency.
cachetoken Used to retrieve the customer’s card details, and in turn the currency associated with their card.

 

 

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",
  "cachetoken": "token_posted_by_st.js"
}

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',
  'cachetoken' => 'token_posted_by_st.js'
);

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

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/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",
  "cachetoken": "token_posted_by_st.js"
}]}'

 

Field specification

Key

Field name Type Length Request Description
accounttypedescription Alpha 20 This must be submitted as “CURRENCYRATE”.
cachetoken Alphanumeric including hyphen Variable This contains a reference to the customer’s payment details. This is the value posted to your servers after the customer has entered their payment details into your HTML form and clicked “Submit”.
dccbaseamount 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 Alpha 3 The merchant’s currency in iso3a format. Click here for a full list of available currencies.
dcctype Alpha 3 The value submitted must be “DCC”.
orderreference Alphanumeric including
symbols
255 Your unique order reference that can be stored on Secure Trading’s system.
requesttypedescriptions  Alpha 20 You must submit “CURRENCYRATE”, as shown in the request example.
sitereference Alphanumeric including
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.

 

This information, along with the original merchant’s currency and amount, is returned in the following fields:

currencyiso3a Customer’s currency.
baseamount The amount in the customer’s currency.
dcccurrencyiso3a The merchant’s currency.
dccbaseamount The amount in the merchant’s currency.

Note: If the customer’s card has been issued in the same country as you, the customer currency and amount returned may hold the same value as the merchant currency and amount.

 

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 '[email protected]'
    }]
}
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) "[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",
     "maskedpan": "411111######1111",
     "errormessage": "Ok",
     "issuercountryiso2a": "ZZ",
     "dccconversionrate": "1.5626",
     "operatorname": "[email protected]"
  }],
  "secrand": "zO9"
}

 

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.

Key

Field name Type Length Response Description
accounttypedescription Alpha 20

This is returned as “CURRENCYRATE”.
acquirerresponsecode Alphanumeric 255 Used by the DCC provider to indicate the outcome of the request.
acquirerresponsemessage Alphanumeric 255
baseamount 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 Alpha 3 The customer’s currency in iso3a format. This is determined by analysing the card details submitted in the cachetoken.

Click here for a full list of available currencies.

dccbaseamount 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 Numeric 255 The conversion rate used to calculate the amount in the customer’s currency.
dccconversionratesource Alphanumeric 255 The source of the conversion rate returned from the DCC provider.
dcccurrencyiso3a Alpha 3 The merchant’s currency in iso3a format. Click here for a full list of available currencies.
dccexpirytimestamp Date Time
“YYYY-MM-DD HH:MM:SS”
19 The expiry date of the CURRENCYRATE look-up.
Subsequent AUTH requests using the CURRENCYRATE as a parent must settle before this date and time.
Format: YYYY-MM-DD HH:MM:SS
dccmarginratepercentage 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.
dccproviderdata Alphanumeric 255   A unique string that contains information on the calculated conversion rate, returned directly from certain conversion rate providers.
dcctype Alpha 3 This is returned as “DCC”.
englishacquirertypedescription 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 Numeric 9 Issuer Identification Number (IIN) – This is the first 9 digits from the start of the customer’s card number.
issuercountryiso2a 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 Alphanumeric including “#” 12-19 The customer’s card number. This is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
paymenttypedescription Alpha 20 Payment method (e.g. “VISA” or “MASTERCARD”).
requesttypedescription  Alpha 20 This is returned as “CURRENCYRATE”.
transactionreference Alphanumeric including
hyphens
 25 A unique reference for the transaction assigned by Secure Trading.

 


 

3. Process AUTH

 

AUTH request

After you have received the CURRENCYRATE response and prompted the customer to choose the final currency, you will need to submit an AUTH request in order to process the payment. The request has a similar structure to a standard AUTH request, the main differences being that you must submit additional DCC fields that were returned in the CURRENCYRATE response.

The field specification that can be found after the code examples will list all the required fields for the request, but before proceeding, please ensure you understand the following fields, which are especially important as they are used to determine the currency in which the payment is to be processed.

dccoffered This value represents whether the customer has chosen to pay using the customer’s currency or the merchant’s currency.

1 – Customer has chosen to pay in the customer’s currency.
2 – An error has occurred that has prevented the customer from paying in the customer’s currency (e.g. the CURRENCYRATE response returned an error), so they are completing the payment in the merchant’s currency instead.
3 – Customer has chosen to pay in the merchant’s currency.

dcccurrencyiso3a The merchant’s currency.
dccbaseamount The amount in the merchant’s currency.
currencyiso3a The final currency (the currency the customer chose, between either the merchant’s currency or customer’s currency).
baseamount The amount in the final currency.

 

Field specification
Full field specification table can be found below the examples.

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.

 

Example request


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "USD",
  "baseamount": "1641",
  "orderreference": "My_Order_123",
  "parenttransactionreference": "23-71-101",
  "dcctype": "DCC",
  "dccoffered": "1",
  "dccconversionrate": "1.5626",
  "dcccurrencyiso3a": "GBP",
  "dccbaseamount": "1050",
  "orderreference": "My_Order_123",
  "cachetoken": "token_posted_by_st.js"
}

strequest = securetrading.Request()
strequest.update(auth)
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('AUTH'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'USD',
  'baseamount' => '1641',
  'orderreference' => 'My_Order_123',
  'parenttransactionreference' => '23-71-101',
  'dcctype' => 'DCC',
  'dccoffered' => '1',
  'dccconversionrate' => '1.5626',
  'dcccurrencyiso3a' => 'GBP',
  'dccbaseamount' => '1050',
  'orderreference' => 'My_Order_123',
  'cachetoken' => 'token_posted_by_st.js'
);

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

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"[email protected]",
"version": "1.00",
"request": [{
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "USD",
  "baseamount": "1641",
  "orderreference": "My_Order_123",
  "parenttransactionreference": "23-71-101",
  "dcctype": "DCC",
  "dccoffered": "1",
  "dccconversionrate": "1.5626",
  "dcccurrencyiso3a": "GBP",
  "dccbaseamount": "1050",
  "orderreference": "My_Order_123",
  "cachetoken": "token_posted_by_st.js"
}]}'

 

AUTH response

You will need to check the AUTH response returned 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. This is explained in greater detail on our best practices page.

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.


{
  u 'requestreference': u 'A0bxh87wt',
    u 'version': u '1.00',
    u 'responses': [{
        u 'transactionstartedtimestamp': u '2017-04-21 10:08:49',
        u 'retrievalreferencenumber': u '711110230101',
        u 'parenttransactionreference': u '23-71-101',
        u 'stan': u '230101',
        u 'dcccurrencyiso3a': u 'GBP',
        u 'livestatus': u '0',
        u 'merchantcategorycode': u '1234',
        u 'dccenabled': u '1',
        u 'settleduedate': u '2017-04-21',
        u 'dcctype': u 'DCC',
        u 'dccratio': u '0.6398537477148080438756855576',
        u 'dccbaseamount': u '1050',
        u 'errorcode': u '0',
        u 'baseamount': u '1641',
        u 'dccconversionratesource': u 'Conversion rate source',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'merchantcity': u 'sdf',
        u 'transactionreference': u '23-67-101',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'orderreference': u 'My_Order_123',
        u 'dccmarginratepercentage': u '2.5000',
        u 'accounttypedescription': u 'ECOM',
        u 'acquirerresponsecode': u '00',
        u 'requesttypedescription': u 'AUTH',
        u 'acquirerresponsemessage': u 'Approved or completed Successfully',
        u 'securityresponsesecuritycode': u '2',
        u 'currencyiso3a': u 'USD',
        u 'authcode': u '00001',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'dccoffered': u '1',
        u 'maskedpan': u '411111######1111',
        u 'dccconversionrate': u '1.5626',
        u 'securityresponseaddress': u '0',
        u 'securityresponsepostcode': u '0',
        u 'issuercountryiso2a': u 'ZZ',
        u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A3579dkvx"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [0] => array(39) {
      ["transactionstartedtimestamp"] => string(19) "2017-04-21 10:08:49"
      ["retrievalreferencenumber"] => string(12) "711110230101"
      ["parenttransactionreference"] => string(9) "23-71-101"
      ["stan"] => string(6) "230101"
      ["dcccurrencyiso3a"] => string(3) "GBP"
      ["livestatus"] => string(1) "0"
      ["merchantcategorycode"] => string(4) "1234"
      ["dccenabled"] => string(1) "1"
      ["settleduedate"] => string(10) "2017-04-21"
      ["dcctype"] => string(3) "DCC"
      ["dccratio"] => string(30) "0.6398537477148080438756855576"
      ["dccbaseamount"] => string(4) "1050"
      ["errorcode"] => string(1) "0"
      ["baseamount"] => string(4) "1641"
      ["dccconversionratesource"] => string(22) "Conversion rate source"
      ["merchantnumber"] => string(8) "00000000"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["merchantcity"] => string(3) "sdf"
      ["transactionreference"] => string(9) "23-67-101"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["orderreference"] => string(12) "My_Order_123"
      ["dccmarginratepercentage"] => string(6) "2.5000"
      ["accounttypedescription"] => string(4) "ECOM"
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(4) "AUTH"
      ["acquirerresponsemessage"] => string(4) "Approved or completed Successfully"
      ["securityresponsesecuritycode"] => string(1) "2"
      ["currencyiso3a"] => string(3) "USD"
      ["authcode"] => string(6) "000001"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["dccoffered"] => string(1) "1"
      ["maskedpan"] => string(16) "411111######1111"
      ["dccconversionrate"] => string(6) "1.5626"
      ["securityresponseaddress"] => string(1) "0"
      ["securityresponsepostcode"] => string(1) "0"
      ["issuercountryiso2a"] => string(2) "ZZ"
      ["settlestatus"] => string(1) "0"
    }
  }
}
{
  "requestreference": "W23-fjgvn3d8",
  "version": "1.00",
  "response": [{
    "transactionstartedtimestamp": "2017-04-21 10:08:49",
    "retrievalreferencenumber": "711110230101",
    "parenttransactionreference": "23-71-101",
    "stan": "230101",
    "dcccurrencyiso3a": "GBP",
    "livestatus": "0",
    "merchantcategorycode": "1234",
    "dccenabled": "1",
    "settleduedate": "2017-04-21",
    "dcctype": "DCC",
    "dccratio": "0.6398537477148080438756855576",
    "dccbaseamount": "1050",
    "errorcode": "0",
    "baseamount": "1641",
    "dccconversionratesource": "Conversion rate source",
    "merchantnumber": "00000000",
    "merchantcountryiso2a": "GB",
    "merchantcity": "sdf",
    "transactionreference": "23-67-101",
    "merchantname": "Test Merchant",
    "paymenttypedescription": "VISA",
    "orderreference": "My_Order_123",
    "dccmarginratepercentage": "2.5000",
    "accounttypedescription": "ECOM",
    "acquirerresponsecode": "00",
    "requesttypedescription": "AUTH",
    "acquirerresponsemessage": "Approved or completed Successfully",
    "securityresponsesecuritycode": "2",
    "currencyiso3a": "USD",
    "authcode": "000001",
    "errormessage": "Ok",
    "operatorname": "[email protected]",
    "dccoffered": "1",
    "maskedpan": "411111######1111",
    "dccconversionrate": "1.5626",
    "securityresponseaddress": "0",
    "securityresponsepostcode": "0",
    "issuercountryiso2a": "ZZ",
    "settlestatus": "0"
  }],
  "secrand": "p6h"
}

 

Field specification

Key

Field name Type Length Request Response Description
accounttypedescription Alpha 20

 This must be submitted as “ECOM” (e-commerce). This is returned in the response.
baseamount 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.

Click here for a full list of available currencies.

cachetoken Alphanumeric including hyphen Variable This is the same cachetoken as submitted in the CURRENCYRATE request.
currencyiso3a Alpha 3 The final currency.

Click here for a full list of available currencies.

dccbaseamount 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 Numeric 255 The conversion rate used to calculate the amount in the customer’s currency.
dccconversionratesource Alphanumeric 255 The source of the conversion rate returned from the DCC provider.
dcccurrencyiso3a Alpha 3 The merchant’s currency in iso3a format.

Click here for a full list of available currencies.

dccenabled Numeric 1 Indicates if your account is configured for DCC:
1= Yes
0 = No
dccmarginratepercentage 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 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 – An error has occurred which has prevented the customer from paying in the customer’s currency (e.g. the CURRENCYRATE response returned an error), so they are paying in the merchant’s currency instead.

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

dccprovider Alphanumeric 255   The name of the third-party DCC provider that has provided the conversion rate used in the payment.
dccproviderdata Alphanumeric 255    A unique string that contains information on the calculated conversion rate, returned directly from certain conversion rate providers.
dccratio Numeric 255 The ratio between both amounts processed in the request in main units.
dcctype Alpha 3 The value submitted must be “DCC”. This is returned in the response.
issuercountryiso2a 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 Alphanumeric including “#” 12-19 The customer’s card number. This is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
parenttransactionreference Alphanumeric including hyphen 25 Retrieve the transactionreference value from the CURRENCYRATE response, and submit this in the parenttransactionreference field in the subsequent AUTH request. This value will be returned in the AUTH response in the parenttransactionreference field.

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.

paymenttypedescription Alpha 20 Payment method (e.g. “VISA” or “MASTERCARD”).
requesttypedescriptions  Alpha 20 You must submit “AUTH”, as shown in the request example.

*The field ‘requesttypedescription’ is returned instead e.g. “requesttypedescription”:”AUTH”

transactionreference Alphanumeric including
hyphens
 25 A unique reference for the transaction assigned by Secure Trading. You will need to store this reference in order to perform updates or a refund, at a later time.

 

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.