Onboard a client

Overview of endpoints in the onboarding process

Take a look at the requests that you need to use to construct an onboarding experience for your client:

1. POST /commerce/v1/clients - send basic client information, create a party to represent the client's business, and to get a client ID. In the response you receive outstanding onboarding requirements:
   • Due diligence question IDs.
   • Required documents.
   • Required attestations.
2. GET /commerce/v1/questions - to retrieve additional client onboarding questions that your client must answer. The POST /commerce/v1/clients response contains the question IDs.
3. PATCH /commerce/v1/clients/{id} - to send more detailed information required for CIP (Customer Identification Program), including answers to outstanding questions.
4. GET /commerce/v1/documents/{id}/file - get documents that must be read and attested by your client.
5. POST /commerce/v1/clients/{id}/verifications - send an instruction to J.P. Morgan to perform the due diligence and verification checks to complete onboarding.
6. GET /commerce/v1/clients/{id} - to check the onboarding status of your client.

Endpoints for onboarding

All onboarding endpoints use the clients resource, and include commerce in the path URL, for example:

https://{baseurl}/commerce/v1/clients

Create a client profile with minimum data

To create a client, send a POST /commerce/v1/clients request with:

• A parties list of objects.
• A product with the value MERCHANT_SERVICES.

These objects contain both information about the client as an organization party, and an individual party who can act as the controller for the client business.

In your parties objects, include:

• partyType: ORGANIZATION for the client organization.
• partyType: INDIVIDUAL to represent the controller.
• externalId: Your own unique identifier for the client organization, individual, and subsequent individual party. The externalId field is optional.
• roles: Must be CLIENT for ORGANIZATION and CONTROLLER for INDIVIDUAL party. For additional owners, with more than a 25% ownership of the company, you must also add a party with the role BENEFICIAL_OWNER .
• organizationDetails for the organization must include:
  • organizationType
  • organizationName
  • At least one entry in addresses.
• individualDetails for the individual party must include:
  • firstName
  • lastName

Sample createClient request body with minimum data:

Create a client profile with full data

You can also send a full payload with all the required information about your client and their organization.

The following example is a complete request with all required fields populated for a sole proprietorship organization. The complete request includes details about the organization's industry type. For reference information on the North American Industry Classification System (NAICS), go here. 

Sample createClient request body with complete data:

Complete due diligence questions

Due diligence questions are an essential part of onboarding your client to J.P. Morgan Payments. Questions must be asked in the exact wording provided, and answers returned in the required format.

The format of answers can be:

• Boolean (True/False)
• String (Description or Drop down selection)
• Integer (Numeric value) and Date.

To complete due diligence questions for a client, you must:

1. Retrieve the question IDs. You find these in the outstanding object in the success response to any of these calls:
   • GET /commerce/v1/clients/{id}
   • POST /commerce/v1/clients
   • POST /commerce/v1/clients/{id}
2. Get the questions to display to your client using GET /commerce/v1/questions, including a comma-separated list of question IDs in the questionIds parameter. These can include follow-up questions in subQuestions.
3. Send the answers, in the format provided by each question, using PATCH /commerce/v1/clients/{id}. Include any answers to follow-up questions.

Get the questions to ask your client

A successful 200 or 201 response to the preceding /commerce/v1/clients requests includes an outstanding object. Within outstanding is a list of questionIds.

If questionIds is populated, you must retrieve the questions using their ID and present them to your client.

Sample response to /commerce/v1/clients with questionIds 300001, 300002, 300003.

Present the questions

Send a request to GET /commerce/v1/questions with the questionIds in the request parameters.

Sample request:

Sample response:

Capturing 'child' answers to follow-up questions

In some cases, you must send additional information or an answer to a further question.

Follow-up questions are only required if the answer to the parent question is positive (that is, your user answers "true" to the parent question).

In the following example, when the user answers "true" to question ID 30026, the follow-up question ID 30027 is required. Only show the child question ID 30027 to your client if the response to question ID 30026 is "true":

Send the question responses

In the response to a GET /commerce/v1/questions request, responseSchema tells you how to present each question to your client and how the client expresses their answer.

After you present the questions and gather the answers, send the question responses using PATCH /commerce/v1/clients/{id}.

Sample of answers in the questionResponses object:

Client attestations and additional documents

In addition to customer onboarding questions, your client must also complete:

• Attestations listed in attestationDocumentIds: contains the outstanding attestations that the client must complete - such as disclosure and consent forms, and terms and conditions. The object tells you which documents are required by ID, which you can then request using GET /commerce/v1/documents/{id}.
• Documents listed in documentRequestIds: contains any supported documents that may be required, depending on the verification details already submitted. This can include copies of documents that support the verifications, such as a Social Security document.

Get and send attestations

Your client must be able to show that they agree to the terms and conditions of Merchant Services, as well as giving their consent for their data to be used.

To send attestations:

1. Call GET /commerce/v1/clients/{id} (or check the response to a POST request to the same endpoint). In the response, an attestation is required when the attestationDocumentIds field in the outstanding object is populated.
2. Call GET /commerce/v1/documents/{attestationDocumentId}. In the response, the documentType field shows which document must be attested by the client.
3. Call GET /commerce/v1/documents/{attestationDocumentId}/file to return the document itself, so you can display it to your client.
4. Send a PATCH /commerce/v1/clients/{id} to pass the attestation.

