Device Identification and Fraud Prevention With ThreatMetrix


ThreatMetrix is the industry leader in device identification based fraud management. Their global fraud-prevention network is based on third generation device identification and transaction behavior tracking technology that delivers device and transaction confidence scores, reason codes and attributes in real-time. Using device identification coupled with their advanced rules-engine, and machine learning technology, ThreatMetrix is able to stop first-time fraud and recognize valued, returning customers more effectively than competing alternatives.

The USAePay gateway provides an interface for integrating the ThreatMetrix service into merchant's existing transaction processing. Merchants looking to enhance their fraud prevention efforts can leverage this premium service with a minimal amount of code change. Once integrated, the ThreatMetrix scoring and extended device profile data is visible within the merchant console. The ThreatMetrix fraud module can be configured on a per source key basis to block transactions which reach a given score.

For pricing information merchants should contact their merchant service provider.

For development assistance please contact the integration support department.

API Integration

Device identification is currently available on the Transaction API, PHP library and Dot Net DLL. Partial support is available in the Soap API using the runTransactionAPI method. Full support in the Soap API will be available in 1.5 when it is released. Developers using other libraries can request assistance by contacting the developer integration department at

There are three addition/changes that need to be made by the merchant's developer or software vendor:

  • Retrieving a session identifier from USAePay
  • Displaying the profiling HTML to customer
  • Include the session identifier in the transaction request sent to the gateway

Retrieve Session Identifier

To properly track the customer throughout the payment process a unique session id is required. This session id must be generated by USAePay and should be stored throughout the check out process. A session id is retrieved by calling the "getsession" action in the profiler api.

Example REST request: SourceKey=123123123123123123&Hash=s/sjhj2489sh/fe2cece09552cbb5855865c1f582252cff1e2dea

The SourceKey variable is generated in the merchant console. It must be setup with a pin assigned. The Hash is calculated by concatenating the action (getsession), the pin, and a random seed separated by colons. For example, if your pin is '1234' and your seed is 'sjhj2489sh', the prehashed text would be getsession:1234:sjhj2489sh and the sha1 hash would be fe2cece09552cbb5855865c1f582252cff1e2dea. The Hash variable is then set to type/seed/hash. In this example Hash would be set to s/sjhj2489sh/fe2cece09552cbb5855865c1f582252cff1e2dea

Example response:

<code xml>
<?xml version="1.0"?>

The SessionID variable should be stored for the duration of the payment process. The OrgID is needed for the HTML display but does not need to be stored for later use.

Display Profiling HTML

Taking the variables received during the 'getsession' call above, display the following HTML to the customer. Typically this html can be added to bottom of the same page that is used to collect the card number.

<code html>
<p style="background:url([OrgID]&session_id=[SessionID]&m=1)"></p>
<img src="[OrgID]&session_id=[SessionID]&m=2" 
  width="1" height="1" alt="">
<script src="[OrgID]&session_id=[SessionID]"
      value="[OrgID]&session_id=[SessionID]" />

Add SessionID to Transaction Request

The session id needs to be passed in the UMsession variable with the rest of the transaction data. Example sale request: UMkey=123123123123123123& UMcard=4444555566667779& UMexpir=1212& UMamount=10.00& UMinvoice=12345& UMdescription=Example+Order& UMsession=u820nnd3t9tsfr7bhnxxfaww1sess57sspnk8hmrzkyrvh4wu9fa9w7idon4wue8

There are also additional response variables such as the profiler score that the developer may wish to capture. While it is not necessary to do anything with these variables, they can be useful in making business decisions such as whether to ship product or not. Example response:

<code html>

The UMprofilerScore variable contains the score calculated by ThreatMetrix based on the device and transaction details. The higher the number, the less risk. "0" represents a clean, safe transaction. "-99" is a high risk transaction and should be investigated manually. UMprofilerResponse will return 'reject','pass','review' or 'error'. The first three of these are based on score thresholds (ie >-30 = pass, >-60 = warn <-60 = reject). 'error' indicates that the gateway was unable to complete the profiling request. A list of factors that triggered the score will be returned in the UmprofilerReason variable.

