Skip to main content

Run a Merchant fraud check using the 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.

Choose a profile and get the profile 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, for example, 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 profile yet, follow the steps to create a profile using 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:

  • Confirm the profile has the Assess merchant fraud risk task (COMPANY_MERCHANT_FRAUD_SCREENING).

  • 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.

  • Confirm the profile has data for these required keys, which are in the collected_data object:

    • metadata.name: The company's name.

    • metadata.addresses: An array of objects containing the company's address history.

  • 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 using the API.

To learn how to add/update the fields in the profile's collected_data, see Update Passfort's profile data.

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 Merchant fraud check runs 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

check_type

*Required

string

COMPANY_MERCHANT_FRAUD_SCREENING

variant.alias

Optional

array of string

Sample value:

merchant_fraud

task_ids

Optional, but we recommend including it whenever possible.

array of string

Sample value:

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

variant

*Required

object

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

variant.alias

*Required

string

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

Sample value:

default

variant.id

*Required

string

This key is optional if variant.alias is provided.

Sample value:

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

Sample request body:

{
   "check_type": "COMPANY_MERCHANT_FRAUD_SCREENING",
    "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 to 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:

  • 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 captured in Run the check.

  • data.check.check_type: The type of check was run. When the Merchant fraud check was run, the value is COMPANY_MERCHANT_FRAUD_SCREENING.

  • 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 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 Get 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 want to work through the following sections to learn whether there are any inquiry matches.

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

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, either 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, for example, 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, the decision is WARN, a user should review the task to determine whether the matches are true matches or false positives.

Additional information

In this section: