Trust Payments docs Search
Contents

Protect Plus (API)

 

Warning
The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.

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

Info
If you are already processing e-commerce payments using our JavaScript Library, your existing solution can be updated to also submit Protect Plus requests with minimal changes to the mark-up. Click here to learn more.

 

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

Status good
Sign up for Protect Plus
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:

 

 

Warning
Protect Plus does not guarantee against fraud
You should consider all data regarding a transaction before accepting the payment.

 

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 request

Process overview

  1. 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).
  2. Trust Payments checks the payment details, generates a fraudcontrolshieldstatuscode and returns this information to your system in a RISKDEC response.
  3. Your system will need to check the shield status code and determine whether or not to proceed with the payment.
  4. 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.
  5. Trust Payments contacts the acquiring bank to process the payment.
  6. Trust Payments returns the response JWT to your system. You will need to interpret the response.

 

Info
By default, when you opt to perform the RISKDEC before the AUTH, we automatically suspend authorised transactions when the fraudcontrolshieldstatuscode is “CHALLENGE” or “DENY”. This will allow you to investigate further and make a more informed choice on whether or not to authorise a suspicious transaction. This behaviour can be changed. Please contact the Support Team for further information.

 

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

  1. When the customer clicks “Pay” on your checkout, the JavaScript library submits a request to Trust Payments.
  2. Trust Payments contacts the acquiring bank to process the payment.
  3. Trust Payments returns the response JWT to your system. You will need to interpret the response.
  4. 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).
  5. Trust Payments checks the payment details, generates a fraudcontrolshieldstatuscode and returns this information to your system in a RISKDEC response.
  6. Your system will need to check the shield status code and determine whether or not to proceed with the payment.
  7. 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:

  • “C” – Continue with the transaction.
  • “S” – Stop transaction.

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:

  • “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” – Returned when a parent AUTH request has been declined.
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

Info
In order to reduce fraud, Visa has mandated that all merchants with a Merchant Category Code (MCC) of 6012 are required to send additional fields in AUTH and ACCOUNTCHECK requests. Click here for further information.

 

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.

Warning
It is important to thoroughly test your integration using your test sitereference before processing live payments.

Info

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.
  • For those using Payment Pages, if you’re unsure where to start with your testing, you may find this resource 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.

Warning
Do not use these credentials when processing transactions on your live site reference.
Info
While testing, all card types are supported, but when using your live account, you will receive an error if you do not have a valid merchant number for the payment type submitted.

 

 

3-D Secure v2

The following payment credentials can be used for testing 3-D Secure v2 (a form of SCA):

 

(3DSv2) Test Case 1: Successful Frictionless 3-D Secure Authentication & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000001007 THREEDQUERY
Enrolled: Y
Status: Y
AUTH
Error code: 0 – Ok
DINERS / DISCOVER 6011000000001002
JCB 3337000000000008
MASTERCARD 5200000000001005
VISA (3-D Secure v2.1.0) 4000000000001000
VISA (3-D Secure v2.2.0) 4000000000002701

 

(3DSv2) Test Case 2: Failed Frictionless 3-D Secure Authentication & Failed Authorisation
Card type PAN Handling the response
AMEX 340000000001015 THREEDQUERY
Enrolled: Y
Status: N
AUTH
Error code: 60022 – Unauthenticated
DINERS / DISCOVER 6011000000001010
JCB 3337000000000990
MASTERCARD 5200000000001013
VISA (3-D Secure v2.1.0) 4000000000001018
VISA (3-D Secure v2.2.0) 4000000000002925

 

(3DSv2) Test Case 3: Attempts Stand-In Frictionless 3-D Secure Authentication & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000001023 THREEDQUERY
Enrolled: Y
Status: A
AUTH
Error code: 0 -Ok
DINERS / DISCOVER 6011000000001028
JCB 3337000000007045
MASTERCARD 5200000000001021
VISA (3-D Secure v2.1.0) 4000000000001026
VISA (3-D Secure v2.2.0) 4000000000002719

 

