Run a Merchant fraud check (API)

This developer guide takes you through the steps to run a Merchant fraud check in the PassFort API 4.0 to confirm whether a company and associates have fraudulent merchant accounts.

This check is run on the Assess merchant fraud risk (COMPANY_MERCHANT_FRAUD_SCREENING) task.

1. Get the profile's ID and confirm it has the required keys and values

First, choose a profile for the check and get the profile ID (more information on getting the profile ID below).

Once you have the profile ID, you can make sure the profile has the required fields for the Merchant fraud check to run successfully (also documented below).

Get the profile's ID

Identity checks are always run on profiles with the COMPANY entity type.

Choose a company 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 confirm it has the required fields and to run the check later.

If you haven't created the company's profile yet, follow the steps to create a profile via the API.
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 required fields for the check

To see all data on the profile, make a request to the following endpoint.

Request endpoint:

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

In this example, data is returned for a company profile named "Aerial Traders". The profile has the Merchant fraud check task. The company has one associate named "Blake Carr" who is a beneficial owner.

Sample response:

{
"applications": [ ... ],
"category": "APPLICANT",
"checks": [ ... ],
"collected_data": {
"entity_type": "COMPANY",
"metadata": {
"addresses": [
{
"address": {
"type": "STRUCTURED",
"country": "GBR",
"locality": "London",
"original_freeform_address": "38, Crown Street, London, W1 2ZT",
"original_structured_address": { ... },
"postal_code": "W1 2ZT",
"route": "Crown Street",
"street_number": "38"
}
}
],
"country_of_incorporation": "GBR",
"name": "AERIAL TRADERS",
"number": "012345678"
]
},
"ownership_structure": {
"beneficial_owners": [
{
"entity_type": "INDIVIDUAL",
"linked_profile": {
"applications": [ ... ],
"category": "APPLICANT",
"collected_data": {
"entity_type": "INDIVIDUAL",
"address_history": [
{
"address": {
"type": "STRUCTURED",
"country": "GBR",
"locality": "London",
"original_freeform_address": "112 Guild Street, London, NW8 4QY",
"original_structured_address": { ... },
"postal_code": "NW8 4QY",
"route": "Guild Street",
"street_number": "112"
}
}
],
"personal_details": { ... }
}
},
"display_name": "Blake Carr",
"has_associates": false,
"has_collection_steps": false,
"id": "a7a57663-8d1b-c45b-73e2-19616ce0ebe5",
"role": "INDIVIDUAL_ASSOCIATED",
"status": "NORMAL",
"tags": [ ],
"task_progress": { ... },
"tasks": [ ... ],
"unresolved_event_types": [ ]
},
"merged_resolver_ids": [ ... ],
"natures_of_control": [ ],
"resolver_id": "a52cdc09-c428-3ada-3e20-7a21062e698d",
"shareholdings": [ ... ],
"task_variant_ids": [ ... ],
"total_percentage": 85,
"unverified_task_variant_ids": [ ]
]
}
},
"collection_steps": [ ],
"creation_date": "2020-06-29 13:48:16",
"display_name": "AERIAL TRADERS",
"document_images": [ ],
"events": [ ],
"has_associates": false,
"has_collection_steps": false,
"id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
"linked_to": [ ],
"role": "COMPANY_CUSTOMER",
"root_id": "6bba3592-d9de-1ee5-8e97-ba8d8d13c558",
"status": "NORMAL",
"tags": [ ],
"task_progress": { ... },
"task_types": [
"COMPANY_MERCHANT_FRAUD_SCREENING",
"COMPANY_IDENTIFY_BENEFICIAL_OWNERS"
],
"tasks": [
{
"check_ids": [ ],
"creation_date": "2020-06-29 13:48:16",
"form_instance_ids": [ ],
"id": "a2380e94-47ee-3337-fe2d-9fad0692106f",
"is_complete": false,
"is_expired": false,
"is_skipped": false,
"state": "INCOMPLETE",
"type": "COMPANY_MERCHANT_FRAUD_SCREENING",
"variant": {
"alias": "merchant_fraud",
"id": "e5afcd76-5cfd-51d2-97d1-2d812e1df411",
"task_type": "COMPANY_MERCHANT_FRAUD_SCREENING"
}
},
{
"check_ids": [ ],
"creation_date": "2020-06-29 13:48:16",
"form_instance_ids": [ ],
"id": "a51e03c2-c750-92d3-d6ce-bcb880bcaab0",
"is_complete": false,
"is_expired": false,
"is_skipped": false,
"state": "INCOMPLETE",
"type": "COMPANY_IDENTIFY_BENEFICIAL_OWNERS",
"variant": {
"alias": "identify_shareholders",
"id": "a481458c-cba5-44a2-e779-a5e5cbd6c6c7",
"task_type": "COMPANY_IDENTIFY_BENEFICIAL_OWNERS"
}
}
],
"unresolved_event_types": [ ]
}

