FAQs

Setting Up

What is TransUnion Digital Verification?

TransUnion Digital Verification is “data fingerprinting” software. E-commerce companies use it to analyse their site visitors in real time, so when someone tries to buy online or sign up to an account or service, Digital Verification assess whether that person is real or a fraudster.

Digital Verification monitors activity on your site. When someone clicks to buy, the Digital Verification platform analyses over a thousand data points and instantly confirms whether the visitor is genuine or not. It blocks fraudsters but lets through real buyers — without costly manual reviews.

How does Digital Verification work?

How Can I Start Integrating?

Contact your Account Manager to arrange a call with our Integration Team. You will get an overview of how the System works, as well as getting an opportunity to ask any questions or queries you may have.

After this step, the Integration Team will set up your Account. For details on signing up to Digital Verification, please submit a request via Support Portal.

How many days does it take to Integrate?

This is completely dependent on the resources that you have available to commit to the Digital Verification Integration. That being said, this is a very lightweight process. You will have a dedicated point of contact from the Integration Team available to assist you through, and any queries can be sent to our Support Portal.

Can I Add Additional Users to my IDVision Console?

Only Merchant Admins can add additional users to the Digital Verification Console. If you are the Merchant Admin, please follow the below steps to add a user:

Go to IDVision Console. Web links for EU is here. Web link for US is here.

Login with your email address and password.

SelectManage Usersfrom the Setting option in the Left Navigation bar.

SelectAdd userbutton at the right top side.

Enter User details.

User Type as Merchant Fraud Analyst - Please ensure to have your website in the right box that they need visibility.

Click on button "Create User". This will send an automatic password reset email to the newly created users.

If you are still facing any issue to add a user, justsubmit a request to ourIntegration Team via Support Portaland they will set this up for you.

What is the IDVision Console?

The IDVision Console is our online portal that Merchants can access to review Transactions.

API Keys: Explained

To use Digital Verifications service, you will need a set of API Keys. During the Integration phase, you will be using Test Keys, before your site goes live. These will be given to you in your set-up email, as explained in "How Can I Start Integrating?".

In here you should see the following:

Username: This is your site Username. This Username is used to get an API Token and also needed where Authentication is required.

Password: This is your site Password. This is used during Step 4: Get a Token API request.

Shared Secret: This is your site Shared Secret. This is used during the ‘Get a Token’ API request.

Public Key: This is needed when you integrate our Trustev.js to your website.

How do I Login to the Digital Verification Console?

Here you will be asked to enter yourDigital Verification Console E-mail and Password.

Once you have logged in, you will be presented with the Transaction Manual Review Screen. This is where you will see all your Transaction details, for example, what the Digital Verification Decision was, what factors were used in this Decision, and have the option to update the Status or any Transaction.

JavaScript Integration

What is Trustev.js?

Trustev.js is our JavaScript code that is used to track your customers' behaviour as they move throughout your site. This JavaScript file is responsible for gathering numerous pieces of information from your user, such as:

Browser details

Plug-in details

Velocity details

IP details

OS details

Integrating Trustev.js onto your page is a quick process. It involves inserting 4 lines of code onto each page on your site, and we will handle the rest.

Will Trustev.js cause my website pages to load more slowly?

Here at Digital Verification we have put a huge amount of effort into reducing the load time of Trustev.js to an absolute minimum because we understand the effect that slow load times can have on a customer. We have designed our JavaScript to be loaded asynchronously meaning that your page will not be waiting for our JavaScript to load.

On top of this we have managed to reduce the load times to an average of 150-200 milliseconds meaning that even if your page did have to wait, it wouldn’t be waiting long enough for your customers to notice.

How to know if the Trustev.js is implemented correctly & how to access the TrustevV2.SessionId?

The Trustev.js should be implemented in the head section or at the end of the body section within your page. The Trustev.js involves inserting 4 lines of JavaScript code onto as many pages of your site as possible - as it will track your customer's behaviour as they move throughout your site.

The Trustev.js needs to be hosted and launched in order to generate the TrustevV2.SessionId. Therefore, during testing, you cannot use a simple HTML file, but will need to host it, for example with XAMPP or WAMP.

Once set up you can use the following developer tools included in your browser to test if it is implemented correctly:

Hit F12 while using Google Chrome

Hit Ctrl+Shift+I while using Mozilla Firefox

Hit Command-Option-I while using Safari

Hit F12 while using Internet Explorer

Under the Network tab you should see your Public Key value in the URL, along with a 200 Response code:

If this is correct, then you should navigate to the Console window, also in the developer tools, and type in TrustevV2.SessionId, and press enter. This should print out your TrustevV2.SessionId, which is required when adding a Case. See below:

The variable TrustevV2.SessionId is a publicly accessible variable. As the TrustevV2.SessionId variable is generated within the client-side JavaScript code, you will need to pass this variable to your Server side code. This is up to the developer personally, on what method you prefer. Some options include passing it as a hidden field, with the click of a button, or by using cookies.

Is there another way other than JavaScript to get the session?

It is possible to use jQuery getScript functon to initialize the 3trustev_sess_id with the value returned in TrustevV2.SessionId. The script block is dependent on jQuery fully loading on your page before it is executed, so you must ensure that this is considered first. The same script block can be used on any page, anywhere that you need to initialize a variable with the TrustevV2.SessionId, but you will need to change #trustev_sess_id to the appropriate variable name for the page. The $.getScript is a jQuery function that will wait until the Trustev.js is fully loaded before requesting the sessionId. For more information, please see here: http://api.jquery.com/jquery.getscript/

API Integration

What is an API Token and how do I access it?

The Digital Verification API is secured using Token Authentication. This means that when you wish to communicate with our API, an API Token is required so we can verify that the information is coming from the correct source. An API Token is a unique alphanumeric string that Digital Verification will generate and return to you through our API, after a Get Token request has been made with a correctly formed request message. This request message is made up of information from your Test or Live API Keys.

Example:

X-Authorization: TrustevTest 4b312a24-2495-4ba4-8f85-d891bab1cac8

In the above example, it shows the site Username (TrustevTest), followed by a space, followed by the API Token (4b312a24-2495-4ba4-8f85-d891bab1cac8).

Every call to our API, other than the Get Token request, requires that an API Token is forwarded in the request header, along with your site Username.

In order to access an API Token, you will need your API Key information which will have been emailed to you by the Integration Team. You will need to proceed to Step 4: Get a Token to access one. Once you have successfully created a request to our API, you should receive an API Token which will be available in the response body, under the parameter ‘APIToken’.

Included in the response when you receive the APIToken is a parameter ‘ExpireAt’ which you may extract and use as a check to ensure you receive no errors due to expired tokens. ‘ExpireAt’ will be a timestamp in UTC.

We advise that you store this APIToken for re-use for 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.

Explained: GET Token Response Message:

The ExpireAt field indicates in UTC when the API Token will expire. This can be used as a check to indicate when the Token will expire and avoid receiving errors from our API.

The APIToken should be extracted and placed in the header along with your Username for all subsequent API calls.

The CredentialType field is not needed, and only indicates whether you are using Test or Live API Keys.

Please note:

You can use an API Token for multiple orders/requests, while it is valid. Some developers have implemented Digital Verification by setting a timer to request a Token every 30 minutes. This is an option if convenient for your site set up and will reduce calls to the Digital Verification API.

What format is accepted for the Timestamp?

When communicating with our API, Timestamps are required when Getting a Token and Adding a Digital Verification Case.

The Timestamp is the current timestamp in UTC in the format yyyy-MM-ddTHH:mm:ss.fffZ.

yyyy: The year as a four digit number.

MM: The month from 01 through 12.

dd: The day of the month from 01 through 31.

T: Indicates the beginning of the time element

HH: The hour using a 24 hour clock from 00 to 23.

mm: The minute from 00 through 59.

ss: The second from 00 through 59.

fff: The milliseconds to three places

Z: Denotes that the Timestamp is in UTC.

Example Accepted Timestamp format: 2014-12-11T16:50:21.157Z

What’s a Digital Verification Case?

A Digital Verification Case is a term used by Digital Verification to refer to all the unique data inputs gathered on each ‘transaction’ prior to making a Digital Verification Decision. A Digital Verification Case is made up of transaction information, customer information, payment information, and status information.

The Transaction Information includes the total transnsaction value,currency, delivery & billing details, item information such as the names of the items purchased, quantity and value.

The Customer Information includes details like First and Last name of the customer, their address details, phone number, date of birth, and email address entered.

The Payment Information includes forwarding the payment type (none, credit card, debit card,direct debit, PayPal, Bitcoin), and the BIN of the relevant card should it be available. The BIN (Bank Identification Number) is just the first 6 digits of the credit or debit card used for payment.

The Status Information includes the order status and comment section. Digital Verification requires that a Status is attached to a Digital Verification Case so that we can learn from the decision that you make on a Digital Verification Case. Initially when creating the Digital Verification Case you may assign a status of 'Placed' (8), then, once you have received a Digital Verification Decision, you will have to update this Status to reflect your decision on the Digital Verification Case. Please see Why send statuses? for further information.

Along with all the above mentioned data fields that can be included when creating a Digital Verification Case, a Digital Verification Case will also include all data gathered on a customer through our Trustev.js and consider this full data set when making a Digital Verification Decision.

Once a Digital Verification Case has been added then a Merchant may request a Digital Verification Decision. Our system is designed to allow a Merchant to add some transaction information or all known transaction information and get a Digital Verification Decision on this. Therefore, a Merchant may add a Digital Verification Case and get a Digital Verification Decision before payment gateways are accessed or after, Merchants may use Digital Verification on first time customer registrations, or it can be used once ‘Check-Out’ is selected. The Digital Verification Decision is flexible enough to allow for a fraud assessment on any available data at any point within your site. Please note, Digital Verification charges per transaction. Every time a Digital Verification Decision is made, our system will consider this a complete transaction.

What elements in the Case are single occurrences or collections?

There are a number of elements in the Add Case requests that are a collection of values rather than a single occurrence.

How do I update/ change the Case information OR add new information to the Case?

It is very important not to re-use a Case Number, as this is a unique identifier and will trigger a 400 error. If you are updating a Case then use a PUT as described below.

Should you wish to change the data previously added in a Case, you can use a PUT on the relevant endpoints. A PUT will overwrite the previous data that was entered, so you will need all the information from before, along with your changes.

Note: To do a PUT you must be storing the caseID and the relevant object Id (see below).

Example: You have added a Digital Verification Case successfully with customer details, such as first name, last name, and email information. Customer realises that they gave an incorrect email address and you wish to update the Case now. You will need to use a PUT on the endpoint, api/v2.0/case/{caseId}/customer, and provide the first name & last name again, along with the new email address, replacing the {caseID} parameter with your Case ID.

Therefore, any time you wish to change/ update the Case information with new details you should use the PUT method with the following endpoints; replacing the {caseID} with the Case ID, and replacing the {ID} parameter with the relevant ID returned for that object:

*There is no PUT method available for a Status, as it is a collection of Statuses. Simply POST a new Status anytime there are changes to the status of the order.

** In the case of updating a payment, if the payment failed for auth reasons, and the customer can go back and change their card details, it is best to update us on the statues of that transaction as RejectedAuthFailure, and when they re-submit their card details, open a new Case. This allows for better visilibility of all cases failed for auth reasons.

What if the Payment Type doesn't match any listed by Digital Verification?

If the payment doesn't match any listed by Digital Verification, you can mark the payment method as None(0) so it will still indicate that a payment took place, and our Fraud Team will be able to understant what is happening.

What is a BIN?

A BIN (Bank Identification Number) is the first 6 digits of a credit/ debit card number. We use the BIN to simply get the location where the card was issued. We cannot access any other information about the customer through the BIN. A BIN can also be referred to as an IIN (Issuer Identification Number).

What does the Response Code mean?

The HTTP Response Codes are used to quickly describe the success/ failure of a HTTP request. Digital Verification use the standard HTTP Response Code as shown below:

200 OK – Successful request made.

400 Bad Request – The request is malformed.

401 Not Authorised – Authentication information is either incorrect or missing.

403 Forbidden – Authenticated user does not have access to the resource.

404 Not Found – When a non-existent resource is requested.

405 Method Not Allowed – When an HTTP method is being requested that isn’t allowed for that endpoint.

408 Timeout – The request has timed-out.

