Processing Dynamic Currency Conversion (DCC) payments using our API

  The following process requires the implementation of a solution that utilises our Webservices API to perform the currency conversion and our JavaScript Library to process the payment.

Utilising Webservices API involves the direct handling of sensitive cardholder data on your server and, as such, is subject to stricter PCI compliance standards. Please ensure you have obtained the necessary certification before proceeding.

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

  Before proceeding, please ensure you have met all requirements for processing DCC
Click here to open this information in a new tab

Dynamic Currency Conversion (DCC) is a feature that allows customers to complete the payment in their currency or your local currency. The amounts are calculated using a third-party conversion rate provider with up-to-date conversion rates.

 

Process overview

  In our DCC documentation, we refer to the customer’s currency and the merchant’s currency. These are defined as follows:

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

The DCC payment flow can be split into three main parts, as shown below:

1. Submit CURRENCYRATE request

Your checkout form will need to prompt the customer for their card and billing details (this process follows the standard payment flow). Submit these details, along with the transaction amount, in a CURRENCYRATE request, using our Webservices API.

2. Receive CURRENCYRATE response

We will contact your conversion rate provider to obtain the latest conversion rate between the customer’s currency and the merchant’s currency. We will return a CURRENCYRATE response that contains the amount in both the customer’s currency and merchant’s currency.

3. Process transaction

You must then offer the customer a choice between using either the customer’s currency or the merchant’s currency to complete the payment. You will need to ensure your checkout form has been modified to reference our JavaScript Library, and that the payload submitted within the JWT includes additional fields regarding the currency conversion performed.

 

  Please be aware of the following distinctions:

  • When we discuss the customer’s currency, we are referring to the currency associated with their card. This often correlates to the country the card was issued in, and as such, you may find customers are more accustomed to processing payments in this currency.
  • When we discuss the merchant’s currency, this is the local currency assigned to your account with us. Local customers to your business may be more accustomed to processing payments in this currency.
  • As part of the DCC process, you will need to provide the customer with a choice between the customer’s currency and your local merchant currency, prior to processing the payment. We refer to the currency chosen by the customer as the final currency.

 

1. Submit CURRENCYRATE request

The CURRENCYRATE request is used to determine both the customer’s currency and the amount in the customer’s currency.

 

Example request

The following is an example of a CURRENCYRATE request.

Python PHP cURL Raw JSON Raw XML
#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

currencyrate = {
"sitereference": "test_site12345",
"requesttypedescriptions": ["CURRENCYRATE"],
"accounttypedescription": "CURRENCYRATE",
"dcctype": "DCC",
"dccbaseamount": "1050",
"dcccurrencyiso3a": "GBP",
"orderreference": "My_Order_123",
"pan": "4111111111111111",
"expirydate": "12/2020",
"securitycode": "123"
}

strequest = securetrading.Request()
strequest.update(currencyrate)
stresponse = st.process(strequest) #stresponse contains the transaction response

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

 

Field specification

  Field Format Description
table-required.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) This must be submitted as “CURRENCYRATE”.
table-required.png 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.
table-required.png dcccurrencyiso3a
XPath: /billing/dcc/amount/@currencycode
Alpha (3)

The merchant’s currency in iso3a format.

Click here for a full list of available currencies.

table-required.png dcctype
XPath: /billing/dcc/dcctype
Alpha (3) The value submitted must be “DCC”.
table-required.png expirydate
XPath: /billing/payment/expirydate
Date MM/YYYY The expiry date printed on the card.
table-optional.png orderreference
XPath: /merchant/orderreference
Alphanumeric including
symbols (25)

Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction.

Your unique order reference that can be stored on the Trust Payments system.
table-required.png pan
XPath: /billing/payment/pan
Numeric (12-19) This is the long number printed on the front of the customer’s card.
table-required.png requesttypedescriptions
XPath: /@type
Alpha (20) You must submit “CURRENCYRATE”, as shown in the request example.
table-required.png 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.

table-required.png 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

Python PHP Raw JSON Raw XML
{
u 'requestreference': u 'A0bxh87wt',
u 'version': u '1.00',
u 'responses': [{
u 'transactionstartedtimestamp': u '2017-04-21 09:26:46',
u 'dcccurrencyiso3a': u 'GBP',
u 'livestatus': u '0',
u 'englishacquirertypedescription': u 'Acquirer',
u 'iin': u '411111111',
u 'dcctype': u 'DCC',
u 'dccbaseamount': u '1050',
u 'errorcode': u '0',
u 'orderreference': u 'My_Order_123',
u 'dccconversionratesource': u 'Conversion rate source',
u 'merchantnumber': u '00000000',
u 'dccexpirytimestamp': u '2017-04-25 14:26:00',
u 'transactionreference': u '23-71-101',
u 'paymenttypedescription': u 'VISA',
u 'baseamount': u '1641',
u 'dccmarginratepercentage': u '2.5000',
u 'accounttypedescription': u 'CURRENCYRATE',
u 'acquirerresponsecode': u '0',
u 'requesttypedescription': u 'CURRENCYRATE',
u 'acquirerresponsemessage': u 'Success',
u 'currencyiso3a': u 'USD',
u 'maskedpan': u '411111######1111',
u 'errormessage': u 'Ok',
u 'issuercountryiso2a': u 'ZZ',
u 'dccconversionrate': u '1.5626',
u 'operatorname': u 'webservices@example.com'
}]
}

