Developer Integration Documentation

Sign Up

To sign up for a Trustev account, you can email our Integration Team (integrate@trustev.com).

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 Trustev API.

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

 

Add Trustev.js

This involves adding the Trustev JavaScript (Trustev.js) to as many pages of your website as possible. This ensures that we can track your customer’s behaviour as they move throughout your site. Before you add Trustev.js to your site, you will require your Public Key. This will have been provided to you by our Integration Team at initial set up. This Public Key should be added into our Trustev.js code as indicated below:

TRUSTEV.JS

(function() {
var tv = document.createElement('script'); tv.type = 'text/javascript'; tv.async = true;
tv.src = 'https://app.trustev.com/api/v2.0/TrustevJS?key=publickey';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(tv, s);
})();
</script>

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

Trustev.js is a secure, server generated JavaScript file responsible for gathering details about each session and device that visits your site. These details are then returned to the Trustev Platform and will eventually form part of the Trustev Decision. For more information, see What is Trustev.js?. Trustev.js will load asynchronously which allows it to run in the background without affecting your customer experience should any issues arise.

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

 

Store TrustevV2.SessionId

Once Trustev.js is integrated into your website, you will need to extract the publicly accessible variable, TrustevV2.SessionId. This variable can be accessed from any page that has the Trustev.js code included. You should store this variable, as this TrustevV2.SessionId is required at a later stage in the Integration when adding a Trustev Case.

Get a Token

To communicate with the Trustev API, you will require an API Token. An API Token is an alphanumeric String returned from the Trustev 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. Please see API Keys: Explained for more information.

---

An API Token request, 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 our other API calls, you will require the ‘APIToken’ parameter that is passed down in the response body when a successful Get a Token request has been made. 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. We include an ‘ExpireAt’ parameter in the response also which can be used a check before running into expired API Token errors.

Sample Get Token Response Message

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

PHP HTTP Get A Token Request:

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

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

$exec = curl_exec($curl);
$result = json_decode ($exec, true);
$result['APIToken']; -- This is your API Token
$result['ExpiresIn']; -- This is the Expiry Time in UTC
curl_close($curl);

Add a Case

This API method allows you to ‘Add a Case’. A ‘Trustev 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 which we asked you to store in Step 3.
• The APIToken that you received from our Get Token API request in Step 4, along with your Trustev UserName, available in your Test API Keys.
• A Case Number, which is a String that you may choose. It must be unique to you as a Merchant. We generally suggest that you use your own internal reference number which you associate with the ‘transaction’ as this Case Number. By doing this, it will allow for an easy reference point should you need more information on the Trustev Case through our Trustev Dashboard.

During Integration, you will be using Test API Keys which means that the Trustev Decision you receive on a Trustev 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 Trustev Case, you can influence the Trustev 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.

Please see code below that shows how to forward a Case to the Trustev API. Clicking on the ADD CASE REQUEST below will bring you to our detailed technical document that outlines all the available parameters 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);
//Extract CaseId for use in Step 7: Get a Trustev Decision & Step 8: Add a Status
curl_close($curl);

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

Once you have successfully added a Case, we will pass a Case Id back down in the Response. 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 Trustev Case you have created.

Get a Trustev Decision

This API method allows you to retrieve a Trustev 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 Trustev Decision. During Integration, you will be using Test API Keys, and this will mean that the Trustev 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 Trustev Decision is a decision formulated after utilizing all the data that has been gathered in compiling your Trustev 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 Trustev Case has been added, and a request to get a Trustev Decision has been made, our API will return a Trustev Decision. A Trustev Decision will indicate either: Pass, Flag or Fail.

Before retrieving a Trustev 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 Trustev 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 Trustev Decision.

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

PHP HTTP Get Trustev 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);
// Extract Result & Confidence parameter in Response Body.
curl_close($curl);

