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.
Prerequisites
- A
ClientIdand an API key – if you don’t have these, contact Sales to get access to the Mangopay Hub - An Owner user (natural or legal)
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.
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}
5. Set up relevant hooks (recommended)
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
KYCLevelparameter of the user object has changed toREGULAR
For more information on the requirements for user verification, see:
Guide
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:
- Go to the Sandbox operations section.
- Select Process a KYC document.
- Enter the identifiers of the document and the user, then select the action you want to simulate.
- Click Submit to send the response.
Related resources
Was this page helpful?