(3DSv2) Test Case 4: Unavailable Frictionless 3-D Secure Authentication from the Issuer & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000001031 THREEDQUERY
Enrolled: Y
Status: U
AUTH
Error code: 0 – Ok
DINERS / DISCOVER 6011000000001036
JCB 3337000000000735
MASTERCARD 5200000000001039
VISA (3-D Secure v2.1.0) 4000000000001034
VISA (3-D Secure v2.2.0) 4000000000002313

 

(3DSv2) Test Case 5: Rejected Frictionless 3-D Secure Authentication by the Issuer & Failed Authorisation
Card type PAN Handling the response
AMEX 340000000001049 THREEDQUERY
Enrolled: Y
Status: R
AUTH
Error code: 60022 – Unauthenticated
DINERS / DISCOVER 6011000000001044
JCB 3337000000000321
MASTERCARD 5200000000001047
VISA (3-D Secure v2.1.0) 4000000000001042
VISA (3-D Secure v2.2.0) 4000000000002537

 

(3DSv2) Test Case 6: 3-D Secure Authentication Not Available on Lookup & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000001056 THREEDQUERY
Enrolled: U
Status: None
AUTH
Error code: 0 – Ok
DINERS / DISCOVER 6011000000001051
JCB 3337000000006765
MASTERCARD 5200000000001054
VISA (3-D Secure v2.1.0) 4000000000001059
VISA (3-D Secure v2.2.0) 4000000000002990

 

(3DSv2) Test Case 7: Error on Lookup & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000001064 THREEDQUERY
Enrolled: U
Status: None
AUTH
Error code: 0 – Ok
DINERS / DISCOVER 6011000000001069
JCB 3337000000000016
MASTERCARD 5200000000001062
VISA (3-D Secure v2.1.0) 4000000000001067
VISA (3-D Secure v2.2.0) 4000000000002446

 

(3DSv2) Test Case 8: Timeout on cmpi_lookup Transaction & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000001072 THREEDQUERY
Enrolled: U
Status: None
AUTH
Error code: 0 – Ok
DINERS / DISCOVER 6011000000001077
JCB 3337000000000081
MASTERCARD 5200000000001070
VISA (3-D Secure v2.1.0) 4000000000001075
VISA (3-D Secure v2.2.0) 4000000000002354

 

(3DSv2) Test Case 9: Successful Step Up 3-D Secure Authentication & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000001098 THREEDQUERY
Enrolled: Y
Status: C
AUTH
Error code: 0 – Ok
DINERS / DISCOVER 6011000000001093
JCB 3337000000200004
MASTERCARD 5200000000001096
VISA (3-D Secure v2.1.0) 4000000000001091
VISA (3-D Secure v2.2.0) 4000000000002503

 

(3DSv2) Test Case 10: Failed Step Up 3-D Secure Authentication & No Authorisation
Card type PAN Handling the response
AMEX 340000000001106 THREEDQUERY
Enrolled: Y
Status: C
AUTH
Not performed
DINERS / DISCOVER 6011000000001101
JCB 3337000000200087
MASTERCARD 5200000000001104
VISA (3-D Secure v2.1.0) 4000000000001109
VISA (3-D Secure v2.2.0) 4000000000002370

 

(3DSv2) Test Case 11: Step Up 3-D Secure Authentication is Unavailable & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000001114 THREEDQUERY
Enrolled: Y
Status: C
AUTH
Error code: 0 – Ok
DINERS / DISCOVER 6011000000001119
JCB 3337000000200079
MASTERCARD 5200000000001112
VISA (3-D Secure v2.1.0) 4000000000001117
VISA (3-D Secure v2.2.0) 4000000000002420

 

(3DSv2) Test Case 12: Error on 3-D Secure Authentication & No Authorisation
Card type PAN Handling the response
AMEX 340000000001122 THREEDQUERY
Enrolled: Y
Status: C
AUTH
Not performed
DINERS / DISCOVER 6011000000001127
JCB 3337000000200046
MASTERCARD 5200000000001120
VISA (3-D Secure v2.1.0) 4000000000001125
VISA (3-D Secure v2.2.0) 4000000000002644

 

(3DSv2) Test Case 13: Bypassed 3-D Secure Authentication & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000001080 THREEDQUERY
Enrolled: B
Status: None
AUTH
Error code: 0 – Ok
DINERS / DISCOVER 6011000000001085
JCB 3337000000000537
MASTERCARD 5200000000001088
VISA (3-D Secure v2.1.0) 4000000000001083
VISA (3-D Secure v2.2.0) 4000000000002560

 

3-D Secure v1

The following payment credentials can be used for testing 3-D Secure v1 (a form of SCA):

 

(3DSv1) Test Case 1: Successful 3-D Secure Authentication & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000003961 THREEDQUERY
Enrolled: Y
Status: None
AUTH
Error code: 0 – Ok
DINERS 3005000000006246
DISCOVER 6011000000000004
JCB 3520000000000922
MASTERCARD 5200000000000007
VISA 4000000000000002

 

(3DSv1) Test Case 2: Failed Signature & No Authorisation
Card type PAN Handling the response
AMEX 340000000006022 THREEDQUERY
Enrolled: Y
Status: None
AUTH
Not performed
DINERS 3005000000004373
DISCOVER 6011000000000012
JCB 3520000000002811
MASTERCARD 5200000000000015
VISA 4000000000000010

 

(3DSv1) Test Case 3: Failed Authentication & No Authorisation
Card type PAN Handling the response
AMEX 340000000000033 THREEDQUERY
Enrolled: Y
Status: None
AUTH
Not performed
DINERS 3005000000005925
DISCOVER 6011000000000020
JCB 3520000000009931
MASTERCARD 5200000000000023
VISA 4000000000000028

 

(3DSv1) Test Case 4: Attempts/Non-Participating & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000003391 THREEDQUERY
Enrolled: Y
Status: A
AUTH
Error code: 0 – Ok
DINERS 3005000000005271
DISCOVER 6011000000000038
JCB 3520000000004767
MASTERCARD 5200000000000908
VISA 4000000000000101

 

(3DSv1) Test Case 6: Not Enrolled & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000008135 THREEDQUERY
Enrolled: N
Status: None
AUTH
Error code: 0 – Ok
DINERS 3005000000007269
DISCOVER 6011000000000053
JCB 3520000000006903
MASTERCARD 5200000000000056
VISA 4000000000000051

 

(3DSv1) Test Case 7: Unavailable & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000007780 THREEDQUERY
Enrolled: U
Status: None
AUTH
Error code: 0 – Ok
DINERS 3005000000006030
DISCOVER 6011000000000061
JCB 3520000000002423
MASTERCARD 5200000000000064
VISA 4000000000000069

 

(3DSv1) Test Case 8: Merchant Not Active & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000008416 THREEDQUERY
Enrolled: U
Status: None
AUTH
Error code: 0 – Ok
DINERS 3005000000004837
DISCOVER 6011000000000079
JCB 3520000000006549
MASTERCARD 5200000000000072
VISA 4000000000000077

 

(3DSv1) Test Case 9: cmpi_lookup error & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000006337 THREEDQUERY
Enrolled: U
Status: None
AUTH
Error code: 0 – Ok
DINERS 3005000000009877
DISCOVER 6011000000000087
JCB 3520000000002175
MASTERCARD 5200000000000080
VISA 4000000000000085

 

(3DSv1) Test Case 10: cmpi_authenticate error & No Authorisation
Card type PAN Handling the response
AMEX 340000000009299 THREEDQUERY
Enrolled: Y
Status: None
AUTH
Not performed
DINERS 3005000000005602
DISCOVER 6011000000000095
JCB 3520000000006861
MASTERCARD 5200000000000098
VISA 4000000000000093

 

