​
Introduction

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

Prerequisites

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.

Note - Follow best practices for identity documents

IDENTITY_PROOF documents must adhere to best practices to avoid refusal. Communicate our guidelines for IDs to your end users to help them upload good-quality documents and optimize your acceptance rate.

​
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. Create the page for the user’s file

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 Document validation process article.

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

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

Warning - Storage of KYC documents prohibited

You’re not allowed to store verification documents (in any format, even encoded) on your side unless you have permission from the appropriate authorities in your country.

​
3. Create additional pages 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.

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 one KYC Document Page. If a translation, this can be uploaded as a second file.

​
4. Submit the KYC Document

Once all pages 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}

There are dedicated hooks to provide 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.

Note - Refused or downgraded documents must be re-created

A KYC Document with the status REFUSED or OUT_OF_DATE can’t be re-submitted. You need to create a new document and submit it again.

In the case of a refusal, information about why it was refused is available in the RefusedReasonType and RefusedReasonMessage parameters.

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:

Guide

Requirements by user type

​
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.

Guide

Learn about verification requirements for natural persons

Guide

Learn about verification requirements for legal entities

Was this page helpful?

SubmissionID best practices