Run merchant screening for payment facilitators

As a payment facilitator (PayFac), you can use the Digital Onboarding API to carry out essential screening checks on the sub-merchants who want to accept payments on your platform. The API enables you to comply with the requirement to screen your sub-merchants for network screening—such as Mastercard MATCH (Mastercard Alert to Control High-Risk Merchants) and Visa VMSS (Visa Merchant Screening Service) checks—as well as secondary screening for sanctions before you can enable them to process payments with J.P. Morgan.

This is referred to as "secondary screening" because you should have already screened your sub-merchants as part of your own know your customer (KYC) due diligence process, when the sub-merchant initially signs up for your services and products. The Digital Onboarding API facilitates not only the execution of network screening and secondary screening services but also allows you to pass the network registration details of your sub-merchant. This enables the API to orchestrate the Merchant Network Registration processes, such as enrollment in American Express Opt Blue (Amex Opt Blue).

Merchant screening confirms that your sub-merchant client does not have an issue that prevents them from participating in J.P. Morgan payment networks. Merchant screening complements your own background checks and KYC due diligence process.

Results of the screening process are represented in the API as:

• APPROVED The merchant screening is complete and your sub-merchant has been approved. They are permitted to use the payment network.
• DECLINED The merchant screening found a reason to decline your sub-merchant's access to the payment network. They are not permitted to use the payment network.
• TERMINATED You decide to manually stop the process or remove the sub-merchant from your platform. This status results when you call the /offboarding-requests API to indicate you will no longer process payments with the sub-merchant, or when you need to report a termination to J.P. Morgan and Mastercard MATCH for bad acting as defined by the card networks.

Within a 1-minute SLA, the API provides a response of approved or declined. Capture the result of the screening by performing a GET call to /parties/{partyId}. During this 1-minute SLA period, your sub-merchant reflects a status of REVIEW_IN_PROGRESS. This status may also appear beyond the SLA period if the downstream services cannot complete the screening of the sub-merchant with the provided details in the API. In this scenario, the issue is not exposed in the API. Contact your J.P. Morgan representative for support.

Use the Notifications API to subscribe to webhooks which publish your sub-merchant's status. The Notifications API is not part of the Digital Onboarding API but can be used in conjunction with it. The specific webhook event to subscribe to is EntityScreening in Digital onboarding events. For more details about access to the Notifications API, contact your J.P. Morgan representative.

Submit client details for screening

To perform the screening process:

1. Create a party to represent the sub-merchant using POST /parties. Both the organizationDetails and networkRegistration fields must be filled in.
2. Capture the information for at least one related party by creating additional parties with the parentPartyId set to the merchant party's id. This connects an individual to the merchant screening process.
3. Send the full information set for screening using POST /parties/{id}/validations with the merchant's partyID as the {id}.
4. Use GET /parties/{id} to track the screening process.

American Express Opt Blue requirements

If your sub-merchant participates in American Express Opt Blue (Amex Opt Blue), refer to Network registration details for required fields in the networkRegistration object of the party representing the merchant.

For the individual parties of merchants participating in Amex Opt Blue, a CONTROLLER role is required. The BENEFICIAL_OWNER role for the related party must be assigned for the following US organization types:

• Limited Liability Company (LLC)
• C Corporation
• S Corporation
• Non-Profit Corporation
• Sole Proprietorship
• Unincorporated Association
• Limited Liability Partnership (LLP)
• Limited Partnership
• General Partnership

Exemptions: Merchant organizations outside of the United States are exempt from the BENEFICIAL_OWNER requirement, and there are no restrictions on the assignment of the Beneficial Owner related party role, but these must have a CONTROLLER individual as noted. If your merchant is not participating in Amex Opt Blue, whether US-based or based outside the US, they may have either or both CONTROLLER or BENEFICIAL_OWNER roles. Note that a single individual related party may have both roles assigned in the API, and this satisfies the Amex Opt Blue requirement.

Valid ID types for screening

While the API accepts various enumeration values for organization and individual ID types, the network screening and secondary screening services downstream only accept specific ID types for the screening to work properly. You must use the following ID types based on your sub-merchant's country:

Organization ID types

Individual ID types

Before you begin

To conduct merchant screening, make sure you provide values for the following objects and fields:

General information about creating the party to represent the merchant

All of these fields are within the request body message:

• The parent party (the party you create first) must contain the networkRegistration object, including the payment methods to which your client settles.

Organization details

All of these fields are within the organizationDetails object:

• address Full address of your client's organization, including city and postal code.
• dbaName The name that your client's business operates under. This field is optional.
• website The URL for the website of your client's online business if they trade over the internet.
• websiteAvailable If a website is not available, you can omit the website field but must pass the websiteAvailable field as false instead. If providing a website, send the websiteAvailable field as true.
• organizationName The legal name of your client's organization. This may be the same as the DBA, or it may be different.
• mcc The Merchant Category Code (MCC) for your client.
  • secondaryMcc Add a secondary MCC if your client has more than one MCC.
• organizationIds.idType The ID type in the organizationDetails object. Note the ID requirements for valid organization ID types based on your sub-merchant's country as specified in the preceding section Valid ID types for screening.
• associatedCountries One or more countries in which your client's organization has done business or has a presence. For example, US.

Individual details

All of these fields are within the individualDetails object:

• firstName and lastName of the individual.
• addresses Full address of your client's representative, including city and postal code.
• individualIds Your client must provide one of the valid ID types based on their country as specified in the preceding section Valid ID types for screening. Use:
  • idType The type of individual ID provided by your client.
  • value The ID number for the provided ID type.
• parentPartyId When you create an individual related party, you must include parentPartyId with the organization party's id that is provided in the response after creating the organization party representing the merchant.

Network registration details

All of these fields are within the networkRegistration object:

• settlementPaymentMethods The methods of payment accepted by your sub-merchant which they will be registered with. You can add:
  • VISA for Visa debit and credit cards.
  • DISCOVER for Discover and Diners Club cards.
  • AMEX_OPT_BLUE for American Express cards.
• visaDebitAcceptance Whether your client intends to accept debit card payments from Visa. Required if Visa is selected as a settlementPaymentMethod. You can select:
  • DEBIT_ACCEPTED_ALL If your client accepts all Visa debit card payments.
  • DEBIT_ACCEPTED_CARD_PRESENT If your client accepts Visa debit cards only when the payment is in person. For example, in a physical store.
  • DEBIT_ACCEPTED_CARD_NOT_PRESENT If your client accepts Visa debit cards only when the payment is made online.
  • DEBIT_NOT_ACCEPTED If your client does not accept Visa debit. This means only Visa credit cards are accepted.
• currencyCode The currencies accepted. Only required if AMEX_OPT_BLUE is selected as a settlementPaymentMethod.
• transactionDeviceType The type of payment acceptance to be used. Accepted values are:
  • HOST_BASED_POS_DEVICE For online payments.
  • TERMINAL_BASED_POS_DEVICE For physical, in-store payments.
  • SOFTWARE_POS_DEVICE For payment through an app or other software.
  • ALL_OTHER_POS_DEVICES For payment through a device not available in the other options.
  • UNKNOWN For when the payment device is not known.
• serviceEstablishmentStatus If you previously boarded and registered your sub-merchant with the AMEX_OPT_BLUE network and it was terminated, you must add a value here. The accepted value:
  • R_REINSTATED If your sub-merchant's AMEX_OPT_BLUE service was cancelled and then reinstated.
• serviceEstablishmentStatusUpdateDate The date of the latest update of the merchant's AMEX_OPT_BLUE service. For example, "2025-01-25". This is required if you include a value for serviceEstablishmentStatus.
• settlementPaymentMethodsOptOut If no settlement payment methods are selected, you must set this value to true to confirm the following:
  • The merchant is not registered for any payment methods.
  • The merchant is not able to send an accidental request.

American Express Opt Blue required fields example

If your sub-merchant is participating in American Express Opt Blue for the first time and was not previously registered, you must include the following required fields in the networkRegistration object:

Where:

• settlementPaymentMethods Must include AMEX_OPT_BLUE.
• currencyCode The currency code for American Express transactions (for example, USD, GBP, or EUR).
• amexOptBlueMarketing Set to false if your sub-merchant does not want to participate in American Express marketing programs, or true if they do.

Create a party for merchant screening

To enter your sub-merchant's details for screening:

1. Go to POST /parties.
2. In the request body, add the following required fields:
   • partyType The value must be ORGANIZATION for the merchant organization.
   • organizationDetails The details of the merchant organization.
   • networkRegistration The network registration details, including settlement payment methods.
