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

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

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

Before you begin

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

For more information about implementing the FraudForce SDKs, see iovation's FraudForce guides.

1. Get the blackbox

When the customer starts a new transaction, iovation 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 iovation's 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 iovation FraudForce's Device not Provided rule or another anomaly rule.
iovation 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). If this task does not exist, when you try to run the check in step 3, an error will be returned.
  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. 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.

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

Request endpoint:

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

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.

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"
}
}

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": {
"address_history": [ … ],
"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",
"country": "USA",
"ip_address": "203.0.113.10",
"region": "OREGON"
}
},
"performed_on": "22019-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": { ... }
}

Use the response to:

Confirm the check has 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.

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 iovation detection.


How did we do?


Powered by HelpDocs