Please find below our Integration documentation that outlines each stage in Integrating the TransUnion Digital Verification system to your Site. For more detail on API documentation, please follow the links attached in each section or visit https://app.trustev.com/help.

High Level Integration Overview

At TransUnion Digital Verification we try to make Integration to our platform as straight-forward and seamless as possible.

We have included a Glossary, FAQ Section, Testing Guide, API Libraries, and sample code segments to assist you. Enter a request at Support Portal if you have any queries.

At a high level, Integration can be broken into four main stages:

 

  • Setting Up
  • JavaScript Integration
  • API Integration
  • Going Live

Merchant Integration Checklist

The following checklist outlines the steps that must be followed before an Integration is considered complete.

Step # Process
Setting Up:
1 Sign Up
To signup, please contact the Integration Team who will carry out this process for you. You can contact them via Support Portal.
JavaScript Integration:
2 Add Trustev.js
Trustev.js works behind the scenes to gather your customer information.
3 Extract TrustevV2.SessionId
Publicly accessible variable in our Trustev.js, required when Adding a Digital Verification Case
API Integration:
4 Get A Token
Using your Test API Keys, this method involves getting an Authentication Token to begin API calls.
5 Add A Case
Involves sending Transaction information, Customer information, Item details, Payment details, and Status details.
6 Get a Digital Verification Decision
Using a Case Id, and based on all Trustev.js information & details added to the Digital Verification Case, this API call returns the Digital Verification Decision.
7 Add a Status
When a Digital Verification Decision has been returned, a Status must be forwarded to Digital Verification outlining what decision was made by the Merchant on the 'transaction'.
Going Live:
8 Get Live API Keys
Similar to the process of getting your Test API Keys, once Integration is finished, the Integration Team will swap these out for the Live Keys, which will be sent to you.
9 Integration Team confirmed Integration complete
This section involves our Integration Team working with our Fraud Team to review all the requests received to ensure data is being gathered correctly.
10 Update Terms & Conditions, and Privacy Notices
All privacy notices on the Merchant's Site must be updated to advise that Digital Verification has been implemented.
11 Calibration Phase
Once a good level of Live data is generated, our Fraud Team creates a bespoke configuration to return accurate Digital VerificationDecisions.

Contact Us

We're constantly trying to improve and simplify our Integration process. Any feedback on improvements, big or small, that we could make would be greatly appreciated. Please drop us a line via Support Portal.

Setting Up

The first stage in the Integration Process involves getting set-up to use TransUnion ID Vision soloutions.

01

Sign Up

To sign up for an account, you can contact us via Support Portal.

The Integration Team will work with you to set up your account. They will register your site name and email, and will subsequently provide you with your Test API Keys, which you will need in order to communicate with the Digital Verification API.

If you are having difficulty, please see our FAQs for more detail.

 

JavaScript Integration

The second stage involves inserting the TransUnion Digital Verification JavaScript code into your web site so that we can gather details on your customer’s activity on your site.

02

Add Trustev.js

In this step, you will integrate our Digital Verification JavaScript on your site. We recommend that the Digital Verification JavaScript tags are added to all pages on your site, however at a minimum we require the JavaScript tags to be included in at least 3 pages in your Checkout, Account Creation or Application funnel.

REQUIRED ACTION

 

  • Include the Digital Verification JavaScript tags on your site (as below)
  • Initialise the Digital Verification JavaScript and store the returned Session Id
    • Use the JavaScript snippet below as a template to initialise the JavaScript and store the SessionId
    • The JavaScript should be initialised on every page it is included in
    • Your Public Key will be provided by the Digital Verification Integration team

Digital Verification CDN JavaScript

The following <script> tag should be included between the opening and closing <head> tag in your site.

<!--Reference to the CDN based JavaScript, please use the correct URL for your region-->
<script type="text/javascript" src="https://cdn-us.trustev.com/trustev.min.js"></script>

The following JavaScript snippet can be included either directly in each page, or in another JavaScript file that you maintain. It is important to ensure the TrustevV2.Init() is not executed until trustev.min.js has been fully loaded.

<!--Initialise the JavaScript with your Public Key, and receive a SessionId as a call back-->
<script type="text/javascript">  

             //only call once trustev.min.js has been loaded
            TrustevV2.Init('<publickey>', function(sessionId) {
                     //you should store this sessionId for retrieval at a later point
                     console.log(‘SessionId: ‘ + sessionId);
             });
</script>

NB:Make sure to replace publickey with your Public Key value.

Trustev.min.js is a secure, CDN hosted JavaScript file responsible for gathering details about each session and device that visits your site. These details are then returned to the TransUnion digital Verification Platform and will eventually form part of the Digital Verification Decision. For more information, see What is Trustev.js?

TrustevV2.Init() must be executed in all webpages where the trustev.min.js scripts tags are included, as this function initiates the required data collection to support a decision. The SessionId returned is valid for a 20 minute rolling window. If no activity occurs within this 20minute window, the existing SessionId will be invalidated. The next time you call TrustevV2.Init() you will receive a new SessionId.

If you are experiencing any difficulties with the Trustev.min.js, please see our detailed FAQ - which describes how to verify that the Trustev.js is implemented correctly - or contact our Support Portal.

 

03

Get Digital Verification SessionId

It is recommended to use the callback option from TrustevV2.Init() method to get the Digital Verification SessionId. Please note that TrustevV2.Init() is asynchronous. This variable can be accessed from any page that has called TrustevV2.Init() method.

A valid SessionId is required to call our AddCase API (which is a precursor to our GetDecision API). You will need to call TrustevV2.Init() on every page the Digital Verifcation JavaScript is included in, however you will only ever need the most recent Session Id returned in the TrustevV2.Init() call back to interact with our API..

API Integration

API Overview

The Digital Verifcation API is REST based. See http://en.wikipedia.org/wiki/Representational_state_transfer.

It is designed to:

 

  • have predictable, resource-oriented URLs
  • use HTTP Server Response codes to indicate API errors.
  • provide detailed error information in the HTTP Header of the Server Responses – should errors occur.

HTTP Messages

The HTTP Server Response Messages are as informative as possible. If you run into any issues during Integration,  look at the Response Message we send back – these should usually pinpoint where the issue lies. Please see our FAQ for more information.

High-Level API Integration Overview

The third stage in the Integration process is the API Integration. For full details on our API reference, please see https://app.trustev.com/help.

We have a US and EU data centre available, so depending on your location, these are the API Endpoints:

US Customers - API Endpoint: https://app.trustev.com/api/v2.0/

EU Customers - API Endpoint: https://app-eu.trustev.com/api/v2.0/

In order to communicate with the Digital Verification API, you must have an API Token. An API Token is an alphanumeric string that is returned from a successful HTTP POST to the “Get a Token” method.

This request message is made up of your Site UserName and the current Timestamp, along with two parameters ‘PasswordHash’ and ‘UserNameHash’ which are hashed values made up of the Timestamp, your Site Password, your Site Secret, and your Site UserName. Please see the "Get a Token" step for more information on forming these hashed values correctly.

If a successful request is made then the API Token is returned from the “Get a Token” call. API Tokens expire after 30 minutes - during this time you may use this API Token for authentication in as many of your requests as needed. An ‘ExpireAt’ DateTime parameter is included in the response header so that you may validate your API Token before using it.

This API Token is required on all subsequent calls to the API along with your Site UserName. It must be passed with all requests in the request header in the format:

“X-Authorization: UserName APIToken”
E.G. “X-Authorization: TrustevTest 4b312a24-2495-4ba4-8f85-d891bab1cac8”

Digital Verifcation Decisions are made on Digital Verifcation Cases. That is, data is gathered in a Digital Verifcation Case and a Digital Verifcation Decision is generated based on that data. Use the “Add a Digital Verifcation Case” method to add data to a Digital Verifcation Case.
There are a number of different data fields available, however you may exclude these from the request message if the data is not available. A Digital Verifcation Case is composed of:

 

Please see our Case object for more details.

When Adding a Case you must create a request message with all the data you wish to forward, attaching your API Token and UserName in the request header as described above.

A Digital VerifcationDecision will use all information gathered through the Trustev.js along with all the information sent through the Digital Verifcation API. Once a Digital Verifcation Case has been successfully added then the Response Message will include a Digital Verification Case. There will be an Id field in this Case Response Message. This Id should be stored for later use as it is the reference Id required when you wish to get a Digital Verifcation Decision.

During debugging it might be helpful to view the Digital Verifcation Case that is being returned to you – if all data is being sent correctly to the Digital Verifcation API then you should receive the same Digital Verifcation Case and data back in the Response message.

Please note: our API will add an Id field to each object within the Digital Verifcation Case, visibile in the Add Case Response Message – Transaction, Transaction Address, Customer, Customer Address, Item, Email Address, Payment, and Status. These Ids can also be stored for later use with the Digital Verifcation API should you wish to update this object’s information. Please see our FAQ on this for more information.

Once a Digital Verifcation Case has been added then you may request to get a Digital Verifcation Decision on the Digital Verifcation Case. A Digital Verifcation Decision will be a recommendation based off all of the data sent, and whether we consider it fraudulent or not. For more information please see our FAQs. You must include your API Token and UserName in the Request Header. Further, the endpoint that you communicate with must also include the Digital Verifcation Case Id that was received from the Digital Verifcation API, when the Digital Verifcation Case was added.

https://app.trustev.com/api/v2.0/Decision/ + CaseId
E.G. https://app.trustev.com/api/v2.0/Decision/123456

After a Digital Verifcation Decision has been returned, then you must call the “Add a Status” method to update the status information for the Digital Verifcation Case. This section provides a feedback loop to our system on the order outcome which trains our ML models and improves the system accuracy for your Site. Please see our FAQ on the importance of adding Statuses for more information. There are pre-defined status types from 0 – 10, see here for details, and there is also a comments field if you need to include more information. Our Integration Team and Fraud Team can assist in mapping these to your current Order Processing System during the Integration.

Note: it may be required to update the Status of a Digital Verifcation Case days or weeks after the Case has been processed. For instance, if Chargebacks are charged on the Digital Verifcation Case then the Status of the Case should be updated to reflect this.

Lastly, we suggest that when Integrating the Digital Verifcation API you allow for scenarios where, if the Digital VerifcationAPI is unavailable, that your site should function ‘normally’ but without the Digital Verifcation features – this should allow for minimal impact to your customer’s experience should our services become unavailable for any reason.

04

Get a Token

To communicate with the Digital Verifcation API, you will require an API Token. An API Token is an alphanumeric String returned from the Digital Verifcation API that must be provided by the Merchant in the Request Header for all subsequent API calls. A Merchant can access an API Token through our Get a Token API method. This involves sending a HTTP POST Request Message with your API Key details.

To Get a Token, you will require your Test API Keys - our Integration Team will have issued these to you at sign-up. Please see API Keys: Explained for more information.

We have a US and EU data centre available, so depending on your location, these are the API Endpoints:

US Customers - Token API Endpoint: https://app.trustev.com/api/v2.0/token

EU Customers - Token API Endpoint: https://app-eu.trustev.com/api/v2.0/token


An API Token Request Message, requires four data fields:

1. UserName: This is your Site UserName, available in your Test API Keys

2. Timestamp: This is the Current Timestamp in UTC in the format yyyy-MM-ddTHH:mm:ss.fffZ.
See What format is accepted for the Timestamp? for more information.

3. PasswordHash:  This is a hashed value involving two steps:

Part 1. Create a Sha256Hash of a String in the format of {0}.{1}, where {0} is the Timestamp above, and {1} your Site Password which is available from your Test API Keys

Part 2. Create a Sha256Hash of a String in the format of {0}.{1}, where {0} is the result of Part 1, and {1} is your Shared Secret which is available from your Test API Keys

4. UserNameHash:   This is a hashed value involving two steps:

Part 1. Create a Sha256Hash of a String in the format of {0}.{1}, where {0} is the Timestamp above, and {1} is your Site UserName which is available from your Test API Keys.

Part 2. Create a Sha256Hash of a String in the format of {0}.{1}, where {0} is the result of Part 1, and {1} is your Shared Secret which is available from your Test API Keys.


Example in PHP

$passwordHash = $this->Get256Hash($timestamp . "." . $password);
$passwordHash = $this->Get256Hash($passwordHash . "." . $secret);
$usernameHash = $this->Get256Hash($timestamp . "." . $username);
$usernameHash = $this->Get256Hash($usernameHash . "." . $secret);

For Authentication in all other API calls, you will require the ‘APIToken’ field that is returned in the Response Message of a successful Get a Token request. We advise that you store this APIToken for re-use in subsequent calls to our API. Once the API Token expires, you can request a new token from our API and continue as normal. Please note that the APIToken will stay valid for 30 minutes and during this time you may use it for as many API requests as required. We include an ‘ExpireAt’ field in the Response Message also which can be used a check before running into expired API Token errors.

Sample Get Token Request Message

Sample Get Token Response Message

Please see, What is an API Token and how do I access it? for more information on accessing this.

PHP HTTP Get A Token Request:

$request = json_encode(TOKEN REQUEST);
$url = "https://app.trustev.com/api/v2.0/token";
$contentType = "Content-type: application/json";

$curl = curl_init($url);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => $request,
CURLOPT_HTTPHEADER => [
$contentType
]
]);

$exec = curl_exec($curl);
$result = json_decode ($exec, true);
curl_close($curl);

05

Add a Case

This API method allows you to ‘Add a Case’. A Digital Verifcation Case is our term used for the accumulation of all the data fields relevant to a particular ‘transaction’ which can fall under any of these catagories: Transaction Information, Customer Information, Item Details, Payment Details, and Status Details. This method allows you to add all these data fields in one API call.

See What’s a Case? for more information.

Before adding a Case, you must ensure you have the following information:

 

  • The TrustevV2.SessionId that we advised would need to be accessed in Step 3.
  • The APIToken that you received from our Get Token API request in Step 4, along with your Digital Verifcation UserName, available in your Test API Keys - This is required in the Request Header.
  • A Case Number, which is a alphanumeric String that you may choose. It must be unique to you as a Merchant. For reporting and data analysis, we advise that the Case Number should be a reference to your own internal reference number which you associate with the ‘transaction’. By doing this, it will allow for an easy reference point should you need more information on the Digital Verifcation Case through our Digital Verification Console.

During Integration, you will be using Test API Keys which means that the Digital Verifcation Decision you receive on a Digital Verifcation Case will not be based off the data provided, but will be a random generated result. By altering the Case Number that you provide when Adding a Digital Verifcation Case, you can influence the Digital Verifcation Decision returned during Testing. Please see our Testing Guide for more information.

The more data fields that you can provide, the better the scoring accuracy, however should you not have some of the data fields (we refer to these as ‘case objects’) listed in a Case, then you can simply leave these sections out. We would request that you advise our Integration Team or Fraud Team if data is not to be provided so that we can configure our system for your production move.

We have a US and EU data centre available, so depending on your location, these are the API Endpoints:

US Customers - Case API Endpoint: https://app.trustev.com/api/v2.0/case

EU Customers - Case API Endpoint: https://app-eu.trustev.com/api/v2.0/case

Please see code below that shows how to forward a Case to the Digital Verifcation API. Clicking on the ADD CASE REQUEST below will bring you to our detailed technical document that outlines all the available fields and data types required.

PHP HTTP Add A Case Request

$username = SITE USERNAME;
$token = API TOKEN FROM STEP 5:GET A TOKEN;

$request = json_encode(ADD CASE REQUEST)
$url = "https://app.trustev.com/api/v2.0/case";
$contentType = "Content-type: application/json";
$auth = "X-Authorization:" . $username . " " . $token;
$curl = curl_init($url);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => $request,
CURLOPT_HTTPHEADER => [
$contentType,
$auth,
]
]);