After you have received the CURRENCYRATE response, check if the currency returned in the currencyiso3a field is different to that in the dcccurrencyiso3a field.

If currencies differ: If currencies are the same:

Offer the customer a choice between processing the payment in the customer’s currency or the merchant’s currency.

Note: Select acquirers may require certain information to be displayed to the customer on the currency choice page, such as the conversion rate used and the name of the conversion rate provider. Please be sure to check with your acquiring bank that you are displaying all the information required.

Prompt the customer to confirm they would like to proceed before processing the payment.

 

Field specification

  It is imperative that all transactions, which use the currency conversions provided by the conversion rate provider, are settled before the dccexpirytimestamp (returned in the CURRENCYRATE response).

Failing to do so, by deferring the settlement date, may result in the customer paying an incorrect amount and invalidate your agreement with the conversion rate provider or acquirer.

  Field Format Description
table-returned.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) This is returned as “CURRENCYRATE”.
table-conditional.png acquirerresponsecode
XPath: /acquirerresponsecode
Alphanumeric (255)

Used by the DCC provider to indicate the outcome of the request.

This will vary depending on your acquiring bank. Please contact your bank for further information.

table-conditional.png acquirerresponsemessage
XPath: /acquirerresponsemessage
Alphanumeric (255)
table-returned.png 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.
table-returned.png 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.

table-returned.png 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.
table-returned.png dccconversionrate
XPath: /billing/dcc/conversionrate
Numeric (255) The conversion rate used to calculate the amount in the customer’s currency.
table-returned.png dccconversionratesource
XPath: /billing/dcc/conversionratesource
Alphanumeric (255) The source of the conversion rate returned from the DCC provider.
table-returned.png dcccurrencyiso3a
XPath: /billing/dcc/amount/@currencycode
Alpha (3)

The merchant’s currency in iso3a format.

Click here for a full list of available currencies.

table-returned.png 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
table-returned.png 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.
table-conditional.png dccprovider
XPath: /billing/dcc/provider
Alphanumeric (255)

The name of the third-party DCC provider that has provided the conversion rate used in the payment.

This field is returned when the data has been provided by the conversion rate provider.

table-conditional.png dccproviderdata
XPath: /billing/dcc/dccproviderdata
Alphanumeric (255)

A unique string that contains information on the calculated conversion rate, returned directly from certain conversion rate providers.

This field is returned when the data has been provided by the conversion rate provider.

table-returned.png dcctype
XPath: /billing/dcc/dcctype
Alpha (3) This is returned as “DCC”.
table-returned.png 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.
table-returned.png 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.
table-returned.png 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.

table-returned.png 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.
table-returned.png paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) Payment method (e.g. “VISA” or “MASTERCARD”).
table-returned.png requesttypedescription
XPath: /@type
Alpha (20) This is returned as “CURRENCYRATE”.
table-returned.png transactionreference
XPath: /transactionreference
Alphanumeric including
hyphens (25)
A unique reference for the transaction assigned by Trust Payments.

 

3. Process transaction

After you have received the CURRENCYRATE response and prompted the customer to choose the final currency, the customer will need to click “Pay” on your checkout form in order to complete the payment. You will need to ensure your checkout form has been updated to reference our JavaScript Library, and that the payload submitted as part of the JWT has been updated to include additional fields regarding the currency conversion (as shown below).

  It is imperative that all transactions, which use the currency conversions provided by the conversion rate provider, are settled before the 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 example:)

{
"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",
"requesttypedescriptions":["THREEDQUERY","AUTH"]
},
"iat":1559033849,
"iss":"jwt.user"
}

You will need to check the response JWT to confirm that the payment was successful. As with a standard payment, you will need to pay particular attention to the errorcode and settlestatus fields.

  Receipt text

Select acquirers may require certain information to be displayed to the customer in a receipt, following a transaction, such as the conversion rate used and the name of the conversion rate provider. Please be sure to check with your acquiring bank that you are displaying all the information required.

 

Field specification

  Field Format Description
table-required.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) This must be submitted as “ECOM” (e-commerce).
table-required.png 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.
table-required.png currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3)

The final currency.

Click here for a full list of available currencies.

table-required.png 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.
table-required.png dccconversionrate
XPath: /billing/dcc/conversionrate
Numeric (255) The conversion rate used to calculate the amount in the customer’s currency.
table-optional.png dccconversionratesource
XPath: /billing/dcc/conversionratesource
Alphanumeric (255) The source of the conversion rate returned from the DCC provider.
table-required.png dcccurrencyiso3a
XPath: /billing/dcc/amount/@currencycode
Alpha (3)

The merchant’s currency in iso3a format.

Click here for a full list of available currencies.

table-optional.png 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.
table-required.png 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.

table-optional.png 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.
table-optional.png 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.
table-required.png dcctype
XPath: /billing/dcc/dcctype
Alpha (3) The value submitted must be “DCC”.
table-required.png 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.

table-required.png requesttypedescriptions List This must be set to [“THREEDQUERY”,”AUTH”].
table-required.png 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.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request