Contents

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^ 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",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123"
}]}'

 

Field specification

Key

Field name Type Length Request Description
accounttypedescription Alpha 20 This must be submitted as “CURRENCYRATE”.
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”.
expirydate Date MM/YYYY 7 The expiry date printed on the card.
orderreference Alphanumeric including
symbols
255 Your unique order reference that can be stored on Secure Trading’s system.
pan Numeric 12-19 This is the long number printed on the front of the customer’s card.
requesttypedescriptions  Alpha 20 You must submit “CURRENCYRATE”, as shown in the request example.
securitycode 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 Secure Trading, 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 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.

 

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","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 request.

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

Key

Field name Type Length Request Description
accounttypedescription Alpha 20 This must be submitted as “ECOM” (e-commerce).
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.
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.

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 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.
dcctype Alpha 3 The value submitted must be “DCC”.
parenttransactionreference Alphanumeric including hyphen 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
Alphanumeric 50 Unique reference that identifies your Secure Trading 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.