$exec = curl_exec($curl);
$result = json_decode($exec, true);

curl_close($curl);

Something important to note, is that our API is structured to handle a maximum of 10 Case Requests per TrustevV2.SessionId. If you try to add more than 10 Cases to a Session you will receive a HTTP 403 Forbidden Response, and in that scenario you should start a new session.

Once a Digital Verifcation Case has been successfully added then the Response Message will include a Digital Verifcation Case. There will be an Id field in this Case Response Message. This Id parameter should be extracted and stored as it is required for use in the final two steps.

The data gathered from Trustev.js will also now fall under the unique Digital Verifcation Case you have created.

06

Get a Digital Verifcation Decision

The Digital Verifcation Decision is our recommendation on whether you should allow, block, or flag this transaction for manual review. There are 2 options (and two separate endpoints) to get a Digital Verifcation Decision:

1. The standard Digital Verifcation Decision.

2. The Detailed Decision Endpoint

You should use either, but not both.

This API method allows you to retrieve a Digital Verifcation Decision. You will require the Case Id that was returned in the ‘Add a Case’ method above.

Please see our FAQ for more information on the Digital VerifcationDecision. During Integration, you will be using Test API Keys, and this will mean that the Digital Verifcation Decision returned to you will be a randomly generated result. We provide a Testing Guide at the end of the documentation that outlines how to get expected results from the API.

The Digital Verifcation Decision is a decision formulated after utilizing all the data that has been gathered in compiling your Digital Verifcation Case. This includes all the data gathered as your customer browsed your Site through our Trustev.js, and all the information that was supplied in the ‘Add a Case’ method. Once a Digital Verifcation Case has been added, and a request to get a Digital VerifcationDecision has been made, our API will return a Digital Verifcation Decision. A Digital Verifcation Decision will indicate either: Pass, Flag or Fail.

Before retrieving a Digital Verifcation Decision, you must ensure you have the following information:

 

  • The API Token that you received from our Step 4: Get a Token API request, along with your Digital Verifcation UserName, available in your Test API Keys.
  • The Case Id that is returned in Step 5: Add a Case API request. This Case Id will be added to the end of the URL to get a Digital Verifcation Decision.

 

Digital Verifcation Decision

We have a US and EU data centre available, so depending on your location, these are the API Endpoints:

US Customers - Decision API Endpoint: https://app.trustev.com/api/v2.0/decision/{caseId}

EU Customers - Decision API Endpoint: https://app-eu.trustev.com/api/v2.0/decision/{caseId}

Format: “https://app.trustev.com/api/v2.0/Decision/” + Case Id
Example: “https://app.trustev.com/api/v2.0/Decision/12345”

PHP HTTP Get Digital Verifcation Decision Request

$username = SITE USERNAME;
$token = API TOKEN FROM STEP 4:GET A TOKEN;
$caseId = CASEID FROM STEP 5:ADD A CASE

$url = "https://app.trustev.com/api/v2.0/decision/" . $caseId;
$contentType = "Content-type: application/json";
$auth = "X-Authorization:" . $username . " " . $token;

$curl = curl_init($url);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
$contentType,
$auth,
]
]);

$exec = curl_exec($curl);
curl_close($curl);

Based off all of the information forwarded, you will be returned a Result field in the Response Message of the API call. This Result will indicate:

Decision Meaning Description
0 Unknown This result should not be returned to you. It means that an error has occurred and a Digital Verifcation Decision has not been made on your Digital Verifcation Case. Please contact Support Portal should this occur. Please provide the Case Number and Case Id when sending this request.
1 Pass This result indicates that the Digital Verifcation Case shows no signs for suspicion and the 'transaction' should be accepted.
2 Flag This result indicates that the Digital Verifcation Case contains elements for suspicion which should be reviewed before a final decision is made.
3 Fail This result indicates that the Digital Verifcation Case contains a number of fraudulent features and the 'transaction' should be rejected.

 

Sample Get Digital Verifcation Decision Response Message

 {
"Id": "656b662a-3e15-4c09-8643-c0a7628d6ae3",
"Version": 1,
"SessionId": "efc54b16-17ed-4f57-9a78-6707c2109a23",
"Timestamp": "2015-11-17T15:17:20.4228252",
"Type": 0,
"Result": 3,
"Score": 475,
"Confidence": 54,
"Comment": "C# Decision"
}

The main field to consider in the Response Message above is the Result. The Score is just the numeric value, and is directly represented in the Result. The Confidence is a percentage score that reflects the amount of data sent through and will not vary much from transaction to transaction. It is the Result which should be used.

For a more detailed breakdown of the decision returned, you can login to your Order Review Screen through the Digital Verification Console https://console-eu.trustev.com (For EU Customers) or https://console-us.trustev.com (For US Customers).  Simply select our reporting features, entering in the Case Number you supplied to see the main elements that influenced the Digital Verifcation Decision on any particular Case.

Please note that during Integration you will be using Test API Keys, so the Digital Verifcation Decision and Digital Verifcation Confidence results returned will not be based off the data provided, but will instead be randomly generated.

Additionally, during the Calibration Phase, a number of configuration changes will occur while our Fraud Team work to adjust the logic to match your Site environment. Due to this, we advise that Merchant's continue to make all expected API requests but to not accept/deny orders based off the Digital Verifcation Decision during this time. 

 

Detailed Decision

In some cases merchants wish to see a deeper dive into how we came to that decision. That is where the Detailed Decision Endpoint is used. In addition to Decision, Score and Confidence, we provide more data fileds in the response message around the facts that were considered in the Decision. Either the Decision or the Detailed Decision Endpoint should be used, not both.  

When would I use the Detailed Decision Endpoint?

The Detailed Decision Endpoint would typically be used where additional data related to a Decision is required in realtime. Examples might include adding realtime analysis of a transaction independent of the Digital Verifcation Decision, or performing additional Customer Identification checks. The data returned can also be used to provide additional confidence that the Digital Verifcation Decision is appropriately configured.

How do I implement the Detailed Decision Endpoint?

The Detailed Decision Endpoint is integrated in the same way as the Decision Endpoint. 

Before retrieving a the Detailed Decision, you must ensure you have the following information.

 

  • The APIToken that you received from our Step 4: Get a Token API request, along with your Digital Verifcation UserName available in your Test API Keys.
  • The Case Id that is returned in Step 5: Add a Case API request. This Case Id will be added to the URL to get a Detailed Decision.

We have a US and EU data centre available, so depending on your location, these are the API Endpoints:

US Customers - Detailed Decision API Endpoint: https://app.trustev.com/api/v2.0/detaileddecision/{caseId}

EU Customers - Detailed Decision API Endpoint: https://app-eu.trustev.com/api/v2.0/detaileddecision/{caseId}

PHP HTTP Get Digital Verification Detailed Decision Request

$username = SITE USERNAME;
$token = API TOKEN FROM STEP 4:GET A TOKEN;
$caseId = CASEID FROM STEP 5:ADD A CASE

$url = "https://app.trustev.com/api/v2.0/detaileddecision/" . $caseId;
$contentType = "Content-type: application/json";
$auth = "X-Authorization:" . $username . " " . $token;

$curl = curl_init($url);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
$contentType,
$auth,
]
]);

$exec = curl_exec($curl);
curl_close($curl);

 

Sample Digital Verifcation Detailed Decision Response Message:

{

"CaseNumber": "a90b1a5c-165a-4240-b657-98beec505ac1",

"CaseId": "a79e6816-4a5b-4fd2-aad7-11b7287fde35|1aef4f5a-7660-4ff2-9876-67c6160b17f2",

"RawData": {

"DeviceTag":"a3eee9f1-4ddb-4f40-bc1c-4959cac00160",

"CustomerId": "a3a811cc-8fec-43ed-8116-996b8a88f722",

"Browser": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.111 Safari/537.36",

"OS": "Unknown",

"NavigatorOscpu": "undefined",

"NavigatorLanguage": "en-US",

"NavigatorPlugins": "[{\"name\":\"Widevine Content Decryption Module\",\"description\":\"Enables Widevine licenses for playback of HTML audio/video content. (version: 1.4.8.866)\",\"filename\":\"widevinecdmadapter.dll\",\"length\":1},{\"name\":\"Shockwave Flash\",\"description\":\"Shockwave Flash 20.0 r0\",\"filename\":\"pepflashplayer.dll\",\"length\":2},{\"name\":\"Chrome PDF Viewer\",\"description\":\"\",

\"filename\":\"mhjfbmdgcfjbbpaeojofohoefgiehjai\",\"length\":1},{\"name\":\"Native Client\",\"description\":\"\",

\"filename\":\"internal-nacl-plugin\",\"length\":2},{\"name\":\"Chrome PDF Viewer\",\"description\":\"Portable Document Format\",\"filename\":\"internal-pdf-viewer\",\"length\":1}]",

"ScreenWidth": "1920",

"ScreenHeight": "1080",

"ScreenColorDepth": "24",

"IPAddresses": [{

"Id": "43f54be0-2726-48a6-9ab2-194d7e116788",

"ClientIp": "92.60.203.205",

"Continent": "europe",

"Country": "ireland",

"CountryCode": "ie",

"State": "cork",

"City": "bandon",

"ConnectionType": "tx",

"LineSpeed": "high",

"RoutingType": "fixed",

"SLD": "glenmarshellfish",

"TLD": "com",

"HostingFacility": "false",

"ProxyType": "",

"AnonymizerStatus": ""

}],

"BINInformation": {

"BIN": "411111"
,

"Brand": "VISA",

"CountryISO3166_Code2": "US",

"CardType": "CREDIT",

"Bank": "JPMORGAN CHASE BANK, N.A."

},

"Customer": {

"FirstName": "John",

"LastName": "Doe",

"Emails": [{

"EmailAddress": "johndoe@trustev.com"

}]

}

},

"ComputedData": {

"Velocity": {

"DecisionsWithin1Hour": 0,

"DecisionsWithin24Hours": 0,

"DecisionsWithin7Days": 0,

"DecisionsWithin30Days": 0

},

"BlackList": {

"WasBinHit": false,

"WasEmailDomainHit": false,

"WasFullEmailAddressHit": false,

"WasPostCodeHit": false,

"WasCustomerIdHit": false,

"WasAccountNumberHit": false,

"WasIPHit": false

},

"GreyList": {

"WasBinHit": false,

"WasEmailDomainHit": false,

"WasFullEmailAddressHit": false,

"WasPostCodeHit": false,

"WasCustomerIdHit": false,

"WasAccountNumberHit": false,

"WasIPHit": false

},

"WhiteList": {

"WasBinHit": false,

"WasEmailDomainHit": false,

"WasFullEmailAddressHit": false,

"WasPostCodeHit": false,

"WasCustomerIdHit": false,

"WasAccountNumberHit": false,

"WasIPHit": false

},

"Email": {

"IsDisposable": false,

"IsDomainNotAllowed": false,

"IsUserNameNotAllowed": false,

"ContainsDomainIssue": false,

"ContainsMailboxIssue": true,

"ContainsSyntaxIssue": false

},

"Customer": {

"IsReturningToPlatform": false,

"HasGoodHistory": false,

"HasBadHistory": false,

"HasSuspiciousHistory": false

},

"Location": {

"IsIPCountryDomestic": false,

"BIN": {

"DoesMatchBillingAddressCountry": false,

"DoesMatchDeliveryAddressCountry": false,

"DoesMatchIPCountry": false,

"IsCountryDomestic": false

}

}

},

"Id": "fbaf75bc-9e3f-4e7f-bfbd-e15e9c224ec8",

"Version": 16,

"SessionId": "a79e6816-4a5b-4fd2-aad7-11b7287fde35",

"Timestamp": "2016-02-02T10:51:45.7387305Z",

"Type": 0,

"Result": 3,

"Score": 1020,

"Confidence": 87,

"Comment": "Hybrid Decision for Overall"

}

 

Additional Information

It should be noted that the fields above may change as this endpoint evolves. We can guarantee that any of the above fields will not be removed or renamed. However, there may be additional fields added at any time. We ask that this endpoint is integrated so to avoid any breaking changes if we do add new fields.

 

Note that the expectation is that the DetailedDecision endpoint will return in realtime: <500ms and it’s performance will be comparable with the Decision endpoint.

 

Data Dictionary



Data Field

Description

Format

Case Number

This is the order number, chosen by the Merchant of each transaction.

String

CaseId

The Case ID uniquely identifies a Digital Verifcation Case.

64 digits, combination of numeric and alphabetical

DeviceTag

Guid generated by Digital Verifcation to identify this device.

32 digits, combination of numeric and alphabetical

Digital Verification CustomerId

Guid generated by Digital Verifcation to identify this customer.

32 digits, combination of numeric and alphabetical

Browser

Information on the customer's browser

String

OS

What Operating System the customer is using.

String

NavigatorOscpu

The CPU as reported by the browser.

String

NavigatorLanguage

The language as reported by the browser.

String

NavigatorPlugins

The plugins installed on the browser.

String

ScreenWidth

The width of the screen on the machine that the customer is using.

String

ScreenHeight

The height of the screen on the machine that the customer is using.

String

ScreenColorDepth

The colour depth of the screen on the machine that the customer is using.

String

     

IPAddresses

   

Id

Guid generated by Digital Verifcation to identify this IP address.

32 digits, combination of numeric and alphabetical

ClientIp

IP address.

String

Continent

The continent that this IP address is on.

String

Country

The country that this IP address is on.

String

CountryCode

Country code that this IP address has.

String

State

State that this IP address is in.

String

City

City that this IP address is in.

String

ConnectionType

Indicates the speed of the connection to the Internet, divided into: high, medium, or low.

String

LineSpeed

Indicates the speed of the connection to the Internet, divided into: high, medium, or low.

String

RoutingType

The IP Routing Type (IPRT) specifies how the connection is routed through the Internet and can be used to determine how close the user is to the public IP address.

String

SLD

SecondLevelDomain - The SLD is the part of the domain name that precedes the top-level domain.

String

TLD

TopLevelDomain - Identifies the most general part of the domain name in a Web address. E.g, .com, .co.uk., .ie

String

HostingFacility

Is this customer using a hosting facility or not. If they are, returns 'true', if not, returns 'false'

Boolean

ProxyType

If proxy is detected, this is the type.

String

AnonymizerStatus

A status is assigned to IP addresses that have been detected as a proxy. The status is an indicator, at the highest level that an IP address may be associated with an anonymizing proxy. It is a relative indicator of how recent the proxy was found to be active and the proxy’s category.

String

     

BINInformation

   

BIN

Bank Identification Number, 6 digits.

String

Brand

The brand of the card used for payment.

String

CountryISO3166_Code2

The country where this card was issued.

String

CardType

The type of card.

String

Bank

The bank that issued this card.

String

     

Velocity

   

DecisionsWithin1Hour

How many times this customer has transacted in the last hour.

Integer

DecisionsWithin24Hours

How many times this customer has transacted in the last 24 hours.

Integer

DecisionsWithin7Days

How many times this customer has transacted in the last 7 days.

Integer

DecisionsWithin30Days

How many times this customer has transacted in the last 30 days.

Integer

     

BlackList

   

WasBinHit

Was this BIN blacklisted. If yes 'true', if no 'false'.

Boolean

WasEmailDomainHit

Was this email domain blacklisted. If yes 'true', if no 'false'.

Boolean

WasFullEmailAddressHit

Was this email address blacklisted. If yes 'true', if no 'false'.

Boolean

WasPostCodeHit

Was this postcode blacklisted. If yes 'true', if no 'false'.

Boolean

WasCustomerIdHit

Was this customerId blacklisted. If yes 'true', if no 'false'.

