Run merchant screening

As a payment facilitator (Payfac), you can use the Onboarding API to carry out essential screening checks on the merchants who want to accept payments on your platform.

Merchant screening is a way to confirm that your merchant clients do not have any issues to prevent them from participating in J.P. Morgan payment networks. It complements your own background checks and Know Your Customer (KYC) due diligence process.

There are three possible outcomes of the screening process, represented in the API as:

• APPROVED — The merchant screening is complete and your client has been approved. They are permitted to use the payment network.
• DECLINED — The merchant screening found a reason to decline your client's access to the payment network. They are not permitted to use the payment network.
• TERMINATED — Your merchant decides to manually stop the process and cannot be added as a merchant on your platform. 

Submit client details for screening

To perform the screening process:

1. Create a party to represent the 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.

Once you have sent the merchant's details for screening, they are automatically screened periodically to ensure they are still able to use J.P. Morgan banking and payment services.

Before you begin

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

General information about the party being created to represent the merchant

All of these fields are within the createPartyRequest object:

• externalId — Your own unique identifier for your client.
• partyType — Whether your client is an INDIVIDUAL or an ORGANIZATION. In most cases, the party is an ORGANIZATION. In this case, you need to add information about the organization and an associated individual — either a BENEFICIAL_OWNER or a CONTROLLER. 
• The parent party (the party you create first) must contain the networkRegistration object, including the payment methods your client will settle to. 

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 is operating under.
• websiteAvailable — Whether or not your client trades over the internet.
• website — The URL for the website of your client's online business if they trade over the internet.
• organizationName — The legal name of your client's organization. This may be the same as the DBA, or it may be different.
• mcc — Merchant Category Code (MCC) for your client.
  • secondaryMcc — To be added if your client has more than one MCC.
• organizationIds.idType — The ID type in the organizationDetails object. The value for this can be either BUSINESS_REGISTRATION_ID or EIN.
• associatedCountries — Any country 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 three types of using:
  • idType — The type of individual ID provided by your client. One each for PASSPORT, SSN (Social Security Number), or NATIONAL_ID.
  • The value is the passport number, Social Security Number (SSN), or national ID number for the ID.

Network registration details

These fields represent the payment types your merchant client intends to use, and related information. Some of these fields are dependent on the payment methods accepted by your clients.

All of these fields are within the networkRegistration object:

• settlementPaymentMethods — The methods of payment accepted (and settled). You can add:
  • VISA — for Visa debit and credit cards.
  • DISCOVER — for Discover 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 cient 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 your client previously used the AMEX_OPT_BLUE network and it was terminated, you must add a value here. Accepted values:
  • D_CANCELLED — If your client's AMEX_OPT_BLUE service was cancelled for derogatory or negative reasons.
  • N_CANCELLED — If your client's AMEX_OPT_BLUE service was cancelled for normal reasons.
  • R_REINSTATED — If your client'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, "2024-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 you do not want the merchant to be screened for any payment methods. This is to prevent accidental requests being sent without this important information.  

Create a party for merchant screening

To enter your client's details for screening:

1. Send all required party details for both individuals and your client's organization using POST /parties.
2. If needed, add any additional individuals to your client using POST /parties  with the ID returned in your POST/ parties request as the parentPartyId.
3. Send the request to POST /parties/{id}/validations.
4. Check the status of the screening with GET /parties/{id}.

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

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

Add related individuals to a screening request

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

To add related parties to the root party:

1. Send a further POST /parties request, with the organization's partyId as the value for parentPartyId.
2. Specify the related party's relationship via the roles field. There should be at least one CONTROLLER or BENEFICIAL_OWNER associated with the organization.

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

Example Response for an approved additional party:

Send the completed party details for screening

To complete the screening request, send a request to POST /parties/{id}/validations without a request body. Use the parent party ID as the {id} in this request. 

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, you can use GET /parties/{id}. Use the parent party ID as the {id} in this request. 

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

• NEW — When you have not yet submitted the party details for screening. Make sure you have sent the request using POST /parties/{id}/validations.
• REVIEW_IN_PROGRESS — When the merchant screening is in progress.
• APPROVED — When the merchant screening is complete and your client has been approved.
• DECLINED — When the merchant screening found a reason to decline your client's access to the payment network.
• TERMINATED — When Your merchant decides to manually stop the process and cannot be added as a merchant on your platform.

The response shows the status of the request:

Example response showing profileStatus: "APPROVED". This means your client has passed the merchant screening successfully:

You have completed the merchant screening process. 

Next steps

Take a look at the testing pages to help with your implementation of Merchant screening.