Run a Device fraud detection check (API)

This developer guide takes you through the steps to run a Device fraud detection detection check in the PassFort API 4.0 to assess whether the individual's device is reputable.

This check is run on the Assess device reputation task (ASSESS_DEVICE_REPUTATION).

What the process looks like

PassFort sits in between the data provider's SDK and their fraud prevention service.

To start, get the ID of the profile you want to run the check on, and use TransUnion (formerly iovation) FraudForce's SDK or embedded webpage to capture the device token. TransUnion FraudForce calls the device token the blackbox.

Next, run the check via PassFort, sending the profile ID and blackbox.

PassFort contacts TransUnion FraudForce's fraud prevention service to run the check and imports the fraud conclusions.

Before you begin

This guide assumes you've already implemented TransUnion (formerly iovation) FraudForce's SDKs and/or web app.

For more information about implementing the FraudForce SDKs, see the TransUnion FraudForce guides.

1. Get the blackbox

When the customer starts a new transaction, TransUnion generates a blackbox which you can send to PassFort in the request to run the Device fraud detection check.

To learn how to generate the blackbox, see the TransUnion FraudForce guides.

If you're unable to capture the blackbox, you can run the Device fraud detection check sending an empty string. You may want to do this if you're using TransUnion FraudForce's Device not Provided rule or another anomaly rule.
TransUnion generates a new blackbox for every transaction, even if the transaction is coming from the same user and device.

2. Get the profile's ID and confirm it has the required fields for the check

You should find the corresponding profile for the check so you can:

  1. Get the profile ID.
  2. Make sure the profile has the Assess device reputation task (required for the Device fraud detection check to run successfully).
  3. Get the Assess device reputation task ID.

Get the profile's ID

Device fraud detection checks are always run on profiles with the INDIVIDUAL entity type.

Choose an individual profile to run the check on, and take note of the profile's ID number (e.g. a2c4393a-e219-67a4-5ab4-2186952e9038). You'll need it to run the check later.

If you haven't created the profile yet, follow these steps to create an individual profile via the API. To improve the efficiency of the process for this check by getting the blackbox at the same time as you create the profile in PassFort.
You can also create a profile via the portal. To get the profile ID, view the profile in the portal and copy the string of letters and numbers after /onboarding/ in the URL.

Confirm the profile has the Assess device reputation task and get the task ID

To see a profile's tasks, make a request to the following endpoint.

Request endpoint:

GET https://api.passfort.com/4.0/profiles/{profile_id}/tasks

In this example, the profile only has the Assess device reputation task.

Sample response:

[
{
"check_ids": [ ],
"creation_date": "2019-11-21 13:48:16",
"form_instance_ids": [ ],
"id": "72aadb55-8b02-8495-d6b0-e1627ec23612",
"is_complete": false,
"is_expired": false,
"is_skipped": false,
"state": "INCOMPLETE",
"type": "INDIVIDUAL_ASSESS_DEVICE_REPUTATION",
"variant": {
"alias": "assess_device_reputation",
"id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
"task_type": "INDIVIDUAL_ASSESS_DEVICE_REPUTATION"
}
}
]

Use the response to:

  1. Confirm the profile has the Assess device reputation task (INDIVIDUAL_ASSESS_DEVICE_REPUTATION).
  2. Take note of the corresponding task ID (tasks.id). Use the task alias (variant.alias) to confirm that you're looking at the right task. If there is more than one task with the same alias (which happens when a task has more than one version), use the task with "is_expired": "false". Note that the task variant ID (variant.id) won't be used to run this check, so you don't need to take note of it.
If the profile has any addresses in collected_data.address_history, the most recent address will be sent to TransUnion FraudForce when you run the check in the next step. The profile address will be added to these fields in TransUnion FraudForce: billingCity, billingCountry, billingPostalCode, billingRegion, and billingStreet.

3. Run the check

Now that you have the profile ID and blackbox, you can run the check and get the results.

Run the check

To run the check, send a request to the endpoint below.

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/checks
By default, the Device fraud detection check will run asynchronously. You can send mode as a query parameter to run the check synchronously.

