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.
Read this article to learn more.
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.
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:
- 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.
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 – 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.
Configuration
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.
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 = "webservices@example.com"
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' => 'webservices@example.com',
'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 webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "webservices@example.com",
"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":"webservices@example.com",
"version":"1.00",
"request":[{
"currencyiso3a":"GBP",
"requesttypedescriptions":["RISKDEC"],
"sitereference":"test_site12345",
"baseamount":"1011",
"orderreference":"My_Order_123",
"accounttypedescription":"FRAUDCONTROL",
"pan":"4111111111111111",
"expirydate":"12/2020"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</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 'responses': [{
u 'fraudcontrolresponsecode': u '0100',
u 'paymenttypedescription': u 'VISA',
u 'orderreference': u 'My_Order_123',
u 'transactionstartedtimestamp': u '2016-12-07 16:19:28',
u 'issuer': u 'Test Issuer',
u 'issuercountryiso2a': u 'GB',
u 'errormessage': u 'Ok',
u 'operatorname': u 'webservices@example.com',
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"
["responses"] => 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:12:39"
["issuer"] => string(11) "Test Issuer"
["issuercountryiso2a"] => string(2) "GB"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "webservices@example.com"
["accounttypedescription"] => string(12) "FRAUDCONTROL"
["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",
"issuer":"Test Issuer",
"issuercountryiso2a":"GB",
"errormessage":"Ok",
"operatorname":"webservices@example.com",
"accounttypedescription":"FRAUDCONTROL",
"transactionreference":"1-2-345678",
"requesttypedescription":"RISKDEC",
"maskedpan":"411111######1111",
"fraudcontrolreference":"TEST",
"fraudcontrolshieldstatuscode":"ACCEPT",
"livestatus":"0"
}],
"secrand":"E0ksvyuH5VKg"
}
<responseblock version="3.67">
<requestreference>X336659733</requestreference>
<response type="RISKDEC">
<merchant>
<orderreference>My_Order_123</orderreference>
<operatorname>webservices@example.com</operatorname>
</merchant>
<transactionreference>1-2-345678</transactionreference>
<billing>
<payment type="VISA">
<issuer>Test Issuer</issuer>
<issuercountry>GB</issuercountry>
<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 = "webservices@example.com"
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' => 'webservices@example.com',
'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 webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -d '{
"alias": "webservices@example.com",
"version": "1.00",
"request": [{
"currencyiso3a": "GBP",
"requesttypedescriptions": ["RISKDEC"],
"sitereference": "test_site12345",
"baseamount": "1011",
"orderreference": "My_Order_123",
"accounttypedescription": "FRAUDCONTROL",
"parenttransactionreference": "1-2-3"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"currencyiso3a":"GBP",
"requesttypedescriptions":["RISKDEC"],
"sitereference":"test_site12345",
"baseamount":"1011",
"orderreference":"My_Order_123",
"accounttypedescription":"FRAUDCONTROL",
"parenttransactionreference":"1-2-3"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</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 'responses': [{
u 'fraudcontrolresponsecode': u '0100',
u 'paymenttypedescription': u 'VISA',
u 'orderreference': u 'My_Order_123',
u 'transactionstartedtimestamp': u '2016-12-07 16:25:19',
u 'issuer': u 'Test Issuer',
u 'issuercountryiso2a': u 'US',
u 'errormessage': u 'Ok',
u 'operatorname': u 'webservices@example.com',
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"
["responses"] => array(1) {
[0] => array(17) {
["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"
["issuer"] => string(11) "Test Issuer"
["issuercountryiso2a"] => string(2) "GB"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "webservices@example.com"
["parenttransactionreference"] => string(10) "1-2-345678"
["accounttypedescription"] => string(12) "FRAUDCONTROL"
["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",
"issuer":"Test Issuer",
"issuercountryiso2a":"GB",
"errormessage":"Ok",
"operatorname":"webservices@example.com",
"parenttransactionreference":"1-2-345678",
"accounttypedescription":"FRAUDCONTROL",
"transactionreference":"1-2-345679",
"requesttypedescription":"RISKDEC",
"maskedpan":"411111######1111",
"fraudcontrolreference":"TEST",
"fraudcontrolshieldstatuscode":"ACCEPT",
"livestatus":"0"
}],
"secrand":"ft9j6l"
}
<responseblock version="3.67">
<requestreference>X336659733</requestreference>
<response type="RISKDEC">
<merchant>
<orderreference>My_Order_123</orderreference>
<operatorname>webservices@example.com</operatorname>
</merchant>
<transactionreference>18-65-2</transactionreference>
<billing>
<payment type="VISA">
<issuer>Test Issuer</issuer>
<issuercountry>GB</issuercountry>
<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 | |
| 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. Only returned if checks are performed successfully. |
|
| rulecategorymessage XPath: /fraudcontrol/categorymessage |
Text (undefined length) |
Condition that was met to return the DENY or CHALLENGE fraudcontrolshieldstatuscode. Only returned if checks are performed successfully. |
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.
