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.