Boolean

WasAccountNumberHit

Was this Account Number blacklisted. If yes 'true', if no 'false'.

Boolean

WasIPHit

Was this IP blacklisted. If yes 'true', if no 'false'.

Boolean

     

GreyList

   

WasBinHit

Was this BIN greylisted. If yes 'true', if no 'false'.

Boolean

WasEmailDomainHit

Was this email domain greylisted. If yes 'true', if no 'false'.

Boolean

WasFullEmailAddressHit

Was this email address greylisted. If yes 'true', if no 'false'.

Boolean

WasPostCodeHit

Was this postcode greylisted. If yes 'true', if no 'false'.

Boolean

WasCustomerIdHit

Was this customerId greylisted. If yes 'true', if no 'false'.

Boolean

WasAccountNumberHit

Was this Account Number greylisted. If yes 'true', if no 'false'.

Boolean

WasIPHit

Was this IP greylisted. If yes 'true', if no 'false'.

Boolean

     

WhiteList

   

WasBinHit

Was this BIN whitelisted. If yes 'true', if no 'false'.

Boolean

WasEmailDomainHit

Was this email domain whitelisted. If yes 'true', if no 'false'.

Boolean

WasFullEmailAddressHit

Was this email address whitelisted. If yes 'true', if no 'false'.

Boolean

WasPostCodeHit

Was this postcode whitelisted. If yes 'true', if no 'false'.

Boolean

WasCustomerIdHit

Was this customerId whitelisted. If yes 'true', if no 'false'.

Boolean

WasAccountNumberHit

Was this Account Number whitelisted. If yes 'true', if no 'false'.

Boolean

WasIPHit

Was this IP whitelisted. If yes 'true', if no 'false'.

Boolean

     

Email

   

IsDisposable

Is this a disposable email? If it is, returns 'true', if not returns 'false'.

Boolean

IsDomainNotAllowed

Is this email domain listed as spam or malicious? If it is, returns 'true', if not returns 'false'.

Boolean

IsUserNameNotAllowed

Is this email username listed as spam or malicious? If it is, returns 'true', if not returns 'false'.

Boolean

ContainsDomainIssue

Does email contain domain issue? If it does, returns 'true', if not returns 'false'.

Boolean

ContainsMailboxIssue

Does this mailbox have issues receiving emails or does it not exist? If it does have issues or does not exist, returns 'true', if not returns 'false'.

Boolean

ContainsSyntaxIssue

Does this email contain typos or errors? If it does, returns 'true', if not returns 'false'.

Boolean

     

Customer

   

IsReturningToPlatform

Have we seen this customer before? If yes, returns 'true', if we haven't, returns 'false'.

Boolean

HasGoodHistory

If this customer has been here before, do they have a good history? If yes, returns 'true', if we haven't, returns 'false'.

Boolean

HasBadHistory

If this customer has been here before, do they have a bad history? If yes, returns 'true', if we haven't, returns 'false'.

Boolean

HasSuspiciousHistory

If this customer has been here before, do they have a suspicious history? If yes, returns 'true', if we haven't, returns 'false'.

Boolean

     

Location

   

IsIPCountryDomestic

Is this IP originating from "allowed" countries, i.e. countries that the merchant ships/sells to. If it is, returns 'true', if not returns 'false'.

Boolean

BIN: DoesMatchBillingAddressCountry

Does the BIN match the country in the billing address? If it does, returns 'true', if not, returns 'false'.

Boolean

BIN: DoesMatchDeliveryAddressCountry

Does the BIN match the country in the delivery address? If it does, returns 'true', if not, returns 'false'.

Boolean

BIN: DoesMatchIPCountry

Does the BIN match the country of the IP address? If it does, returns 'true', if not, returns 'false'.

Boolean

BIN: IsCountryDomestic

Is this BIN originating from "allowed" countries, i.e. countries that the merchant ships/sells to. If it is, returns 'true', if not returns 'false'.

Boolean

 

07

Add a Status

The final step in the Integration process is adding a Status to reflect the outcome of the Digital Verification Case, once you have received a Digital Verification Decision. During the Add a Case step, all transactions/orders automatically receive the status of Placed (8). That being said, this is a temporary status which should be updated to reflect the transaction/order outcome. Please see Why send Statuses? for further information.

This is a critical step in assessing Fraud accuracy and it ultimately feeds our machine learning model to eliminate your Fraud. The Statuses you forward will become a collection of Statuses on the Digital Verification Case, so our system can see the decisions you’ve made throughout the process.

As outlined in Step 6: Get a Digital Verification Decision, the result returned to you will indicate whether or not Digital Verification recommends processing the ‘transaction’. Merchants can face a number of scenarios, and each transaction outcome may not be as simple as Yes/No, therefore we require that a Status is forwarded to Digital Verification, indicating what the final outcome was.

Please see the statuses that can be forwarded to us:

Status Type Status Reason
0 Completed
1 RejectedFraud
2 RejectedAuthFailure
3 RejectedSuspicious
4 Cancelled
5 ChargebackFraud
6 ChargebackOther
7 Refunded
8 Placed
9 OnHoldReview
12 ReportedFraud

Please Note: It is important that Statuses continue to be added to accurately reflect the outcome, as our system will learn off your decisions. This may involve adding a Status several weeks after a Digital Verification Case has been evaluated. For instance, when a Chargeback occurs, Merchants should have a process in place to add the Status of the Case and communicate this back to the Digital Verification API.

We provide a number of options to update the Statuses of your orders:

  1. Using the Status API Endpoint
  2. Providing a CSV file through our sFTP service
  3. Updating the order Status through the Manual Review Screen

Option 1: Using the Status API Endpoint

In the same way that you complete Token, Case, and Decision requests against our API. The easiest, and most convenient way for Merchants to keep Digital Verification up-to-date on the current Status of orders, is to ensure that Status API requests are being issued from your internal order processing system. We would expect that when Order Statuses are changed in your system, you would send a Status API request to the Digital Verification API outlining the accurate status of the order.

We have a US and EU data centre available, so depending on your location, these are the API Endpoints:

US Customers - Status API Endpoint: https://app.trustev.com/api/v2.0/case/{caseId}/status

EU Customers - Status API Endpoint: https://app-eu.trustev.com/api/v2.0/case/{caseId}/status

Sample Add Status Request Message

{
"Status":0,
"Comment":"Order Completed",
"Timestamp":"2016-01-18T11:54:53.005Z"
}

Below is an example in PHP of sending a Status request

PHP HTTP Add a Status Request

$username = {your UserName from your API Keys};
$token = {APIToken value from Token Response Message};
$caseId ={CaseId from the Case Response Message};

$request = json_encode(ADD STATUS REQUEST)
$url = "https://app.trustev.com/api/v2.0/case/" . $caseId . "/status";
$contentType = "Content-type: application/json";
$auth = "X-Authorization:" . $username . " " . $token;
$curl = curl_init($url);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => $request,
CURLOPT_HTTPHEADER => [
$contentType,
$auth,
]
]);

$exec = curl_exec($curl);
$result = json_decode($exec, true);
curl_close($curl);


Option 2: Providing a CSV file through our sFTP service

Digital Verification provides a means for Merchants to batch update the Case Statuses of their Cases (orders) to ensure a feedback loop is maintained between your Site and Digital Verification analysis

The process involves 3 steps:

 

  1. Merchant prepares a Status Update CSV file in a standard format
  2. Merchant uploads the Status Update CSV file to a location on our server via sFTP
  3. Digital Verification imports the Status Update CSV file and updates the records for the Cases in the Digital Verification system
Getting Started

Please contact our Integration Team, they will provide the information you need to set up a connection with this service.

The following information should be provided to the Integration Team:

 

  • Merchant Name
  • Public IPs that will be accessing our sFTP service
  • Frequency that we expect to receive Status updates

In return, we will provide:

 

  • The sFTP host details
  • Your sFTP UserName and Password

