Protect Plus for Webservices API

  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.

  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 AVSSecurity Code Checks and 3-D Secure into account.

 

Configuration

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

  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:

Python PHP cURL Raw JSON Raw XML
#!/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

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.

Python PHP Raw JSON Raw XML
{
u 'requestreference': u 'A0dcb11e6',
u 'version': u '1.00',
u 'responses': [{
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 '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'
}]
}
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 JWTto 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.

Python PHP cURL Raw JSON Raw XML
#!/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

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.

Python PHP Raw JSON Raw XML
{
u 'requestreference': u 'Ad4ft45gp',
u 'version': u '1.00',
u 'responses': [{
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 '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'
}]
}

 

Interpreting the response

Here is the field specification for a RISKDEC response:

  Field Format Description
table-returned.png 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.

table-returned.png fraudcontrolreference
XPath: /fraudcontrol/reference
Alphanumeric (255) Unique reference to identify the Risk Decision check performed.
table-returned.png fraudcontrolresponsecode
XPath: /fraudcontrol/responsecode
Numeric (4) A numeric code that is mapped to a description of the results of the Risk Decision checks performed.
table-returned.png 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.
table-returned.png requesttypedescription
XPath: /@type
Alpha (20) You will be returned “RISKDEC”.
table-conditional.png 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.

table-conditional.png 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.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request