Get attestation documents

Determine the required documents that need to be attested in a response to any of the following calls:

• GET /commerce/v1/clients
• POST /commerce/v1/clients
• POST /commerce/v1/clients/{id}

In the following response example, document ID 62d29548-f55a-458e-b9bb-ed32a6a05a1b requires client attestation.

To check the required document type that you need to present to your client, send a request to GET /commerce/v1/documents/{id} with an ID from the attestationDocumentIds in the path.

To access the file itself, send a request to GET /commerce/v1/documents/{id}/file.

The response carries the document that can be displayed in your platform experience.

Present attestations to your client

Your clients agree to terms and conditions and the content of other written documents when they make their attestation.

Present attestation documents to your client in a format they can easily read, and provide some interaction so they can demonstrate that they have read and understood what they are attesting.

For example, refer to the following sample text that can be accompanied by check box to show your client agrees:

• To attest terms and conditions:
  • I have read and agree to the Terms and Conditions, the Merchant Account Agreement, and the preceding certifications.
• To verify information being sent is accurate:
  • I, client name here, hereby certify, to the best of my knowledge, that the information provided is complete and correct.

Send attestation

To send the attestation, call PATCH /commerce/v1/clients/{id} and include the following required information in the addAttestations object:

• attesterFullName - The full name of the party attesting.
• attestationTime - A timestamp of the attestation.
• documentId - The given ID of the document being attested - this is the same attestationDocumentIds value you used to get the document.
• ipAddress - The client's IP address from which the attestation was made.

Sample addAttestations request:

Complete the onboarding steps

After you submit all the required documents, attestations, and answers, you can request the completion of the onboarding process.

To complete the onboarding process, send a POST /commerce/v1/clients/{id}/verifications request. J.P. Morgan performs the required checks and due diligence processes. In many cases, your client is likely to be onboarded without further input after this point. In some cases, more information can be requested. 

Sample request:

If successful, you receive a 202 Accepted response.

Send additional documents

After submitting all client details for verification, your client may still be asked to upload documents to confirm the identity of the party being onboarded. For example, they may need to upload a copy of their Driver's License.

To add additional documentation:

1. Send a GET /commerce/v1/clients/{id} request and check the outstanding object. If an additional document is required, the documentRequestIds field is populated with an ID.
2. Send a GET /commerce/v1/document-requests/{id} request. The response contains the required document type that must be uploaded.
3. Your client must provide the additional document direct to J.P. Morgan. 

Sample response GET /commerce/v1/clients/{id} with documentRequestIds populated:

Check which additional documents are required

Verify the required documents in the response to a POST /commerce/v1/clients or PATCH /commerce/v1/clients/{id} request.

Sample with outstanding documentRequestIds:

Understand client and party onboarding status

You can update outstanding information about the client by sending a PATCH request to /commerce/v1/clients/{id}..

The status values on the response shows you how far your client, and related parties, have been onboarded.

Client status

customerIdentityStatus represents the progress of the client's CIP verification.

Possible values:

• NOT_STARTED - CIP verification has not started. The request has not been submitted.
• REVIEW_IN_PROGRESS - Onboarding verifications have started and are in progress. During review, you may need to collect additional documents or information - which is shown in the outstanding object in the GET /commerce/v1/clients/{ID} request.
• INFORMATION_REQUESTED - Your client or related parties must provide additional information or documents to proceed with verification. When the requested information is provided, client status becomes REVIEW_IN_PROGRESS.
• APPROVED - Your client's CIP verification is complete.

status represents the overall progress - CIP verification and KYC - of your client's onboarding journey. status cannot complete - APPROVED - until all onboarding stages have been completed for both the client and related parties.

Possible values:

• NEW - Onboarding verifications haven't started yet since there isn't enough information available yet.
• REVIEW_IN_PROGRESS - Onboarding verifications have started and are in progress. During review, you may need to collect additional documents or information - which is shown in the outstanding object in the GET /commerce/v1/clients/{ID} request.
• INFORMATION_REQUESTED - Your client or related parties must provide additional information or documents to proceed with verification. After the requested information is provided, status changes to REVIEW_IN_PROGRESS.
• APPROVED - Your client and all related parties have successfully completed due diligence and onboarding.
• DECLINED - Your client cannot be onboarded based on their response to our due diligence processes.
• SUSPENDED - Either:
  • During onboarding, your client hasn't provided requested information or documents within the defined period.
  • After onboarding, you placed a request to temporarily make the client's account inactive.
• TERMINATED - You have placed a request to permanently terminate your client's Merchant Services accounts.

Profile status

profileStatus represents the onboarding status of a party. The term profile refers to the party profile kept on each party associated with a client.

Possible values:

• REVIEW_IN_PROGRESS - Either:
  • Due diligence review is in progress.
  • During review, a request has been placed to collect additional documents or information.
• INFORMATION_REQUESTED - Your client's Beneficial Owner or Controller is requested to provide additional information or documents to proceed with verification.
• APPROVED - Your client's Beneficial Owner or Controller has completed onboarding. This may not yet mean that your client has completed all the onboarding stages, but this party is onboarded.

Show your client their details

To get all information in your client's Merchant Services profile, use the request GET /clients/{id}, using the clientId in the path.

Sample request:

Reference table of fields for POST /clients

Next steps

As soon as your client completes onboarding, you can set up their Merchant Services account.