500 Unknown – Indicates an Internal Server Error.

We also include some extra information in the HTTP Response Message. We always recommend checking this should you run into issues during Integration. Our Response Messages give a detailed description of the issue encountered, which should assist in debugging.

Should you find that the Response Codes OR Response Messages are not providing enough information, please contact our Integration Team and they will investigate the issue that you are experiencing.

Id: This is generated by the Digital Verification API. You do not need to extract or store this ID.

Version: This is an internal number - it is used for the configuration details for the Merchant. Again, there is no need to extract/ store this field as it is only used for internal reporting.

SessionID: The Session ID of the Case.

Timestamp: The current Timestamp in UTC.

Type: This is used only for internal reporting.

Result: Indicates whether our decision is to Pass (1), Flag (2) or Fail (3) this order. This should be extracted and used within your code.

Score: This value will vary from merchant to merchant and from order to order, and is based on configuration details, the data points provided, and a number of other details. You do not need to extract or consider this field, as it is directly represented in the Result.

Comment: This is for internal reports - there is no need to extract or store this.

When can I get/request a Digital Verification Decision?

Once a Digital Verification Case has been added then a Merchant may request a Digital Verification Decision. Our system is designed to allow a Merchant to add some transaction information, or all known transaction information, and get a Digital Verification Decision on this. Therefore, a Merchant may add a Case and get a Digital Verification Decision before payment gateways are accessed, or after, Merchants may use Digital Verification on first time customer registrations, or it can be used once ‘Check-Out’ is selected. The Digital VerificationDecision is flexible enough to allow for a fraud assessment on any available data at any point within your site.

Please note, Digital Verification charges per transaction. Every time a Digital Verification Decision is made, our system will consider this a complete transaction, unless Test API Keys are being used.

What is a 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. In the example below a Score between 0-225 will result in a Pass Decision (1). 225 -299 Flag (2) and 300 and above Fail (3). There is no traditional "maximum score"; the score can technically go up to the thousands, depending o how many fraud "facts" it hits. Please note, that these thresholds will vary depending on your configuration, but our Fraud Team will work with you to outline these.

The Digital Verification Score element is included as it can be helpful during manual review, using the Digital Verification Console, as it will indicate where on the scale it lay in terms of Pass/Flag/Fail. However as stated, the Result is a direct representation of the Score and is the most important field.

What does the Digital Verification Decision mean?

Once a Digital Verification Case has been added, Digital Verification will make a Digital Verification Decision based on the information supplied. We will then supply a Digital Verification Decision: Pass, Flag or Fail.

(1) Pass – Digital Verification Case shows no signs for suspicion and the ‘transaction’ should be accepted (2) Flag – Digital Verification Case contains elements for suspicion which should be reviewed before a final decision is made (3) Fail – Digital Verification Case contains a number of fraudulent features and the ‘transaction’ should be rejected.

Why send Statuses?

One of the most important sections of integrating to Digital Verification is to ensure that accurate Digital Verification Case Statuses are sent to us. Status updates allow our system to learn from the previous decisions to further enhance the score accuracy.

Our system learns off the decision you made regarding a Digital Verification Case, so these statuses must be accurate and kept up to date. We would not consider an Integration ready for a Live environment until a system is in a place to add Statuses to our API.

When you initially create a Digital Verification Case through our ‘Add a Case’ method, you may include an initial status here, like ‘Placed’, which is an OrderStatus of 8. Once you have received a Digital Verification Decision on the Digital Verification Case through our Step 6: Get a Digital Verification Decision method, you must now make a call to Add a Status to this, so that you can update us on what happened. For example, was this Digital Verification Case rejected due to card authentication issue? Was this Digital Verification Case completed as expected? Did this Digital Verification Case receive a Fail decision from Digital Verification and you are now rejecting it? These scenarios, and more, need to be forwarded to us.

Status Type

Reason

Description

0

Completed

Order Completed

1

RejectedFraud

Order Rejected due to Fraud

2

RejectedAuthFailure

Order Rejected due to Card Authentication Failure

3

RejectedSuspicious

Order Rejected due to suspected Fraud

4

Cancelled

Order Cancelled

5

ChargebackFraud

Return of funds to customer due to Fraud