3. Send the request.
4. Make a note of the id in the response. This is the parent party ID that you will use when creating related parties (individuals) and submitting for validation.

Here is a sample of a complete POST /parties request with partyId for a merchant organization:

In the response, you receive the id for your newly created party:

Create related parties

You can screen additional individuals related to your sub-merchant's business by creating a new party connected to the organization using its ID as a parentPartyId.

To add individuals associated with the sub-merchant:

1. Send a new POST /parties request, with the sub-merchant's organization's partyId as the value for parentPartyId.
2. In the request body, add the following required fields:
   • partyType The value must be INDIVIDUAL for related party individuals.
   • individualDetails The details of the individual.
   • roles The role of this individual, such as CONTROLLER or BENEFICIAL_OWNER.
3. Send the request.
4. Repeat these steps for each individual associated with the merchant.

Example request payload for POST /parties if the root party's ID is 2000000555:

Example response for an approved additional party:

Submit the merchant for screening

To submit the sub-merchant and all related parties for screening:

1. Go to POST /parties/{id}/validations.
2. Use the parent party id (the sub-merchant organization) as the {id} in the request.
3. Do not include a request body.
4. Send the request.
5. The screening process begins automatically.

A successful response confirms the date and time the request was accepted. For example:

Check the status of a merchant screening request

To check the status of a screening request, use GET /parties/{id}. Use the parent party ID as the {id} in this request.

Subscribe to the Notifications API webhooks to receive real-time updates on your sub-merchant's screening status. Subscribe to the EntityScreening event in Digital onboarding events. For more details on access to the Notifications API, contact your J.P. Morgan representative.

In the response, check the profileStatus for the most up-to-date status of your merchant screening request. Possible values are:

• NEW You have not yet submitted the party details for screening. If unexpected, make sure you sent the POST /parties/{id}/validations request.
• REVIEW_IN_PROGRESS Merchant screening is in progress. If your sub-merchant status remains in REVIEW_IN_PROGRESS longer than the 1-minute SLA period, there is an issue where the screening was unable to be completed due to the data provided or a downstream issue. Contact your J.P. Morgan representative for support.
• APPROVED Merchant screening is complete and your sub-merchant has been approved.
• DECLINED Merchant screening found a reason to decline your sub-merchant's access to the payment network.
• TERMINATED You decide to manually stop the process or remove the sub-merchant from your platform. This status results when you call the /offboarding-requests API to indicate you will no longer process payments with the sub-merchant, or when you need to report a termination to J.P. Morgan and Mastercard MATCH for bad acting as defined by the card networks.

The response shows the status of the request:

Example response with a profileStatus of APPROVED. Your sub-merchant passed the merchant screening successfully:

Update merchant details

If you need to update merchant details after the initial screening:

After the screening request is complete (when profileStatus is APPROVED), you are permitted to update the following fields for your sub-merchant:

• address Address details within the organizationDetails or individualDetails object
• email The email address of the party
• phone Phone details within the organizationDetails or individualDetails object

Important notes:

• PATCH calls are not permitted while the screening request is in process (when profileStatus is REVIEW_IN_PROGRESS).
• While profileStatus is NEW, update all fields of a party as needed with PATCH before you send the POST /parties/{id}/validations call.

To update permitted fields:

1. Go to PATCH /parties/{id}.
2. Use the party id of the merchant or individual you want to update.
3. In the request body, include only the fields you want to update.
4. Send the request.
5. The response reflects the updated party record.

Example PATCH request

Here is an example of updating the phone number for a sub-merchant organization:

PATCH /parties/2001484074

Example PATCH response

The response reflects the updated phone number:

Example PATCH request for address update

Here is an example of updating the business address for a sub-merchant organization. Note that while the party is getting a new street address and the city, state, and postal code remain the same, all address fields are required in the request:

PATCH /parties/2001484074

Example PATCH response for address update

The response reflects the updated business address:

Offboarding a sub-merchant party

Use the offboarding request to offboard a sub-merchant and stop processing for that sub-merchant.

The POST /offboarding-requests call supports offboarding the root party of the sub-merchant business. A successful offboarding request results in a profileStatus of TERMINATED. This request supports requirements by the card networks for when your sub-merchant is reported to be bad-acting as defined by the card networks, and when using the appropriate reason, it will orchestrate sending the Mastercard MATCH termination (addition) request.