(3DSv1) Test Case 11: Authentication Unavailable & Successful Authorisation
Card type PAN Handling the response
AMEX 340000000000116 THREEDQUERY
Enrolled: Y
Status: None
AUTH
Error code: 0 – Ok
DINERS 3005000000007376
DISCOVER 6011000000000103
JCB 3520000000005780
MASTERCARD 5200000000000031
VISA 4000000000000036

 

(3DSv1) Test Case 12: Bypassed Authentication & Successful Authorisation
Card type PAN Handling the response
AMEX 340099000000001 THREEDQUERY
Enrolled: B
Status: None
AUTH
Error code: 0 – Ok
DINERS 3000990000000006
DISCOVER 6011990000000006
JCB 3500990000000001
MASTERCARD 5200990000000009
VISA 4000990000000004

 

 

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.

URL
Displaying the test ACS page

 

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.

 

For Mobile SDK implementations:

After your Android or iOS app has been updated to utilise our Mobile SDK, process a payment using one of the card numbers listed above and your app 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:

 

 

Info
When the status is “N”, indicating the customer failed authentication, the errorcode “60022” will be returned.

 

 

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.

Info
Only the billing premise, billing postcode and security code field values dictate the outcome of the AVS and security code checks performed. As such, entering any details into the other address fields will not affect the outcome of these checks.

 

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

URL
The procedure to follow when testing non-card payment methods will vary. For the most relevant testing information, please refer to the documentation provided for the specific payment method:
Link to Payment Pages docs / Link to Webservices 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

 

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

 

PAYMENT MASTERCARD
Acquirer advice code ‘1’ can only be returned for recurring Mastercard transactions.
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

Please refer to the following resources when testing Protect Plus:

 

 

Testing DCC

Please refer to the following resources when testing DCC:

 

Using Account Check to verify customer’s details

 

Follow these instructions when using Account Checks to verify the customer’s details prior to processing a payment.

Info
If you are already processing e-commerce payments using our JavaScript Library, your existing solution can be updated to also submit Account Check requests with minimal changes to the mark-up. Click here to learn more.

 

 

Prerequisites

Warning
The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.

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

Padlock
All businesses within the EEA (European Economic Area) are mandated to use 3-D Secure when processing e-commerce Account Checks, as part of the PSD2 mandate.

 

To process an e-commerce Account Check that is authenticated with 3-D Secure, you will need to utilise our JavaScript Library instead of the solution described below. Click here to get started.

 

The following content should only be utilised by merchants processing Account Checks that are Mail or Telephone Order (MOTO), Merchant Initiated Transactions (MIT), or using other workflows that are exempt from the PSD2 mandate.

Status attention
In order to reduce fraud, Visa has mandated that all merchants with a Merchant Category Code (MCC) of 6012 are required to send additional fields in AUTH and ACCOUNTCHECK requests.

 

Failure to submit these fields will result in a “60025” (Invalid request) error being returned in the response. Click here for further information.

Info
  • Account checks are only available for certain acquiring banks. Before you begin, please contact our Support Team and ensure your acquiring bank supports this functionality.
  • Account checks can only be performed for card-based payment methods.

 

 

Mandate considerations

Visa and Mastercard have mandated that you must obtain cardholder consent if storing card details for future use, and that these must be flagged at the time of the first authorisation, by submitting the credentialsonfile field in your requests. To do so, you will need to ensure the ACCOUNTCHECK request submitted includes the additional field credentialsonfile, with value set to “1”.

You must also flag any subsequent payments that are utilising previously-stored credentials, by including the credentialsonfile field in these requests with value set to “2”.

Click here to learn more about Credentials on File.

 

Checks performed