Once you have received a UserName and Password to allow connection to the folder on the sFTP server, you can begin to upload files to the server. 

 

  1. Merchant prepares a Status Update CSV file in a standard format

All files should be in CSV format.

File Size should be limited to 2000 rows per file

Naming Convention

Please ensure when you upload your file, the name of the file take the format of:

[username].[timestamp].csv

where [username] is your API username, [timestamp] is the date and time the file was generated in the format of yyyyMMddThhmmss. You can use your Test API Username during Testing, but will need to update to your Live API Username once Integration is complete.

Content

Please ensure that your file contains comma-delimited values as defined below. Each entry for a Status update should be on a separate line and should follow the format as set out below. Headers do not need to be included in the file, and we will simply skip this line if provided.

CaseId,Status,Comment,Timestamp

Status codes can be found above, under the Status Overview section

Sample

 

  • 1bf86563-75f1-a78d-8f2b-5d03bb3bc804|d8d381d0-7d58-4411-4014-a236785f921c,0,Automated Update,2015-01-24T14:27:39.185Z
  • 1bf86563-75f1-a78d-8f2b-5d03bb3bc804|d8d381d0-7d58-4411-4014-a236785f921c,1,Automated Update,2015-01-24T14:29:14.852Z
  • 1bf86563-75f1-a78d-8f2b-5d03bb3bc804|d8d381d0-7d58-4411-4014-a236785f921c,2,Automated Update,2015-01-24T14:35:58.371Z

Please note: The Timestamp column (UTC) in the CSV file should be the Timestamp of when that Order Status was changed. The CSV file will be executed line-by-line, however providing an accurate timestamp ensures that only the most recent Status is considered in our system logic.

 

  1. Merchant uploads the Status Update CSV file to a location on our server via sFTP

There will be two folders in your sFTP account once you have connected:

 

  • Incoming
    • This folder is where the Status Update CSV file should be uploaded to.
  • Outgoing
    • This folder is where the completed CSV file will be stored
  1. Digital Verification imports the Status update CSV file and updates the records for the Cases in the Digital Verification system

This service will process the 'Incoming' folder daily, and update the Statuses in the Digital Verification System. After processing is complete, the file will be moved to the 'Outgoing' folder.

We will include a 'Status Code' column in the Outgoing CSV file indicating the success/failure of the Status update. It is important that you review to ensure we have successfully updated your orders. Success will be marked with a 200 OK, and failed updates marked with a 500. 

 

Option 3: Updating the order Status through the Manual Review Screen

Overview

The following document is aimed at walking developers through the Manual Review Screen available on the Digital Verification Console https://console-eu.trustev.com (For EU Customers) or https://console-us.trustev.com (For US Customers). This is our online portal that Merchants can access to review orders. The Digital Verification Console is where you will see the Transactions processed by Digital Verification. During the Integration phase the Manual Review Screen can be used to validate that Requests have been received, that Statuses are being updated and the Transaction data is being correctly processed etc. To note: Only Decisioned Cases will appear on the Manual Review Screen.

The workflow will typically be as follows:
  • A transaction is submitted on the Merchants web site.
  • The Developer or Merchant will:
    • Log into the Digital Verification Console.
    • Use the Search functionality to locate the Transaction using the Merchant’s Case Number.
    • Click on the Search results listing for the Transaction to display the detailed results on the Manual Review screen.

This is discussed in detail below.

Log In to the DIGITAL vERIFICATION cONSOLE.

The first step is to log in to the Digital Verification Console. This is available here -  https://console-eu.trustev.com (For EU Customers) or https://console-us.trustev.com (For US Customers). You will be presented with the following screen:

ConsoleLogIn.png
 

The credentials you will need are as follows:

  1. Username: This will be the email you provided to the Integration Team during the initial setup phase.

  2. Password: A password e-mail will be sent to you where you will be promted to enter a password of your choosing.

If you do not have any of these credentials, please contact our Support Portal.

Using the Digital Verification Console Search Features


There are a number of features available on the Digital Verification Console to help you review transactions and analyse fraud issues.


Transactions Overview Screen

The first screen that you will be presented with is the Home Page. By clicking the search icon, it will bring you to the Search Transactions Screen. 

DV.png

Below is the Transaction Review Screen:

ScreenReview.png

  

On the Transaction Review Screen there are a number of functions available:

  1. Filter transaction by date: this allows you to give a time range in which to review transactions.

  2. Search for a specific Transaction by Case Number: this allows you to search by specific Case Number, to review the details of a single Transaction. It is also possible to do partial searches, by using an asterisk (*).

  3. Filter transaction by the Digital Verification Decision and/or the Status of a transaction.
  4. Search for transactions with a specific E-mail address that was used.
  5. Filter the transaction by Transaction Value.
  6. View Transactions: Here you will see the details of the transactions. Unless specified by a filter implied, you will see the last placed transactions in chronological order, from newest to oldest.

     

    SearchT.png

    You will be presented with:

    1. The date and time of the transaction.

    2. The Case Number.

    3. The current Status of that transaction.

    4. The Currency.

    5. The Value of that transaction.

    6. The Decision that Digital Verification returned, on whether this was a fraudulent transaction or not.

    7. The Customers first name, last name and e-mail.

 

Understanding the Manual Review Screen 

From the Transaction Overview Screen above, you can click through to manually review each  transaction. Depending on the result of each transaction (i.e. “good” transaction or “failed” transaction) you will be presented with a screen that breaks down all the details of the transactions into the following groups:

Decision Summary:

Decision-1.png

The Decision Summary shows what the decision was on this particular transaction. It is colour coded in relation to the Decision; green being the best, red being the worst. The higher your score, the the greater the evidence of fraud in the transaction. In the example above, we can see that this was a fraudulent transaction. 

This colour coded decision and number reflects the thresholds configured by our Fraud Team, to reflect your site’s fraud needs. That’s to say, each customer will get a personalized configuration of what score is a pass, fail, or flag. Please see “What is a Digital Verification Score?” for a deeper explanation. 

This transaction has hit a score of 1500 and is therefore fraud. We can also see that Digital Verification confidence in this score is 100%. See “What is the Digital Verification Confidence Score?” for more information on this. 

It is necessary to note that when Test Keys are used the Decisions are randomized. For example, they request through the API a Decision for order 123, and receive a Pass. If they went into the Order Review Screen, they might see a Fail for this order. Live API Keys are needed for accurate Decisions, therefore during Integrations you should not be taking these Decisions as accurate.

Fact Summary:
 
Fact.png

The Fact Summary breaks down the decision, into what “facts” were hit with this transaction. Again, these facts are colour coded, with red being the heaviest weightings and highest in terms of fraud, and green being the lowest.

In the example above, we see “Email is a disposable Email address” and “Device Blacklisted” in red. This means that they are regarded as serious indications of fraud. In comparison, “BIN country not does not match Merchant Location” although still adding to the score, is not regarded as serious.

The Fact Summary allows you to review on a per transaction basis, to get a comprehensive overview of what factors made this transaction pass or fail, and why. The facts shown above are just an example for demo purposes. The Fraud Team will work closely with you during the Calibration Phase, to learn more about your fraud problems, and which of these facts should weigh heavier than others.

Transaction and Case Details: 

 CaseD1.png

In the above screen, we can see the Case details. This is all of the data that is passed through your Case Request during the API call “Add Case”. Essentially, these are the details inputted by the customer of your website when they checkout. We see their name, email, phone number, address and address type (e.g. Billing/Delivery) , etc. We can also see some additional details identified by Digital Verification, like IP Location, and some of the card details (note: these are not PII, the BIN just allows us to tell the country of issue). We can also see the breakdown of what this customer ordered. In certain cases this can be an identifier of fraud if the Total Value is significantly higher than the average. Under "Transaction Information" we also see information on the velocity, completed transactions and rejected transactions.

 

 

Overall Transaction History:

Transaction.png