To offboard a sub-merchant:

1. Go to POST /offboarding-requests.
2. In the request body, include:
   • partyId — The ID of the merchant party to offboard.
   • reason — The reason for offboarding. See the supported reason codes below.
3. Send the request.
4. The merchant's status changes to TERMINATED and is reported to J.P. Morgan and the relevant card networks, such as Mastercard MATCH.

Supported offboarding reason codes

The reason field describes why the sub-merchant is being offboarded. The following reason codes are supported:

• EXCESSIVE_FRAUD The merchant effected fraudulent transactions of any type (counterfeit or otherwise) meeting or exceeding the following minimum reporting standard: the merchant's fraud-to-sales dollar volume ratio was 8% or greater in a calendar month, and the merchant effected 10 or more fraudulent transactions totaling USD 5,000 or more in that calendar month.

• EXCESSIVE_DISPUTES With respect to a merchant reported by a Mastercard acquirer, the number of Mastercard chargebacks in any single month exceeded 1% of the number of Mastercard sale transactions in that month, and those chargebacks totaled USD 5,000 or more. With respect to a merchant reported by an American Express acquirer (ICA numbers 102 through 125), the merchant exceeded the chargeback thresholds of American Express, as determined by American Express.

• TRANSACTION_LAUNDERING The Merchant engaged in laundering activity. Laundering means that a merchant presented to its acquirer transaction records that were not valid transactions for sales of goods or services between that merchant and a bona fide cardholder.

• ILLEGAL_TRANSACTIONS The merchant engaged in illegal transactions.

• COMMON_POINT_OF_PURCHASE Account data is stolen at the merchant and then used for fraudulent purchases at other merchant locations.

• BANKRUPTCY_LIQUIDATION_INSOLVENCY The merchant was unable or is likely to become unable to discharge its financial obligations.

• MERCHANT_OR_THIRD_PARTY_VIOLATION With respect to a merchant reported by a Mastercard acquirer, the merchant was in violation of one or more standards that describe procedures to be employed by the merchant in transactions in which cards are used, including, by way of example and not cardholders, minimum or maximum transaction amount restrictions, and prohibited transactions set forth in chapter 5 of the Mastercard Rules manual. With respect to a merchant reported by an American Express acquirer (ICA numbers 102 through 125), the merchant was in violation of one or more American Express bylaws, rules, operating regulations, and policies that set forth procedures to be employed by the merchant in transactions in which American Express cards are used.

• ACCOUNT_INFORMATION_SECURITY_NONCOMPLIANCE The merchant failed to comply with Payment Card Industry (PCI) Data Security Standard requirements.

• ACCOUNT_DATA_COMPROMISE An occurrence that results, directly or indirectly, in the unauthorized access to or disclosure of account data.

• MERCHANT_IDENTITY_THEFT The acquirer has reason to believe that the identity of the listed merchant or its principal owner(s) was unlawfully assumed for the purpose of unlawfully entering into a merchant agreement.

• PAYMENT_NETWORK_DISQUALIFICATION The merchant was determined to be a questionable merchant as per the criteria set forth in the Mastercard Questionable Merchant Audit Program (refer to section 8.4 of the Security Rules and Procedures manual).

• BUSINESS_REASON The merchant is being offboarded by the platform due to strategic or operational business decisions rather than compliance issues or violations of payment network rules. This may include but is not limited to mutual agreement, merchant-initiated decision, platform-initiated decision, or end of contractual term. This reason code can also be used to terminate and resubmit a sub-merchant party with data corrections when the party is stuck in an interim status (such as profileStatus = REVIEW_IN_PROGRESS) due to invalid data provided to downstream services in the screening request.

Example offboarding request

Here is an example of offboarding a sub-merchant using the BUSINESS_REASON code:

POST /offboarding-requests

Example offboarding response

The response confirms acceptance of the offboarding request:

To verify the offboarding request, perform a GET /parties/{partyId} call using the sub-merchant's partyId. If offboarded, the response shows the updated profileStatus of TERMINATED. If you are subscribed to webhooks via the Notifications API, we publish the EntityScreening event with the updated status as well.

Next steps

Review the testing page to help with your implementation of merchant screening.