Dealing with refusals

If Mangopay doesn’t validate a document, you may be able to obtain more information about the reason why with the GET View a KYC Document endpoint.

Two returned parameters may prove useful:

• Flags - One or several codes which give more information about the identity proof document type. See the flags list below for more information.
• RefusedReasonType - Information about the refusal reason for all types of documents. See the list of refused reason types below for more information.

Once the reason for refusal is identified, you can create a new KYC Document and resubmit it to Mangopay.

Note - RefusedReasonType hierarchy

Because a refused document can have multiple flags, RefusedReasonType values are given a hierarchy to display the most relevant flags first. The order of criticality is as follows:

1. DOCUMENT_FALSIFIED
2. DOCUMENT_HAS_EXPIRED
3. DOCUMENT_NOT_ACCEPTED
4. DOCUMENT_UNREADABLE
5. DOCUMENT_INCOMPLETE
6. DOCUMENT_DO_NOT_MATCH_USER_DATA
7. UNDERAGE_PERSON

Flags list

Flag	Description
009000	The document is suspected to be fraudulent, which means: The user will be blocked until reception of a valid identity proof (document with better visual quality or a different accepted identity proof) Mangopay’s team will check all related transactions
009001	The fonts analyzed don’t match those expected for the kind of identity proof submitted (e.g. for a French national identity card).
009002	The picture of the person is altered.
009003	The document is partially or totally covered.
009004	The document is blurred.
009005	The document is cut off: piece of information missing, machine-readable zone (MRZ) not readable, etc.
009006	The document is not readable due a glare on the photo.
009007	The incorrect side of the document was submitted.
009008	Two different documents were uploaded at the same time.
009009	The document is not accepted (deprecated since June 13th, 2022). Please contact the Mangopay Support team.
009010	There is no document in the image.
009011	The photo of the document is too dark.
009012	The document is damaged.
009013	The document has a punched hole.
009014	The document corner has been physically cut off.
009015	The document contains severely diminished colors (due to resolution issues, low-quality liquid scan rather than photo, or washed-out background for instance).
009016	The document has a glare obscuring a security chip.
009017	Some features of the document are obscured.
009018	The back of the document is needed for processing.
009019	Mangopay doesn’t support this kind of document.
009020	The document owner is under the age of 18 years old.
009021	The document has expired.
009022	The first name on the identity document doesn’t match the declared information in: The FirstName parameter for a natural user. The LegalRepresentativeFirstName parameter for a legal user.
009023	The last name on the identity document doesn’t match the declared information in: The LastName parameter for a natural user. The LegalRepresentativeLastName parameter for a legal user. Note that for French identity documents, Mangopay supports the spouse name, widow’s name, or alias name as declared LastName (or LegalRepresentativeLastName).
009024	The document information is not readable because the image resolution is too low (please note that prior to June 13th, 2022, the 009009 error was returned instead).
009025	The document information is not readable because the image is in black and white (rather than in color).
009026	The document is considered paper-based (printed on paper), rather than being a card or passport format.
009100	A match couldn’t be made with a relevant flag, but you can find out more about the issue by reviewing the RefusedReasonType and RefusedReasonMessage values. Please contact the Support team via the Dashboard if you require further details.

Refused reason types

The tables below describe each RefusedReasonType as it relates to the document type, along with recommendations for resubmitting the document. The labels used in the Mangopay Dashboard are given alongside.

Ensure you also check the RefusedReasonMessage parameter for personalized information from Mangopay’s teams, which is also shown in the Dashboard.

Identity proof