6

ChargebackOther

Return of funds to customer for other reasons

7

Refunded

Customer refunded

8

Placed

Order has been placed on system

9

OnHoldReview

Order is under review, no decision made yet.

12

ReportedFraud

If the Transaction is deemed fraudulent after the Transaction was fulfilled, then the Transaction Status should be set to ReportedFraud

13

AccountTakeover

If a transaction takes place on an account while the customer’s account has been compromised.

14

AccountTakeoverChargeback

If a chargeback is received from a transaction which took place on a customer’s account while compromised.

Please see below some sample scenarios outlining when to use each Status:

(0) Completed - Merchant is happy that the order can be completed & no fraudulent behaviour noted.

(1) RejectedFraud - Merchant has seen this customer before and is certain that it is Fraud OR due to the Digital Verification Decision returned, the Merchant rejects the customer due to Fraud.

(2) RejectedAuthFailure - Order is rejected due to Card Authentication issues or insufficient funds.

(3) RejectedSuspicious - Merchant is suspicious of the customer and feels it may be potentially fraudulent. Merchant does not want to mark it as definite fraud, but is rejecting the order for the moment.

(4) Cancelled - Order is added, however customer decides that they do not wish to proceed, and wants the order cancelled.

(5) ChargebackFraud - Merchant has been issued with a Chargeback notice due to Fraud.

(6) ChargebackOther - Merchant has been issued with a Chargeback notice due to goods not being delivered or being charged twice on their account for the same item.

(7) Refunded - Merchant refunds a customer due to an issue that is not fraud related.

(8) Placed - Customer has created an order but it is still in progress -- Please note, that all orders added to the Digital Verification API will be automatically set to a status of Placed initially.

(9) OnHoldReview - Order is under review & no decision has yet been made.

(12) ReportedFraud - If the Transaction is deemed fraudulent after the Transaction was fulfilled, then the Transaction Status should be set to ReportedFraud

(13) AccountTakeover - Customer account has been confirmed as compromised and unauthorized access confirmed. Subsequent transaction did not originate from genuine customer.

(14) AccountTakeoverChargeback- Customer's account has been confirmed as compromised and the related transaction has been confirmed as a Chargeback.

Please note: If, and when a Chargeback is received on a Digital Verification Case, a Status must be forwarded to Digital Verification to reflect that this has occurred. Due to this fact, we ask that Merchants have in place a system to facilitate the forwarding of Chargeback statuses through our API, using Order Status 5 or 6. For any questions regarding Statuses please contact Support Portal.

What is the difference between Completed and Placed?

Placed is a temporary status applied at Step 05: Add a Case. It means that the transaction has been placed, but the Digital Verification Decision has not yet been made, thus it stays as Placed for now. Once you "Update a Status", you can reflect the outcome of this transaction. If it has been passed as non-fraudulent and the transaction has gone through, you can update it as Completed (or choose any of the other statuses).

What are the accepted Country Codes?

During the 'Add a Case' section of the Integration process, you will need to forward delivery/billing information to the API. Part of this includes forwarding the Country Code.

What are the codes for the Currency Types?

During the Add a Case section of the Integration process, you will need to forward the Currency type code in the Transaction details. The Currency Codes we use are ISO 4217. This code list is used in banking and business globally.

Do you have a WDSL service definition?

The Digital Verification API is implemented as a .NET WebApi project, therefore while it is REST-based, there is no WDSL service definition. As a result, you will not be able to use SOAP to consume a WDSL definition – SOAP is not supported by default.

If you follow REST-ful principles and follow the lightweight method calls documented in our detailed Technical documentation – https://app.trustev.com/help. All of the endpoints, methods and method signatures for our API are available there.

Is there a way to verify if the API calls are working as expected?

The Integration Team have access to monitor the API activity. If it is a general enquiry, then contact our Support Portal. If it is a question about a specific order number, transaction, session, etc. then the relative identifying number or Id number should be included.

Going Live

I've Finished Implementing the Code, Now What?

Once you have completed our Integration process, and our Integration Team have confirmed that all the data is being received correctly, then the Integration Team will have an official handover phone call with the Merchant, to introduce them to the Fraud Team point of contact. This will help as to assess your Fraud requirements, and also gather some blacklist and whitelist information that you already have.

