How to submit a KYC Document

​

Introduction

This how-to guide will show you how to successfully submit a KYC Document for validation by Mangopay.

The KYC Document object allows you to submit any type of verification document for your users. Find out more about the different types in the Types of verification document article.

​

1. Create the KYC Document

Create the document with the UserId and indicate which type is being submitted.

POST /v2.01/{ClientId}/users/{UserId}/kyc/documents

The response shows the Status “CREATED” and contains an Id, which is the unique identifier of the KYC Document object. You need to save this for the next step.

​

2. Upload a file to the KYC Document

Now that you have created the KYC Document container, you can upload files to it to be submitted.

With the Id of the KYC Document as the KycDocumentId path parameter, create the KYC Document Page containing the file uploaded by the user. The file must be encoded in Base64 (which is handled natively in our SDKs) and respect the format and size constraints described in the submission article.

POST /v2.01/{ClientId}/users/{UserId}/kyc/documents/{KycDocumentId}/pages

The 204 No content response means that the file has been uploaded successfully.

​

3. Upload additional files as needed

Repeat Step 2 as many times as necessary. Each file of the real-life document requires a separate API call (Step 2) to upload the file in a dedicated KYC Document Page.

You can upload up to 5 files to each KYC Document, and each upload requires a call to the POST Create a KYC Document Page endpoint. Each file can contain as many real-life pages as required.

For example:

• National identity cards typically have 2 files: the front side and back side of the card.
• Passports have 1 file: the full-page spread displaying the photo.
• Documents for legal users may have many physical pages but in one file, so requiring one API call to create the KYC Document Page. If a translation is required, this can be uploaded as a second file.

​

4. Submit the KYC Document

Once all files are uploaded, submit the document for review by Mangopay’s teams by changing the Status from CREATED to VALIDATION_ASKED.

PUT/v2.01/{ClientId}/users/{UserId}/kyc/documents/{KycDocumentId}

​

5. Set up relevant webhooks (recommended)

There are dedicated event types to provide webhook notifications of the outcome of the review by Mangopay:

• KYC_SUCCEEDED, notifying that the KYC Document status has changed to VALIDATED.
• KYC_FAILED, notifying that the KYC Document status has changed to REFUSED.

For the IDENTITY_PROOF and REGISTRATION_PROOF documents, the document can be downgraded as a result of modifying user information. This is notified with the hook:

• KYC_OUTDATED, notifying that the status has changed to OUT_OF_DATE.

If all the required documents are validated, then the user obtains the verified status. You can be notified of this event with the hook:

• USER_KYC_REGULAR, notifying that the KYCLevel parameter of the user object has changed to REGULAR

For more information on the requirements for user verification, see:

​

6. Simulate the response from Mangopay in Sandbox

The outcome of Mangopay’s review is indicated by the change of status of the document.

In the Dashboard, you can simulate the response from Mangopay:

1. Go to the Sandbox operations section.
2. Select Process a KYC document.
3. Enter the identifiers of the document and the user, then select the action you want to simulate.
4. Click Submit to send the response.

​

Related resources