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_dataobject: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
INDIVIDUALentity type and anaddress. 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}/checksBy 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 |
*Required string |
|
Optional array of string | Sample value:
|
Optional, but we recommend including it whenever possible. array of string | Sample value:
|
*Required object | For a sample value, see the following sample request body. |
*Required string This key is optional if | Sample value:
|
*Required string This key is optional if | Sample value:
|
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 isCOMPANY_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 arePass,Refer, orError. If there are no potential matches to terminated accounts, the decision isPass. If there are one or more, the decision isRefer.
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
decisionisPASS.If there is one or more, the
decisionisWARN.
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_dataandtermination_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_codeandtermination_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 beWARN, 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.