Protect Plus (API)

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

Protect Plus is a sophisticated counter-fraud service that provides your site with an extra layer of security against fraudulent transactions. It makes use of the industry’s largest negative database to perform a comprehensive suite of fraud assessments, including identity checks against the UK electoral roll and BT databases.
Process overview

Before you can get started, you will need to contact our Sales Team and enable Protect Plus on your account.
What checks are performed?
We analyse the customer’s billing, delivery and payment details using a rule-based system to detect suspicious patterns in user activity. Our system will assist you in deciding on whether or not to process a customer’s transaction based on the perceived level of risk. Checks performed include:
- The industry’s largest negative database.
- Neural-based fraud assessments.
- Tumbling or Swapping, where there is an unusual usage pattern in the card number, expiration date or customer details associated with a transaction.

What happens after the checks are performed?
The Protect Plus system will analyse transaction details and issue one of the following fraudcontrolshieldstatuscode values:
“ACCEPT” | The details are not deemed suspicious. |
“CHALLENGE” | Further investigation is recommended. |
“DENY” | The details are suspicious and a transaction should not be performed. |
“NOSCORE” | Transaction was declined by the acquirer before checks were performed. |
Order of requests
Protect Plus checks are performed when a RISKDEC request is submitted to our system. There are two methods in which you can configure your system to process RISKDEC requests using our Webservices API:
- RISKDEC then AUTH – Perform the checks first, then seek authorisation for the payment. By default, we suspend suspicious payments, allowing you to investigate them before proceeding.
- AUTH then RISKDEC – Seek authorisation for the payment first, then perform the checks. Checks performed are more accurate because they take the results of AVS, Security Code Checks and 3-D Secure into account.
RISKDEC then AUTH request
Process overview
- When the customer clicks “Pay” on your checkout, your system submits a RISKDEC request to Trust Payments using the Webservices API (we provide an example of how to structure this request below).
- Trust Payments checks the payment details, generates a fraudcontrolshieldstatuscode and returns this information to your system in a RISKDEC response.
- Your system will need to check the shield status code and determine whether or not to proceed with the payment.
- If you opt to process the payment, you can process a payment using our JavaScript as described here, with one important difference.
The JWT in the payload must be updated to include field parenttransactionreference, including the unique transactionreference returned in the RISKDEC response.
This is used to inherit data from the initial request. - Trust Payments contacts the acquiring bank to process the payment.
- Trust Payments returns the response JWT to your system. You will need to interpret the response.

