Run a Device fraud detection check using the API

This developer guide takes you through the steps to run a Device fraud 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.

The provider name for TransUnion, formerly iovation, Device Fraud is iovation FraudForce.

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 TruValidate's SDK or embedded webpage to capture the device token. TransUnion Device Risk calls the device token the blackbox.

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

Passfort contacts TransUnion TruValidate's fraud prevention service to run the check and imports the fraud conclusions.

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 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 TruValidate'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.

Choose a profile and get the profile 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, for example, a2c4393a-e219-67a4-5ab4-2186952e9038. You'll need it to run the check later.

If you haven't created the profile yet, use the API to create an individual profile. To improve the efficiency of the process for this check, get 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:

Confirm the profile has the Assess device reputation task (INDIVIDUAL_ASSESS_DEVICE_REPUTATION).
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 TruValidate when you run the check in the next step. The profile address will be added to these fields in TransUnion TruValidate: billingCity, billingCountry, billingPostalCode, billingRegion, and billingStreet.

Run the check

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

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 also 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 following sample request body 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` *Required object	See the following sample request body for a sample value.	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 This key is optional if `variant.alias` is provided.	Sample value: `ea70ade9-3de3-1785-203b-68044cd3ecbb`	The unique identifier for the check.

In the following example, 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 runs asynchronously by default, the check state is likely RUNNING in the response. See the next section 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:

secret: Authenticate 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 previously captured.
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 previously captured.
data.check.result: The results of the check. Possible results for the Document verification check are Pass, Fail, Refer , or Error. To learn what triggers each result, see the configuration article for your data provider: TransUnion TruValidate.

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 the following section, Get more information about the check result, to learn more about the device and location.

Get more information about the check result

If you want to get more information about the check result, make a call to the following endpoint.

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 following endpoint.

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.

Additional information

In this section:

Run a Device fraud detection check using the API

What the process looks like

Get the blackbox

Choose a profile and get the profile ID

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

Run the check

Get the check result

Get more information about the check result

Additional information

Search results