All Account Checks processed will perform checks on the cardholder’s first line of address, the cardholder’s postcode and the security code, to ensure the details entered by the customer are valid.

Click here to learn more about these checks.

 

 

Process overview

    1. Merchant submits ACCOUNTCHECK request.
    2. Trust Payments validates the request and contacts the bank.
    3. The acquiring bank will contact the card issuer to perform AVS and security code checks.
    4. Trust Payments receives results of the request and passes this back to the merchant.
    5. Merchant receives and interprets this response.

 

Warning
No funds are reserved by ACCOUNTCHECK requests

The customer’s account is not debited when an ACCOUNTCHECK request is performed.

Info
Similar to standard AUTH requests, AVS and Security Code Checks are performed on ACCOUNTCHECK requests. We recommend reading our documentation on these checks before proceeding.

 

 

ACCOUNTCHECK request

The fields required in an ACCOUNTCHECK request are the same as a standard AUTH request, except with the following differences:

 

Field specification

  Field Format Description
credentialsonfile
XPath: /operation/credentialsonfile		 Numeric (1) This must be set to “1”, to indicate the customer agreed for the payment credentials to be stored for future transactions. See below for further information.

 

About inheritance

You can submit any field that you can submit in an AUTH request and these will be inherited by any subsequent child requests. Click here to learn more.

 

The following is an example of an ACCOUNTCHECK request:

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

accountcheck= {
    "currencyiso3a": "GBP",
    "requesttypedescriptions": ["ACCOUNTCHECK"],
    "sitereference": "test_site12345",
    "baseamount": "0",
    "orderreference": "My_Order_123",
    "accounttypedescription": "MOTO",
    "pan": "4111111111111111",
    "expirydate": "12/2020",
    "securitycode": "123",
    "billingpremise": "789",
    "billingpostcode": "TE45 6ST",
    "credentialsonfile": "1"
}

strequest = securetrading.Request()
strequest.update(accountcheck)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
'username' => '[email protected]',
'password' => 'Password1^',
);