PHP Library Integration

For developers using the [[phplibrary|PHP Library]] integration is much easier. On the payment page, add the following code to retrieve the sessionid and display the profiling html:

<code php>

$client = new umTransaction();
$client->key = '12341234123412341234';
$client->pin = '1234';

$session = $client->getSession();

// you should store $session['sessionid'] in your order record so that 
// it is available when the transaction is submitted.  you could also
// place it in a hidden input var:
?><input type="hidden" name="sessionid" value="<?php echo htmlentities($session['sessionid'])?>"><?php

// display the profiler html 
echo $session['html'];

When submitting the transaction, make sure to add the session variable:

<code php>
$client = new umTransaction();
$client->key = '12341234123412341234';
$client->pin = '1234';
$client->session = $_POST['sessionid'];
$client->card = $_POST['cardnumber'];
$client->exp = $_POST['exp'];
$client->amount = $_POST['amount'];

    echo "<b>Card approved</b><br>";
    echo "<b>Authcode:</b> " . $client->authcode . "<br>";
    echo "<b>AVS Result:</b> " . $client->avs_result . "<br>";
    echo "<b>Cvv2 Result:</b> " . $client->cvv2_result . "<br>";
} else {
    echo "<b>Card Declined</b> (" . $client->result . ")<br>";
    echo "<b>Reason:</b> " . $client->error . "<br>";   
    if($client->curlerror) echo "<b>Curl Error:</b> " . $client->curlerror . "<br>";    
echo "<b>RefNum: </b> " . $client->refnum . '<br>';

echo "<br>";
echo "<b>Profiler Response</b><br>";
echo "Score: " . $client->profiler_score . '<br>';
echo "Response: " . $client->profiler_response . '<br>';
echo "Reason: " . $client->profiler_reason . '<br>';


Dot Net DLL Integration

Add the following code to retrieve the sessionid and display the profiling html:

Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay

usaepay.SourceKey = "Your_source_key_here"
usaepay.Pin = "ABA123"

Dim getSessionResult As New Dictionary(Of String, String)
Dim sessionid As String

getSessionResult = usaepay.GetSessionId()

If Not getSessionResult Is Nothing Then
    If Not getSessionResult.Count <=0 Then
        If getSessionResult.ContainsKey("sessionid") Then
            sessionid = getSessionResult.Item("sessionid")
            WebBrowser1.DocumentText = getSessionResult.Item("html")
        End If
    End If
End If

To submit the transaction with session variable:

Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
Dim message As String
usaepay.SourceKey = "Your_source_key_here"
usaepay.Pin = "ABA123"
usaepay.Session = sessionid 
usaepay.Amount = 2.23
usaepay.Description = "A test transaction"
usaepay.CardHolder = "Joe Schmoe"
usaepay.CardNumber = "4444555566667779"
usaepay.CardExp = "1212"

    If usaepay.ResultCode = "A" Then
        message = "Transaction approved" & vbLf _
       & "Auth Code: " & usaepay.AuthCode & vbLf _
       & "Ref Num: " & usaepay.ResultRefNum & vbLf _
       & "AVS: " & usaepay.AvsResult & vbLf _
       & "CVV: " & usaepay.Cvv2Result
    ElseIf usaepay.ResultCode = "D" Then
    message = "Transaction Declined" & vbLf _
       & "Ref Num: " & usaepay.ResultRefNum
    message = "Transaction Error" & vbLf _
       & "Ref Num: " & usaepay.ResultRefNum & vbLf _
       & "Error: " & usaepay.ErrorMesg & vbLf _
       & "Error Code: " & usaepay.ErrorCode & vbLf
    End If

    If Not String.IsNullOrEmpty(usaepay.Session) Then
        message &= vbLf & vbLf & "Profiler Score: " & usaepay.ProfilerScore & vbLf _
                & "Profiler Response: " & usaepay.ProfilerResponse & vbLf _
                & "Profiler Reason: " & usaepay.ProfilerReason & vbLf
    End If

    Catch ex As Exception
    MsgBox("Caught Exception: " & ex.Message)
End Try