Refused reason type	Issue	Recommendation
API: DOCUMENT_MISSING Dashboard: MISSING	The document is missing from the image or the file.	Check that you upload the correct file and that it contains the identity proof. Check the Accepted ID documents know which document is accepted for the identity proof in your case.
API: DOCUMENT_INCOMPLETE Dashboard: INCOMPLETE	The document is incomplete, for example the back of the identity card is missing.	Check that you upload the correct file and that it contains both sides of the identity proof (if applicable).
API: DOCUMENT_UNREADABLE Dashboard: UNREADABLE	Readability refers not only to the clarity of personal information but also to the visibility of security features that help verify the document’s authenticity. Issues such as low image resolution, glare, shadows, blurriness, modified contrast, or the document being cutoff in the image frame may lead to this result.	Take a new picture of the identity document, ensuring the ID best practices are followed, before re-submitting the document.
API: DOCUMENT_NOT_ACCEPTED Dashboard: NOT ACCEPTED	The document is not accepted; it doesn’t fit the verification requirements outlined by us.	Check the Accepted ID documents know which document is accepted for the identity proof in your case.
API: DOCUMENT_DO_NOT_MATCH_USER_DATA Dashboard: DATA MISMATCH	The individual indicated on the document doesn’t correspond to the one registered.	Check that you upload the correct file and that it contains the identity proof of the user.
API: DOCUMENT_HAS_EXPIRED Dashboard: EXPIRED	The document has passed its expiry date; it is no longer valid.	Submit an in-date accepted identity proof.
API: DOCUMENT_FALSIFIED Dashboard: FALSIFIED	The document seems to be fraudulent or contains inconsistent information.	Check that the document is in line with the requirements and ID best practices and has not been altered by any means.
API: SPECIFIC_CASE Dashboard: SPECIFIC	Specific or multiple issues.	Refer to the RefusedReasonMessage for details.
API: UNDERAGE_PERSON Dashboard: UNDERAGE	The individual indicated on the document is under 18.	Mangopay users must be 18 years old or older.

Registration proof

Refused reason type	Issue	Recommendation
API: DOCUMENT_MISSING Dashboard: MISSING	The document is missing from the image or the file.	Check that the uploaded file is in one of the accepted formats (PDF, JPEG, JPG, PNG) and complies with size requirements (min. 1KB; max. about 7MB (10MB when Base64 encoded)). The file must be accessible and not password protected.
API: DOCUMENT_INCOMPLETE Dashboard: INCOMPLETE	The document is incomplete or not sufficient on its own.	Ensure the document is dated and that all pages are present and in one of the supported languages (or along with a sworn translation). For most countries, declared legal representative should appear in the document. In some cases, an additional document may be requested, for example: Registration proof of the company president Appointment of a director Refer to the RefusedReasonMessage for more details.
API: DOCUMENT_UNREADABLE Dashboard: UNREADABLE	The document is not clear enough.	Check the clarity and readability of your file before re-submitting a clear and up-to-date accepted registration proof.
API: DOCUMENT_NOT_ACCEPTED Dashboard: NOT ACCEPTED	The document is not accepted; it doesn’t fit the verification requirements outlined by us.	Check the Accepted local KYB documents to know which document is needed for the registration proof in your case. Ensure the document uploaded is submitted as the correct KYC Document Type.
API: DOCUMENT_DO_NOT_MATCH_USER_DATA Dashboard: DATA MISMATCH	The declarative data provided (in the User object) does not match the document uploaded.	Check that the User object has the correct: LegalPersonType for the local structure Business information (registered legal name, headquarters address, company number) Legal representative details (first name, last name, date of birth) In most scenarios, the declared legal representative must appear on the registration proof document.
API: DOCUMENT_HAS_EXPIRED Dashboard: EXPIRED	The document is not valid or was issued more than 3 months ago.	Check that the document was issued within the last 3 months. For some countries, the requirements don’t include the 3-month rule but the document has a validity period which it has passed and/or it must be the latest up-to-date version of the document.
API: DOCUMENT_FALSIFIED Dashboard: FALSIFIED	The document seems to be fraudulent or contains inconsistent information.	Check that the document is in line with the requirements and submission guidelines and has not been altered by any means.
API: SPECIFIC_CASE Dashboard: SPECIFIC	Specific or multiple issues.	Refer to the RefusedReasonMessage for details.
API: UNDERAGE_PERSON Dashboard: UNDERAGE	Not applicable.	-

Articles of association

