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.
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.
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)
- For US customers, please use https://cdn-us.trustev.com/trustev.min.js
- For EU customers, please use https://cdn-eu.trustev.com/trustev.min.js
- 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.
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 Verification 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 Verification 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 Verification Decisions are made on Digital Verification Cases. That is, data is gathered in a Digital Verification Case and a Digital Verification Decision is generated based on that data. Use the “Add a Digital Verification Case” method to add data to a Digital Verification 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 Verification 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 VerificationDecision will use all information gathered through the Trustev.js along with all the information sent through the Digital Verification API. Once a Digital Verification 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 Verification Decision.
During debugging it might be helpful to view the Digital Verification Case that is being returned to you – if all data is being sent correctly to the Digital Verification API then you should receive the same Digital Verification Case and data back in the Response message.
Please note: our API will add an Id field to each object within the Digital Verification 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 Verification API should you wish to update this object’s information. Please see our FAQ on this for more information.
Once a Digital Verification Case has been added then you may request to get a Digital Verification Decision on the Digital Verification Case. A Digital Verification 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 Verification Case Id that was received from the Digital Verification API, when the Digital Verification 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 Verification Decision has been returned, then you must call the “Add a Status” method to update the status information for the Digital Verification 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 – 14, 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 Verification Case days or weeks after the Case has been processed. For instance, if Chargebacks are charged on the Digital Verification Case then the Status of the Case should be updated to reflect this.
Lastly, we suggest that when Integrating the Digital Verification API you allow for scenarios where, if the Digital VerificationAPI is unavailable, that your site should function ‘normally’ but without the Digital Verification features – this should allow for minimal impact to your customer’s experience should our services become unavailable for any reason.
Get a Token
To communicate with the Digital Verification API, you will require an API Token. An API Token is an alphanumeric String returned from the Digital Verification 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
{ "UserName": "sample_UserName", "Timestamp": "2015-11-17T16:48:19.001493Z", "PasswordHash": "sample_PasswordHash",UserNameHash": "sample_UserNameHash"}
Sample Get Token Response Message
{ "ExpireAt": "2015-11-17T16:48:19.001493Z", "APIToken": "dcfdcbba-a15e-4a5f-9388-d2db642b314f", "CredentialType": 1}
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);
Add a Case
This API method allows you to ‘Add a Case’. A Digital Verification 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 Verification 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 Verification Case through our IDVision Console.
During Integration, you will be using Test API Keys which means that the Digital Verification Decision you receive on a Digital Verification 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 Verification Case, you can influence the Digital Verification 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 Verification 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 Verification 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 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 Verification Case you have created.
Get a Digital Verification Decision
The Digital Verification 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 Verification Decision:
1. The standard Digital Verification Decision.
2. The Detailed Decision Endpoint
You should use either, but not both.
This API method allows you to retrieve a Digital Verification 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 VerificationDecision. During Integration, you will be using Test API Keys, and this will mean that the Digital Verification 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 Verification Decision is a decision formulated after utilizing all the data that has been gathered in compiling your Digital Verification 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 Verification Case has been added, and a request to get a Digital VerificationDecision has been made, our API will return a Digital Verification Decision. A Digital Verification Decision will indicate either: Pass, Flag or Fail.
Before retrieving a Digital Verification 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 Verification 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 Verification Decision.
Digital Verification 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 Verification 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 Verification Decision has not been made on your Digital Verification 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 Verification Case shows no signs for suspicion and the 'transaction' should be accepted. |
| 2 | Flag | This result indicates that the Digital Verification Case contains elements for suspicion which should be reviewed before a final decision is made. |
| 3 | Fail | This result indicates that the Digital Verification Case contains a number of fraudulent features and the 'transaction' should be rejected. |
Sample Get Digital Verification 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, "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.
For a more detailed breakdown of the decision returned, you can login to your Order Review Screen through the IDVision 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 Verification Decision on any particular Case.
Please note that during Integration you will be using Test API Keys, so the Digital Verification Decision 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 Verification Decision during this time.
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 and Score, 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 Verification Decision, or performing additional Customer Identification checks. The data returned can also be used to provide additional confidence that the Digital Verification 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 Verification 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 Verification 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,
"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 Verification Case. |
64 digits, combination of numeric and alphabetical |
|
DeviceTag |
Guid generated by Digital Verification to identify this device. |
32 digits, combination of numeric and alphabetical |
|
Digital Verification CustomerId |
Guid generated by Digital Verification 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 Verification 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 |
|
|
||
|
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 |
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 |
| 13 | AccountTakeover |
| 14 | AccountTakeoverChargeback |
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:
- Using the Status API Endpoint
- Providing a CSV file through our sFTP service
- 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
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:
- Merchant prepares a Status Update CSV file in a standard format
- Merchant uploads the Status Update CSV file to a location on our server via sFTP
- 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.
-
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.
-
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
-
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 IDVision 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 IDVision 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 IDVision 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 IDVision Console.
The first step is to log in to the IDVision 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:
The credentials you will need are as follows:
-
Username: This will be the email you provided to the Integration Team during the initial setup phase.
-
Password: A password e-mail will be sent to you where you will be promted to enter a password of your choosing.
Using the IDVision Console Search Features
There are a number of features available on the IDVision 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.
Below is the Transaction Review Screen:
On the Transaction Review Screen there are a number of functions available:
-
Filter transaction by date: this allows you to give a time range in which to review transactions.
-
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 (*).
- Filter transaction by the Digital Verification Decision and/or the Status of a transaction.
- Search for transactions with a specific E-mail address that was used.
- Filter the transaction by Transaction Value.
-
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.
You will be presented with:
-
The date and time of the transaction.
-
The Case Number.
-
The current Status of that transaction.
-
The Currency.
-
The Value of that transaction.
-
The Decision that Digital Verification returned, on whether this was a fraudulent transaction or not.
- 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:
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.
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:
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.
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:
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:
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:
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:
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 IDVision 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.
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 | 7 - Refunded |
| 1 - RejectedFraud | 8 - Placed |
| 2 - RejectedAuthFailure | 9 - OnHoldReview |
| 3 - RejectedSuspicious | 12 -ReportedFraud |
| 4 - Canceled | 13 - AccountTakeover |
| 5 - ChargebackFraud | 14 - AccountTakeoverChargeback |
| 6 - ChargebackOther |
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:
Communication between Merchant and Digital Verification Order Review Screen with webhook:
Knowlege Based Autentication
If as part of your solution you are using our Knowledge Based Authentication product, the following documentation explains the steps to be taken in order to use the KBA service. If you are not using the KBA product you can ignore all of this section.
- CaseId: This is the Id returned for a successful Add Case Request.
- Status : This field shows the Status of KBA
- AuthURL: This is the URL one should be using to generate and submit a passcode for that Customer.
- MultiPassStatus: Shows the Status of MultiPassQuestion (Essentially multi-pass means that a consumer could get one more question after the first initial exam)
- MultiPassQuestions: Questions to be displayed to a Customer if the MultiPassStatus = 1
Sample KBA Object in Detailed Decision Response
"KBA": {
"Timestamp": "2018-04-10T14:35:14.8831085Z",
"Status": 0,
"AnswerUrl": "https://app.trustev.com/api/v2.0/case/{apiCaseId}/kba",
"Questions": [
{
"Id": 0,
"QuestionText": "Question No 1",
"Choices": [
{
"Id": 0,
"Answer": false,
"ChoiceText": "1,000"
},
{
"Id": 1,
"Answer": false,
"ChoiceText": "10,000"
},
{
"Id": 2,
"Answer": false,
"ChoiceText": "100,000"
},
{
"Id": 3,
"Answer": false,
"ChoiceText": "None of the Above"
}
]
},
{
"Id": 1,
"QuestionText": "Question No 2",
"Choices": []
},
{
"Id": 2,
"QuestionText": "Question No 3",
"Choices": []
},
{
"Id": 3,
"QuestionText": "Question No 4",
"Choices": []
}
],
"MultiPassQuestions": [
{
"Id": 4,
"QuestionText": "MultipassQuestion",
"Choices": []
}
],"MultiPassStatus
POST KBA
The KBA object is returned via the Detailed Decision Response and has the list of KBA questions and MultiPass questionnaire if that needs to be used. Please follow the steps below:
- Display the KBA Questions and options in your webpage and allow the Customer to answer them.
- Send the KBA answers to TU by making a POST to the KBA end point.
- Call another Detailed Decision to see the updated score and Status of KBA
Http Method: POST
URL: {Use the AuthURL in KBAobject}
Http Headers:
Content-Type: Application/json
X-Authorization: Username APIToken
Sample Request body:
{
"Questions": [
{
"Choices": [
{
"Answer": false,
"ChoiceText": "30KG",
"Id": 0
},
{
"Answer": true,
"ChoiceText": "50KG",
"Id": 1
},
{
"Answer": false,
"ChoiceText": "34KG",
"Id": 2
},
{
"Answer": false,
"ChoiceText": "None of the Above",
"Id": 3
}
],
"Id": 4,
"QuestionText": "What is your weight?"
},
{
"Choices": [ ],
"Id": 6,
"QuestionText": "What is your eye colour?"
},
{
"Choices": [],
"Id": 2,
"QuestionText": "What is your mother's name?"
},
{
"Choices": [],
"Id": 3,
"QuestionText": "What was your first car?"
}
]
}
Available KBA Statuses
|
Status |
Value |
Description |
|
NotConfigured |
-1 |
KBA is not configured for the Client |
|
Offered |
0 |
KBA is offered |
|
MultiPassOffered |
1 |
MultiPass Question may be offered to the Customer |
|
Ineligible |
2 |
Case is not eligible for KBA |
|
NoData |
3 |
Not enough data to generate KBA questionnaire |
|
Passed |
4 |
KBA Passed |
|
Failed |
5 |
KBA Failed |
|
Abandoned |
6 |
KBA submission is not made within the time limit allowed |
If as part of your solution you are using our One Time Passcode product, the following documentation explains the steps to be taken in order to use the OTP service. If you are not using the OTP product you can ignore all of this section. "OTP": { "Timestamp": "0001-01-01T00:00:00Z", "Status": 0, "AuthURL": "https://app.trustev.com/api/v2.0/case/{apiCaseId}/authentication/otp", "Passcode": null, "DeliveryType": 0, "Language": 0 } Generate OTP This will generate a Passcode and send to the Customer Phone Number shared via Add Case. Http Method: POST URL: https://app.trustev.com/api/v2.0/case/{apiCaseId}/authentication/otp Http Headers: Content-Type: Application/json X-Authorization: Username APIToken Sample Request body: { "DeliveryType": 0, "Language": 0 } Submit OTP Client have to send the Passcode entered by Customer to TU for verification and result. Http Method: PUT URL: https://app.trustev.com/api/v2.0/case/{apiCaseId}/authentication/otp Http Headers: Content-Type: Application/json X-Authorization: Username APIToken Sample Request body: { "Passcode": 12345 } Available OTP Statuses Below given are the Statuses you can use to update the final status of a Transaction. Status Value Description Offered 0 OTP is offered Pass 1 OTP is passed Fail 2 OTP is failed Ineligible 3 Case not eligible for OTP InProgress 4 Passcode sent to the Customer PhoneNumber MaxRetryHit 5 Passcode resubmission limit has been hit. Abandoned 6 Passcode submission is not made within the time limit allowed NotConfigured 7 OTP is not configured for the Client If as part of your solution you are using our Verified Prefill Product, the following documentation explains the steps to be taken in order to use the Verified Prefill service. If you are not using this product you can ignore all of this section. Verified Prefill is a feature that allows a merchant to retrieve personal details about an end user using a minimum input from the consumer, and make these details available to prefill forms when users are registering with a merchant. In order to offer the personal details for a user we have to identify that user and verify that the user is who they claim to be. Sample Verified Pre Fill Add Case Request { "SessionId": "3e327029-f96f-4858-9038-91eb8626c2de", "CaseNumber": "29ef03c7-037d-4531-863e-c56a796e4f88", "CaseType": 4, "IdentityConsentId": "i consent to this v4.4", "Customer": { "PhoneNumber": "4045049006", "SocialSecurityNumber": "0006" } Description of each field SessionID: This is the SessionID used from the JS. CaseNumber: This is a unique case identifier CaseType: The type of case being added, Verified Prefill is CaseType 4. IdentityConsentID: A field for passing in the confirmed consent that the consumer agreed to. Customer: The details of the input phone number and SSN submitted by for the customer Sample Success Response for Verified Prefill in the Detailed Decision Response "AuthenticatedDataRequest": { "Details": { "Email": "ATESTA@transunion.com", "FirstName": "AARON", "MiddleName": "ANGUS", "LastName": "TESTA", "PhoneNumber": "4045049006", "SocialSecurityNumber": "666010001", "AddressCity": "ATLANTA", "AddressCountry": "us", "AddressZipCode": "30326", "AddressState": "GA", "AddressPoBox": null, "AddressStreetNumber": "100", "AddressStreetName": "ACORN", "AddressStreetPreDirectional": null, "AddressStreetPostDirectional": null, "AddressStreetUnit": "apartment 1", "AddressStreetType": "AVE", "DateOfBirth": "04/15/1972", "Prefix": "MAJ", "GenerationalSuffix": "SR", "SalutationalSuffix": "MD", "Maternal": "APELLIDO" }, "Status": 1, "StatusDescription": "Success" Status: This field shows the Status of Authentication Details Status Description: This is a description of the API call Available Verified Pre Fill Statuses Status Value Description Started 0 Verified Pre Fill has started Success 1 Verified Pre Fill was a success NoDetailsAvailable 2 No details available for Verified Pre Fill InvalidCase 3 The Case is invalid Ineligible 4 The Case is not eligible for Verified Pre Fill Error 5 An Error has occurred Misconfigured 6 The feature is misconfigured NoConsent 7 No Consent was given for Verified Pre Fill NoPhoneNumber 9 Invalid Phone Number InsufficientInformationAvailable 10 This will be returned when either a SSN or a DOB is not present on the add case request. Consent Text and Privacy Policy Consent text for your reference: “By clicking Accept [or a word that has a substantially similar meaning as “Accept”], you allow [Subscriber] and our service providers to access information on file with your mobile operator, specifically, name, address and email, to auto populate this form. See our Privacy Policy for how we treat your data.” This text needs to be in the Privacy Policy: You authorize your wireless operator to disclose your mobile number, name, address, email, network status, customer type, customer role, billing type, mobile device identifiers (IMSI and IMEI) and other subscriber details, if available, to [merchant name] and service providers for the duration of the business relationship, solely for identity verification and fraud avoidance. 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. 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. 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. The Mobile App Integration Libraries are responsible for the following: 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. 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.One Time Passcode
Sample OTP Object in the Detailed Decision Response
Verified-Prefill
Mobile Application Integration
Mobile App Integration Library Availablity
A Note on Mobile App Security
Responsibilities of the Mobile App Integration libraries
Merchant implemented Mobile App Integration requirements
Merchant App / Merchant API / Digital Verification API interaction diagram
Going Live
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.
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.
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
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/netclientapiPHP Library
https://github.com/Trustev/phpclientapiJava Library
https://github.com/Trustev/javaclientapi
For any queries, please contact our Integration Team.
Minimum requirements for the IDVision products
|
Fields |
Authentication |
Identity Verification |
Fraud Force Device - based Reputation |
Verified Prefill |
|
JavaScript |
|
|
X |
X |
|
Session ID |
X |
X |
X |
X |
|
Case Number |
X |
X |
X |
X |
|
Name |
X |
X |
X |
|
|
Address |
X |
X |
X |
|
|
|
|
|
X |
|
|
Phone Number with Country Code |
|
|
X |
X |
|
Transaction Details |
|
|
Required for Ecommerce |
|
|
SSN - Last 4 |
|
X |
|
X |
|
SSN - Last 4 padded with zeros |
X |
X |
|
|
|
SSN - Full 9 digits |
X |
X |
|
|
|
Consent Language |
|
|
|
X |
Testing Guide
To simulate responses of “pass”, “flag” or “fail” for testing purposes, please use one of the 3 email addresses below to trigger the required response. You will be returned the corresponding result when you make a call in Step 6: Get A Digital Verification Decision.
|
Required Response |
Email address to use |
|
“pass” |
|
|
“flag” |
|
|
“fail” |
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 IDVision 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 IDVision 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 IDVision 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 IDVision 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 IDVision 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 IDVision Console | IDVision Console 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. |
| IDVision 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. |
| IDVision 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.
CURLOPT_SSL_VERIFYPEER => false2. 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:
For PHP.ini File: curl.cainfo = '{absolute path to}/cacert.pem'For cURL option: CURLOPT_CAINFO => 'C:\...\cacert.pem'