Device Identification and Fraud Prevention With ThreatMetrix
Overview
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 devtickets@usaepay.com
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:
https://www.usaepay.com/interface/profiler/getsession? 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"?>
<Output>
<Result>A</Result>
<SessionID>u820nnd3t9tsfr7bhnxxfaww1sess57sspnk8hmrzkyrvh4wu9fa9w7idon4wue8</SessionID>
<OrgID>sdffss</OrgID>
</Output>
</code>
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(https://content-05.usaepay.com/fp/clear.png?org_id=[OrgID]&session_id=[SessionID]&m=1)"></p>
<img src="https://content-05.usaepay.com/fp/clear.png?org_id=[OrgID]&session_id=[SessionID]&m=2"
width="1" height="1" alt="">
<script src="https://content-05.usaepay.com/fp/check.js?org_id=[OrgID]&session_id=[SessionID]"
type="text/javascript"></script>
<object
type="application/x-shockwave-flash"
data="https://content-05.usaepay.com/fp/fp.swf?org_id=[OrgID]&session_id=[SessionID]"
width="1"
height="1"
id="obj_id">
<param
name="movie"
value="https://content-05.usaepay.com/fp/fp.swf?org_id=[OrgID]&session_id=[SessionID]" />
<div></div>
</object>
</code>
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:
https://www.usaepay.com/gate?
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>
UMversion=2.9&
UMstatus=Approved&
UMauthCode=000038&
UMrefNum=1453072&
....
UMprofilerScore=-15&
UMprofilerResponse=pass&
UMprofilerReason=NewDeviceID&
UMfiller=filled
</code>
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>
<?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'];
</code>
When submitting the transaction, make sure to add the session variable:
<code php>
<?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'];
$client->invoice="1234";
if($client->Process())
{
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>';
</code>
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"
Try
usaepay.Sale()
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
Else
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
MsgBox(message)
Catch ex As Exception
MsgBox("Caught Exception: " & ex.Message)
End Try