Account checks
An ACCOUNTCHECK request allows a card to be validated by checking the cardholder’s first line of address, the cardholder’s postcode and the security code, to ensure the details entered by the customer are valid. Click here to learn more about the checks performed.
Requirements
- Account checks are only available for certain acquiring banks. Before you begin, please contact our Support Team and ensure your acquiring bank supports this functionality.
- Account checks can only be performed for card-based payment methods.
Failure to submit these fields will result in a “60025” (Invalid request) error being returned in the response.
Update your payment form
You can update your payment form to instruct our JavaScript library to process an Account check prior to performing a standard transaction. This is done by specifying custom requestTypes, as shown in the example below:
<html>
<head>
</head>
<body>
<div id="st-notification-frame"></div>
<form id="st-form" action="https://www.example.com" method="POST">
<div id="st-card-number" class="st-card-number"></div>
<div id="st-expiration-date" class="st-expiration-date"></div>
<div id="st-security-code" class="st-security-code"></div>
<button type="submit" id="st-form__submit" class="st-form__submit">
Pay securely
</button>
</form>
<script src=<DOMAIN>/js/v2/st.js></script>
<script>
(function() {
var st = SecureTrading({
jwt: 'INSERT YOUR JWT HERE'
});
st.Components({"requestTypes":["ACCOUNTCHECK","THREEDQUERY","AUTH"]});
})();
</script>
</body>
</html>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Using Account Check to verify customer’s details
Follow these instructions when using Account Checks to verify the customer’s details prior to processing a payment.
Prerequisites
If you are unsure, please contact our Support Team for assistance.
To process an e-commerce Account Check that is authenticated with 3-D Secure, you will need to utilise our JavaScript Library instead of the solution described below. Click here to get started.
The following content should only be utilised by merchants processing Account Checks that are Mail or Telephone Order (MOTO), Merchant Initiated Transactions (MIT), or using other workflows that are exempt from the PSD2 mandate.
Failure to submit these fields will result in a “60025” (Invalid request) error being returned in the response. Click here for further information.
- Account checks are only available for certain acquiring banks. Before you begin, please contact our Support Team and ensure your acquiring bank supports this functionality.
- Account checks can only be performed for card-based payment methods.
Mandate considerations
Visa and Mastercard have mandated that you must obtain cardholder consent if storing card details for future use, and that these must be flagged at the time of the first authorisation, by submitting the credentialsonfile field in your requests. To do so, you will need to ensure the ACCOUNTCHECK request submitted includes the additional field credentialsonfile, with value set to “1”.
You must also flag any subsequent payments that are utilising previously-stored credentials, by including the credentialsonfile field in these requests with value set to “2”.
Click here to learn more about Credentials on File.
Checks performed
All Account Checks processed will perform checks on the cardholder’s first line of address, the cardholder’s postcode and the security code, to ensure the details entered by the customer are valid.
Click here to learn more about these checks.
Process overview
-
- Merchant submits ACCOUNTCHECK request.
- Trust Payments validates the request and contacts the bank.
- The acquiring bank will contact the card issuer to perform AVS and security code checks.
- Trust Payments receives results of the request and passes this back to the merchant.
- Merchant receives and interprets this response.
The customer’s account is not debited when an ACCOUNTCHECK request is performed.
ACCOUNTCHECK request
The fields required in an ACCOUNTCHECK request are the same as a standard AUTH request, except with the following differences:
- The baseamount can be “0”. A non-zero amount can be submitted – this will be inherited in any subsequent requests that reference this Account check as its parent, unless overridden with a new amount.
- Additional field credentialsonfile must be submitted with value “1”. (See below)
Field specification
| Field | Format | Description | |
 |
credentialsonfile XPath: /operation/credentialsonfile |
Numeric (1) | This must be set to “1”, to indicate the customer agreed for the payment credentials to be stored for future transactions. See below for further information. |
You can submit any field that you can submit in an AUTH request and these will be inherited by any subsequent child requests. Click here to learn more.
The following is an example of an ACCOUNTCHECK request:
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) accountcheck= { "currencyiso3a": "GBP", "requesttypedescriptions": ["ACCOUNTCHECK"], "sitereference": "test_site12345", "baseamount": "0", "orderreference": "My_Order_123", "accounttypedescription": "MOTO", "pan": "4111111111111111", "expirydate": "12/2020", "securitycode": "123", "billingpremise": "789", "billingpostcode": "TE45 6ST", "credentialsonfile": "1" } strequest = securetrading.Request() strequest.update(accountcheck) 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(
'currencyiso3a' => 'GBP',
'requesttypedescriptions' => array('ACCOUNTCHECK'),
'sitereference' => 'test_site12345',
'baseamount' => '0',
'orderreference' => 'My_Order_123',
'accounttypedescription' => 'MOTO',
'pan' => '4111111111111111',
'expirydate' => '12/2020',
'securitycode' => '123',
'billingpremise' => '789',
'billingpostcode' => 'TE45 6ST',
'credentialsonfile' => '1'
);
$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": [{ "currencyiso3a": "GBP", "requesttypedescriptions": ["ACCOUNTCHECK"], "sitereference": "test_site12345", "baseamount": "0", "orderreference": "My_Order_123", "accounttypedescription": "MOTO", "pan": "4111111111111111", "expirydate": "12/2020", "securitycode": "123", "billingpremise": "789", "billingpostcode": "TE45 6ST", "credentialsonfile": "1" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["ACCOUNTCHECK"],"sitereference":"test_site12345","baseamount":"0","orderreference":"My_Order_123","accounttypedescription":"MOTO","pan":"4111111111111111","expirydate":"12\/2020","securitycode":"123","billingpremise":"789","billingpostcode":"TE45 6ST","credentialsonfile":"1"}]}
<?xml version='1.0' encoding='utf-8'?> <requestblock version="3.67"> <alias>[email protected]</alias> <request type="ACCOUNTCHECK"> <merchant> <orderreference>My_Order_123</orderreference> </merchant> <billing> <amount currencycode="GBP">0</amount> <postcode>TE45 6ST</postcode> <premise>789</premise> <payment> <pan>4111111111111111</pan> <securitycode>123</securitycode> <expirydate>12/2020</expirydate> </payment> </billing> <operation> <accounttypedescription>MOTO</accounttypedescription> <sitereference>test_site12345</sitereference> <credentialsonfile>1</credentialsonfile> </operation> </request> </requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
ACCOUNTCHECK response
After the request has been processed, you will receive a single response that contains the response to the ACCOUNTCHECK request:
{
u 'requestreference': u 'Ar2xj1hjr',
u 'version': u '1.00',
u 'response': [{
u 'transactionstartedtimestamp': u '2016-12-07 16:12:00',
u 'livestatus': u '0',
u 'issuer': u 'SecureTrading Test Issuer1',
u 'dccenabled': u '0',
u 'settleduedate': u '2016-12-07',
u 'errorcode': u '0',
u 'orderreference': u 'My_Order_123',
u 'tid': u '27882788',
u 'merchantnumber': u '00000000',
u 'merchantcountryiso2a': u 'GB',
u 'transactionreference': u '23-9-80023',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'baseamount': u '0',
u 'accounttypedescription': u 'MOTO',
u 'acquirerresponsecode': u '00',
u 'requesttypedescription': u 'ACCOUNTCHECK',
u 'securityresponsesecuritycode': u '2',
u 'currencyiso3a': u 'GBP',
u 'authcode': u 'TEST46',
u 'errormessage': u 'Ok',
u 'operatorname': u '[email protected]',
u 'securityresponsepostcode': u '2',
u 'maskedpan': u '411111######1111',
u 'securityresponseaddress': u '2',
u 'issuercountryiso2a': u 'US',
u 'settlestatus': u '0',
u 'credentialsonfile': u '1'
}]
}
array(3) {
["requestreference"] => string(9) "A4cenptwx"
["version"] => string(4) "1.00"
["response"] => array(1) {
[0] => array(28) {
["transactionstartedtimestamp"] => string(19) "2016-12-09 11:04:29"
["livestatus"] => string(1) "0"
["issuer"] => string(26) "SecureTrading Test Issuer1"
["dccenabled"] => string(1) "0"
["settleduedate"] => string(10) "2016-12-09"
["errorcode"] => string(1) "0"
["baseamount"] => string(1) "0"
["tid"] => string(8) "27882788"
["merchantnumber"] => string(8) "00000000"
["securityresponsepostcode"] => string(1) "2"
["transactionreference"] => string(10) "72-9-80018"
["merchantname"] => string(13) "Test Merchant"
["paymenttypedescription"] => string(4) "VISA"
["orderreference"] => string(12) "My_Order_123"
["accounttypedescription"] => string(4) "MOTO"
["acquirerresponsecode"] => string(2) "00"
["requesttypedescription"] => string(12) "ACCOUNTCHECK"
["securityresponsesecuritycode"] => string(1)"2"
["currencyiso3a"] => string(3) "GBP"
["authcode"] => string(6) "TEST39"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "[email protected]"
["merchantcountryiso2a"] => string(2) "GB"
["maskedpan"] => string(16) "411111######1111"
["securityresponseaddress"] => string(1) "2"
["issuercountryiso2a"] => string(2) "US"
["settlestatus"] => string(1) "0"
["credentialsonfile"] => string(1) "1"
}
}
}
{"requestreference":"W23-q3wa45ge","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 16:16:39","livestatus":"0","issuer":"SecureTrading Test Issuer1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"0","tid":"27882788","merchantnumber":"00000000","securityresponsepostcode":"2","transactionreference":"23-9-80024","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"MOTO","acquirerresponsecode":"00","requesttypedescription":"ACCOUNTCHECK","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST53","errormessage":"Ok","operatorname":"[email protected]","merchantcountryiso2a":"GB","maskedpan":"411111######1111","securityresponseaddress":"2","issuercountryiso2a":"US","settlestatus":"0","credentialsonfile":"1"}],"secrand":"NunVEQ"}
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
<requestreference>X575647667</requestreference>
<response type="ACCOUNTCHECK">
<merchant>
<merchantname>Test Merchant</merchantname>
<orderreference>My_Order_123</orderreference>
<tid>27882788</tid>
<merchantnumber>00000000</merchantnumber>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<operatorname>[email protected]</operatorname>
</merchant>
<transactionreference>16-9-1</transactionreference>
<billing>
<amount currencycode="GBP">0</amount>
<payment type="VISA">
<issuer>SecureTrading Test Issuer1</issuer>
<issuercountry>US</issuercountry>
<pan>411111######1111</pan>
</payment>
<dcc enabled="0"/>
</billing>
<authcode>TEST53</authcode>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<timestamp>2013-01-16 10:48:17</timestamp>
<acquirerresponsecode>00</acquirerresponsecode>
<security>
<address>2</address>
<postcode>2</postcode>
<securitycode>2</securitycode>
</security>
<settlement>
<settleduedate>2013-01-16</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<operation>
<accounttypedescription>MOTO</accounttypedescription>
<credentialsonfile>1</credentialsonfile>
</operation>
</response>
<secrand>bByuPvGz9Hcm</secrand>
</responseblock>
Handling the response
- Ensure that the errorcode value returned is “0”, indicating success. (You must not store credentials if an error has occurred)
- Check the values returned in the securityresponseaddress, securityresponsepostcode and securityresponsesecuritycode fields and only proceed if business requirements have been satisfied. (More info provided below)
| Field | Format | Description | |
 |
securityresponseaddress XPath: /security/address |
Numeric (1) | “0” Not given – Your system did not provide the acquiring bank the information required to perform this check.
“1” Not checked – The acquiring bank did not perform this check on the information you provided in the request. “2” Matched – The information you provided in the request matches the information obtained by the acquiring bank, from the customer’s payment issuer. “4” Not matched – The information you provided in the request does not match the information obtained by the acquiring bank, from the customer’s payment issuer. |
|
securityresponsepostcode XPath: /security/postcode |
Numeric (1) | |
|
securityresponsesecuritycode XPath: /security/securitycode |
Numeric (1) |
Transaction queries
If you are unsure, please contact our Support Team for assistance.
If you would like to retrieve information on requests and transactions you have previously submitted, you can submit a TRANSACTIONQUERY request.
Process overview
Your system will need to submit a TRANSACTIONQUERY request to Trust Payments. Trust Payments will then return a response containing the requested information, if a matching request has been found.
For example, you can request information on all transactions processed on your Site Reference between 6pm and 9pm, or find out whether or not a transaction has been settled.
Filters
The TRANSACTIONQUERY request consists primarily of filters. Think of filters as search criteria; the response returned will contain information meeting the specified filters.
For example, a filter with orderreference “100100” would return details of all matching requests with that reference (if any exist and have been processed on your site reference).
And specifying a starttimestamp and endtimestamp will return details of all requests processed on your account between the specified times.
Multiple records can be returned in a single response
We recommend being as specific as reasonably possible in your request, by submitting as many filters as required, in order to avoid returning an excessive number of records in the response.
You can also submit multiple values for each given filter. e.g. You can submit a filter for transactionreference values “23-9-1” and “23-9-2”, and any requests matching these values will be returned in the response. (We include an example of this case below)
TRANSACTIONQUERY request
For the TRANSACTIONQUERY request to be processed successfully, you need to submit at least one valid filter.
Request example
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) query = { "requesttypedescriptions": ["TRANSACTIONQUERY"], "filter":{ "sitereference": [{"value":"test_site12345"}], "currencyiso3a": [{"value":"GBP"}], "transactionreference": [{"value":"23-9-1"},{"value":"23-9-2"}] } } strequest = securetrading.Request() strequest.update(query) 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('TRANSACTIONQUERY'),
'filter' => array(
'sitereference' => array(array('value' => 'test_site12345')),
'currencyiso3a' => array(array('value' => 'GBP')),
'transactionreference' => array(array('value' => '23-9-1'),array('value' => '23-9-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": ["TRANSACTIONQUERY"], "filter":{ "sitereference": [{"value":"test_site12345"}], "currencyiso3a": [{"value":"GBP"}], "transactionreference": [{"value":"23-9-1"},{"value":"23-9-2"}] } }]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["TRANSACTIONQUERY"],"filter":{"sitereference":[{"value":"test_site12345"}],"currencyiso3a":[{"value":"GBP"}],"transactionreference":[{"value":"23-9-1"},{"value":"23-9-2"}]}}]}
<?xml version="1.0" encoding="utf-8"?> <requestblock version="3.67"> <alias>[email protected]</alias> <request type="TRANSACTIONQUERY"> <filter> <sitereference>test_site12345</sitereference> <currencyiso3a>GBP</currencyiso3a> <transactionreference>23-9-1</transactionreference> <transactionreference>23-9-2</transactionreference> </filter> </request> </requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Field specification
The following table lists all fields that you can include in the filter when processing a TRANSACTIONQUERY request.
Note that although none of the following filter fields are required, at least one filter must be submitted for the request to be processed successfully. For this reason, all fields have been marked below as conditional.
| Field | Format | Description | |
 |
accounttypedescription XPath: /filter/accounttypedescription |
Alpha (20) | The source of the transaction.
|
|
billingemail XPath: /filter/billingemail |
Email (255) | The customer’s billing email address.
Maximum length of 255 (maximum of 64 characters before the ”@” symbol). |
|
billingfirstname XPath: /filter/billingfirstname |
Alphanumeric including symbols (127) | The customer’s billing first name. |
|
billinglastname XPath: /filter/billinglastname |
Alphanumeric including symbols (127) | The customer’s billing last name. |
|
billingpostcode XPath: /filter/billingpostcode |
Alphanumeric including symbols (25) | The customer’s billing postcode. |
|
billingpremise XPath: /filter/billingpremise |
Alphanumeric including symbols (20) | The number or name of the premise of the customer’s billing address. |
|
billingstreet XPath: /filter/billingstreet |
Alphanumeric including symbols (20) | The street name of the customer’s billing address. |
|
currencyiso3a XPath: /filter/currencyiso3a |
Alpha (3) | The transaction currency. |
|
customerip XPath: /filter/customerip |
IP address (39) | The customer’s IP address. |
|
endtimestamp XPath: /filter/endtimestamp |
Date Time YYYY-MM-DD HH:MM:SS | Only requests processed before the timestamp specified will be returned.
(Unlike with other filters, you can only submit one endtimestamp in a request) |
|
orderreference XPath: /filter/orderreference |
Alphanumeric including symbols (255) | Unique reference number supplied by the merchant for the request. |
|
pan XPath: /filter/pan |
Numeric (12-19) | This is the card number printed on the front of the customer’s card. |
|
parenttransactionreference XPath: /filter/parenttransactionreference |
Alphanumeric including hyphens (25) | Unique reference of the parent request. |
|
paymenttypedescription XPath: /filter/paymenttypedescription |
Alpha (20) | The customer’s card type (e.g. “VISA” or “MASTERCARD”). |
|
requesttypedescription XPath: /filter/requesttypedescription |
Alpha (20) | The request type associated with transaction. For example, “AUTH” or “REFUND”. |
|
sitereference XPath: /filter/sitereference |
Alpha (50) | The site reference that processed the transaction. |
|
starttimestamp XPath: /filter/starttimestamp |
Date Time YYYY-MM-DD HH:MM:SS | Only requests processed after the timestamp specified will be returned.
(Unlike with other filters, you can only submit one starttimestamp in a request) |
|
transactionreference XPath: /filter/transactionreference |
Alphanumeric including hyphens (25) | The unique reference associated with the transaction, assigned by Trust Payments. |
TRANSACTIONQUERY response
Once you have successfully submitted a TRANSACTIONQUERY request, you will be returned a response that is divided into separate records.
Each record will contain a varying number of response fields, which depend on the request type indicated in the record. For example, if the record has a requesttypedescription of “AUTH“, then you would need to refer to the field specification in the Authorisation document.
Additionally, the response contains a field called found, which indicates the number of records that match the filters specified in the request. If found has a value of “0”, no records have been found using your specified filters.
For example, here is a simplified example of the structure of the response, consisting of 2 records (both are type “AUTH”):
{
u 'requestreference': u 'W72-pg3q2he9',
u 'version': u '1.00',
u 'response': [{
u 'transactionstartedtimestamp': u '2019-12-17 09:36:21',
u 'errormessage': u 'Ok',
u 'errorcode': u '0',
u 'records': [{
u 'transactionstartedtimestamp': u '2019-12-17 09:35:03',
u 'sitereference': u 'test_site12345',
u 'interface': u 'PASS-JSON-JSON',
u 'livestatus': u '0',
u 'issuer': u 'SecureTrading Test Issuer1',
u 'dccenabled': u '0',
u 'settleduedate': u '2019-12-17',
u 'errorcode': u '0',
u 'baseamount': u '1050',
u 'tid': u '27882788',
u 'securityresponsepostcode': u '0',
u 'transactionreference': u '72-9-80005',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'accounttypedescription': u 'ECOM',
u 'fraudrating': u '0',
u 'splitfinalnumber': u '1',
u 'acquirerresponsecode': u '00',
u 'requesttypedescription': u 'AUTH',
u 'expirydate': u '10/2022',
u 'securityresponsesecuritycode': u '2',
u 'currencyiso3a': u 'GBP',
u 'authcode': u 'TEST22',
u 'settlebaseamount': u '1050',
u 'errormessage': u 'Ok',
u 'issuercountryiso2a': u 'US',
u 'merchantcountryiso2a': u 'GB',
u 'maskedpan': u '411111######1111',
u 'securityresponseaddress': u '0',
u 'operatorname': u '[email protected]',
u 'settlestatus': u '0'
}, {
u 'transactionstartedtimestamp': u '2019-12-17 09:35:10',
u 'sitereference': u 'test_site12345',
u 'interface': u 'PASS-JSON-JSON',
u 'livestatus': u '0',
u 'issuer': u 'SecureTrading Test Issuer1',
u 'dccenabled': u '0',
u 'settleduedate': u '2019-12-17',
u 'errorcode': u '0',
u 'baseamount': u '1050',
u 'tid': u '27882788',
u 'securityresponsepostcode': u '0',
u 'transactionreference': u '72-9-80006',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'accounttypedescription': u 'ECOM',
u 'fraudrating': u '0',
u 'splitfinalnumber': u '1',
u 'acquirerresponsecode': u '00',
u 'requesttypedescription': u 'AUTH',
u 'expirydate': u '10/2022',
u 'securityresponsesecuritycode': u '2',
u 'currencyiso3a': u 'GBP',
u 'authcode': u 'TEST03',
u 'settlebaseamount': u '1050',
u 'errormessage': u 'Ok',
u 'issuercountryiso2a': u 'US',
u 'merchantcountryiso2a': u 'GB',
u 'maskedpan': u '411111######1111',
u 'securityresponseaddress': u '0',
u 'operatorname': u '[email protected]',
u 'settlestatus': u '0'
}],
u 'found': u '2',
u 'requesttypedescription': u 'TRANSACTIONQUERY'
}]
}
array(3) {
["requestreference"] => string(9) "W72-pg3q2he9"
["version"] => string(4) "1.00"
["response"] => array(1) {
[0] => array(6) {
["transactionstartedtimestamp"] => string(19) "2019-12-17 09:36:21"
["errormessage"] => string(2) "Ok"
["errorcode"] => string(1) "0"
["records"] => array(2) {
[0] => array(31) {
["transactionstartedtimestamp"] => string(19) "2019-12-17 09:35:03"
["sitereference"] => string(14) "test_site12345"
["interface"] => string(14) "PASS-JSON-JSON"
["livestatus"] => string(1) "0"
["issuer"] => string(26) "SecureTrading Test Issuer1"
["dccenabled"] => string(1) "0"
["settleduedate"] => string(10) "2019-12-17"
["errorcode"] => string(1) "0"
["baseamount"] => string(4) "1050"
["tid"] => string(8) "27882788"
["securityresponsepostcode"] => string(1) "0"
["transactionreference"] => string(10) "72-9-80005"
["merchantname"] => string(13) "Test Merchant"
["paymenttypedescription"] => string(4) "VISA"
["accounttypedescription"] => string(4) "ECOM"
["fraudrating"] => string(1) "0"
["splitfinalnumber"] => string(1) "1"
["acquirerresponsecode"] => string(2) "00"
["requesttypedescription"] => string(4) "AUTH"
["expirydate"] => string(7) "10/2022"
["securityresponsesecuritycode"] => string(1) "2"
["currencyiso3a"] => string(3) "GBP"
["authcode"] => string(6) "TEST22"
["settlebaseamount"] => string(4) "1050"
["errormessage"] => string(2) "Ok"
["issuercountryiso2a"] => string(2) "US"
["merchantcountryiso2a"] => string(2) "GB"
["maskedpan"] => string(16) "411111######1111"
["securityresponseaddress"] => string(1) "0"
["operatorname"] => string(23) "[email protected]"
["settlestatus"] => string(1) "0"
}
[1] => array(31) {
["transactionstartedtimestamp"] => string(19) "2019-12-17 09:35:10"
["sitereference"] => string(14) "test_site12345"
["interface"] => string(14) "PASS-JSON-JSON"
["livestatus"] => string(1) "0"
["issuer"] => string(26) "SecureTrading Test Issuer1"
["dccenabled"] => string(1) "0"
["settleduedate"] => string(10) "2019-12-17"
["errorcode"] => string(1) "0"
["baseamount"] => string(4) "1050"
["tid"] => string(8) "27882788"
["securityresponsepostcode"] => string(1) "0"
["transactionreference"] => string(10) "72-9-80006"
["merchantname"] => string(13) "Test Merchant"
["paymenttypedescription"] => string(4) "VISA"
["accounttypedescription"] => string(4) "ECOM"
["fraudrating"] => string(1) "0"
["splitfinalnumber"] => string(1) "1"
["acquirerresponsecode"] => string(2) "00"
["requesttypedescription"] => string(4) "AUTH"
["expirydate"] => string(7) "10/2022"
["securityresponsesecuritycode"] => string(1) "2"
["currencyiso3a"] => string(3) "GBP"
["authcode"] => string(6) "TEST03"
["settlebaseamount"] => string(4) "1050"
["errormessage"] => string(2) "Ok"
["issuercountryiso2a"] => string(2) "US"
["merchantcountryiso2a"] => string(2) "GB"
["maskedpan"] => string(16) "411111######1111"
["securityresponseaddress"] => string(1) "0"
["operatorname"] => string(23) "[email protected]"
["settlestatus"] => string(1) "0"
}
}
["found"] => string(1) "2"
["requesttypedescription"] => string(16) "TRANSACTIONQUERY"
}
}
}
{"requestreference":"W72-pg3q2he9","version":"1.00","response":[{"transactionstartedtimestamp":"2019-12-17 09:36:21","errormessage":"Ok","errorcode":"0","records":[{"transactionstartedtimestamp":"2019-12-17 09:35:03","sitereference":"test_site12345","interface":"PASS-JSON-JSON","livestatus":"0","issuer":"SecureTrading Test Issuer1","dccenabled":"0","settleduedate":"2019-12-17","errorcode":"0","baseamount":"1050","tid":"27882788","securityresponsepostcode":"0","transactionreference":"72-9-80005","merchantname":"Test Merchant","paymenttypedescription":"VISA","accounttypedescription":"ECOM","fraudrating":"0","splitfinalnumber":"1","acquirerresponsecode":"00","requesttypedescription":"AUTH","expirydate":"10\/2022","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST22","settlebaseamount":"1050","errormessage":"Ok","issuercountryiso2a":"US","merchantcountryiso2a":"GB","maskedpan":"411111######1111","securityresponseaddress":"0","operatorname":"[email protected]","settlestatus":"0"},{"transactionstartedtimestamp":"2019-12-17 09:35:10","sitereference":"test_site12345","interface":"PASS-JSON-JSON","livestatus":"0","issuer":"SecureTrading Test Issuer1","dccenabled":"0","settleduedate":"2019-12-17","errorcode":"0","baseamount":"1050","tid":"27882788","securityresponsepostcode":"0","transactionreference":"72-9-80006","merchantname":"Test Merchant","paymenttypedescription":"VISA","accounttypedescription":"ECOM","fraudrating":"0","splitfinalnumber":"1","acquirerresponsecode":"00","requesttypedescription":"AUTH","expirydate":"10\/2022","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST03","settlebaseamount":"1050","errormessage":"Ok","issuercountryiso2a":"US","merchantcountryiso2a":"GB","maskedpan":"411111######1111","securityresponseaddress":"0","operatorname":"[email protected]","settlestatus":"0"}],"found":"2","requesttypedescription":"TRANSACTIONQUERY"}],"secrand":"uISZfw8wKWR"}
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
<requestreference>Xv18xwv52</requestreference>
<response type="TRANSACTIONQUERY">
<record type="AUTH">
<acquirerresponsecode>00</acquirerresponsecode>
<operation>
<splitfinalnumber>1</splitfinalnumber>
<sitereference>test_site12345</sitereference>
<interface>CERT-XML-XML</interface>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
<settlement>
<settleduedate>2019-12-17</settleduedate>
<settlebaseamount>1050</settlebaseamount>
<settlestatus>0</settlestatus>
</settlement>
<billing>
<dcc enabled="0"/>
<amount currencycode="GBP">1050</amount>
<payment type="VISA">
<issuer>SecureTrading Test Issuer1</issuer>
<expirydate>10/2022</expirydate>
<pan>411111######1111</pan>
<issuercountry>US</issuercountry>
</payment>
</billing>
<live>0</live>
<merchant>
<tid>27882788</tid>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<merchantname>Test Merchant</merchantname>
<operatorname>[email protected]</operatorname>
</merchant>
<transactionreference>72-9-80003</transactionreference>
<timestamp>2019-12-17 09:17:58</timestamp>
<error>
<message>Ok</message>
<code>0</code>
</error>
<fraud>
<rating>0</rating>
</fraud>
<authcode>TEST35</authcode>
<security>
<postcode>0</postcode>
<securitycode>2</securitycode>
<address>0</address>
</security>
</record>
<record type="AUTH">
<acquirerresponsecode>00</acquirerresponsecode>
<operation>
<splitfinalnumber>1</splitfinalnumber>
<sitereference>test_site12345</sitereference>
<interface>CERT-XML-XML</interface>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
<settlement>
<settleduedate>2019-12-17</settleduedate>
<settlebaseamount>1050</settlebaseamount>
<settlestatus>0</settlestatus>
</settlement>
<billing>
<dcc enabled="0"/>
<amount currencycode="GBP">1050</amount>
<payment type="VISA">
<issuer>SecureTrading Test Issuer1</issuer>
<expirydate>10/2022</expirydate>
<pan>411111######1111</pan>
<issuercountry>US</issuercountry>
</payment>
</billing>
<live>0</live>
<merchant>
<tid>27882788</tid>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<merchantname>Test Merchant</merchantname>
<operatorname>[email protected]</operatorname>
</merchant>
<transactionreference>72-9-80004</transactionreference>
<timestamp>2019-12-17 09:18:00</timestamp>
<error>
<message>Ok</message>
<code>0</code>
</error>
<fraud>
<rating>0</rating>
</fraud>
<authcode>TEST06</authcode>
<security>
<postcode>0</postcode>
<securitycode>2</securitycode>
<address>0</address>
</security>
</record>
<found>2</found>
<error>
<message>Ok</message>
<code>0</code>
</error>
<timestamp>2019-12-17 09:19:00</timestamp>
</response>
<secrand>IDBpVj</secrand>
</responseblock>
A maximum of 500 records can be returned per response.
The found field will never return a value higher than 500, even if more than 500 requests meet the specified criteria.
Understanding errors
Please ensure you understand the Error Codes returned in the response:
- At the highest level of the response, along with transactionstartedtimestamp and found, there is an errorcode. This indicates whether or not the TRANSACTIONQUERY request was successful. If the error code here is not “0”, the TRANSACTIONQUERY request was not successful. You must address the problem and try again.
- In addition to this, each record will contain their own errorcode. This indicates whether or not the request represented in the record was successful.
- For a full list of error codes used by Trust Payments please click here.
Additional resources
3-D Secure (version 1)
If you are unsure, please contact our Support Team for assistance.
The following documentation explains how to manually perform 3-D Secure using version 1 through our Webservices API.
The process described below only supports 3-D Secure version 1.
We recommend all merchants utilise 3-D Secure version 2 by using our JavaScript Library.
If you are already processing e-commerce payments using our JavaScript Library, you do not need to follow the process described below, as the JavaScript Library will handle the 3-D Secure process automatically.
3-D Secure is a protocol designed to reduce fraud and chargebacks during e-commerce transactions. It allows Mastercard and Visa card issuers to provide an extra level of protection, by authenticating the customer’s identity at the point of sale, sometimes by prompting for a previously-agreed PIN and/or password.
Process overview
- Your system will need to send a THREEDQUERY request using our Webservices API (including the customer’s card details) and interpret the response returned.
- Trust Payments will check whether the customer’s card is enrolled in 3-D Secure.
If the customer is enrolled in 3-D Secure, your system will need to redirect the customer to the card issuer’s server (ACS URL) and handle the customer being redirected to your server (Term URL).
Your system will need to send an AUTH request using our Webservices API and interpret the response returned.
1. Check customer enrolment
To determine whether or not the customer’s card is enrolled in the 3-D Secure scheme, you need to manually submit a THREEDQUERY request using our Webservices API.
THREEDQUERY Request
The following example demonstrates how to structure a THREEDQUERY request:
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) threedquery= { "termurl":"https://termurl.com", "accept":"text/html,*/*", "pan": "4111111111111111", "expirydate": "12/2020", "securitycode": "123", "currencyiso3a":"GBP", "requesttypedescriptions": ["THREEDQUERY"], "accounttypedescription":"ECOM", "sitereference": "test_site12345", "baseamount": "1050" } strequest = securetrading.Request() strequest.update(threedquery) 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(
'termurl' => 'https://termurl.com',
'accept' => 'text/html,*/*',
'pan' => '4111111111111111',
'expirydate' => '12/2020',
'securitycode' => '123',
'currencyiso3a' => 'GBP',
'requesttypedescriptions' => array('THREEDQUERY'),
'accounttypedescription' => 'ECOM',
'sitereference' => 'test_site12345',
'baseamount' => '1050'
);
$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": [{ "termurl":"https://termurl.com", "accept":"text/html,*/*", "pan": "4111111111111111", "expirydate": "12/2020", "securitycode": "123", "currencyiso3a":"GBP", "requesttypedescriptions": ["THREEDQUERY"], "accounttypedescription":"ECOM", "sitereference": "test_site12345", "baseamount": "1050" }]}'
Here is the specification of the fields included in the THREEDQUERY request described above:
Key
| Field name | Type | Length | Request | Description |
| accept | Alphanumeric | 1024 |  |
The exact content of the HTTP accept-header field as received from the cardholder’s user agent. |
| accounttypedescription | Alpha | 20 | |
This must be submitted as “ECOM” (e-commerce). |
| baseamount | Numeric | 13 | |
The amount of the transaction in base units, with no commas or decimal points, so £10 is submitted as 1000. This value must be greater than zero. (Max length may vary depending on your acquiring bank – Contact your bank for further info) |
| currencyiso3a | Alpha | 3 | |
The currency that the transaction will be processed in. |
| expirydate | Date MM/YYYY | 7 | |
The expiration date printed on the card. |
| pan |
Numeric | 12-19 | |
This is the long number printed on the front of the customer’s card.
We return a masked version of this PAN in the response, in the field maskedpan. e.g. “411111######1111” |
| requesttypedescriptions | Alpha | 20 | |
The request type required is “THREEDQUERY”. |
| 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 field 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 | 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. |
| termurl | URL | 1024
More info |
|
This field value is a URL of a script/file located on your system that is able to manage customers who are returned to your system. It is used to instruct the card issuer where to send the customer’s browser after they have been authenticated on the card issuer’s ACS. |
| useragent | Alphanumeric | 255 |  |
The exact content of the HTTP user-agent header field as received from the cardholder’s user agent. We strongly recommend you submit this field, as failure to do so may forfeit the liability shift. |
THREEDQUERY Response
This section documents how to interpret a THREEDQUERY response, which is used to indicate whether or not the customer’s card is enrolled in the card issuer’s 3-D Secure scheme.
The example below demonstrates the structure of a THREEDQUERY response, indicating that the customer’s card is enrolled in a 3-D Secure scheme:
{
u 'requestreference': u 'Aw5mpjtv6',
u 'version': u '1.00',
u 'response': [{
u 'transactionstartedtimestamp': u '2016-12-07 16:55:47',
u 'livestatus': u '0',
u 'issuer': u 'SecureTrading Test Issuer1',
u 'xid': u 'amh1OCtINGpuemJaVmQreU5YT2Y=',
u 'pareq': u 'eJxVUmFPw9C12xiQowlCopiIqGji5Yqj25lPCwOutoQKHZzxqOQgF5soqzk=',
u 'dccenabled': u '0',
u 'settleduedate': u '2016-12-07',
u 'errorcode': u '0',
u 'threedversion': u '1.0.2',
u 'tid': u '27882788',
u 'merchantnumber': u '00000000',
u 'merchantcountryiso2a': u 'GB',
u 'transactionreference': u '1-2-345678',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'acsurl': u 'https://webapp.securetrading.net/acs/visa.cgi',
u 'accounttypedescription': u 'ECOM',
u 'requesttypedescription': u 'THREEDQUERY',
u 'md': u 'UEZOVVBqeE5SRDQ4VFVSSVBucE9abUp5WWtTlDR0NLaFVSZUV5aStFPQ==',
u 'maskedpan': u '411111######0211',
u 'errormessage': u 'Ok',
u 'operatorname': u '[email protected]',
u 'enrolled': u 'Y',
u 'issuercountryiso2a': u 'US',
u 'settlestatus': u '0'
}]
}
array(3) {
["requestreference"] => string(9) "A2cjnruwy"
["version"] => string(4) "1.00"
["response"] => array(1) {
[0] => array(25) {
["transactionstartedtimestamp"] => string(19) "2016-12-09 11:25:36"
["livestatus"] => string(1) "0"
["issuer"] => string(26) "SecureTrading Test Issuer1"
["xid"] => string(28) "ZlcyU1hQcUhmaEtzd2I1SmkrMnM="
["pareq"] => string(27) "eJxVUstuwjAQ/BXEHZxjoOrXA=="
["dccenabled"] => string(1) "0"
["settleduedate"] => string(10) "2016-12-09"
["errorcode"] => string(1) "0"
["threedversion"] => string(5) "1.0.2"
["tid"] => string(8) 27882788"
["merchantnumber"] => string(8) "00000000"
["merchantcountryiso2a"] => string(2) "GB"
["transactionreference"] => string(10) "1-2-345678"
["merchantname"] => string(13) "Test Merchant"
["paymenttypedescription"] => string(4) "VISA"
["acsurl"] => string(45) "https://webapp.securetrading.net/acs/visa.cgi"
["accounttypedescription"] => string(4) "ECOM"
["requesttypedescription"] => string(11) "THREEDQUERY"
["md"] => string(72) "UEZOVVBqeVQand2VTFRKzptZGY2RXZXOGQrS2V5Tko5cEk9"
["maskedpan"] => string(16) "411111######0211"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "[email protected]"
["enrolled"] => string(1) "Y"
["issuercountryiso2a"] => string(2) "US"
["settlestatus"] => string(1) "0"
}
}
}
{"requestreference":"W23-08yvq0db","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 16:57:44","livestatus":"0","issuer":"SecureTrading Test Issuer1","xid":"KzRLRmhSUEZ0OWZJSkJIMDU1dDk=","pareq":"eJxVUu9PwjAQ\/NtY9ts6tP8Ac1Rqq+","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","threedversion":"1.0.2","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345678","merchantname":"Test Merchant","paymenttypedescription":"VISA","acsurl":"https:\/\/webapp.securetrading.net\/acs\/visa.cgi","accounttypedescription":"ECOM","requesttypedescription":"THREEDQUERY","md":"UEZOVVBqeE5SRD06bWRzS1dBbnFZY01JRjEwZGOWhrPQ==","maskedpan":"411111######0211","errormessage":"Ok","operatorname":"[email protected]","enrolled":"Y","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"0gqEPDTnCWlvTr6G"}
Check the error code field value
If the errorcode value returned in the response is not ‘0’, an error has occurred. If an errorcode other than ‘0’ is returned, please consult the table below and attempt to resolve the issue:
| Error code | Description |
| 0 | Request was successful. |
| 30000 | Invalid field. |
| 60031 | The THREEDQUERY request used a payment type that is not supported by Trust Payments 3-D Secure. |
| other | Other errors will require further investigation. Click here for a full list of possible error codes. |
If you were unable to resolve the issue, you can instruct your system to perform a standard AUTH without using 3-D Secure.
Check the enrolled field value
If the enrolled value returned in the response is “Y”, the customer’s card is enrolled in 3-D secure. Please refer to the following table for enrolled values:
| Enrolled | Description | Action |
| Y | The card is enrolled in the card issuer’s 3-D Secure scheme. | Send the customer to the card issuer’s Access Control Server (ACS). The URL for the ACS is provided in the acsurl of the THREEDQUERY response. |
| N | The card is not enrolled in the card issuer’s 3-D Secure scheme. | Perform an AUTH Request, including the transactionreference returned in the THREEDQUERY response (example can be found below). |
| U | The card’s enrolment in the card issuer’s 3-D Secure scheme could not be determined. | This typically indicates a temporary problem with the card issuer’s systems. You can configure your system to resubmit the same THREEDQUERY request. If this continues to fail, submit a standard AUTH request using our Webservices API, including the transactionreference returned in the THREEDQUERY response. |
Here is the specification of the fields included in the THREEDQUERY response described above:
Key
| Field name | Type | Length | Response | Description |
| requesttypedescription | Alpha | 20 | |
“THREEDQUERY” is always returned in the response. |
| xid | Alphanumeric | 255 | |
The unique identifier for the transaction, assigned by the MPI (Merchant Plug-In) (in this case, Trust Payments). |
| enrolled | Char | 1 | |
Determines if the cardholder is enrolled in a 3-D Secure scheme.
|
| pareq | Alphanumeric including symbols | 2048 | |
The unique identifier for the transaction, assigned by the MPI (Merchant Plug-In) (in this case, Trust Payments). |
| md | Alphanumeric including symbols | 1024 |  |
Returned if card is enrolled.
The unique 3-D Secure reference for this transaction. |
| acsurl | URL | 1024 | |
Returned if card is enrolled.
The URL of the Access Control Server (ACS) to be used in authenticating the cardholder. |
| threedversion | Numeric | 6 | |
Only returned for accounts with certain acquiring banks.
The version of the 3-D Secure protocol. |
Your progress
Following the instructions above, your system should now be able to determine whether or not a customer’s card is enrolled in a 3-D Secure scheme. If the customer’s card is enrolled, follow the “Authenticate the customer” section below, otherwise skip ahead to the “Authorisation” section.
2. Authenticate the customer
If the card is not enrolled, skip ahead to the “Authorisation” section.
If the customer is enrolled in the card issuer’s 3-D Secure scheme, your system must send the customer’s browser to the card issuer-hosted Access Control Server (ACS) using an HTTPS POST. The URL for the ACS can be found in the acsurl field of the THREEDQUERY response.
On the ACS, the customer will be authenticated, sometimes by prompting for a previously-agreed PIN and/or password. The browser must send data from the termurl, pareq and md in HTML fields ‘TermUrl’, ‘PaReq’ and ‘MD’, respectively (These field names are case sensitive).
Following authentication, the customer will be returned to your servers using an HTTPS POST. You will need to parse this response, as it will contain the ‘PaRes’ and ‘MD’ fields, for constructing the subsequent AUTH Request needed to process the payment.
The following is an example of how to redirect the cardholder to the card issuer’s ACS :
<!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.01//EN'>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<title>Processing payment</title>
<style type="text/css">
h3,h3,h4 { font-family: verdana, arial, sans-serif;
font-weight: normal;}
#logo {float: left;}
</style>
</head>
<body OnLoad="document.form.submit();" >
<form name="form" id="form" action="$acsurl" method="POST">
<div>
<input type="hidden" name="PaReq" value="$pareq" />
<input type="hidden" name="TermUrl" value="$termurl" />
<input type="hidden" name="MD" value="$md" />
</div>
<noscript>
<div>
<h3>JavaScript is currently disabled or is not supported by your browser.</h3>
<h4>Please click Submit to continue processing your 3-D Secure transaction.</h4>
<input type="submit" value="Submit">
</div>
</noscript>
</form>
</body>
</html>
Referencing 3-D Secure transactions
In most circumstances, your system will need to store data about the transaction in your database while the customer is being authenticated on the card issuer’s ACS, to be retrieved when the customer returns to your system via the termurl. As the 3-D Secure specification requires that only the md and pares fields are returned to your system, it is recommended that the md field is used to look up any corresponding customer session to complete the transaction.
Waiting for the customer to return from the ACS
Your system will need to consider the length of time it may take for the customer to enter their details on the card issuer’s ACS. The time the customer will spend on the ACS will depend on a number of factors. Longer wait times may occur when the customer is signing up to a 3-D Secure scheme for the first time, or recovering a forgotten password. While your system needs to allow time for the customer to return, it is entirely possible for the customer to close their browser on the card issuer’s ACS and not return at all. There are no specific regulations as to how long your system must wait for the customer to be redirected from the ACS to your Term URL, but we recommend waiting for no more than two hours.
Your progress
Following the instructions above, your system should now be able to redirect the browsers of customers with cards enrolled in a 3-D Secure scheme to the ACS for authentication. Your system can now proceed and submit an AUTH request using our Webservices API to process the payment, by following the instructions below.
3. Authorisation
3-D authorisations are used to seek authorisation for authenticated transactions from your acquiring bank. This is performed by manually submitting an AUTH Request using our Webservices API and interpreting the response returned.
AUTH Request
For enrolled cards only
The following example demonstrates how to structure a 3-D AUTH request when the card is enrolled in a 3-D Secure scheme:
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) auth= { "requesttypedescriptions": ["AUTH"], "md":"UEZOVVBqeE5SRDQ4VFVSSVBrRjVXSGhOZFZReVUzVlalBVeE", "pares":"eJzVWFmzosgSfudXdPQ8Gt1sbkzYRhQ7KCjI/sYOsimgoL/+lp7Tp5" } strequest = securetrading.Request() strequest.update(auth) stresponse = st.process(strequest) #stresponse contains the transaction response
<?php
if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);
$configData = array(
'username' => '[email protected]',
'password' => 'Password1^',
);
$requestData = array(
'requesttypedescriptions' => array('AUTH'),
'md' => 'UEZOVVBqeE5SRDQ4VFVSSVBtSllOVTlMYVdaUlJXWnZVRTA0UVdwVlJXZFpRo5cEk9',
'pares' => 'eJztWEnTqsi2nfMrKqqGxik6UajwJFCOxLb5BNvgHdPneIihB/fq2eNv777/BdaScGg='
);
$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": [{ "requesttypedescriptions": ["AUTH"], "md":"UEZOVVBqeE5SRDVS1FLVG9aenQrRGhaNk1NPQ==", "pares":"eJztWMmyq7iynfMVFVVDxyk6Y0OX0U1wTQ==" }]}'
For non-enrolled cards only
For cards that are NOT enrolled in the card issuer’s 3-D Secure scheme (or have unknown enrolment), you will need to submit the following fields in order to inherit transaction information needed to perform the authorisation:
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) auth= { "requesttypedescriptions": ["AUTH"], "sitereference": "test_site12345", "parenttransactionreference": "1-2-345678" } strequest = securetrading.Request() strequest.update(auth) stresponse = st.process(strequest) #stresponse contains the transaction response
<?php
if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);
$configData = array(
'username' => '[email protected]',
'password' => 'Password1^',
);
$requestData = array(
'requesttypedescriptions' => array('AUTH'),
'sitereference' => 'test_site12345',
'parenttransactionreference' => '1-2-345678'
);
$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": [{ "requesttypedescriptions": ["AUTH"], "sitereference": "test_site12345", "parenttransactionreference": "1-2-345678" }]}'
Inheritance
The example AUTH requests shown above (both enrolled and not-enrolled) contain all the fields that are required for submission. All other information required to seek authorisation will be inherited from the previous THREEDQUERY request stored on our system.
We allow the submission of additional fields in the AUTH request that have not been submitted in the THREEDQUERY request (e.g. the customer name, if omitted in the query).
Click here for a full list of fields that can be submitted in an AUTH request.
Here is the specification of the fields included in the AUTH requests described above:
Key
| Field name | Type | Length | Request | Description |
| pares | Alphanumeric including symbols | 1024 | |
Only send if card is enrolled.
Must be the value returned in the pares field of the HTTPS POST from the card issuer’s ACS, otherwise this may forfeit the liability shift. |
| md | Alphanumeric including symbols | 65536 | |
Only send if card is enrolled.
The unique 3-D Secure reference for this transaction. Supplied if enrolled is “Y” |
| parenttransactionreference | Alphanumeric including hyphens | 25 | |
Only send if card is NOT enrolled.
Unique reference of the parent THREEDQUERY request. |
| sitereference | Alphanumeric including underscore | 50 | |
Only send if card is NOT enrolled.
The site reference processing the transaction. |
AUTH Response
The data returned in the AUTH response will depend on both the card enrollment status, and whether or not the customer was successfully authenticated on the card issuer’s ACS.
Your system should be able to interpret the response data in each of the following scenarios.
Enrolled and authenticated
{
u 'requestreference': u 'Av87m7xq9',
u 'version': u '1.00',
u 'response': [{
u 'transactionstartedtimestamp': u '2016-12-08 08:34:48',
u 'parenttransactionreference': u '1-2-345678',
u 'livestatus': u '0',
u 'issuer': u 'SecureTrading Test Issuer1',
u 'splitfinalnumber': u '1',
u 'xid': u 'amh1OCtINGpuemJaVmQreU5YT2Y=',
u 'dccenabled': u '0',
u 'settleduedate': u '2016-12-07',
u 'errorcode': u '0',
u 'cavv': u 'Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=',
u 'merchantnumber': u '00000000',
u 'merchantcountryiso2a': u 'GB',
u 'status': u 'Y',
u 'transactionreference': u '1-2-345679',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'baseamount': u '1050',
u 'eci': u '05',
u 'accounttypedescription': u 'ECOM',
u 'tid': u '27882788',
u 'acquirerresponsecode': u '00',
u 'requesttypedescription': u 'AUTH',
u 'securityresponsesecuritycode': u '2',
u 'currencyiso3a': u 'GBP',
u 'authcode': u 'TEST40',
u 'errormessage': u 'Ok',
u 'operatorname': u '[email protected]',
u 'maskedpan': u '411111######0211',
u 'securityresponsepostcode': u '0',
u 'enrolled': u 'Y',
u 'securityresponseaddress': u '0',
u 'issuercountryiso2a': u 'US',
u 'settlestatus': u '0'
}]
}
array(3) {
["requestreference"] => string(9) "A278afgrx"
["version"] => string(4) "1.00"
["response"] => array(1) {
[0] => array(33) {
["transactionstartedtimestamp"] => string(19) "2016-12-09 11:46:34"
["parenttransactionreference"] => string(10) "1-2-345678"
["livestatus"] => string(1) "0"
["issuer"] => string(26) "SecureTrading Test Issuer1"
["splitfinalnumber"] => string(1) "1"
["xid"] => string(28) "ZlcyU1hQcUhmaEtzd2I1SmkrMnM="
["dccenabled"] => string(1) "0"
["settleduedate"] => string(10) "2016-12-09"
["errorcode"] => string(1) "0"
["tid"] => string(8) "27882788"
["merchantnumber"] => string(8) "00000000"
["merchantcountryiso2a"] => string(2) "GB"
["status"] => string(1) "Y"
["transactionreference"] => string(10) "1-2-345679"
["merchantname"] => string(13) "Test Merchant"
["paymenttypedescription"] => string(4) "VISA"
["baseamount"] => string(4) "1050"
["enrolled"] => string(1) "Y"
["eci"] => string(2) "05"
["accounttypedescription"] => string(4) "ECOM"
["cavv"] => string(28) "Q0FWVkNBVlZDQVZWQ0FWVkNBVlY="
["acquirerresponsecode"] => string(2) "00"
["requesttypedescription"] => string(4) "AUTH"
["securityresponsesecuritycode"] => string(1) "2"
["currencyiso3a"] => string(3) "GBP"
["authcode"] => string(6) "TEST30"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "[email protected]"
["securityresponsepostcode"] => string(1) "0"
["maskedpan"] => string(16) "411111######0211"
["securityresponseaddress"] => string(1) "0"
["issuercountryiso2a"] => string(2) "US"
["settlestatus"] => string(1) "0"
}
}
}
{"requestreference":"W23-n68rw97k","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 17:21:59","parenttransactionreference":"1-2-345678","livestatus":"0","issuer":"SecureTrading Test Issuer1","splitfinalnumber":"1","xid":"ZldiREFPMW5HYi90UDhxMDJTV2Q=","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","status":"Y","transactionreference":"1-2-345679","merchantname":"Test Merchant","paymenttypedescription":"VISA","baseamount":"1050","enrolled":"Y","eci":"05","accounttypedescription":"ECOM","cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST05","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######0211","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"bsZP"}
Enrolled but NOT authenticated
{
u 'requestreference': u 'Aq2qmp0j3',
u 'version': u '1.00',
u 'response': [{
u 'transactionstartedtimestamp': u '2016-12-13 11:11:58',
u 'parenttransactionreference': u '1-2-345678',
u 'livestatus': u '0',
u 'issuer': u 'SecureTrading Test Issuer1',
u 'splitfinalnumber': u '1',
u 'dccenabled': u '0',
u 'settleduedate': u '2016-12-13',
u 'errorcode': u '60022',
u 'tid': u '27882788',
u 'merchantnumber': u '00000000',
u 'merchantcountryiso2a': u 'GB',
u 'status': u 'N',
u 'transactionreference': u '1-2-345679',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'baseamount': u '1050',
u 'accounttypedescription': u 'ECOM',
u 'requesttypedescription': u 'AUTH',
u 'currencyiso3a': u 'GBP',
u 'maskedpan': u '411111######0211',
u 'errormessage': u 'Unauthenticated',
u 'operatorname': u '[email protected]',
u 'enrolled': u 'Y',
u 'issuercountryiso2a': u 'US',
u 'settlestatus': u '3'
}]
}
array(3) {
["requestreference"] => string(9) "A35ahjnwx"
["version"] => string(4) "1.00"
["response"] => array(1) {
[0] => array(25) {
["transactionstartedtimestamp"] => string(19) "2016-12-13 10:41:57"
["parenttransactionreference"] => string(10) "1-2-345678"
["livestatus"] => string(1) "0"
["issuer"] => string(26) "SecureTrading Test Issuer1"
["splitfinalnumber"] => string(1) "1"
["dccenabled"] => string(1) "0"
["settleduedate"] => string(10) "2016-12-13"
["errorcode"] => string(5) "60022"
["tid"] => string(8) "27882788"
["merchantnumber"] => string(8) "00000000"
["merchantcountryiso2a"] => string(2) "GB"
["status"] => string(1) "N"
["transactionreference"] => string(10) "1-2-345679"
["merchantname"] => string(13) "Test Merchant"
["paymenttypedescription"] => string(4) "VISA"
["baseamount"] => string(3) "1050"
["accounttypedescription"] => string(4) "ECOM"
["requesttypedescription"] => string(4) "AUTH"
["currencyiso3a"] => string(3) "GBP"
["maskedpan"] => string(16) "411111######0211"
["errormessage"] => string(15) "Unauthenticated"
["operatorname"] => string(23) "[email protected]"
["enrolled"] => string(1) "Y"
["issuercountryiso2a"] => string(2) "US"
["settlestatus"] => string(1) "3"
}
}
}
{
"requestreference": "W23-mjuwx1f5",
"version": "1.00",
"response": [{
"transactionstartedtimestamp": "2016-12-13 11:00:44",
"parenttransactionreference": "1-2-345678",
"livestatus": "0",
"issuer": "SecureTrading Test Issuer1",
"splitfinalnumber": "1",
"dccenabled": "0",
"settleduedate": "2016-12-13",
"errorcode": "60022",
"tid": "27882788",
"merchantnumber": "00000000",
"merchantcountryiso2a": "GB",
"status": "N",
"transactionreference": "1-2-345679",
"merchantname": "Test Merchant",
"paymenttypedescription": "VISA",
"baseamount": "1050",
"accounttypedescription": "ECOM",
"requesttypedescription": "AUTH",
"currencyiso3a": "GBP",
"maskedpan": "411111######0211",
"errormessage": "Unauthenticated",
"operatorname": "[email protected]",
"enrolled": "Y",
"issuercountryiso2a": "US",
"settlestatus": "3"
}],
"secrand": "3J"
Not enrolled
{
u 'requestreference': u 'Adyw3fdbw',
u 'version': u '1.00',
u 'response': [{
u 'transactionstartedtimestamp': u '2016-12-07 16:47:39',
u 'parenttransactionreference': u '1-2-345678',
u 'livestatus': u '0',
u 'issuer': u 'SecureTrading Test Issuer1',
u 'splitfinalnumber': u '1',
u 'dccenabled': u '0',
u 'settleduedate': u '2016-12-07',
u 'errorcode': u '0',
u 'tid': u '27882788',
u 'merchantnumber': u '00000000',
u 'merchantcountryiso2a': u 'GB',
u 'transactionreference': u '1-2-345679',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'baseamount': u '1050',
u 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u '00',
u 'requesttypedescription': u 'AUTH',
u 'securityresponsesecuritycode': u '2',
u 'currencyiso3a': u 'GBP',
u 'authcode': u 'TEST23',
u 'errormessage': u 'Ok',
u 'operatorname': u '[email protected]',
u 'maskedpan': u '411111######0021',
u 'securityresponsepostcode': u '0',
u 'enrolled': u 'N',
u 'securityresponseaddress': u '0',
u 'issuercountryiso2a': u 'US',
u 'settlestatus': u '0'
}]
}
array(3) {
["requestreference"] => string(9) "A256agnuw"
["version"] => string(4) "1.00"
["response"] => array(1) {
[0] => array(29) {
["transactionstartedtimestamp"] => string(19) "2016-12-09 11:53:36"
["parenttransactionreference"] => string(10) "1-2-345678"
["livestatus"] => string(1) "0"
["issuer"] => string(26) "SecureTrading Test Issuer1"
["splitfinalnumber"] => string(1) "1"
["dccenabled"] => string(1) "0"
["settleduedate"] => string(10) "2016-12-09"
["errorcode"] => string(1) "0"
["tid"] => string(8) "27882788"
["merchantnumber"] => string(8) "00000000"
["merchantcountryiso2a"] => string(2) "GB"
["transactionreference"] => string(10) "1-2-345679"
["merchantname"] => string(13) "Test Merchant"
["paymenttypedescription"] => string(4) "VISA"
["baseamount"] => string(4) "1050"
["enrolled"] => string(1) "N"
["accounttypedescription"] => string(4) "ECOM"
["acquirerresponsecode"] => string(2) "00"
["requesttypedescription"] => string(4) "AUTH"
["securityresponsesecuritycode"] => string(1) "2"
["currencyiso3a"] => string(3) "GBP"
["authcode"] => string(6) "TEST08"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "[email protected]"
["securityresponsepostcode"] => string(1) "0"
["maskedpan"] => string(16) "411111######0021"
["securityresponseaddress"] => string(1) "0"
["issuercountryiso2a"] => string(2) "US"
["settlestatus"] => string(1) "0"
}
}
}
{"requestreference":"W23-fwpp74eu","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 17:24:51","parenttransactionreference":"1-2-345678","livestatus":"0","issuer":"SecureTrading Test Issuer1","splitfinalnumber":"1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345679","merchantname":"Test Merchant","paymenttypedescription":"VISA","baseamount":"1050","enrolled":"N","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST42","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######0021","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"O3L"}
Managing authorisation response
Your system will need to interpret the AUTH response in order to determine if the transaction was successful. The most important field to check in the response is the errorcode.
| Error code | Description |
| 0 | Cardholder was successfully authenticated on the card issuer’s ACS. Customer’s bank authorised the transaction. Funds will be transferred. |
| 70000 | Cardholder was successfully authenticated on the card issuer’s ACS. Customer’s bank declined the transaction. Funds will NOT be transferred. |
| 60022 | Cardholder was NOT successfully authenticated on the card issuer’s ACS. Trust Payments did not contact the acquiring bank to seek authorisation. Funds will NOT be transferred. |
| 99999 | An error code of ‘99999’ indicates an unknown error occurred, which requires manual inspection. We recommend contacting our Support Team for assistance, providing a copy of the entire request submitted and the response returned. In the interest of security, ensure you omit or mask sensitive field values, such as card details. |
| other | Click here for a full list of error codes used by Trust Payments. |
Regardless of the errorcode returned in the response, we strongly recommend that you refer to our best practices and configure your system to perform all of the checks outlined.
Here is the specification of the fields that are included in the AUTH responses described above, which are specific to 3-D Secure:
Key
| Field name | Type | Length | Response | Description |
| enrolled | Char | 1 | |
Indicates if the cardholder is enrolled in a 3-D Secure scheme:
|
| xid | Alphanumeric | 255 | |
The unique identifier for the transaction, assigned by the MPI (Merchant Plug-In) (in this case, Trust Payments). |
| status | Char | 1 | |
Returned if card is enrolled.
Indicates whether or not the customer was authenticated on the card issuer’s ACS:
|
| cavv | Alphanumeric | 32 | |
Returned if card is enrolled and authenticated.
The unique Cardholder Authentication Verification Value (CAVV) associated with the transaction, provided by the card issuer. |
| eci | Alphanumeric | 2 | |
Returned if card is enrolled and authenticated.
The ECI (E-Commerce Indicator) security level associated with the transaction. |
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.