$requestData = array(
'currencyiso3a' => 'GBP',
'requesttypedescriptions' => array('ACCOUNTCHECK'),
'sitereference' => 'test_site12345',
'baseamount' => '0',
'orderreference' => 'My_Order_123',
'accounttypedescription' => 'MOTO',
'pan' => '4111111111111111',
'expirydate' => '12/2020',
'securitycode' => '123',
'billingpremise' => '789',
'billingpostcode' => 'TE45 6ST',
'credentialsonfile' => '1'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "currencyiso3a": "GBP",
  "requesttypedescriptions": ["ACCOUNTCHECK"],
  "sitereference": "test_site12345",
  "baseamount": "0",
  "orderreference": "My_Order_123",
  "accounttypedescription": "MOTO",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123",
  "billingpremise": "789",
  "billingpostcode": "TE45 6ST",
  "credentialsonfile": "1"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["ACCOUNTCHECK"],"sitereference":"test_site12345","baseamount":"0","orderreference":"My_Order_123","accounttypedescription":"MOTO","pan":"4111111111111111","expirydate":"12\/2020","securitycode":"123","billingpremise":"789","billingpostcode":"TE45 6ST","credentialsonfile":"1"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="ACCOUNTCHECK">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <amount currencycode="GBP">0</amount>
      <postcode>TE45 6ST</postcode>
      <premise>789</premise>
      <payment>
        <pan>4111111111111111</pan>
        <securitycode>123</securitycode>
        <expirydate>12/2020</expirydate>
      </payment>
    </billing>
    <operation>
      <accounttypedescription>MOTO</accounttypedescription>
      <sitereference>test_site12345</sitereference>
      <credentialsonfile>1</credentialsonfile>
    </operation>
  </request>
</requestblock>

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

 

ACCOUNTCHECK response

After the request has been processed, you will receive a single response that contains the response to the ACCOUNTCHECK request:

{
  u 'requestreference': u 'Ar2xj1hjr',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-07 16:12:00',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2016-12-07',
        u 'errorcode': u '0',
        u 'orderreference': u 'My_Order_123',
        u 'tid': u '27882788',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'transactionreference': u '23-9-80023',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'baseamount': u '0',
        u 'accounttypedescription': u 'MOTO',
        u 'acquirerresponsecode': u '00',
        u 'requesttypedescription': u 'ACCOUNTCHECK',
        u 'securityresponsesecuritycode': u '2',
        u 'currencyiso3a': u 'GBP',
        u 'authcode': u 'TEST46',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'securityresponsepostcode': u '2',
        u 'maskedpan': u '411111######1111',
        u 'securityresponseaddress': u '2',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0',
        u 'credentialsonfile': u '1'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A4cenptwx"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(28) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:04:29"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-09"
      ["errorcode"] => string(1) "0"
      ["baseamount"] => string(1) "0"
      ["tid"] => string(8) "27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["securityresponsepostcode"] => string(1) "2"
      ["transactionreference"] => string(10) "72-9-80018"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["orderreference"] => string(12) "My_Order_123"
      ["accounttypedescription"] => string(4) "MOTO"
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(12) "ACCOUNTCHECK"
      ["securityresponsesecuritycode"] => string(1)"2"
      ["currencyiso3a"] => string(3) "GBP"
      ["authcode"] => string(6) "TEST39"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["maskedpan"] => string(16) "411111######1111"
      ["securityresponseaddress"] => string(1) "2"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "0"
      ["credentialsonfile"] => string(1) "1"
    }
  }
}
{"requestreference":"W23-q3wa45ge","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 16:16:39","livestatus":"0","issuer":"SecureTrading Test Issuer1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"0","tid":"27882788","merchantnumber":"00000000","securityresponsepostcode":"2","transactionreference":"23-9-80024","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"MOTO","acquirerresponsecode":"00","requesttypedescription":"ACCOUNTCHECK","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST53","errormessage":"Ok","operatorname":"[email protected]","merchantcountryiso2a":"GB","maskedpan":"411111######1111","securityresponseaddress":"2","issuercountryiso2a":"US","settlestatus":"0","credentialsonfile":"1"}],"secrand":"NunVEQ"}
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
  <requestreference>X575647667</requestreference>
  <response type="ACCOUNTCHECK">
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <orderreference>My_Order_123</orderreference>
      <tid>27882788</tid>
      <merchantnumber>00000000</merchantnumber>
      <merchantcountryiso2a>GB</merchantcountryiso2a>
      <operatorname>[email protected]</operatorname>
    </merchant>
    <transactionreference>16-9-1</transactionreference>
    <billing>
      <amount currencycode="GBP">0</amount>
      <payment type="VISA">
        <issuer>SecureTrading Test Issuer1</issuer>
        <issuercountry>US</issuercountry>
        <pan>411111######1111</pan>
      </payment>
      <dcc enabled="0"/>
    </billing>
    <authcode>TEST53</authcode>
    <live>0</live>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <timestamp>2013-01-16 10:48:17</timestamp>
    <acquirerresponsecode>00</acquirerresponsecode>
    <security>
      <address>2</address>
      <postcode>2</postcode>
      <securitycode>2</securitycode>
    </security>
    <settlement>
      <settleduedate>2013-01-16</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <operation>
      <accounttypedescription>MOTO</accounttypedescription>
      <credentialsonfile>1</credentialsonfile>
    </operation>
  </response>
  <secrand>bByuPvGz9Hcm</secrand>
</responseblock>

 

Handling the response

Warning
It is strongly recommended that you check the security fields returned in the response, and manually investigate transactions where the returned securityresponsesecuritycode is “4” (indicating the customer entered a security code that doesn’t match the value found on the back of the card).
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

Status good
Sign up for Protect Plus
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:

 

Warning
Protect Plus does not guarantee against fraud
You should consider all data regarding a transaction before accepting the payment.

 

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 request