Here we can see the history of transactions that have been processed from the same device and/or email address. Above we can see that although there is different email addresses being used in different cities, they are coming from the same device. This function can be used to pick up on any devices or emails that need to be blacklisted. Further, it can help to eliminate the likelihood of Digital Verification failing a good customer, as it is possible to whitelist also. this also gives you visibility into how many overall transaction this customer made and how many are Completed/Rejected or Pending.

Update Status:

 

StatusUpdate-1.png

As mentioned in the documentation, it is necessary to update the status of each transaction. Ideally this should be done with your company's manual review system, which can be synced to Digital Verification. However if needed, we provide this functionality also. As explained in the documentation, transactions are automatically given the status of Placed when the Case is added (i.e. transaction is processed). Once Digital Verification has returned a decision, you will need to update the system on the outcome of this, by updating the status of the order from Completed to one of the options below:

status-1

Digital Verification provides a mechanism to ensure that the Order data in a Merchant’s system can stay synchronised with the Order data stored in Digital Verification system.

This is implemented via a webhook which is used to send back an Order Status update to the Merchant’s Site as Status changes take place in other parts of the system. You can view the documentation around this here.

  

Any issues during your use of the Manual Review screen can be directed to our Support Portal.

 

Webhook

Digital Verification provide a mechanism to ensure that the Order data in a Merchant’s system can stay synchronised with the Order data stored in Digital Verification system.

This is implemented via a webhook which is used to send back an Order Status update to the Merchant’s Site as Status changes take place in other parts of the system.

For example, in your Order Review Screen on the Digital Verification Console - https://console-eu.trustev.com (For EU Customers) or in https://console-us.trustev.com (For US Customers), you will see the option to update the Status of an order.

StatusUpdate.png

On Submit, the Digital Verification system sends back a JSON object to a specified endpoint. This allows the Merchant to have both the Digital Verification system and their own internal order processing system up-to-date.

This is an optional feature, however in order to complete integration, we require that a Merchant provides us with an endpoint on their system that can receive a JSON object.

This JSON object: 

{
"Status": 0,
"Comment": "Wenhook comment",
"SessionId": "edffc5f6-2bf8-411c-974e-04ff24968a4d",
"CaseId": "edffc5f6-2bf8-411c-974e-04ff24968a4d|9288c4b2-5f66-4664-84d6-efd70b9f9d4c",
CaseNumber": "96f9868d-5ff5-4a5c-becc-1ca030d3422b"
}
The above JSON Object includes:
  • CaseNumber: This is the CaseNumber field that was supplied in your Add Case request. We recommend during Integration that you use your internal order number for this to allow for uniformity across Digital Verification systems and your own.

  • CaseId: This is the ID field that was returned from the Digital Verification API during the POST Case request. This ID field is used with Decision and Status endpoint on the API.

  • Comment : This field will reflect the comment enetered while updating the Status.
  • SessionId: This is the ID field that was supplied in your Add Case Request. This field should have retrieved from the browser by loading the JavaScript.
  • Status: This is the Status code that was assigned. These are the possible Status codes that you can receive: 

 0 - Completed 6 - ChargebackOther
 1 - RejectedFraud 7 - Refunded
 2 - RejectedAuthFailure 8 -  Placed
 3 - RejectedSuspicious 9 - OnHoldReview
 4 - Canceled   12 - ReportedFraud
 5 - ChargebackFraud  

 

Please note: The Digital Verification webhook will send a Status update to the endpoint you provide when any Status updates occur. As such, if you update the Status directly through the Digital Verification API Status endpoint - POST api/v2.0/case/{caseId}/status - our API will also POST back what the Status change was. 

Communication between Merchant and Digital Verification API with webhook:

2-1

 

Communication between Merchant and Digital Verification Order Review Screen with webhook:3-1

 

Mobile Application Integration

 

Digital Verification provides support for native iOS and Android Mobile Apps.

The overall integration process is the very similar to the process described above. There is one key area of difference: Mobile Apps do not use the Javascript Integration. Instead they use Digital Verification provided Mobile App integration libraries to gather information about the physical device on which the App is running.

 The section on ‘API Integration’ applies equally well to Mobile App and Browser based integrations. All API endpoints described in the API Integration section can be used for Mobile Apps.

 

Mobile App Integration Library Availablity

Digital Verification provides Mobile App integration libraries for both iOS and Android. To get a copy of these Mobile App Integration Libraries contact the Digital Verification Integration team. We limit access to these Mobile App Integration Libraries for security reasons and access is provided to approved Merchants only.

Note that sample applications are also available from the Digital Verification Integration team.

 

 

A Note on Mobile App Security

Mobile Apps are inherently less secure than Browser based applications as the source code for these Mobile Apps resides on the Mobile device and is more vulnerable to hacking and reverse engineering.

 For this reason, sensitive information such as usernames, passwords and secret keys should not be included in the Mobile App source code or configuration files. Merchants must keep such information in their own APIs with which the Mobile App communicates.

 Also note that login/authentication on Mobile Apps is the responsibility of the Merchants Mobile App. It is assumed that the Merchant ensures that users of their Mobile App are appropriately authenticated.

 

Responsibilities of the Mobile App Integration libraries

The Mobile App Integration Libraries are responsible for the following:

 

  • Gathering information about the physical device and passing this information to the Digital Verification system.
  • Generating a Digital Verification SessionID and making this accessible to the Mobile App.
  • Passing information from the AddDetail method to the Digital Verification system.
  • Generating and managing Mobile Device Identification information.

Merchant implemented Mobile App Integration requirements

  • The Merchants Mobile App must be implemented on iOS or Android.
  • The Merchant App must implement an authorization/login mechanism for the Mobile Apps if appropriate.
  • The Merchant App must provide an API with which the Mobile App communicates to process any of the Digital Verification API Endpoints described in the ‘API Integration’ section. As a minimum the Merchant must provide API endpoints to forward requests from the Mobile App to the following Digital Verification endpoints:
    • Case
    • Decision
    • Status
  • The Merchant App must pass the Merchants PublicKey to the Mobile App Integration library InitSessionMethod.
  • The Merchant App must retrieve and manage the Digital Verification SessionID which is returned by the Digital Verification Mobile App Integration library.
  • The Merchant App is responsible for managing Sessions on the Mobile App.
  • The Merchant App must make calls to the AddDetail Mobile App Integration Library method to pass information on each page of the Mobile App that the end-user accesses.

 

Merchant App / Merchant API / Digital Verification API interaction diagram

 The interaction diagram below shows the overall sequence of calls between the Merchant’s Mobile App, the Merchant’s API and the Digital Verification API.

 For details of each method see the Mobile App Integration Library documentation and the API Integration documentation.

  Mobile_App_SeqDiagram.png

 


 

 

 

Going Live

The fourth and final stage involves replacing your Test API Keys with Live API Keys, our Integration Team confirming Integration is complete, and moving you into the Calibration Phase.

08

Get Live API Keys

At this stage, our Integration Team will activate your Live API Keys. Live API Keys, which include your Site UserName, Site Password, Shared Secret, and Public Key, will need to replace your Test API Key information within your code. The Integration Team will provide these to you, in the same way they did with the Test API Keys. 

This involves replacing your Public Key in Step 2: Add Trustev.js, replacing the credentials used in Step 4 when Getting a Token, and also replacing the UserName section that is forwarded with your API Token in any of our API calls that require Authentication.

 

09

Integration Team confirm Integration completed

Although Live API Keys have been issued, the Integration is not considered complete until code is active on the production Site and all data is being received and populating as expected. During this time our Integration Team will work directly with the Developer to iron out any issues, and will issue out a confirmation mail once Integration is complete.

11

Update Terms & Conditions, and Privacy Policies

We ask that all Merchants ensure that their Terms & Conditions and/or Privacy Policies grant permission to use personal data for Fraud Prevention purposes and adhere to Data Protection requirements. If this is not the case Terms & Conditions should be updated by your Compliance or Legal teams

12

calibration Phase