Based off all of the information forwarded, you will be returned a Result parameter in the Response Body 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 Trustev Decision has not been made on your Trustev Case. Please contact support@trustev.com should this occur. Please provide the Case Number and Case Id when sending this request.
1	Pass	This result indicates that the Trustev Case shows no signs for suspicion and the 'transaction' should be accepted.
2	Flag	This result indicates that the Trustev Case contains elements for suspicion which should be reviewed before a final decision is made.
3	Fail	This result indicates that the Trustev Case contains a number of fraudulent features and the 'transaction' should be rejected.

Part of the response body will also contain a Confidence parameter. Please see, What’s a Trustev Confidence Score?, for more information. The Trustev Confidence Score will be a number from 0 – 100, with 100 having 100 percent confidence and 0 having 0 percent confidence in the accuracy of the decision. Our Trustev Confidence score indicates our confidence level in score accuracy based on volume and type of data we have received as part of the Trustev Decision. Certain data fields are weighted higher than others in calculating our confidence levels. The Trustev Confidence score and Trustev Decision should be considered in parallel when making your overall decision.

Sample Get Trustev Decision Response Message

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

For example, you may receive a Decision of Pass, with a Confidence of 10, which means that although the information we received was good, we didn’t receive enough data to be confident that this is/isn’t fraudulent. These scenarios should be flagged for review and our Fraud Team will work with you to configure scoring once Integration is complete.

For a more detailed breakdown of the decision returned, you can login to your Trustev Dashboard. Simply select our reporting features, entering in the Case Number you supplied to see the main elements that influenced the Trustev Decision on any particular Case.

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

Add a Status

The final step in the Integration process is adding a Status to reflect the outcome of the Trustev Case, once you have received a Trustev Decision. During the Add a Case step, all transactions automatically receive the status of 8 Placed. That being said, this is a temporary status which should be updated to reflect the Decision. 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 Trustev Case, so our system can see the decisions you’ve made throughout the process.

As outlined in Step 6: Get a Trustev Decision, the result returned to you will indicate whether or not Trustev recommends processing the ‘transaction’. Merchants can face a number of scenarios, and each customer may not be as simple as Yes/No, therefore we require that a Status is forwarded to Trustev, 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

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 Trustev 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 Trustev API.

PHP HTTP Add a Status Request

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

$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);

Webhook

Trustev provide a mechanism to ensure that the Order data in a Merchant’s system can stay synchronised with the Order data stored in Trustev’s 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 - https://app.trustev.com/dashboard, you will see the option to update the Status of an order.

On Submit, the Trustev system sends back a JSON object to a specified endpoint. This allows the Merchant to have both the Trustev 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: 

{
CaseNumber": "96f9868d-5ff5-4a5c-becc-1ca030d3422b",
"CaseId": "edffc5f6-2bf8-411c-974e-04ff24968a4d|9288c4b2-5f66-4664-84d6-efd70b9f9d4c",
"Status": 0
}

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

 

Please note: The Trustev 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 Trustev 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 Trustev API with webhook:

 

 

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

Once you have successfully completed all the above stages and our Integration Team have confirmed that all the data is being gathered correctly on our system, then your Integration to Trustev is complete.

 

The Integration Team will organize a handover call with the Fraud Team at this stage. Following this, both teams will monitor your site for 24 hours, to confirm all API requests are successful, and then you will be in the Pilot Phase.

Update Terms & Conditions, and Privacy Policies

We advise that all Merchants update their Terms & Conditions, and Privacy Policies, to advise all visitors to your Site that Trustev has been implemented.

Pilot Phase

Once this is completed, you will have entered the Pilot Phase and you will be handed over to our Fraud Team. Our Fraud Team will work with you to recommend the expected Trustev Confidence level for your Trustev Decisions, which may be changed during the Pilot Phase. Our Fraud Team will monitor the Trustev Decisions returned to you for your Live Transactions (Trustev 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 fraud@trustev.com.