Body parameters:

When you make the POST request, include the following parameters in the body.

Key

Value

Description

check_type

Required

String

DEVICE_FRAUD_DETECTION

The type of check that's being run.

device_metadata

Required

Object

See the sample request body below for a sample value.

Object for the metadata for the device.

token

Required

String

Sample value: aLr1ShhpzPGuX69BtmrXqp/aVeFFfHSU14LFYbVQ==

If no blackbox is provided, you can send an empty string to capture the anomaly.

The data provider's blackbox.

action

Required

String

Sample value: transaction

Note that your endpoints are unique to your account.

The data provider's endpoint.

reference_id

Optional

String

Sample value: 12345678

The unique identifier for the end-user’s account, or for the transaction.

stated_ip

Optional

String

Sample value: 203.0.113.10

The IP address that your website captured as the applicant IP.

variant

Optional (but we recommend including it whenever possible)

Object

For a sample value, see the sample request body below.

Object to indicate which variant of the check will run.

variant.alias

Required

String

This key is optional if variant.id is provided, but we recommend sending the alias whenever possible.

Sample value:

default

The check alias.

variant.id

Required

String

This key is optional if variant.alias is provided.

Sample value:

ea70ade9-3de3-1785-203b-68044cd3ecbb

The unique identifier for the check.

In the example below, we'll run the check.

Sample request body:

{
"check_type": "DEVICE_FRAUD_DETECTION",
"device_metadata": {
"token": "aLr1ShhpzPGuX69BtmrXqp/aVeFFfHSU14LFYbVQ==",
"action": "transaction",
"reference_id": "12345678",
"stated_ip": "203.0.113.10"
},
"variant": {
"alias": "default"
}
}

Sample response:

{
"check_type": "DEVICE_FRAUD_DETECTION",
"device_metadata": {
"action": "transaction",
"reference_id": "12345678",
"stated_ip": "203.0.113.10",
"token": "aLr1ShhpzPGuX69BtmrXqp/aVeFFfHSU14LFYbVQ=="
},
"id": "76c19e06-d7f8-11ea-9a50-aedd8ce87537",
"instructed_on": "2019-11-21 13:48:16",
"performed_on": "2019-11-21 13:48:16",
"providers": [],
"state": "PENDING",
"task_ids": [
"3d7a333c-418d-72a1-007b-06854dbb28eb"
],
"variant": { ... }
}

Because this check run asynchronously by default, the check state will likely be RUNNING in the response. See next step to learn how to get the check results as soon as they come in from the data provider.

Get the check result

Listen to the Check completed webhook to get a notification when the check is finished running and learn what the result is.

This webhook sends a payload whenever results are returned from any check (including checks other than the Device fraud detection check).

Payloads from this webhook have several important keys:

  • secretAuthenticate the request by ensuring this secret matches your secret.
  • id: The check ID. Use it to confirm the payload is for your check by matching it to the check ID you captured in step 2.
  • data.check.check_type: The type of check was run. When the Device fraud detection check was run, the value is DEVICE_FRAUD_DETECTION.
  • data.check.variant.alias: The alias for the check variant. You can use it for additional confirmation that the payload is for your check by matching it to the check variant alias you captured in step 2.
  • data.check.result: The results of the check. Possible results for the Document verification check are PassFail, Refer or Error. To learn what triggers each result, see the configuration article for your data provider: TransUnion (formerly iovation) FraudForce.

In this example, the Device fraud detection check has passed.

Sample payload:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "CHECK_COMPLETED",
"secret": "yourSecret",
"timestamp": 1570807808,
"data": {
"check": {
"check_type": "DEVICE_FRAUD_DETECTION",
"id": "ea70ade9-3de3-1785-203b-68044cd3ecbb",
"result": "Pass",
"variant": {
"alias": "device_fraud",
"id": "ea565b55-47d9-1858-4588-3a22a3838707",
"name": "Device fraud detection"
}
},
"customer_ref": null,
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
}
}

Use the response to:

Confirm the check passed:

  • If the check has passed, result is Pass.
  • If the check needs further review, result is Refer.
  • If the check hasn't passed, result is Fail.
  • If an error occurred, result is Error.

See Getting more information about the check result to learn more about the device and location.

Getting more information about the check result

If you want to get more information about the results from the webhook, make a call to the endpoint below.

In the request body, include the check ID (check.id) and the profile ID (data.profile_id) from the webhook payload.

We recommend listening to the Check completed webhook to find out when the check is finished because it's more efficient than continuously polling the endpoint below.

Request endpoint:

GET https://api.passfort.com/4.0/profiles/{profile_id}/checks/{check_id}

In this example, the check passed. We can see from the response that it was run on an Android device from Portland, Oregon in the United States.

Sample response:

{
"check_type": "DEVICE_FRAUD_DETECTION",
"completed_on": "2019-11-21 13:48:17",
"decision": "PASS",
"device_metadata": {
"action": "transaction",
"reference_id": "12345678",
"stated_ip": "203.0.113.10",
"token": "aLr1ShhpzPGuX69BtmrXqp/aVeFFfHSU14LFYbVQ=="
},
"errors": [ ],
"id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
"input_data": {
"contact_details": { },
"device_metadata": {
"action": "transaction",
"reference_id": "12345678",
"stated_ip": "203.0.113.10",
"token": "aLr1ShhpzPGuX69BtmrXqp/aVeFFfHSU14LFYbVQ=="
},
"entity_type": "INDIVIDUAL",
"personal_details": { … }
},
"instructed_on": "2019-11-21 13:48:16",
"output_data": {
"device_fraud_detection": {
"matched_rules": [
{
"name": "Evidence Exists",
"reason": "Evidence found",
"score": -50
}
],
"provider_reference": "6023104444588795",
"recommendation": "Allow",
"recommendation_reason": "No evidence found",
"total_score": -50
},
"device_metadata": {
"action": "transaction",
"device_id": "2237563594328450",
"device_type": "ANDROID",
"reference_id": "12345678",
"stated_ip": "203.0.113.10",
"token": "aLr1ShhpzPGuX69BtmrXqp/aVeFFfHSU14LFYbVQ=="
},
"entity_type": "INDIVIDUAL",
"ip_location": {
"city": "PORTLAND",
"coordinates": {
"latitude": 45.51815,
"longitude": -122.67416
},
"country": "USA",
"ip_address": "203.0.113.10",
"region": "OREGON"
},
},
"performed_on": "2019-11-21 13:48:16",
"providers": [
{
"instructed_on": "2019-11-21 13:48:16",
"provider_name": "iovation FraudForce",
"variant_name": ""
}
],
"result": "Pass",
"started_on": "2019-11-21 13:48:16",
"state": "COMPLETE",
"task_ids": [
"3d7a333c-418d-72a1-007b-06854dbb28eb"
],
"variant": { ... }
}

The output_data object that's returned in the response contains the information returned from the data provider:

  • device_fraud_detection.matched_rules: This array of objects contains one object for each of the rules the data provider has matched the device with. Each rule has its own score that contributes to the device's total score.
  • device_fraud_detection.provider_reference: The reference supplied by the data provider.
  • device_fraud_detection.recommendation: The data provider's recommendation for the device. Can be Allow, Review, Deny.
  • device_fraud_detection.recommendation_reason: The reason the data provider has given for their recommendation.
  • device_fraud_detection.total_score: The transaction score the data provider has given for the device. Devices with higher scores are deemed more trustworthy.
  • device_metadata.reference_id: The reference ID that the data provider discovered for the device. You can check this against input_data.device_metadata.reference_id to ensure it matches what you sent.
  • device_metadata.stated_ip: The IP address that the data provider has discovered for the device. You can check this against input_data.device_metadata.stated_ip to ensure it matches what you sent.
  • device_metadata.token: The device's blackbox. If this is an empty string, it may be because the transaction was made by a fraudster attempting to evade TransUnion detection.
  • ip_location: The location of the device, including latitude and longitude.


How did we do?


Powered by HelpDocs (opens in a new tab)