Refused reason type	Issue	Recommendation
API: DOCUMENT_MISSING Dashboard: MISSING	The document is missing from the image or the file.	Check that the uploaded file is in one of the accepted formats (PDF, JPEG, JPG, PNG) and complies with size requirements (min. 1KB; max. about 7MB (10MB when Base64 encoded)). The file must be accessible and not password protected.
API: DOCUMENT_INCOMPLETE Dashboard: INCOMPLETE	The document is incomplete or not sufficient on its own.	Ensure the document is dated and that all pages are present and in one of the supported languages (or along with a sworn translation). In some cases, an additional document may be requested, for example: Appointment of a director Minutes of a resolution (e.g. in France, the procès-verbal d’assemblée générale) Refer to the RefusedReasonMessage for more details.
API: DOCUMENT_UNREADABLE Dashboard: UNREADABLE	The document is not clear enough.	Check the clarity and readability of your file before re-submitting clear and up-to-date accepted articles of association.
API: DOCUMENT_NOT_ACCEPTED Dashboard: NOT ACCEPTED	The document is not accepted; it doesn’t fit the verification requirements outlined by us.	Check the Accepted local KYB documents to know which document is needed for the registration proof in your case. Ensure the document uploaded is submitted as the correct KYC Document Type.
API: DOCUMENT_DO_NOT_MATCH_USER_DATA Dashboard: DATA MISMATCH	The declarative data provided (in the User object) does not match the document uploaded.	Check that the User object has the correct: LegalPersonType for the local structure Business information (registered legal name, headquarters address, company number)
API: DOCUMENT_HAS_EXPIRED Dashboard: EXPIRED	The document is not the latest up-to-date version.	Submit the latest signed copy of the articles of association which is up to date, fully accurate, and includes any recent modifications.
API: DOCUMENT_FALSIFIED Dashboard: FALSIFIED	The document seems to be fraudulent or contains inconsistent information.	Check that the document is in line with the requirements and submission guidelines and has not been altered by any means.
API: SPECIFIC_CASE Dashboard: SPECIFIC	Specific or multiple issues.	Refer to the RefusedReasonMessage for details.
API: UNDERAGE_PERSON Dashboard: UNDERAGE	Not applicable.	-

Shareholder declaration

Refused reason type	Issue	Recommendation
API: DOCUMENT_MISSING Dashboard: MISSING	The document is missing from the image or the file.	Check that the uploaded file is in one of the accepted formats (PDF, JPEG, JPG, PNG) and complies with size requirements (min. 1KB; max. about 7MB (10MB when Base64 encoded)). The file must be accessible and not password protected.
API: DOCUMENT_INCOMPLETE Dashboard: INCOMPLETE	The date, name or signature is missing, or the document was left blank. There may also be pages or information missing in the table regarding beneficial owners.	Check your form to ensure all mandatory parts are complete, including the checkboxes. Check your understanding and calculation of who the beneficial owners are, especially in complex cases involving indirect ownership via holding companies.
API: DOCUMENT_UNREADABLE Dashboard: UNREADABLE	The document is not clear enough.	Check the clarity and readability of your file before re-submitting the Shareholder Declaration.
API: DOCUMENT_NOT_ACCEPTED Dashboard: NOT ACCEPTED	The document is not accepted; it doesn’t fit the verification requirements outlined by us.	Check that the document is the latest version of the Mangopay Shareholder Declaration form or, if requested, an official extract of the beneficial owners registry in the relevant jurisdiction.
API: DOCUMENT_DO_NOT_MATCH_USER_DATA Dashboard: DATA MISMATCH	The entity indicated on the document doesn’t correspond to the one registered, or the information related to the beneficial owners is not consistent with other provided documents and/or data sources.	Check the consistency of the information registered for the entity.
API: DOCUMENT_HAS_EXPIRED Dashboard: EXPIRED	The document is outdated and its information is not up to date.	Check the consistency of the information and ensure you provide a recent and up-to-date document.
API: DOCUMENT_FALSIFIED Dashboard: FALSIFIED	The document seems to be fraudulent or contains inconsistent information.	Check that the document is in line with the requirements and submission guidelines and has not been altered by any means.
API: SPECIFIC_CASE Dashboard: SPECIFIC	Specific or multiple issues.	Refer to the RefusedReasonMessage for details.
API: UNDERAGE_PERSON Dashboard: UNDERAGE	Not applicable.	-