Process overview

 

Info
By default, when you opt to perform the RISKDEC before the AUTH, we automatically suspend authorised transactions when the fraudcontrolshieldstatuscode is “CHALLENGE” or “DENY”. This will allow you to investigate further and make a more informed choice on whether or not to authorise a suspicious transaction. This behaviour can be changed. Please contact the Support team for further information.

 

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

 

 

Info
Specifying for the RISKDEC to be performed after the AUTH allows Trust Payments to take into account the results of AVS, Security Code Checks and 3-D Secure checks performed when analysing the submitted details for fraud.

 

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:

  • “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” – Returned when a parent AUTH Request has been declined.
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:

  • “C” – Continue with the transaction.
  • “S” – Stop transaction.

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:

  1. Your system submits a RISKDEC request.
  2. 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”.
  3. 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:

  1. Your system submits a THREEDQUERY request.
  2. You will need to redirect the customer’s browser to the ACS, and then process the AUTH (if the customer has been successfully authenticated).
  3. 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”).

 

Info
Click here for further information on implementing 3-D Secure on your system

3-D Secure (version 1)

 

Warning
The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.

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

 

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.

Info
For a fully authenticated 3-D Secure transaction, in the event of a dispute at a later date the card issuer will usually take responsibility of the chargeback instead of the merchant. The liability issues involved with 3-D Secure transactions can be found in this FAQ.
.

 

Process overview

1
Check customer enrolment

  • 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.
2
Authenticate the customer

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).

3
Authorisation

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:

Info
When reading the field specifications included on this page, please ensure that you reference the relevant code examples for your chosen language.

 

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.

Click here for a full list of available currencies.
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.

Info
The acsurl, md and pareq fields are only returned in a THREEDQUERY response for enrolled cards.

 

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]xample.com',
        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"}
Info
The md and pareq typically contain values far longer than displayed in the example above and therefore have been abbreviated, for your convenience.

 

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.

Warning
When performing an AUTH request without 3-D Secure, this will result in forfeiting the liability shift.

 

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.

  • “Y” – Card is enrolled.
  • “N” – Card is not enrolled.
  • “U” – Unable to determine if card is enrolled.
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

 

Info
Only attempt to authenticate the customer if their card is confirmed to be enrolled in a 3-D Secure scheme.

 

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).

 

URL
The size of the ACS page displayed in the customer’s browser is controlled by the ACS provider (cannot be modified by merchants or Trust Payments). As a guideline, Visa and Mastercard both state that the Verified by Visa authentication window should be 390×400 pixels in size

 

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.

 

Warning
When the customer’s browser is redirected to your server from the ACS, please be aware that some ACS will also include a field called “realPan”, which contains the customer’s card number in plain text. It is imperative that you do not store the value of realPan on your own server.

 

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=="
}]}'
Info
The md and pares fields typically contain values far longer than displayed in the example above and therefore have been abbreviated for your convenience. When submitting these fields, your system must submit their full values, unmodified.

 

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:

Info
Please note that other fields that can be returned are documented on our page covering AUTH requests.

 

Key

Field name Type Length Response Description
enrolled Char 1 Indicates if the cardholder is enrolled in a 3-D Secure scheme:

  • “Y” – Card is enrolled.
  • “N” – Card is not enrolled.
  • “U” – Unable to determine if card is enrolled.
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:

  • “Y” – Customer authenticated.
  • “N” – Customer not authenticated.
  • “A” – An authentication attempt occurred but could not be completed.
  • “U” – Unable to perform authentication.
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.

 

Info
The above fields may be requested by a card issuer in the event of a disputed transaction and are included in the response for your reference.

 

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.

 

investors in people logo   pci - security standards council logo

TRUST Payments LTD, No.1 Royal Exchange, London, EC3V 3DG.
A company registered in England and Wales with Company Number 04591066. VAT Number 756265116