Use the response to:

  1. Confirm the profile has the Assess merchant fraud risk task (COMPANY_MERCHANT_FRAUD_SCREENING).
  2. Take note of the task ID (tasks.id). 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 (tasks.variant) won't be used to run the check.
  3. Confirm the profile has data for these required keys, which are in the collected_data object:
    1. metadata.name: The company's name.
    2. metadata.addresses: An array of objects containing the company's address history.
  4. Confirm the profile has at least one associate that has the INDIVIDUAL entity type and an address. The associate can be returned in any of the following objects: ownership_structure, officers, authorized_persons, unauthorized_persons.

If these fields do not exist on the profile or do not contain valid data, the check will return an error when you try to run it.

To learn how to add a company associate, see Create a profile for an associate and link it to a company.

To learn how to add/update the fields in the collected_data field of the company's profile or the associate's profile, see Update PassFort's profile data.

2. Run the check

Sending the request

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

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/checks
By default, the Merchant fraud check runs asynchronously, but 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

COMPANY_MERCHANT_FRAUD_SCREENING

The type of check that's being run.

variant.alias

Optional

Array of string

Sample value:

merchant_fraud

The unique identifier for the check variant that will run.

task_ids

Optional (we recommend including it whenever possible)

Array of string

Sample value:

3d7a333c-418d-72a1-007b-06854dbb28eb

The unique identifier for the task variant the check will run on (i.e. the COMPANY_MERCHANT_FRAUD_SCREENING task).

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.

Sample request body:

{
"check_type": "COMPANY_MERCHANT_FRAUD_SCREENING",
variant: {
"alias": "merchant_fraud"
},
"variant": {
"alias": "default"
}
}

Sample response:

{
"check_type": "COMPANY_MERCHANT_FRAUD_SCREENING",
"id": "ea565b55-47d9-1858-4588-3a22a3838707",
"instructed_on": "2020-06-29 14:26:44",
"performed_on": "2020-06-29 14:26:44",
"providers": [ ],
"state": "PENDING",
"task_ids": [ ... ],
"variant": { ... }
}

Take note of the check id in the response because you'll need it for the next steps to learn how to get the check results.

Because this check runs asynchronously, the check state is expected to be PENDING in the response.

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 Merchant fraud check).

Payloads from this webhook have several important keys:

  1. secret: Authenticate the request by ensuring this secret matches your secret.
  2. 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.
  3. data.check.check_type: The type of check was run. When the Merchant fraud check was run, the value is COMPANY_MERCHANT_FRAUD_SCREENING.
  4. 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.
  5. data.check.result: The results of the check. Possible results for the Merchant fraud check are Pass, Refer, or Error. If there are no potential matches to terminated accounts, the decision is Pass. If there are one or more, the decision is Refer.

In this example, the Merchant fraud check returned one or more potential matches to terminated accounts.

Sample payload:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "CHECK_COMPLETED",
"secret": "yourSecret",
"timestamp": 1570807808,
"data": {
"check": {
"check_type": "COMPANY_MERCHANT_FRAUD_SCREENING",
"id": "ea565b55-47d9-1858-4588-3a22a3838707",
"result": "Refer",
"variant": {
"alias": "merchant_fraud",
"id": "ea565b55-47d9-1858-4588-3a22a3838707",
"name": "Merchant fraud check"
}
},
"customer_ref": null,
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
}
}

See Getting more information about the check result to learn which potential matches were discovered and more.

Even if there are no matches to terminated accounts and the decision is PASS, you may wish to follow the steps below to learn whether there are any inquiry matches.

Getting more information about the check result

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

In the request body, include the profile ID and the check ID.

Request endpoint:

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

In this example, there is one potential match to a terminated account and one potential match to an inquiry. To learn more about these match types, see the description below.

Sample response:

{
"check_type": "COMPANY_MERCHANT_FRAUD_SCREENING",
"completed_on": "2020-06-29 14:27:50",
"decision": "WARN",
"errors": [ ],
"id": "2d20e97c-bab8-11ea-b0e9-5c33da64241d",
"input_data": {
"entity_type": "COMPANY",
"metadata": {
"addresses": [
{
"address": {
"country": "GBR",
"locality": "London",
"original_freeform_address": "38, Crown Street, London, W1 2ZT",
"original_structured_address": { ... },
"postal_code": "W1 2ZT",
"route": "Crown Street",
"street_number": "38",
"type": "STRUCTURED"
}
}
],
"name": "AERIAL TRADERS"
},
"ownership_structure": {
"beneficial_owners": [
{
"entity_type": "INDIVIDUAL",
"linked_profile": {
"applications": [ ... ],
"category": "APPLICANT",
"collected_data": {
"address_history": [
{
"address": {
"country": "GBR",
"locality": "London",
"original_freeform_address": "112 Guild Street, London, NW8 4QY",
"original_structured_address": { ... },
"postal_code": "NW8 4QY",
"route": "Guild Street",
"street_number": "112",
"type": "STRUCTURED"
}
}
],
"entity_type": "INDIVIDUAL",
"personal_details": { ... }
},
"creation_date": "2020-06-29 13:48:16",
"display_name": "Blake Carr",
"has_associates": false,
"has_collection_steps": false,
"id": "a7a57663-8d1b-c45b-73e2-19616ce0ebe5",
"role": "INDIVIDUAL_ASSOCIATED",
"status": "NORMAL",
"tags": [ ],
"task_progress": { ... },
"tasks": [ ... ],
"unresolved_event_types": [ ]
},
"merged_resolver_ids": [ ... ],
"natures_of_control": [ ],
"resolver_id": "a52cdc09-c428-3ada-3e20-7a21062e698d",
"shareholdings": [ ... ],
"task_variant_ids": [ ... ],
"total_percentage": 85,
"unverified_task_variant_ids": [ ]
}
]
}
},
"instructed_on": "2020-06-29 14:27:50",
"output_data": {
"authorized_persons": [
{
"entity_type": "INDIVIDUAL",
"immediate_data": {
"address_history": [
{
"address": {
"country": "GBR",
"locality": "London",
"original_freeform_address": "112 Guild Street, London, NW8 4QY",
"original_structured_address": { ... },
"postal_code": "NW8 4QY",
"route": "Guild Street",
"street_number": "112",
"type": "STRUCTURED"
}
}
],
"entity_type": "INDIVIDUAL",
"personal_details": { ... }
},
"resolver_id": "64a828ec-bab8-11ea-b5a0-fedee76236e1"
}
],
"entity_type": "COMPANY",
"merchant_fraud_results": {
"inquiry_matches": [
{
"associate_match_fields": [
{
"address": {
"inquiry_data": {
"address_lines": [
"112 Guild Street, London, NW8 4QY"
],
"country": "GBR",
"locality": "London",
"type": "STRUCTURED"
},
"match_data": {
"address_lines": [
"596 BALBOA ROAD",
"SUITE 201"
],
"country": "USA",
"locality": "SAN DIEGO",
"postal_code": "92123",
"state_province": "CA",
"type": "STRUCTURED"
},
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"alt_phone_number": {
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"associate_id": "3bebb6b1-a998-11ea-afe8-100102ac1442",
"driving_licence": {
"match_data": {
"country_code": "USA",
"document_type": "DRIVING_LICENCE",
"number": "*****"
},
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"name": {
"inquiry_data": "Blake Carr",
"match_data": "BLAKE CARR",
"match_strength_description": "Exact match",
"provider_match_type": "M01"
},
"national_id": {
"match_data": "*****",
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"phone_number": {
"match_data": "3165557625",
"match_strength_description": "No match",
"provider_match_type": "M00"
}
}
],
"company_match_fields": {
"address": {
"inquiry_data": {
"address_lines": [
"38, Crown Street, London, W1 2ZT"
],
"country": "GBR",
"locality": "London",
"type": "STRUCTURED"
},
"match_data": {
"address_lines": [
"596 BALBOA ROAD",
"SUITE 201"
],
"country": "USA",
"locality": "SAN DIEGO",
"postal_code": "92123",
"state_province": "CA",
"type": "STRUCTURED"
},
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"doing_business_as_name": {
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"name": {
"inquiry_data": "AERIAL TRADERS",
"match_data": "AERIAL TRADERS",
"match_strength_description": "Exact match",
"provider_match_type": "M01"
},
"national_tax_id": {
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"phone_number": {
"match_data": "6365558963",
"match_strength_description": "No match",
"provider_match_type": "M00"
}
},
"match_id": "2019-10-193196"
}
],
"termination_matches": [
{
"associate_match_fields": [
{
"address": {
"inquiry_data": {
"address_lines": [
"38, Crown Street, London, W1 2ZT"
],
"country": "GBR",
"locality": "London",
"type": "STRUCTURED"
},
"match_data": {
"address_lines": [
"596 BALBOA ROAD",
"SUITE 201"
],
"country": "USA",
"locality": "SAN DIEGO",
"postal_code": "92123",
"state_province": "CA",
"type": "STRUCTURED"
},
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"alt_phone_number": {
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"associate_id": "3b1ebb6b-a998-11ea-afe8-02410ca01124",
"driving_licence": {
"match_data": {
"country_code": "USA",
"document_type": "DRIVING_LICENCE",
"number": "*****"
},
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"name": {
"inquiry_data": "Blake Car",
"match_data": "Blake Carr",
"match_strength_description": "Phonetic match",
"provider_match_type": "M02"
},
"national_id": {
"match_data": "*****",
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"phone_number": {
"match_data": "3165557625",
"match_strength_description": "No match",
"provider_match_type": "M00"
}
}
],
"company_match_fields": {
"address": {
"inquiry_data": {
"address_lines": [
"38, Crown Street, London, W1 2ZT"
],
"country": "GBR",
"locality": "London",
"type": "STRUCTURED"
},
"match_data": {
"address_lines": [
"596 BALBOA ROAD",
"SUITE 201"
],
"country": "USA",
"locality": "SAN DIEGO",
"postal_code": "92123",
"state_province": "CA",
"type": "STRUCTURED"
},
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"doing_business_as_name": {
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"name": {
"inquiry_data": "AERIAL TRADERS",
"match_data": "AERIAL TRADERS",
"match_strength_description": "Exact match",
"provider_match_type": "M01"
},
"national_tax_id": {
"match_strength_description": "No match",
"provider_match_type": "M00"
},
"phone_number": {
"match_data": "6365558963",
"match_strength_description": "No match",
"provider_match_type": "M00"
}
},
"entry_date": "2019-02-10",
"match_id": "2019-02-101996",
"match_reason_code": "13 - Illegal Transactions",
"match_reason_description": "The merchant was engaged in illegal transactions",
"source_contact_details": [
{
"other_details": [
{
"name": "bank_name",
"value": "HSBC"
},
{
"name": "first_name",
"value": "Jon"
},
{
"name": "last_name",
"value": "Doe"
},
{
"name": "email",
"value": "jon.doe@hsbc.com"
},
{
"name": "phone_number",
"value": "05312315612"
}
],
"source_name": "HSBC"
}
]
}
]
}
},
"performed_on": "2020-06-29 14:27:50",
"providers": [
{
"instructed_on": "2020-06-29 14:27:50",
"is_monitored": true,
"provider_name": "Mastercard MATCH",
"variant_name": "MATCH"
}
],
"result": "Refer",
"started_on": "2020-06-29 14:27:50",
"state": "COMPLETE",
"task_ids": [ ... ],
"variant": { ... }
}

Use the response to confirm whether the check has any potential matches to terminated accounts:

  • If there aren't any, the decision is PASS.
  • If there is one or more, the decision is WARN.

The output_data object contains the information about any matches (termination or inquiry):

  • termination_matches: Shows any potential matches to the company or associate that have had their accounts terminated.
  • termination_matches.inquiry_data and termination_matches.match_data: Shows which data was matched.
  • termination_matches.match_strength_description: Indicates what kind of match was discovered (e.g. an exact match, phonetic match, or no match).
  • termination_matches.match_reason_code and termination_matches.match_reason_description: Provides the reason the match was terminated.
  • termination_matches.source_contact_details: Contains the contact information for the person on the data provider network who reported the account.
  • inquiry_matches: Contains any potential matches to the company or associate that have had their accounts recently searched by other members of the data provider's network. Note that these matches were not reported and did not have their accounts terminated. These matches will not cause the check decision to be WARN, and no action is required on them to progress the application.

The input_data object contains the details of the company and associate(s) searched in the provider's database.

If there are any potential matches to terminated accounts (i.e. the decision is WARN, a user should review the task to determine whether the matches are true matches or false positives).


How did we do?


Powered by HelpDocs (opens in a new tab)