Contents

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]',
  '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.

 

Transaction updates

 

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.

 

After processing requests and transactions with us, you can update some of the details at a later time by submitting a TRANSACTIONUPDATE request.

 

Process overview

Here are some examples of the updates that can be performed using this feature:

 

Requirements

You can only perform updates on requests of the following types:

Info
You can only update AUTH and REFUND requests when they are in a pending settlement status (‘0’, ‘1’ or ‘2’) and NOT when in cancelled (‘3’) or settled (‘100’) status. Click here for further information on possible settle status values.

 

Walkthrough

You have previously processed a successful AUTH (with transactionreference “1-2-3”) on your site (with Site Reference “test_site12345”). It has a settlestatus of “1”, meaning it will be settled automatically within 24 hours. You wish to update the settlestatus to “2”, which will suspend the Settlement of funds to your bank account.

Step 1: Your system submits a TRANSACTIONUPDATE request to Trust Payments, including:


#!/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":{"settlestatus":"2"}
}
  
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('settlestatus' => '2')
);

$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":{"settlestatus":"2"}
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["TRANSACTIONUPDATE"],"filter":{"sitereference":[{"value":"test_site12345"}],"transactionreference":[{"value":"1-2-3"}]},"updates":{"settlestatus":"2"}}]}
<?xml version="1.0" encoding="utf-8"?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="TRANSACTIONUPDATE">
    <filter>
     <sitereference>test_site12345</sitereference>
     <transactionreference>1-2-3</transactionreference>
    </filter>
    <updates>
     <settlement>
      <settlestatus>2</settlestatus>
     </settlement>
    </updates>
  </request>
</requestblock>

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

 

Info

When performing a single TRANSACTIONUPDATE request:

  • You can only update one transaction. (Updating multiple transactions necessitates one TRANSACTIONUPDATE request per transaction)
  • You can update multiple fields in a single transaction by using a single TRANSACTIONUPDATE request.

Trust Payments receives and interprets the TRANSACTIONUPDATE request and performs the updates on the specified transaction, providing the request submitted was valid (otherwise returns an error).

Step 2: Your system receives and interprets a TRANSACTIONUPDATE response and updates your records, as appropriate. Your system should ensure the error code value returned is “0”, indicating a successful update.

The AUTH “1-2-3” on site “test_site12345” has now been assigned settlestatus “2”, which will suspend the payment.

 

TRANSACTIONUPDATE request

The TRANSACTIONUPDATE request consists of two parts:

The following is an example of a TRANSACTIONUPDATE request:


#!/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":{"settlestatus":"2"}
}
  
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('settlestatus' => '2')
);

$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":{"settlestatus":"2"}
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["TRANSACTIONUPDATE"],"filter":{"sitereference":[{"value":"test_site12345"}],"transactionreference":[{"value":"1-2-3"}]},"updates":{"settlestatus":"2"}}]}
<?xml version="1.0" encoding="utf-8"?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="TRANSACTIONUPDATE">
    <filter>
     <sitereference>test_site12345</sitereference>
     <transactionreference>1-2-3</transactionreference>
    </filter>
    <updates>
     <settlement>
      <settlestatus>2</settlestatus>
     </settlement>
    </updates>
  </request>
</requestblock>

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

 

Filters

Field Format Description
sitereference
XPath: /filter/sitereference
Alphanumeric including underscore (50) The unique reference for the Trust Payments site associated with the transaction you would like to update.
transactionreference
XPath: /filter/transactionreference
Alphanumeric including hyphens (25) The unique Trust Payments reference for the transaction you would like to update.

 

Updates

The following fields can be updated when performing updates on AUTH and REFUND requests.

Field Format Description
orderreference
XPath: /updates/merchant/orderreference
Alphanumeric including
symbols (255)
Update the unique order reference that can be stored on the Trust Payments system.
settlebaseamount
XPath: /updates/settlement/settlebaseamount
Numeric (13) The amount of the transaction in base units, with no commas or decimal points, so £10.50 would be 1050. This value must be above zero and less than or equal to the original authorisation amount.
settleduedate
XPath: /updates/settlement/settleduedate
Date YYYY-MM-DD Date the transaction will be settled. If today or earlier, the transaction will settle when Settlement is next run (providing not suspended or cancelled).
settlestatus
XPath: /updates/settlement/settlestatus
Numeric (3) This value relates to the status of the transaction.

 

URL
Different update fields are required when updating different request types. Please refer to the following resources for further information:

 

About settle status

 

  • A suspended (status 2) transaction will be automatically reversed or cancelled (status 3) after 7 days from authorisation, as the authorisation code will have expired. (Authorisation codes are valid for 7 days).
  • Once a transaction is set to reversed/cancelled (status 3), the transaction will not settle and the status cannot be changed.

Click here for further information on the settle status.

 

TRANSACTIONUPDATE response

Please find below an example of a TRANSACTIONUPDATE response that was returned following a successful transaction update.


{
  u 'requestreference': u 'A3jbd6w7a',
    u 'version': u '1.00',
    u 'response': [{
      u 'errorcode': u '0',
        u 'requesttypedescription': u 'TRANSACTIONUPDATE',
        u 'transactionstartedtimestamp': u '2019-12-17 10:58:20',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A057aegmt"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(5) {
      ["errorcode"] => string(1) "0"
      ["requesttypedescription"] => string(17) "TRANSACTIONUPDATE"
      ["transactionstartedtimestamp"] => string(19) "2019-12-17 10:58:20"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
    }
  }
}
{"requestreference":"W23-tkrxwkc6","version":"1.00","response":[{"errorcode":"0","requesttypedescription":"TRANSACTIONUPDATE","transactionstartedtimestamp":"2019-12-17 10:58:20","errormessage":"Ok","operatorname":"[email protected]"}],"secrand":"SptlJutnBnQ"}
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
  <requestreference>Xj73e17g4</requestreference>
  <response type="TRANSACTIONUPDATE">
    <timestamp>2019-12-17 10:58:20</timestamp>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
  </response>
  <secrand>qfZtw074MBlmIq</secrand>
</responseblock>

Ensure the Error Code is “0”. This indicates the TRANSACTIONUPDATE request was processed successfully. If the error code is not “0”, the request may not have been processed as expected. If you are experiencing difficulties, read our Troubleshooting page.

 


 

Troubleshooting

If you submit a TRANSACTIONUPDATE request immediately after the transaction you are trying to update, you may be returned a “20004 Missing parent” error. If this happens, please wait a few seconds and retry.

 


 

Additional resources

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