The Live Keys will be provided after the call. Once you switch into the Live Keys, the Integration Team will monitor the website for the next 24 hours in order to ensure that the date is coming as expected. Then you will be moved to the Calibration Phase. The steps involved in Calibration Phase are as follows:

DAY 1 - Calibration Commencement

1. We will schedule weekly Fraud Workshop calls with your fraud team to review accuracy, rates and decision quality and discuss findings to date. All dashboards and review screens will begin populating and we will walk through examples and provide end users with best practices.

DAY 1-14 : Listening Phase and fraud trend identification

2. Two-week listening period: during this period our fraud team will review your Digital Verification Decisions and build extensive profiles in the data to guarantee detection of fraud profiles within the decision logic. We will also conduct an extensive Decision Quality review to ensure continuous accuracy improvements and minimal false positive rates. At this stage we also can implement any business rules required.

DAY 14-30 : Fine Tuning and production preparation

3. The Final 2 weeks is a fine tuning stage where we implement changes based on trends, false positives and negatives to ensure that the logic is in line with any business rules and fraud trends identified. At this stage we will begin preparing all black/gray/white lists from historical data and build customer histories.

DAY 30 - Calibration complete - Digital Verification is now LIVE

4. Once these final configurations are complete and you are satisfied with the design logic in place, we will provide a summary of calibration report in order to given you an insight into the logic, highlight scenarios, fraud identified and the benefits. We will set up a call to discuss the some of the finding and confirm next steps. Once our decision is begin used in production you will have round the clock support and have a dedicate Fraud Specialist who will be monitoring your data daily for trends, spikes in activity and ensuring the highest level of Decision Quality.

Note: We advise, that during Calibration Phase, you do not base your decisions solely off the Digital Verification Decision returned. Although in most cases the Digital Verification Decisions returned will be accurate, every Merchant will have a different Fraud problem which our Fraud Team has to gather details on and ensure that going forward our system is fitted exactly to suit yours. You can contact our Fraud Team for any fraud related queries.

Test API Keys VS Live API Keys

You will receive your Test API Keys over email from the Integration Team. These Test API Keys will be used throughout your Integration process, in order to add our Trustev.js to your site pages and to communicate with our API.

Your Test API Keys and Live API Keys include the following:

Username

Password

Shared Secret

Public Key

Test API Keys and Live API Keys work in almost the same way. Test API Keys are used before moving Digital Verification into a Live environment. Test API Keys allow you to communicate with our API, and our API will handle the data just like Live API Keys. The main difference is that while using Test API Keys, the Digital Verification Decision is either randomly generated or based off the Case Number, whereas Live API Keys will work off each data point, process the data received, and return a Digital Verification Decision.

Our testing guide allows developers to trigger expected outcomes of “pass”,”flag”,”fail” by passing using one of three email’s addresses provided.

Once you have completed all the steps involved in Integrating, and our Integration Team have confirmed that all the data is being gathered correctly, then you will be advised to swap to Live API Keys. Our Integration Team will activate these Live API Keys for you, and once activated,they will be sent out to you, via your email address.

When swapping in your Live API Keys, please ensure that the following changes are made to your developer code:

Your Test Public Key is replaced in the Trustev.js code on all pages to your Live Public Key.

Your API Key information, that is required in Step 4: Get A Token, are all updated to reflect your Live API Key information. This includes Merchants Username, site Password, and site Shared Secret.

Where Authentication is required in an API call, your header includes both the returned API Token with your Merchants site Username amended. Please ensure that the Test site Username is also updated to your Live site Username for each API call.

Blacklist & Whitelist Feature

Our system is designed to allow our Merchants to supply us with blacklist and whitelist information. We include this option to allow our system automatically block/allow certain Devices and/or Email Addresses. Blacklist information will block all mentioned Devices and/or Emails, giving the customer a Fail immediately upon return, while our Whitelist will guarantee that regular good customers can continue to have their order completed without being checked for Fraud behaviour.

At any stage in the Integration process, you may forward this information to our Fraud Team, so that once you Go Live we can ensure that these details are set up for your Live environment. This information can be edited, added to, and amended at a later date if required.