RISKDEC request example
Here is an example of a RISKDEC request, the details of which can be inherited in future payments processed using our JavaScript Library:
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) riskdec= { "sitereference": "test_site12345", "requesttypedescriptions": ["RISKDEC"], "accounttypedescription": "ECOM", "currencyiso3a": "GBP", "baseamount": "1011", "orderreference": "My_Order_123", "pan": "4111111111111111", "expirydate": "12/2020", "securitycode": "123" } strequest = securetrading.Request() strequest.update(riskdec) stresponse = st.process(strequest) #stresponse contains the transaction response
<?php if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) { throw new Exception('Composer autoloader file could not be found.'); } require_once($autoload); $configData = array( 'username' => '[email protected]', 'password' => 'Password1^', ); $requestData = array( 'sitereference' => 'test_site12345', 'requesttypedescriptions' => array('RISKDEC'), 'accounttypedescription' => 'FRAUDCONTROL', 'currencyiso3a' => 'GBP', 'baseamount' => '1011', 'orderreference' => 'My_Order_123', 'pan' => '4111111111111111', 'expirydate' => '12/2020', 'securitycode' => '123' ); $api = \Securetrading\api($configData); $response = $api->process($requestData); var_dump($response->toArray()); ?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{ "alias": "[email protected]", "version": "1.00", "request": [{ "currencyiso3a": "GBP", "requesttypedescriptions": ["RISKDEC"], "sitereference": "test_site12345", "baseamount": "1011", "orderreference": "My_Order_123", "accounttypedescription": "FRAUDCONTROL", "pan": "4111111111111111", "expirydate": "12/2020", "securitycode": "123" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["RISKDEC"],"sitereference":"test_site12345","baseamount":"1011","orderreference":"My_Order_123","accounttypedescription":"FRAUDCONTROL","pan":"4111111111111111","expirydate":"12\/2020"}]}
<?xml version="1.0" encoding="utf-8"?> <requestblock version="3.67"> <alias>[email protected]</alias> <request type="RISKDEC"> <merchant> <orderreference>My_Order_123</orderreference> </merchant> <billing> <amount currencycode="GBP">1011</amount> <payment> <expirydate>12/2020</expirydate> <pan>4111111111111111</pan> </payment> </billing> <operation> <accounttypedescription>FRAUDCONTROL</accounttypedescription> <sitereference>test_site12345</sitereference> </operation> </request> </requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
RISKDEC response example
Here is an example of the associated RISKDEC response:
For the RISKDEC response field specification, scroll down to the “Interpreting the response” section.
{ u 'requestreference': u 'A0dcb11e6', u 'version': u '1.00', u 'response': [{ u 'acquirerrecommendedaction': u 'C', u 'fraudcontrolresponsecode': u '0100', u 'paymenttypedescription': u 'VISA', u 'orderreference': u 'My_Order_123', u 'transactionstartedtimestamp': u '2016-12-07 16:19:28', u 'errormessage': u 'Ok', u 'operatorname': u '[email protected]', u 'fraudcontrolreference': u 'TEST', u 'accounttypedescription': u 'FRAUDCONTROL', u 'errorcode': u '0', u 'transactionreference': u '1-2-345678', u 'maskedpan': u '411111######1111', u 'requesttypedescription': u 'RISKDEC', u 'fraudcontrolshieldstatuscode': u 'ACCEPT', u 'livestatus': u '0' }] }
array(3) { ["requestreference"] => string(9) "A58cdfkpy" ["version"] => string(4) "1.00" ["response"] => array(1) { [0] => array(15) { ["errorcode"] => string(1) "0" ["orderreference"] => string(12) "My_Order_123" ["fraudcontrolresponsecode"] => string(4) "0100" ["paymenttypedescription"] => string(4) "VISA" ["maskedpan"] => string(16) "411111######1111" ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:12:39" ["errormessage"] => string(2) "Ok" ["operatorname"] => string(23) "[email protected]" ["accounttypedescription"] => string(12) "FRAUDCONTROL" ["acquirerrecommendedaction"] => string(1) "C" ["transactionreference"] => string(9) "1-2-345678" ["requesttypedescription"] => string(7) "RISKDEC" ["fraudcontrolreference"] => string(4) "TEST" ["fraudcontrolshieldstatuscode"] => string(6) "ACCEPT" ["livestatus"] => string(1) "0" } } }
{"requestreference":"W23-wt77f0n8","version":"1.00","response":[{"errorcode":"0","fraudcontrolresponsecode":"0100","paymenttypedescription":"VISA","orderreference":"My_Order_123","transactionstartedtimestamp":"2016-12-07 16:23:03","errormessage":"Ok","operatorname":"[email protected]","accounttypedescription":"FRAUDCONTROL","acquirerrecommendedaction":"C","transactionreference":"1-2-345678","requesttypedescription":"RISKDEC","maskedpan":"411111######1111","fraudcontrolreference":"TEST","fraudcontrolshieldstatuscode":"ACCEPT","livestatus":"0"}],"secrand":"E0ksvyuH5VKg"}
<?xml version="1.0" encoding="utf-8"?> <responseblock version="3.67"> <requestreference>X336659733</requestreference> <response type="RISKDEC"> <merchant> <orderreference>My_Order_123</orderreference> <operatorname>[email protected]</operatorname> </merchant> <transactionreference>1-2-345678</transactionreference> <billing> <payment type="VISA"> <pan>411111######1111</pan> </payment> </billing> <timestamp>2012-06-21 13:32:43</timestamp> <fraudcontrol> <shieldstatuscode>ACCEPT</shieldstatuscode> <reference>TEST</reference> <recommendedaction>C</recommendedaction> <responsecode>0100</responsecode> </fraudcontrol> <live>0</live> <error> <message>Ok</message> <code>0</code> </error> <operation> <accounttypedescription>FRAUDCONTROL</accounttypedescription> </operation> </response> <secrand>2ngbLQ3DO</secrand> </responseblock>
AUTH then RISKDEC request
Process overview
- When the customer clicks “Pay” on your checkout, the JavaScript library submits a request to Trust Payments.
- Trust Payments contacts the acquiring bank to process the payment.
- Trust Payments returns the response JWT to your system. You will need to interpret the response.
- Following this, your system submits a RISKDEC request to Trust Payments using the Webservices API, including the field parenttransactionreference, which is the unique transactionreference value returned in the response JWT (we provide an example of how to structure this request below).
- Trust Payments checks the payment details, generates a fraudcontrolshieldstatuscode and returns this information to your system in a RISKDEC response.
- Your system will need to check the shield status code and determine whether or not to proceed with the payment.
- If you want to suspend or cancel a payment, you will need to process a transaction update request using the Webservices API.
Request example
Here is an example of a RISKDEC request to be submitted using our Webservices API, following a payment processed using our JavaScript Library.
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) riskdec= { "sitereference": "test_site12345", "requesttypedescriptions": ["RISKDEC"], "accounttypedescription": "FRAUDCONTROL", "currencyiso3a": "GBP", "baseamount": "1011", "orderreference": "My_Order_123", "parenttransactionreference": "1-2-3" } strequest = securetrading.Request() strequest.update(riskdec) stresponse = st.process(strequest) #stresponse contains the transaction response
<?php if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) { throw new Exception('Composer autoloader file could not be found.'); } require_once($autoload); $configData = array( 'username' => '[email protected]', 'password' => 'Password1^', ); $requestData = array( 'sitereference' => 'test_site12345', 'requesttypedescriptions' => array('RISKDEC'), 'accounttypedescription' => 'FRAUDCONTROL', 'currencyiso3a' => 'GBP', 'baseamount' => '1011', 'orderreference' => 'My_Order_123', 'parenttransactionreference' => '1-2-3' ); $api = \Securetrading\api($configData); $response = $api->process($requestData); var_dump($response->toArray()); ?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -d '{ "alias": "[email protected]", "version": "1.00", "request": [{ "currencyiso3a": "GBP", "requesttypedescriptions": ["RISKDEC"], "sitereference": "test_site12345", "baseamount": "1011", "orderreference": "My_Order_123", "accounttypedescription": "FRAUDCONTROL", "parenttransactionreference": "1-2-3" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["RISKDEC"],"sitereference":"test_site12345","baseamount":"1011","orderreference":"My_Order_123","accounttypedescription":"FRAUDCONTROL","parenttransactionreference":"1-2-3"}]}
<?xml version="1.0" encoding="utf-8"?> <requestblock version="3.67"> <alias>[email protected]</alias> <request type="RISKDEC"> <merchant> <orderreference>My_Order_123</orderreference> </merchant> <billing> <amount currencycode="GBP">1011</amount> </billing> <operation> <parenttransactionreference>1-2-3</parenttransactionreference> <accounttypedescription>FRAUDCONTROL</accounttypedescription> <sitereference>test_site12345</sitereference> </operation> </request> </requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Response example
Here is an example of the associated RISKDEC response:
For the RISKDEC response field specification, scroll down to the “Interpreting the response” section.
{ u 'requestreference': u 'Ad4ft45gp', u 'version': u '1.00', u 'response': [{ u 'acquirerrecommendedaction': u 'C', u 'fraudcontrolresponsecode': u '0100', u 'paymenttypedescription': u 'VISA', u 'orderreference': u 'My_Order_123', u 'transactionstartedtimestamp': u '2016-12-07 16:25:19', u 'errormessage': u 'Ok', u 'operatorname': u '[email protected]', u 'parenttransactionreference': u '1-2-345678', u 'fraudcontrolreference': u 'TEST', u 'accounttypedescription': u 'FRAUDCONTROL', u 'errorcode': u '0', u 'transactionreference': u '1-2-345679', u 'maskedpan': u '411111######1111', u 'requesttypedescription': u 'RISKDEC', u 'fraudcontrolshieldstatuscode': u 'ACCEPT', u 'livestatus': u '0' }] }
array(3) { ["requestreference"] => string(9) "A0bjmprty" ["version"] => string(4) "1.00" ["response"] => array(1) { [0] => array(16) { ["errorcode"] => string(1) "0" ["orderreference"] => string(12) "My_Order_123" ["fraudcontrolresponsecode"] => string(4) "0100" ["paymenttypedescription"] => string(4) "VISA" ["maskedpan"] => string(16) "411111######1111" ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:14:35" ["errormessage"] => string(2) "Ok" ["operatorname"] => string(23) "[email protected]" ["parenttransactionreference"] => string(10) "1-2-345678" ["accounttypedescription"] => string(12) "FRAUDCONTROL" ["acquirerrecommendedaction"] => string(1) "C" ["transactionreference"] => string(9) "1-2-345679" ["requesttypedescription"] => string(7) "RISKDEC" ["fraudcontrolreference"] => string(4) "TEST" ["fraudcontrolshieldstatuscode"] => string(6) "ACCEPT" ["livestatus"] => string(1) "0" } } }
{"requestreference":"W23-eyqd5u3x","version":"1.00","response":[{"errorcode":"0","fraudcontrolresponsecode":"0150","paymenttypedescription":"VISA","orderreference":"My_Order_123","transactionstartedtimestamp":"2016-12-07 16:24:50","errormessage":"Ok","operatorname":"[email protected]","parenttransactionreference":"1-2-345678","accounttypedescription":"FRAUDCONTROL","acquirerrecommendedaction":"C","transactionreference":"1-2-345679","requesttypedescription":"RISKDEC","maskedpan":"411111######1111","fraudcontrolreference":"TEST","fraudcontrolshieldstatuscode":"ACCEPT","livestatus":"0"}],"secrand":"ft9j6l"}
<?xml version="1.0" encoding="utf-8"?> <responseblock version="3.67"> <requestreference>X336659733</requestreference> <response type="RISKDEC"> <merchant> <orderreference>My_Order_123</orderreference> <operatorname>[email protected]</operatorname> </merchant> <transactionreference>18-65-2</transactionreference> <billing> <payment type="VISA"> <pan>411111######1111</pan> </payment> </billing> <timestamp>2012-06-21 13:32:43</timestamp> <fraudcontrol> <shieldstatuscode>ACCEPT</shieldstatuscode> <reference>TEST</reference> <recommendedaction>C</recommendedaction> <responsecode>0150</responsecode> </fraudcontrol> <live>0</live> <error> <message>Ok</message> <code>0</code> </error> <operation> <parenttransactionreference>1-2-345679</parenttransactionreference> <accounttypedescription>FRAUDCONTROL</accounttypedescription> </operation> </response> <secrand>UIPGZ</secrand> </responseblock>
Interpreting the response
Here is the field specification for a RISKDEC response:
Field | Format | Description | |
![]() |
acquirerrecommendedaction XPath: /fraudcontrol/recommendedaction |
Char (1) | Either:
Note that this is ONLY a recommendation. Protect Plus does not guarantee against fraud. |
![]() |
fraudcontrolreference XPath: /fraudcontrol/reference |
Alphanumeric (255) | Unique reference to identify the Risk Decision check performed. |
![]() |
fraudcontrolresponsecode XPath: /fraudcontrol/responsecode |
Numeric (4) | A numeric code that is mapped to a description of the results of the Risk Decision checks performed. |
![]() |
fraudcontrolshieldstatuscode XPath: /fraudcontrol/shieldstatuscode |
Alpha (10) | One of the following values:
|
![]() |
requesttypedescription XPath: /@type |
Alpha (20) | You will be returned “RISKDEC”. |
![]() |
rulecategoryflag XPath: /fraudcontrol/categoryflag |
Alphanumeric (255) | Reference used to identify a condition that was met to return the DENY or CHALLENGE fraudcontrolshieldstatuscode. |
![]() |
rulecategorymessage XPath: /fraudcontrol/categorymessage |
Text (undefined length) | Condition that was met to return the DENY or CHALLENGE fraudcontrolshieldstatuscode. |
Testing
We recommend that you thoroughly test your solution before enabling on your live Site Reference.
Click here for details that you can submit to simulate different RISKDEC responses on our test system.
Alternative Payment Methods (API)DCC