Once all above steps have been completed, you will have entered the Calibration Phase and you will be handed over to our Fraud Team. Our Fraud Team will monitor the Digital Verification Decisions returned to you for your Live Transactions (Digital Verification Cases), and ensure that the expected results are being given based off all the data fields forwarded. Should you require assistance at any stage in this section, please contact our Support Portal.

Resources

API Libraries

Please find below a link to our API Libraries, available on GitHub.

C# Library

https://github.com/Trustev/netclientapi

PHP Library

https://github.com/Trustev/phpclientapi

Java Library

https://github.com/Trustev/javaclientapi

 

For any queries, please contact our Integration Team.

 

Testing Guide

Our Testing Guide allows developers to simulate expected outcomes by adding the words “pass”, “flag” or “fail” to the Case Number that is supplied in Step 5: Adding a Case.

You will be returned the corresponding result when you make a call in Step 6: Get A Digital Verification Decision. Please note, that it is case sensitive, so you must ensure that these are lower case. If you do not wish to use this option, then the Digital Verification Decision returned will be randomly generated.

 FAQs

Please see our detailed Digital Verification FAQs, at http://www.trustev.com/developers/developers-faq.html

Glossary

API Token An API Token is an alphanumeric GUID that is returned from the Digital Verification API when a successful request has been made to Get a Token. An API Token must be used anywhere Authentication is required. This is accessible in Step 4: Get a Token of the Digital Verification API.
API Keys API Keys are used in the authentication of the communication wth the Digital Verification API. Each Merchant Site has its own set of API Keys. Sites are configured for a specific set of API Keys. API Keys are provided to you by the Digital Verification Integration Team.
BIN Number The first 6 digits of the credit or debit card used for payment.
Case A Case is made up of Transaction Information, Customer Information, Payment Information, and Status Information. Please see What's a Case? for more information.
CaseId The Case ID uniquely identifies a Digital Verification Case. It is returned from the Digital Verification API through the response header in Step 5: Add a Case. This Case Id should be stored as it needs to be used in Step 6: Get a Digital Verification Decision and Step 7: Add a Status.
Case Number The Case Number can be any alphanumeric String. A Case Number is required in Step 5: Add A Case. You may choose what the Case Number is set to. This means, should you have a query on a Digital Verification Case at a later date then you will be able to access all the information on this Digital Verification Case by referencing this Case Number on the Digital Verification Console.
Live API Keys Live API Keys are access keys used on the live decisioning system in contrast to Test API Keys used during initial Integration.

Merchants obtain their Live API Keys from the Integration Team. Please see Test API Keys VS Live API Keys for more information. These are needed after the Integration steps 1 – 8 are complete and our Integration Team have confirmed that all data is being accurately received.

LongTermAccessToken This is the long term access token that is received from the relevant Social Network API. It allows access to a Merchant's customer data on a Social Account.
LongTermAccessTokenExpiry This is the long term token expiry datetime that is received from the relevant Social Network API. See LongTermAccessToken above.
Public Key This is your Site Public Key, which is part of your API Keys sent to you by the Integration Team. This is required when you Integrate Trustev.js to your website. There is a Test API Key version and a Live API Key version of your Site Public Key.
Session A Session is the container used to record all customer movements throughout the website, right up until purchase.
Server Responses The Digital Verification API uses REST. We use HTTP Response Codes to indicate any API Errors. See What does the Response Code mean? for more information.
ShortTermAccessToken This is the short term access token which is received from the relevant Social Network API.
ShortTemAccessTokenExpiry This is the short term token expiry datetime that is received from the relevant Social Network API.
Site Password Part of your API Keys is a password field. API Keys are provided by the Integration Team at sign up.This is your Site Password (NOTE: different from Digital Verification Console Password). It is used in Step 4: Get a Token. There is a Test API Keys version and a Live API Keys version of your Site Password.
Site Username This is your Site Username (NOTE: different from Digital Verification Console Username).This is part of your API Keys, which are provided by the Integration team. It is needed in Step 4: Get A Token, and also at any stage that Authentication is required. There is a Test API Keys version and a Live API Keys version of your Site Username.
Site Shared Secret This is your Site Shared Secret, available from the Digital Verification Console. It is used in Step 4: Get a Token. There is a Test API Keys version and a Live API Keys version of your Site Shared Secret.
Social Network Account Secret This is the Secret that is attached to your Social Network Developer's Account.
Social Network Id The Social Network ID, i.e. the Facebook Account ID.
Social Network Type Codes that represent the different Social Network Types, e.g. Facebook. See Social object for more information.
Test API Keys These are required in order to communicate with the Digital Verification API. They are provided during the sign up process by our Integration Team. These are required in order to communicate with the Digital Verification API.
Timestamp Current Timestamp in UTC. Accepted format: yyyy-MM-ddTHH:mm:ss.fffZ See http://www.trustev.com/developers-faq#what-format-is-accepted-for-the-timestamp for more information.
Trustev.js This is JavaScript code that you must insert into each page of your site. It works in the background to collect data on your customers.
TrustevV2.SessionId For every unique Session created by a user or a device, Trustev.js generates a TrustevV2.SessionId. This is required during communication with the Digital Verification API. TrustevV2.SessionId is a publicly accessible JavaScript variable.
Digital Verification Account A Digital Verification Account is an account on the Digital Verification Console. In order to begin Integration to Digital Verification, you will require a Digital Verification Account. This will be set up for you by our Integration Team. They can be contacted via Support Portal.
Digital Verification Confidence A Digital Verification Confidence score represents our confidence over a decision based on the level of details supplied within a Trustev Digital Verification. It has a range of zero to 100. Higher Confidence Score represents higher confidence.
Digital Verification Confidence Threshold A Confidence Threshold is the minimum value that you should Flag Digital Verification Decisions for. During Integration, we would advise setting a Confidence Threshold of 40.

This Confidence Threshold is subject to review during your Calibration Phase, and our Fraud Team may recommend lowering or raising this level as per the data that is received.
Digital Verification Digital Verification Console Digital Verification Consile is available at - https://console-eu.trustev.com (For EU Customers) or https://console-us.trustev.com (For US Customers). The Digital Verification Console includes access to the order review screen. 
Digital Verification Console Password In order to login to the Digital Verification Console, you will need to set a password. The Integration Team will send you a link to set this password at sign up. There is a 'Forgot Password' option at login to the Digital Verification Console if required. 
Digital Verification Console Username At log in to the Digital Verification Console this username refers to the email address given to the Integration at signup. 
Digital Verification Decision The Digital Verification Decision is based off all the data that has been gathered on a Digital Verification Case. A Digital Verification Decision will return 0 - Unknown, 1 - Pass, 2 - Flag, 3 - Fail.
Digital Verification Score A Digital Verification Score is generated based on the information supplied within a Digital Verification Case and will return a score ranging from zero to possibly thousands depending on the number of fraudulent features. The Digital Verification Score will determine the Digital Verification Decision. A Digital Verification Score between 0-225 will result in a Pass Decision (1). 225 -299 Flag (2) and 300 and above Fail (3).

cURL and SSL

If you are using PHP and communicating with our API through cURL then some issues may arise. The issues relates to cURL not being configured to trust the server's HTTPS certificate. By default, cURL is set up to not trust any CAs.

There are two ways to solve this problem:

1. Configure cURL to accept any server certificate. This isn’t optimal from a security point of view as it will cause cURL to blindly accept any server certificate, without any verification as to whether it is trusted or not.

2. Setting the CURLOPT_CAINFO parameter. This is used to point towards a CA certificate that cURL should trust. Firstly, get the CA certificate from https://app.trustev.com.

In Firefox, open up the security details for the site by double-clicking on the padlock icon in the lower right corner. Then click on 'View Certificate'. Bring up the 'Details' tab of the cert page and select the certificate at the top of the hierarchy. This is the CA Root Certificate. Then select 'Export', and save the CA Certificate to your selected location, making sure to select the X.509 Certificate (PEM) as the type.format.

Further information available here.

You can now include this certificate in your php.ini file or within each cURL option. See below: