Protect Plus (API)
If you are unsure, please contact our Support Team for assistance.
Protect Plus is a sophisticated counter-fraud service that provides your site with an extra layer of security against fraudulent transactions. It makes use of the industry’s largest negative database to perform a comprehensive suite of fraud assessments, including identity checks against the UK electoral roll and BT databases.
Process overview
Before you can get started, you will need to contact our Sales Team and enable Protect Plus on your account.
What checks are performed?
We analyse the customer’s billing, delivery and payment details using a rule-based system to detect suspicious patterns in user activity. Our system will assist you in deciding on whether or not to process a customer’s transaction based on the perceived level of risk. Checks performed include:
- The industry’s largest negative database.
- Neural-based fraud assessments.
- Tumbling or Swapping, where there is an unusual usage pattern in the card number, expiration date or customer details associated with a transaction.
What happens after the checks are performed?
The Protect Plus system will analyse transaction details and issue one of the following fraudcontrolshieldstatuscode values:
| “ACCEPT” | The details are not deemed suspicious. |
| “CHALLENGE” | Further investigation is recommended. |
| “DENY” | The details are suspicious and a transaction should not be performed. |
| “NOSCORE” | Transaction was declined by the acquirer before checks were performed. |
Order of requests
Protect Plus checks are performed when a RISKDEC request is submitted to our system. There are two methods in which you can configure your system to process RISKDEC requests using our Webservices API:
- RISKDEC then AUTH – Perform the checks first, then seek authorisation for the payment. By default, we suspend suspicious payments, allowing you to investigate them before proceeding.
- AUTH then RISKDEC – Seek authorisation for the payment first, then perform the checks. Checks performed are more accurate because they take the results of AVS, Security Code Checks and 3-D Secure into account.
RISKDEC then AUTH request
Process overview
- When the customer clicks “Pay” on your checkout, your system submits a RISKDEC request to Trust Payments using the Webservices API (we provide an example of how to structure this request below).
- Trust Payments checks the payment details, generates a fraudcontrolshieldstatuscode and returns this information to your system in a RISKDEC response.
- Your system will need to check the shield status code and determine whether or not to proceed with the payment.
- If you opt to process the payment, you can process a payment using our JavaScript as described here, with one important difference.
The JWT in the payload must be updated to include field parenttransactionreference, including the unique transactionreference returned in the RISKDEC response.
This is used to inherit data from the initial request. - Trust Payments contacts the acquiring bank to process the payment.
- Trust Payments returns the response JWT to your system. You will need to interpret the response.
RISKDEC request example
Here is an example of a RISKDEC request, the details of which can be inherited in future payments processed using our JavaScript Library:
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) riskdec= { "sitereference": "test_site12345", "requesttypedescriptions": ["RISKDEC"], "accounttypedescription": "ECOM", "currencyiso3a": "GBP", "baseamount": "1011", "orderreference": "My_Order_123", "pan": "4111111111111111", "expirydate": "12/2020", "securitycode": "123" } strequest = securetrading.Request() strequest.update(riskdec) 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('RISKDEC'),
'accounttypedescription' => 'FRAUDCONTROL',
'currencyiso3a' => 'GBP',
'baseamount' => '1011',
'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": [{ "currencyiso3a": "GBP", "requesttypedescriptions": ["RISKDEC"], "sitereference": "test_site12345", "baseamount": "1011", "orderreference": "My_Order_123", "accounttypedescription": "FRAUDCONTROL", "pan": "4111111111111111", "expirydate": "12/2020", "securitycode": "123" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["RISKDEC"],"sitereference":"test_site12345","baseamount":"1011","orderreference":"My_Order_123","accounttypedescription":"FRAUDCONTROL","pan":"4111111111111111","expirydate":"12\/2020"}]}
<?xml version="1.0" encoding="utf-8"?> <requestblock version="3.67"> <alias>[email protected]</alias> <request type="RISKDEC"> <merchant> <orderreference>My_Order_123</orderreference> </merchant> <billing> <amount currencycode="GBP">1011</amount> <payment> <expirydate>12/2020</expirydate> <pan>4111111111111111</pan> </payment> </billing> <operation> <accounttypedescription>FRAUDCONTROL</accounttypedescription> <sitereference>test_site12345</sitereference> </operation> </request> </requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
RISKDEC response example
Here is an example of the associated RISKDEC response:
For the RISKDEC response field specification, scroll down to the “Interpreting the response” section.
{
u 'requestreference': u 'A0dcb11e6',
u 'version': u '1.00',
u 'response': [{
u 'acquirerrecommendedaction': u 'C',
u 'fraudcontrolresponsecode': u '0100',
u 'paymenttypedescription': u 'VISA',
u 'orderreference': u 'My_Order_123',
u 'transactionstartedtimestamp': u '2016-12-07 16:19:28',
u 'errormessage': u 'Ok',
u 'operatorname': u '[email protected]',
u 'fraudcontrolreference': u 'TEST',
u 'accounttypedescription': u 'FRAUDCONTROL',
u 'errorcode': u '0',
u 'transactionreference': u '1-2-345678',
u 'maskedpan': u '411111######1111',
u 'requesttypedescription': u 'RISKDEC',
u 'fraudcontrolshieldstatuscode': u 'ACCEPT',
u 'livestatus': u '0'
}]
}
array(3) {
["requestreference"] => string(9) "A58cdfkpy"
["version"] => string(4) "1.00"
["response"] => array(1) {
[0] => array(15) {
["errorcode"] => string(1) "0"
["orderreference"] => string(12) "My_Order_123"
["fraudcontrolresponsecode"] => string(4) "0100"
["paymenttypedescription"] => string(4) "VISA"
["maskedpan"] => string(16) "411111######1111"
["transactionstartedtimestamp"] => string(19) "2016-12-09 11:12:39"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "[email protected]"
["accounttypedescription"] => string(12) "FRAUDCONTROL"
["acquirerrecommendedaction"] => string(1) "C"
["transactionreference"] => string(9) "1-2-345678"
["requesttypedescription"] => string(7) "RISKDEC"
["fraudcontrolreference"] => string(4) "TEST"
["fraudcontrolshieldstatuscode"] => string(6) "ACCEPT"
["livestatus"] => string(1) "0"
}
}
}
{"requestreference":"W23-wt77f0n8","version":"1.00","response":[{"errorcode":"0","fraudcontrolresponsecode":"0100","paymenttypedescription":"VISA","orderreference":"My_Order_123","transactionstartedtimestamp":"2016-12-07 16:23:03","errormessage":"Ok","operatorname":"[email protected]","accounttypedescription":"FRAUDCONTROL","acquirerrecommendedaction":"C","transactionreference":"1-2-345678","requesttypedescription":"RISKDEC","maskedpan":"411111######1111","fraudcontrolreference":"TEST","fraudcontrolshieldstatuscode":"ACCEPT","livestatus":"0"}],"secrand":"E0ksvyuH5VKg"}
<?xml version="1.0" encoding="utf-8"?>
<responseblock version="3.67">
<requestreference>X336659733</requestreference>
<response type="RISKDEC">
<merchant>
<orderreference>My_Order_123</orderreference>
<operatorname>[email protected]</operatorname>
</merchant>
<transactionreference>1-2-345678</transactionreference>
<billing>
<payment type="VISA">
<pan>411111######1111</pan>
</payment>
</billing>
<timestamp>2012-06-21 13:32:43</timestamp>
<fraudcontrol>
<shieldstatuscode>ACCEPT</shieldstatuscode>
<reference>TEST</reference>
<recommendedaction>C</recommendedaction>
<responsecode>0100</responsecode>
</fraudcontrol>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<operation>
<accounttypedescription>FRAUDCONTROL</accounttypedescription>
</operation>
</response>
<secrand>2ngbLQ3DO</secrand>
</responseblock>
AUTH then RISKDEC request
Process overview
- When the customer clicks “Pay” on your checkout, the JavaScript library submits a request to Trust Payments.
- Trust Payments contacts the acquiring bank to process the payment.
- Trust Payments returns the response JWT to your system. You will need to interpret the response.
- Following this, your system submits a RISKDEC request to Trust Payments using the Webservices API, including the field parenttransactionreference, which is the unique transactionreference value returned in the response JWT (we provide an example of how to structure this request below).
- Trust Payments checks the payment details, generates a fraudcontrolshieldstatuscode and returns this information to your system in a RISKDEC response.
- Your system will need to check the shield status code and determine whether or not to proceed with the payment.
- If you want to suspend or cancel a payment, you will need to process a transaction update request using the Webservices API.
Request example
Here is an example of a RISKDEC request to be submitted using our Webservices API, following a payment processed using our JavaScript Library.
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) riskdec= { "sitereference": "test_site12345", "requesttypedescriptions": ["RISKDEC"], "accounttypedescription": "FRAUDCONTROL", "currencyiso3a": "GBP", "baseamount": "1011", "orderreference": "My_Order_123", "parenttransactionreference": "1-2-3" } strequest = securetrading.Request() strequest.update(riskdec) 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('RISKDEC'),
'accounttypedescription' => 'FRAUDCONTROL',
'currencyiso3a' => 'GBP',
'baseamount' => '1011',
'orderreference' => 'My_Order_123',
'parenttransactionreference' => '1-2-3'
);
$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" -d '{ "alias": "[email protected]", "version": "1.00", "request": [{ "currencyiso3a": "GBP", "requesttypedescriptions": ["RISKDEC"], "sitereference": "test_site12345", "baseamount": "1011", "orderreference": "My_Order_123", "accounttypedescription": "FRAUDCONTROL", "parenttransactionreference": "1-2-3" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["RISKDEC"],"sitereference":"test_site12345","baseamount":"1011","orderreference":"My_Order_123","accounttypedescription":"FRAUDCONTROL","parenttransactionreference":"1-2-3"}]}
<?xml version="1.0" encoding="utf-8"?> <requestblock version="3.67"> <alias>[email protected]</alias> <request type="RISKDEC"> <merchant> <orderreference>My_Order_123</orderreference> </merchant> <billing> <amount currencycode="GBP">1011</amount> </billing> <operation> <parenttransactionreference>1-2-3</parenttransactionreference> <accounttypedescription>FRAUDCONTROL</accounttypedescription> <sitereference>test_site12345</sitereference> </operation> </request> </requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Response example
Here is an example of the associated RISKDEC response:
For the RISKDEC response field specification, scroll down to the “Interpreting the response” section.
{
u 'requestreference': u 'Ad4ft45gp',
u 'version': u '1.00',
u 'response': [{
u 'acquirerrecommendedaction': u 'C',
u 'fraudcontrolresponsecode': u '0100',
u 'paymenttypedescription': u 'VISA',
u 'orderreference': u 'My_Order_123',
u 'transactionstartedtimestamp': u '2016-12-07 16:25:19',
u 'errormessage': u 'Ok',
u 'operatorname': u '[email protected]',
u 'parenttransactionreference': u '1-2-345678',
u 'fraudcontrolreference': u 'TEST',
u 'accounttypedescription': u 'FRAUDCONTROL',
u 'errorcode': u '0',
u 'transactionreference': u '1-2-345679',
u 'maskedpan': u '411111######1111',
u 'requesttypedescription': u 'RISKDEC',
u 'fraudcontrolshieldstatuscode': u 'ACCEPT',
u 'livestatus': u '0'
}]
}
array(3) {
["requestreference"] => string(9) "A0bjmprty"
["version"] => string(4) "1.00"
["response"] => array(1) {
[0] => array(16) {
["errorcode"] => string(1) "0"
["orderreference"] => string(12) "My_Order_123"
["fraudcontrolresponsecode"] => string(4) "0100"
["paymenttypedescription"] => string(4) "VISA"
["maskedpan"] => string(16) "411111######1111"
["transactionstartedtimestamp"] => string(19) "2016-12-09 11:14:35"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "[email protected]"
["parenttransactionreference"] => string(10) "1-2-345678"
["accounttypedescription"] => string(12) "FRAUDCONTROL"
["acquirerrecommendedaction"] => string(1) "C"
["transactionreference"] => string(9) "1-2-345679"
["requesttypedescription"] => string(7) "RISKDEC"
["fraudcontrolreference"] => string(4) "TEST"
["fraudcontrolshieldstatuscode"] => string(6) "ACCEPT"
["livestatus"] => string(1) "0"
}
}
}
{"requestreference":"W23-eyqd5u3x","version":"1.00","response":[{"errorcode":"0","fraudcontrolresponsecode":"0150","paymenttypedescription":"VISA","orderreference":"My_Order_123","transactionstartedtimestamp":"2016-12-07 16:24:50","errormessage":"Ok","operatorname":"[email protected]","parenttransactionreference":"1-2-345678","accounttypedescription":"FRAUDCONTROL","acquirerrecommendedaction":"C","transactionreference":"1-2-345679","requesttypedescription":"RISKDEC","maskedpan":"411111######1111","fraudcontrolreference":"TEST","fraudcontrolshieldstatuscode":"ACCEPT","livestatus":"0"}],"secrand":"ft9j6l"}
<?xml version="1.0" encoding="utf-8"?>
<responseblock version="3.67">
<requestreference>X336659733</requestreference>
<response type="RISKDEC">
<merchant>
<orderreference>My_Order_123</orderreference>
<operatorname>[email protected]</operatorname>
</merchant>
<transactionreference>18-65-2</transactionreference>
<billing>
<payment type="VISA">
<pan>411111######1111</pan>
</payment>
</billing>
<timestamp>2012-06-21 13:32:43</timestamp>
<fraudcontrol>
<shieldstatuscode>ACCEPT</shieldstatuscode>
<reference>TEST</reference>
<recommendedaction>C</recommendedaction>
<responsecode>0150</responsecode>
</fraudcontrol>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<operation>
<parenttransactionreference>1-2-345679</parenttransactionreference>
<accounttypedescription>FRAUDCONTROL</accounttypedescription>
</operation>
</response>
<secrand>UIPGZ</secrand>
</responseblock>
Interpreting the response
Here is the field specification for a RISKDEC response:
| Field | Format | Description | |
 |
acquirerrecommendedaction XPath: /fraudcontrol/recommendedaction |
Char (1) | Either:
Note that this is ONLY a recommendation. Protect Plus does not guarantee against fraud. |
|
fraudcontrolreference XPath: /fraudcontrol/reference |
Alphanumeric (255) | Unique reference to identify the Risk Decision check performed. |
|
fraudcontrolresponsecode XPath: /fraudcontrol/responsecode |
Numeric (4) | A numeric code that is mapped to a description of the results of the Risk Decision checks performed. |
|
fraudcontrolshieldstatuscode XPath: /fraudcontrol/shieldstatuscode |
Alpha (10) | One of the following values:
|
|
requesttypedescription XPath: /@type |
Alpha (20) | You will be returned “RISKDEC”. |
 |
rulecategoryflag XPath: /fraudcontrol/categoryflag |
Alphanumeric (255) | Reference used to identify a condition that was met to return the DENY or CHALLENGE fraudcontrolshieldstatuscode. |
|
rulecategorymessage XPath: /fraudcontrol/categorymessage |
Text (undefined length) | Condition that was met to return the DENY or CHALLENGE fraudcontrolshieldstatuscode. |
Testing
We recommend that you thoroughly test your solution before enabling on your live Site Reference.
Click here for details that you can submit to simulate different RISKDEC responses on our test system.
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.
Testing
Use the credentials provided on this page to test your solution.
When you sign up, you will be provided with a “live” account and a “test” account (the latter is prefixed with “test_”).
When testing, ensure requests submitted to Trust Payments reference your test sitereference.
Before you begin testing…
Please be aware of the following notes:
- Most fields submitted to our test system will be accepted. Any data breaching its defined specification will return an error message.
- Any test data that generates a successful response when submitted while a merchant is in test mode, will produce a declined response when a merchant is switched into live mode. In some cases, the test data may return an error response.
- Our test system attempts to simulate responses in a similar fashion to the live system. However, depending on your acquirer you may find some responses differ slightly from those given by the test system.
- In the interest of security, we recommend against using real payment details when using your test account.
- We recommend specifying the main amount “10.50” when testing. Other amounts can be used but may return unexpected responses.
- If you’re unsure where to start with your testing, you may find these resources helpful:
Test card details
The table below lists test card numbers and customer information that can be submitted to our test bank, along with the responses that should be expected in return.
- A baseamount of 70000 (£700.00) will always return a declined response from the test bank.
- A baseamount of 60010 (£600.10) will always return a bank system error from the test bank.
- Using baseamount 1050 (£10.50) will not generate an error.
3-D Secure v2
The following payment credentials can be used for testing 3-D Secure v2 (a form of SCA):
| Test case | Visa | Mastercard | American Express |
| Success frictionless | 4000000000001026 | 5200000000001005 | 340000000001007 |
| Success step-up | 4000000000001091 | 5200000000001096 | 340000000001098 |
| Failed frictionless | 4000000000001018 | 5200000000001013 | 340000000001015 |
| Failed step-up | 4000000000001109 | 5200000000001104 | 340000000001106 |
| Declined | 4242424242424242 | 5100000000000412 | 300000000000512 |
3-D Secure v1
The following payment credentials can be used for testing 3-D Secure v1 (a form of SCA):
Visa-branded cards
| Visa |
|||||
| Credit | Debit | V Pay | Electron | Purchasing | |
| Enrolled (Y) | 4111110000000211 | 4006260000002473 | 4370000000000111 | 4245190000000311 | 4484000000000411 |
| Not enrolled (N) | 4111110000000021 | 4006260000002481 | 4370000000000921 | 4245190000000121 | 4484000000000221 |
| Unknown enrollment (U) | 4111110000000401 | 4006260000002408 | 4370000000002307 | 4245190000000501 | 4484000000000601 |
Mastercard-branded cards
| Test case | Mastercard |
|||
| Credit | Debit | Maestro (Intl.) | Maestro (UK) | |
| Enrolled (Y) | 5100000000000511
2221000000000611 |
5124990000000911 | 5000000000000611 | 6759000000000711 |
| Not enrolled (N) | 5100000000000321
2221000000000991 |
5124990000000721 | 5000000000000421 | 6759000000000521 |
| Unknown enrollment (U) | 5100000000000701
2221000000000801 |
5124990000000101 | 5000000000000801 | 6759000000000901 |
3-D Secure status testing
To test for different 3-D Secure status values, follow the instructions displayed in the authentication prompt shown on the page (an example is shown below). In the textbox provided, you can enter different PIN values to test for different cases.
For Payment Pages:
With 3-D Secure enabled on your site reference, process a payment using one of the card numbers listed above and your browser will display an authentication prompt with instructions.
For JavaScript library implementations:
After your payment form has been updated to reference our JavaScript library, process a payment using one of the card numbers listed above and your browser will display an authentication prompt with instructions.
The authentication prompt will only be displayed for non-frictionless test card details.
Frictionless cards will bypass authentication. In this case, the payment will be processed immediately (without being prompted by the browser for information).
Follow the instructions displayed within the authentication prompt to complete the payment:
Non 3-D Secure
The following card types are not currently processed using 3-D Secure (a form of SCA):
| Card type | Authorisation | Decline | Expiry date | Security code |
| DINERS | 3000000000000111 | 3000000000000012 | 12/2030 | 123 |
| DISCOVER | 6011000000000301 | 6011000000000202 | 12/2030 | 123 |
| JCB | 3528000000000411 | 3528000000000312 | 12/2030 | 123 |
After the payment has been processed, the error code and status values stored with the processed AUTH are used to convey the final outcome.
Testing AVS and security code checks
If you haven’t already, please read our AVS and Security code documentation before testing:
Link to Payment Pages docs / Link to API docs
The following tables list test details that can be submitted to obtain different responses from the AVS and Security Code Checks. These details can be used with most major payment types.
Premise
| Billing premise | Security response | Security response caption |
| No 789 | 2 | Matched |
| No 123 | 4 | Not Matched |
| No 333 | 1 | Not Checked |
| Leave blank | 0 | Not Given |
Postcode / ZIP code
| Billing postcode | Security response | Security response caption | |
| UK | US | ||
| TE45 6ST | 55555 | 2 | Matched |
| TE12 3ST | 12345 | 4 | Not Matched |
| TE33 3ST | 33333 | 1 | Not Checked |
| Leave blank | Leave blank | 0 | Not Given |
Security code
| Security code | AMEX security code | Security response | Security response |
| 123 | 1234 | 2 | Matched |
| 214 | 2144 | 4 | Not Matched |
| 333 | 3333 | 1 | Not Checked |
| Leave blank | Leave blank | 0 | Not Given |
Testing non-card payment methods
Link to Payment Pages docs / Link to API docs
Testing recurring payments
Testing for the acquirer advice code
When processing recurring payments, some acquirers may return an acquirer advice code in the response. The acquirer advice code is a numeric value used to indicate if further recurring payments can be processed for the given card.
| Code | Description | Action |
| 0 | N/A | No action required |
| 1 | New account information available (Mastercard only) | Query customer for updated payment details |
| 2 | Cannot approve at this time | Try again later. If you are continuing to have difficulties, please contact your acquiring bank |
| 4 | Do not try again | Do not process further recurring transactions |
| 8 | Payment blocked by card scheme |
Where to find the acquirer advice code
- This code is returned in your daily subscription email report.
- It’s viewable within MyST by selecting the additional field to be displayed on the transaction search page. It can also be viewed on the single transaction view.
- Additionally, for those who have processed a recurring AUTH transaction using the API, the code is returned in the acquireradvicecode field in the response.
How to test for different acquirer advice codes
You can test that your system responds appropriately to different acquirer advice codes by processing transactions with the following attributes:
| Visa | ||
| Acquirer advice code returned | Card number | Base amount |
| 0 | 4111111111111111 | 1050 |
| 2 | 4000000000000671 | 1002 |
| 4 | 4000000000000671 | 1004 |
| 8 | 4000000000000671 | 1008 |
| Mastercard | ||
| Acquirer advice code returned | Card number | Base amount |
| 0 | 5100000000000511 | 1050 |
| 1 | 5100000000000271 | 1001 |
| 2 | 5100000000000271 | 1002 |
| 4 | 5100000000000271 | 1004 |
| 8 | 5100000000000271 | 1008 |
Testing Protect Plus
If you haven’t already, please read our Protect Plus document before testing:
Link to Payment Pages docs / Link to API docs
Use the following baseamount values in RISKDEC requests to simulate the different possible responses from the Protect Plus checks:
| baseamount | Possible fraudcontrolresponsecode returned | fraudcontrolshieldstatuscode returned |
| 1011, 2011, 3011 | 0100, 0150 | “ACCEPT” |
| 1033, 2033, 3033 | 0300, 0330, 0500 | “CHALLENGE” |
| 1044, 2044, 3044 | 0250, 0400, 0600, 0700, 0800, 1300 | “DENY” |
Testing DCC
If you haven’t already, please read our DCC document before testing:
Link to Payment Pages docs / Link to API docs
The card numbers listed in this test section are associated with specific local currencies. During your integration, you can use the following international test card details in order to test your system for successful and declined DCC transactions.
Successful authorisations
| Country code | Currency code | Visa Credit | Mastercard Credit |
| DE | EUR | 4500000000000007 | 5500000000000004 |
| GB | GBP | 4300000000002211 | 5311110000001511 |
| JP | JPY | 4900400000000005 | 5590410000000006 |
| US | USD | 4900460000000009 | 5590470000000018 |
Declined authorisations
| Country code | Currency code | Visa Credit | Mastercard Credit |
| DE | EUR | 4500000000002482 | 5500000000002422 |
| GB | GBP | 4300000000002492 | 5311110000002402 |
| JP | JPY | 4900400000002472 | 5590410000002432 |
| US | USD | 4900460000002492 | 5590470000002402 |
Best practices
When receiving our response, your system will need to perform the following checks on the values returned (where applicable) to ensure the request was processed successfully.
Error code
The errorcode is a fundamentally important field as it displays the outcome of the submitted request. It is returned in every response from Trust Payments.
If the errorcode is “0”, this indicates the request was processed successfully.
It is imperative that you have a process in place to check the final status of the processed request, by looking at the values of the other fields returned.
If the errorcode is “30000”, this indicates a field error.
If you look at the errordata field returned, this typically contains the name of the field that was deemed invalid. You will need to retry the request, ensuring all required fields have been submitted, and that all submitted field values follow our specification.
If the errorcode is “70000”, this indicates a payment was declined by your bank.
We recommend that you show an error message to the customer and allow them to try a different method of payment.
If the errorcode is “60010”, “60034” or “99999”, there has been a problem processing the request and the final status is not known.
This can be due to a communication problem with a bank or third party. In such cases, we recommend informing the customer of the problem and to contact you to query the issue. You will need to contact our Support team, providing a copy of the entire request submitted and response returned, and we will contact the relevant parties to establish the status of the request. In the interest of security, ensure you omit or mask sensitive field values, such as card details.
If the errorcode is not listed above, please refer to our full list of errorcodes for assistance. If you need further help, please contact our Support team.
Settle status
It is important to check the value of the settlestatus when processing an AUTH or REFUND request, as this indicates if Settlement will be performed. Here are the basics:
If the settlestatus is “0”, “1” or “10”, you do not need to take any further actions.
The transaction is currently scheduled to settle.
If the settlestatus is “100”, the transaction has been settled.
You cannot perform any further updates to the transaction.
If the settlestatus is “2”, the transaction has been suspended.
Funds will not be settled without your intervention. Please refer to our settlement documentation for further information.
If the settlestatus is “3”, the transaction has been cancelled.
Funds will not be settled and you will need to investigate the problem and try again. In this scenario, it is useful to look at the accompanying errorcode as this will often inform you of the reason behind the transaction failing.
If you haven’t already, we recommend you read our settlement documentation for further detail on how settlement is performed.
Security response
If the AVS and Security Code Checks are performed as part of the request (as is the case for most AUTH and ACCOUNTCHECKs), you will need to check the three security response fields returned, which are defined as follows:
- securityresponseaddress – Does the first line of the billing address entered by the customer match that found on their bank account?
- securityresponsepostcode – Does the billing postcode entered by the customer match that found on their bank account?
- securityresponsesecuritycode – Does the security code entered by the customer match the value found on the back of their card?
If the value is “2”, the customer entered the correct details.
If all values are “2”, there is no reason here to prevent the transaction from settling.
If the value is “1”, the bank was unable to check the customer’s details.
This may be because the customer has a card issued by a foreign country, and your bank was therefore unable to check their address. You may need to consider suspending transactions that fall into this category to allow you to investigate before proceeding with the payment.
If the value is “0”, the customer’s details were not sent to the bank.
This is because the customer didn’t enter any of the details at all, or that these details were not submitted in your request. You may need to consider suspending transactions that fall into this category to allow you to investigate before proceeding with the payment.
If the value is “4”, the customer entered incorrect details.
By default, we will suspend transactions where the security code entered by the customer fails to match the value on their card. Depending on your preferences, you may also prefer to suspend transactions where the address details do not match (disabled by default).
You can request that Trust Payments automatically cancels transactions when the security response fields have a certain value. As mentioned above, we suspend all transactions where the security code entered by the customer fails to match the value on their card. You can specify the circumstances under which transactions are suspended to match your own preferences (you can even disable such checks entirely). This is achieved by modifying your Security Policy. To discuss changes to your account’s security policy, please contact our Support team.
Request type description
Each response will contain a requesttypedescription. The value of this field returned in the response should always match the value submitted in the request.
e.g. If you are sending an “AUTH” request, ensure the requesttypedescription returned is “AUTH”.
If you receive requesttypedescription with value “ERROR”, the request may not have been processed successfully and you will need to investigate.
Live status
Check the live status value returned is “0” while testing and “1” when processing live payments.
Amount & currency
When submitting an amount and currency, check that the same values are returned in the response.
Response site security
If you are processing transactions using our Payment Pages interface, and have configured URL notifications or redirects to be triggered upon transaction completion, you will need to re-calculate the site security hash using the fields returned and check it matches the corresponding hash returned from Trust Payments. This is to ensure the content returned hasn’t been modified by an unauthorised party. Click here to learn more.
Account checks (API)
If you are unsure, please contact our Support Team for assistance.
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.
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.
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” errorcode being returned in the response.
ACCOUNTCHECK request
The fields required in an ACCOUNTCHECK request are the same as a standard AUTH request. The difference is that the baseamount can be “0”. You can also submit any field that you can submit in an AUTH request and these will be inherited by any subsequent child requests.
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": "ECOM", "pan": "4111111111111111", "expirydate": "12/2020", "securitycode": "123", "billingpremise": "789", "billingpostcode": "TE45 6ST" } 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' => 'ECOM',
'pan' => '4111111111111111',
'expirydate' => '12/2020',
'securitycode' => '123',
'billingpremise' => '789',
'billingpostcode' => 'TE45 6ST'
);
$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": "ECOM", "pan": "4111111111111111", "expirydate": "12/2020", "securitycode": "123", "billingpremise": "789", "billingpostcode": "TE45 6ST" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["ACCOUNTCHECK"],"sitereference":"test_site12345","baseamount":"0","orderreference":"My_Order_123","accounttypedescription":"ECOM","pan":"4111111111111111","expirydate":"12\/2020","securitycode":"123","billingpremise":"789","billingpostcode":"TE45 6ST"}]}
<?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>ECOM</accounttypedescription> <sitereference>test_site12345</sitereference> </operation> </request> </requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
ACCOUNTCHECK response
The ACCOUNTCHECK response has the same structure as a standard AUTH response, except for the requesttypedescription value returned being “ACCOUNTCHECK”.
Inheritance
It is possible to take the value of the transactionreference field returned in the ACCOUNTCHECK response and submit this in the parenttransactionreference field of a new request, such as an AUTH. The new request will inherit billing and delivery details from the ACCOUNTCHECK (including the card details required for the payment), which means you are not required to submit this information again.
{
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 'ECOM',
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'
}]
}
array(3) {
["requestreference"] => string(9) "A4cenptwx"
["version"] => string(4) "1.00"
["response"] => array(1) {
[0] => array(27) {
["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) "ECOM"
["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"
}
}
}
{"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":"ECOM","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"}],"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>ECOM</accounttypedescription>
</operation>
</response>
<secrand>bByuPvGz9Hcm</secrand>
</responseblock>
The results of account checks are returned in the securityresponseaddress, securityresponsepostcode and securityresponsesecuritycode fields. The specification of these fields are outlined in the table 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) |
Protect Plus
Protect Plus is a sophisticated counter-fraud service that provides your site with an extra layer of security against fraudulent transactions. It makes use of the industry’s largest negative database to perform a comprehensive suite of fraud assessments, including identity checks against the UK electoral roll and BT databases.
Process overview
Before you can get started, you will need to contact our Sales team and enable Protect Plus on your account.
What checks are performed?
We analyse the customer’s billing, delivery and payment details using a rule-based system to detect suspicious patterns in user activity. Our system will assist you in deciding on whether to process a customer’s transaction based on the perceived level of risk. Checks performed include:
- The industry’s largest negative database.
- Neural-based fraud assessments.
- Tumbling or Swapping, where there is an unusual usage pattern in the card number, expiration date or customer details associated with a transaction.
What happens after the checks are performed?
The Protect Plus system will analyse transaction details and issue one of the following fraudcontrolshieldstatuscode values:
| “ACCEPT” | The details are not deemed suspicious. |
| “CHALLENGE” | Further investigation is recommended. |
| “DENY” | The details are suspicious and a transaction should not be performed. |
| “NOSCORE” | Transaction was declined by the acquirer before checks were performed. |
Order of requests
Protect Plus checks are performed when you submit a RISKDEC request. You can update a standard AUTH request to also include a RISKDEC in two different ways:
- RISKDEC then AUTH – Perform the checks first, then seek authorisation for the payment. By default, we suspend suspicious payments, allowing you to investigate them before proceeding.
- AUTH then RISKDEC – Seek authorisation for the payment first, then perform the checks. Checks performed are more accurate because they take the results of AVS, Security Code Checks and 3-D Secure into account.
RISKDEC then AUTH request
Process overview
- Submit request. Trust Payments checks the transaction details and generates a fraudcontrolshieldstatuscode.
- Trust Payments processes the AUTH.
- If the fraudcontrolshieldstatuscode is “ACCEPT“, Trust Payments returns a response to your server following successful authorisation.
- If the fraudcontrolshieldstatuscode is “CHALLENGE” or “DENY“, Trust Payments automatically suspends the transaction (updates to settle status “2”) following successful authorisation and returns a response to your server. This allows you to review the transaction and either opt to proceed by updating the settle status to “1” or to cancel by updating the settle status to “3”.
Request example
Here is an example of a combined RISKDEC then AUTH request. Notice how the structure is the same as a standard AUTH request, except “RISKDEC” is included in the requesttypedescriptions field before “AUTH”.
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) auth= { "sitereference": "test_site12345", "requesttypedescriptions": ["RISKDEC","AUTH"], "accounttypedescription": "ECOM", "currencyiso3a": "GBP", "baseamount": "1011", "orderreference": "My_Order_123", "cachetoken": "token_posted_by_st.js" } strequest = securetrading.Request() strequest.update(auth) stresponse = st.process(strequest) #stresponse contains the transaction response
<?php
if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);
$configData = array(
'username' => '[email protected]',
'password' => 'Password1^',
);
$requestData = array(
'sitereference' => 'test_site12345',
'requesttypedescriptions' => array('RISKDEC','AUTH'),
'accounttypedescription' => 'ECOM',
'currencyiso3a' => 'GBP',
'baseamount' => '1011',
'orderreference' => 'My_Order_123',
'cachetoken' => 'token_posted_by_st.js'
);
$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": [{ "currencyiso3a": "GBP", "requesttypedescriptions": ["RISKDEC","AUTH"], "sitereference": "test_site12345", "baseamount": "1011", "orderreference": "My_Order_123", "accounttypedescription": "ECOM", "cachetoken": "token_posted_by_st.js" }]}'
Response example
Here is an example of a combined RISKDEC then AUTH response. Notice how the response is divided into two parts; the first represents the “RISKDEC” response and the second represents the “AUTH” response (as indicated by the values of the requesttypedescription fields).
For the RISKDEC response field specification, scroll down to the “Interpreting the response” section.
{
u 'requestreference': u 'A0dcb11e6',
u 'version': u '1.00',
u 'response': [{
u 'acquirerrecommendedaction': u 'C',
u 'fraudcontrolresponsecode': u '0100',
u 'paymenttypedescription': u 'VISA',
u 'orderreference': u 'My_Order_123',
u 'transactionstartedtimestamp': u '2016-12-07 16:19:28',
u 'errormessage': u 'Ok',
u 'operatorname': u '[email protected]',
u 'fraudcontrolreference': u 'TEST',
u 'accounttypedescription': u 'FRAUDCONTROL',
u 'errorcode': u '0',
u 'transactionreference': u '1-2-345678',
u 'maskedpan': u '411111######1111',
u 'requesttypedescription': u 'RISKDEC',
u 'fraudcontrolshieldstatuscode': u 'ACCEPT',
u 'livestatus': u '0'
}, {
u 'transactionstartedtimestamp': u '2016-12-07 16:19:28',
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 'orderreference': u 'My_Order_123',
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 '1011',
u 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u '00',
u 'requesttypedescription': u 'AUTH',
u 'securityresponsesecuritycode': u '2',
u 'currencyiso3a': u 'GBP',
u 'authcode': u 'TEST19',
u 'errormessage': u 'Ok',
u 'operatorname': u '[email protected]',
u 'securityresponsepostcode': u '0',
u 'maskedpan': u '411111######1111',
u 'securityresponseaddress': u '0',
u 'issuercountryiso2a': u 'US',
u 'settlestatus': u '0'
}]
}
array(3) {
["requestreference"] => string(9) "A58cdfkpy"
["version"] => string(4) "1.00"
["response"] => array(2) {
[0] => array(15) {
["errorcode"] => string(1) "0"
["orderreference"] => string(12) "My_Order_123"
["fraudcontrolresponsecode"] => string(4) "0100"
["paymenttypedescription"] => string(4) "VISA"
["maskedpan"] => string(16) "411111######1111"
["transactionstartedtimestamp"] => string(19) "2016-12-09 11:12:39"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "[email protected]"
["accounttypedescription"] => string(12) "FRAUDCONTROL"
["acquirerrecommendedaction"] => string(1) "C"
["transactionreference"] => string(9) "1-2-345678"
["requesttypedescription"] => string(7) "RISKDEC"
["fraudcontrolreference"] => string(4) "TEST"
["fraudcontrolshieldstatuscode"] => string(6) "ACCEPT"
["livestatus"] => string(1) "0"
}
[1] =>array(29) {
["transactionstartedtimestamp"] => string(19) "2016-12-09 11:12:39"
["parenttransactionreference"] => string(9) "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"
["orderreference"] => string(12) "My_Order_123"
["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) "1011"
["accounttypedescription"] => string(4) "ECOM"
["acquirerresponsecode"] => string(2) "00"
["requesttypedescription"] => string(4) "AUTH"
["securityresponsesecuritycode"] => string(1) "2"
["currencyiso3a"] => string(3) "GBP"
["authcode"] => string(6) "TEST53"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "[email protected]"
["securityresponsepostcode"] => string(1) "0"
["maskedpan"] => string(16) "411111######1111"
["securityresponseaddress"] => string(1) "0"
["issuercountryiso2a"] => string(2) "US"
["settlestatus"] => string(1) "0"
}
}
}
{"requestreference":"W23-wt77f0n8","version":"1.00","response":[{"errorcode":"0","fraudcontrolresponsecode":"0100","paymenttypedescription":"VISA","orderreference":"My_Order_123","transactionstartedtimestamp":"2016-12-07 16:23:03","errormessage":"Ok","operatorname":"[email protected]","accounttypedescription":"FRAUDCONTROL","acquirerrecommendedaction":"C","transactionreference":"1-2-345678","requesttypedescription":"RISKDEC","maskedpan":"411111######1111","fraudcontrolreference":"TEST","fraudcontrolshieldstatuscode":"ACCEPT","livestatus":"0"},{"transactionstartedtimestamp":"2016-12-07 16:23:03","parenttransactionreference":"1-2-345678","livestatus":"0","issuer":"SecureTrading Test Issuer1","splitfinalnumber":"1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"1011","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345679","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST14","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######1111","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"E0ksvyuH5VKg"}
AUTH then RISKDEC request
Process overview
- Submit request. Trust Payments processes the AUTH.
- Trust Payments checks the transaction details, generates a fraudcontrolshieldstatuscode and returns a response to your server.
- If the fraudcontrolshieldstatuscode is “CHALLENGE” or “DENY“, Trust Payments recommends that you suspend the transaction (update to settle status “2”) following authorisation and review the details of the transaction before proceeding. At a later time, you can allow the payment to settle by updating the settle status to “1” or alternatively you can cancel by updating the settle status to “3”.
Request example
Here is an example of a combined AUTH then RISKDEC request. Notice how the structure is the same as a standard AUTH request, except “RISKDEC” is included in the requesttypedescriptions field after “AUTH”.
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) auth= { "sitereference": "test_site12345", "requesttypedescriptions": ["AUTH","RISKDEC"], "accounttypedescription": "ECOM", "currencyiso3a": "GBP", "baseamount": "1011", "orderreference": "My_Order_123", "cachetoken": "token_posted_by_st.js" } strequest = securetrading.Request() strequest.update(auth) stresponse = st.process(strequest) #stresponse contains the transaction response
<?php
if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);
$configData = array(
'username' => '[email protected]',
'password' => 'Password1^',
);
$requestData = array(
'sitereference' => 'test_site12345',
'requesttypedescriptions' => array('AUTH','RISKDEC'),
'accounttypedescription' => 'ECOM',
'currencyiso3a' => 'GBP',
'baseamount' => '1011',
'orderreference' => 'My_Order_123',
'cachetoken' => 'token_posted_by_st.js'
);
$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" -d '{ "alias": "[email protected]", "version": "1.00", "request": [{ "currencyiso3a": "GBP", "requesttypedescriptions": ["AUTH","RISKDEC"], "sitereference": "test_site12345", "baseamount": "1011", "orderreference": "My_Order_123", "accounttypedescription": "ECOM", "cachetoken": "token_posted_by_st.js" }]}'
Response example
Here is an example of a combined AUTH then RISKDEC response. Notice how the response is divided into two parts; the first represents the “AUTH” response and the second represents the “RISKDEC” response (as indicated by the values of the requesttypedescription fields).
For the RISKDEC response field specification, scroll down to the “Interpreting the response” section.
{
u 'requestreference': u 'Ad4ft45gp',
u 'version': u '1.00',
u 'response': [{
u 'transactionstartedtimestamp': u '2016-12-07 16:25:19',
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 'orderreference': u 'My_Order_123',
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 'baseamount': u '1011',
u 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u '00',
u 'requesttypedescription': u 'AUTH',
u 'securityresponsesecuritycode': u '2',
u 'currencyiso3a': u 'GBP',
u 'authcode': u 'TEST57',
u 'errormessage': u 'Ok',
u 'operatorname': u '[email protected]',
u 'securityresponsepostcode': u '0',
u 'maskedpan': u '411111######1111',
u 'securityresponseaddress': u '0',
u 'issuercountryiso2a': u 'US',
u 'settlestatus': u '0'
}, {
u 'acquirerrecommendedaction': u 'C',
u 'fraudcontrolresponsecode': u '0100',
u 'paymenttypedescription': u 'VISA',
u 'orderreference': u 'My_Order_123',
u 'transactionstartedtimestamp': u '2016-12-07 16:25:19',
u 'errormessage': u 'Ok',
u 'operatorname': u '[email protected]',
u 'parenttransactionreference': u '1-2-345678',
u 'fraudcontrolreference': u 'TEST',
u 'accounttypedescription': u 'FRAUDCONTROL',
u 'errorcode': u '0',
u 'transactionreference': u '1-2-345679',
u 'maskedpan': u '411111######1111',
u 'requesttypedescription': u 'RISKDEC',
u 'fraudcontrolshieldstatuscode': u 'ACCEPT',
u 'livestatus': u '0'
}]
}
array(3) {
["requestreference"] => string(9) "A0bjmprty"
["version"] => string(4) "1.00"
["response"] => array(2) {
[0] => array(28) {
["transactionstartedtimestamp"] => string(19) "2016-12-09 11:14:35"
["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"
["orderreference"] => string(12) "My_Order_123"
["tid"] => string(8) "27882788"
["merchantnumber"] => string(8) "00000000"
["securityresponsepostcode"] => string(1) "0"
["transactionreference"] => string(10) "1-2-345678"
["merchantname"] => string(13) "Test Merchant"
["paymenttypedescription"] => string(4) "VISA"
["baseamount"] => string(4) "1011"
["accounttypedescription"] => string(4) "ECOM"
["acquirerresponsecode"] => string(2) "00"
["requesttypedescription"] => string(4) "AUTH"
["securityresponsesecuritycode"] => string(1) "2"
["currencyiso3a"] => string(3) "GBP"
["authcode"] => string(6) "TEST01"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "[email protected]"
["merchantcountryiso2a"] => string(2) "GB"
["maskedpan"] => string(16) "411111######1111"
["securityresponseaddress"] => string(1) "0"
["issuercountryiso2a"] => string(2) "US"
["settlestatus"] => string(1) "0"
}
[1] => array(16) {
["errorcode"] => string(1) "0"
["orderreference"] => string(12) "My_Order_123"
["fraudcontrolresponsecode"] => string(4) "0100"
["paymenttypedescription"] => string(4) "VISA"
["maskedpan"] => string(16) "411111######1111"
["transactionstartedtimestamp"] => string(19) "2016-12-09 11:14:35"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "[email protected]"
["parenttransactionreference"] => string(10) "1-2-345678"
["accounttypedescription"] => string(12) "FRAUDCONTROL"
["acquirerrecommendedaction"] => string(1) "C"
["transactionreference"] => string(9) "1-2-345679"
["requesttypedescription"] => string(7) "RISKDEC"
["fraudcontrolreference"] => string(4) "TEST"
["fraudcontrolshieldstatuscode"] => string(6) "ACCEPT"
["livestatus"] => string(1) "0"
}
}
}
{"requestreference":"W23-eyqd5u3x","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 16:24:50","livestatus":"0","issuer":"SecureTrading Test Issuer1","splitfinalnumber":"1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"1011","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345678","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST12","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######1111","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"},{"errorcode":"0","fraudcontrolresponsecode":"0150","paymenttypedescription":"VISA","orderreference":"My_Order_123","transactionstartedtimestamp":"2016-12-07 16:24:50","errormessage":"Ok","operatorname":"[email protected]","parenttransactionreference":"1-2-345678","accounttypedescription":"FRAUDCONTROL","acquirerrecommendedaction":"C","transactionreference":"1-2-345679","requesttypedescription":"RISKDEC","maskedpan":"411111######1111","fraudcontrolreference":"TEST","fraudcontrolshieldstatuscode":"ACCEPT","livestatus":"0"}],"secrand":"ft9j6l"}
Interpreting the response
The AUTH part of the response follows the same structure as a standard AUTH response. The RISKDEC part of the response contains new fields that are described below:
Key
| Field name | Type | Length | Response | Description |
| requesttypedescription | Alpha | 20 |  |
You will be returned “RISKDEC”. |
| fraudcontrolshieldstatuscode | Alpha | 10 | |
One of the following values:
|
| fraudcontrolreference | Alphanumeric | 255 | |
Unique reference to identify the Risk Decision check performed. |
| fraudcontrolresponsecode | Numeric | 4 | |
A numeric code that is mapped to further information on the results of the Risk Decision checks performed. |
| acquirerrecommendedaction | Char | 1 | |
Either:
Note that this ONLY a recommendation. Protect Plus does not guarantee against fraud. |
| rulecategoryflag | Alphanumeric | 255 |  |
Reference used to identify a condition that was met to return the DENY or CHALLENGE fraudcontrolshieldstatuscode. |
| rulecategorymessage | Alphanumeric | Not defined | |
Condition that was met to return the DENY or CHALLENGE fraudcontrolshieldstatuscode. |
Testing
We recommend that you thoroughly test your solution before enabling on your live Site Reference.
Click here for details that you can submit to simulate different RISKDEC responses on our test system.
Protect Plus with 3-D Secure
Protect Plus can be used in conjunction with 3-D Secure.
Method A – RISKDEC before THREEDQUERY and AUTH
When performing the RISKDEC request before the THREEDQUERY and AUTH, the RISKDEC response can assist you in deciding whether or not to proceed with the transaction. We automatically suspend transactions deemed suspicious by the Protect Plus system.
Here is the flow to follow:
- Your system submits a RISKDEC request.
- Your system submits a THREEDQUERY request, ensuring the transactionreference returned in the RISKDEC response is submitted in the parenttransactionreference field.
Note: If the fraudcontrolshieldstatuscode is “CHALLENGE” or “DENY”, the THREEDQUERY will fail, returning the errorcode “60107”. - You will need to redirect the customer’s browser to the ACS, and then process the AUTH (if the customer has been successfully authenticated).
Method B – THREEDQUERY and AUTH before RISKDEC
When performing the RISKDEC request after the THREEDQUERY and AUTH, information on whether or not the customer is enrolled in 3-D Secure (in addition to the results of the AVS and security code checks) can be used by the Protect Plus system to assist you in deciding whether or not to proceed with the transaction.
Here is the flow to follow:
- Your system submits a THREEDQUERY request.
- You will need to redirect the customer’s browser to the ACS, and then process the AUTH (if the customer has been successfully authenticated).
- Your system submits a RISKDEC request, ensuring the transactionreference returned in the AUTH response is submitted in the parenttransactionreference field.
Note: If the fraudcontrolshieldstatuscode is “CHALLENGE” or “DENY”, we recommend that you suspend the transaction for review (update to settle status “2”).
Duplicate checks (API)
When enabled on your account, duplicate checks suspend transactions that are identical to previous transactions processed within the last 15 minutes. This is to automatically prevent assumed duplicate transactions (e.g. If the customer refreshes their browser and inadvertently sends two requests).
To enable duplicate checks on your account, please contact our Support team.
Managing transactions flagged as duplicates
When a transaction is suspended, its settlestatus is set to “2”, and the funds will not be settled into your bank account until you manually update the transaction. You can update the settlestatus to “1”, and this will instruct us to settle the pending transaction in the next settlement batch. Click here for information on settlement.
Emails informing of duplicates
When duplicates are flagged on your account, you will be informed using the email address you provided when you signed up with us. If you prefer, we can arrange these emails to be sent to a different address. Please contact our Support team for assistance.
Fraud checks (API)
Fraud rating
The fraud check analyses all transactions processed on your account and assigns a numerical fraud rating, which indicates the level of risk based on a number of pre-defined criteria.
- Before the fraud checks have been processed, the fraud rating will be “-1”.
- Following the processing of the fraud checks, a fraud rating of “0” indicates that no suspicious characteristics were detected.
- Every suspicious attribute found by the fraud checks will increment the fraud rating. A higher fraud rating indicates a higher likelihood of fraud.
- All transactions with a fraud rating of “2” or higher are collated into a daily email notification sent to the email address associated with your account.
- By default, we will suspend all transactions with a fraud rating of “5” of higher.
You can configure the thresholds that trigger these actions (e.g. in order to reduce the occurrences of false-positives) by contacting our Support team.
Reason codes
Trust Payments performs the following checks on authorised transactions in settlestatus “0” against records for the previous 7 days. If any of the following criteria are met, the fraud rating for the transaction will be incremented. A higher fraud rating indicates a greater chance of fraud, and as such transactions with high fraud ratings may be suspended in line with your Security Policy.
If matched, these criteria will raise the fraud rating:
The following increment the rating by 1:
- X – Same card number has been declined before with different expiry dates.
- E – Email address has been used with different declined cards or expiry dates.
- N – Cardholder name has been used with different declined cards or expiry dates.
- C – Card details are associated with a very high number of successful transactions.
- V – Cardholder name believed to be randomly-generated (e.g. “ghghghghg”).
- P – Postcode entered did not match that on the customer’s bank’s records.
The following increment the rating by 2:
- S – Security code entered did not match that on the customer’s card.
The following increment the rating by 10:
- G – Card number or billing address has been found in our negative database
The character on the left represents what we call the reason code. Following fraud checks, you can view which of the checks failed (if any), by matching the resulting reason codes with the list above. If any of the criteria are met, we will increment the fraud rating by the number shown above.
Viewing fraud rating and reason codes in MyST
You can view the fraud rating and reason codes (if any) for each transaction in MyST.
Transaction search
Select “Fraud rating” and “Fraud reason” in the optional “Fields” tab when performing a search on the “Transaction Search” page.
This allows you to compare fraud ratings/reasons of multiple transactions that meet your search criteria.
Single transaction view
The fraud rating and reason(s) are also visible in the single transaction view, as shown below.
Updating affected transactions
Sign in to MyST, search for the transaction and click “Update”. Modify the settlestatus of the transaction and click “Update”.
You can also update the settlestatus by submitting a TRANSACTIONUPDATE request.
Allowing transactions to settle
If you have manually investigated a transaction that has been flagged with a particular fraud rating and would like to instruct us to settle the transaction, you can manually override a transaction by updating the settlestatus to “1”. Settlement is performed once a day and all transactions with settlestatus “1” are settled regardless of their fraud rating.
Suspending transactions
If you believe a transaction to be suspicious but it has not been automatically suspended, you can manually suspend a transaction by updating the settlestatus to “2”. Suspended transactions can later be re-enabled for settlement by updating the settlestatus to “1” (as described above). They can also be permanently cancelled by updating the settlestatus to “3”.
Cancelling transactions
If you have manually investigated a suspended transaction and would like to cancel the payment, you can manually cancel a transaction by updating the settlestatus to “3”.
Cancelled transactions can never be settled by Trust Payments.
Negative database
Trust Payments’s internal negative database is a record of card numbers and billing email addresses previously associated with suspicious transactions.
When any transaction receives a fraud rating of “10” or higher, we will automatically add the card number and billing email address to the database.
When you process a transaction that includes a card number and/or billing email address that has been stored in the negative database, the fraud rating is increased by “10”, which immediately suspends the transaction under default configuration. (This requires fraud checks to be enabled on your account) If a transaction is suspended due to an entry in the negative database, it is shown with the reason code “G” in MyST.
Bypassing fraud checks
You can manually flag transactions to bypass the results of fraud checks by including a settlestatus of “1” in the payload submitted within your JWT.
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.
AVS and security code checks
The Address Verification System and security code checks provide you with a further level of security to a transaction, allowing additional checks regarding the validity of the address and security code information supplied by the customer.
Introduction to AVS
A customer’s address is checked against the address that the card issuer holds for that card. The issuing bank will indicate to the acquiring bank whether there is a match between the entered address and the registered card address. The checks performed are focused on the house number and postcode provided by the customer.
Introduction to security code checks
The security code is a three or four digit number printed on credit and debit cards. It is not stored by Trust Payments, and also must never be stored by merchants.
The number is often printed on the back of the card, on the signature strip.
Alternatively, on American Express cards the security code can be found on the front of the card, on the right–hand side, above the embossed card number.
Process overview
Here is how the AVS and security code checks fit into the standard payment process:
Depending on your account configuration, Trust Payments may perform certain actions on the transaction if the results of the AVS and security code checks do not meet a required standard. This behaviour is configured as part of your security policy (scroll down for further information on the security policy).
Requirements
Supported cards and banks
The availability of the AVS and security code check facility is dependent on the acquiring bank and card issuer, although it should be noted that most cards support this functionality.
The ability to conduct address checks is dependent on the location of your acquiring bank in relation to the location of the issuing bank of the card being presented. Most acquirers do support the process but only on locally issued cards. All UK cards and a number of US cards are address checked by all UK acquirers.
Security code checks are performed on all Visa, Mastercard and American Express branded cards worldwide and the results are checked internationally by all acquirers.
Please contact our Support team for further information on supported acquirers and card types.
Required fields
For checks to be successfully performed on the customer’s details, the customer will need to provide their billing postcode, billing premise and their card’s security code.
If this information is not present in the request to Trust Payments, we will return a “Not given” response.
Response codes
There are four different possible responses following AVS and security code checks. Each response is assigned a distinct code, as shown in the following table:
| Code | Description | Comment |
| 0 | “Not given” | Your acquirer was not provided with the information required to perform this check. |
| 1 | “Not checked” | Your acquirer was unable to perform checks on the information provided. |
| 2 | “Matched” | The information provided by the customer matches that on the card issuer’s records. |
| 4 | “Not matched” | The information provided by the customer does NOT match that on the card issuer’s records. |
Together, the AVS and security code checks consist of three total checks, and we assign a response code for each:
- Card security code
- Billing postcode
- Billing premise
Security policy
Your account’s security policy consists of preferences on how we respond to instances where the address (premise & postcode) and security code entered by the customer does not directly match those found on the card issuer’s records. We can automatically suspend transactions that return certain response codes:
To discuss or make changes to your security policy, please contact the Support team.
You can perform AVS and security code checks without debiting the customer. This is achieved by performing an Account Check. Click here to learn more about Account Checks.
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.