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

FlagDescription
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
009001The fonts analyzed don’t match those expected for the kind of identity proof submitted (e.g. for a French national identity card).
009002The picture of the person is altered.
009003The document is partially or totally covered.
009004The document is blurred.
009005The document is cut off: piece of information missing, machine-readable zone (MRZ) not readable, etc.
009006The document is not readable due a glare on the photo.
009007The incorrect side of the document was submitted.
009008Two different documents were uploaded at the same time.
009009The document is not accepted (deprecated since June 13th, 2022). Please contact the Mangopay Support team.
009010There is no document in the image.
009011The photo of the document is too dark.
009012The document is damaged.
009013The document has a punched hole.
009014The document corner has been physically cut off.
009015The document contains severely diminished colors (due to resolution issues, low-quality liquid scan rather than photo, or washed-out background for instance).
009016The document has a glare obscuring a security chip.
009017Some features of the document are obscured.
009018The back of the document is needed for processing.
009019Mangopay doesn’t support this kind of document.
009020The document owner is under the age of 18 years old.
009021The 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).
009024The 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).
009025The document information is not readable because the image is in black and white (rather than in color).
009026The document is considered paper-based (printed on paper), rather than being a card or passport format.
009100

A match couldn’t be made with the 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.

Ensure you also check the RefusedReasonMessage parameter for personalized information from Mangopay’s teams.

​
Identity proof

Refused reason typeIssueRecommendation
DOCUMENT_MISSINGThe 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.

DOCUMENT_INCOMPLETEThe 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).
DOCUMENT_UNREADABLEThe document provided is not clear enough.Check the clarity and readability of your file before re-submitting the identity proof.
DOCUMENT_NOT_ACCEPTEDThe 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.
DOCUMENT_DO_NOT_MATCH_USER_DATAThe 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.
DOCUMENT_HAS_EXPIREDThe document has passed its expiry date; it is no longer valid.Submit an in-date accepted identity proof.
DOCUMENT_FALSIFIEDThe document seems to be fraudulent or contains inconsistent information.-
SPECIFIC_CASESpecific issue.Please refer to the RefusedReasonMessage for more information about the issue from Mangopay’s teams.
UNDERAGE_PERSONThe individual indicated on the document is under 18.Mangopay users must be 18 years old or older.

​
Registration proof

Refused reason typeIssueRecommendation
DOCUMENT_MISSINGThe document is missing from the image or the file.

Check that you upload the correct file and that it contains the accepted registration document.

Check the Accepted local KYB documents to know which document is needed for the registration proof in your case.

DOCUMENT_INCOMPLETEThe document is incomplete (e.g., some pages are missing).

Check that you include all pages of the accepted registration proof and that they upload successfully.

In cases where the entity is legally represented by another entity, please also provide the extract of the representation entity. This allows Mangopay to identify the natural person who is the legal representative.

DOCUMENT_UNREADABLEThe document provided is not clear enough.Check the clarity and readability of your file before re-submitting a clear and up-to-date accepted registration proof.
DOCUMENT_NOT_ACCEPTEDThe 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.
DOCUMENT_DO_NOT_MATCH_USER_DATAThe people appearing on the document do not include the declared legal representative.Check that the legal representative declared for the user is the correct person before submitting the accepted registration proof which lists them. A proxy may be possible in exceptional circumstances.
DOCUMENT_HAS_EXPIREDThe document is from more than 3 months ago.Submit a recent accepted registration proof which is not older than 3 months.
DOCUMENT_FALSIFIEDThe document seems to be fraudulent or contains inconsistent information.-
SPECIFIC_CASESpecific issue.Please refer to the RefusedReasonMessage for more information about the issue from Mangopay’s teams.
UNDERAGE_PERSONNot applicable.-

​
Articles of association

Refused reason typeIssueRecommendation
DOCUMENT_MISSINGThe document is missing from the image or the file.

Check that you upload the correct file and that it contains the accepted articles of association.

Check the Accepted local KYB documents to know which document is needed for the articles of association in your case.

DOCUMENT_INCOMPLETEThe document is incomplete, or the registered legal representative doesn’t seem to be one of the persons authorized to represent the entity.Check that you include all pages of the articles of association and that they upload successfully.
DOCUMENT_UNREADABLEThe document provided is not clear enough.Check the clarity and readability of your file before re-submitting clear and up-to-date accepted articles of association.
DOCUMENT_NOT_ACCEPTEDThe 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 articles of association in your case.
DOCUMENT_DO_NOT_MATCH_USER_DATAThe entity indicated on the document doesn’t correspond to the one registered, or the declared legal representative does not appear (if applicable).Check the information registered for the entity, and especially that registered legal representative is correct.
DOCUMENT_HAS_EXPIREDThe document is not up to date or doesn’t reflect the current reality.Submit the latest signed copy of the articles of association which is up to date, fully accurate, and includes any recent modifications.
DOCUMENT_FALSIFIEDThe document seems to be fraudulent or contains inconsistent information.-
SPECIFIC_CASESpecific issue.Please refer to the RefusedReasonMessage for more information about the issue from Mangopay’s teams.
UNDERAGE_PERSONNot applicable.-

​
Shareholder declaration

Refused reason typeIssueRecommendation
DOCUMENT_MISSINGThe document is missing from the image or the file.Check that you upload the correct file and that it contains the Shareholder Declaration.
DOCUMENT_INCOMPLETEThe date, name or signature is missing, or the document was left blank. There may also be information missing in the table regarding beneficial owners.

Check your form to ensure it is complete. Check your understanding and calculation of who the are, especially in complex cases involving indirect ownership via holding companies.

DOCUMENT_UNREADABLEThe document provided is not clear enough.Check the clarity and readability of your file before re-submitting the Shareholder Declaration.
DOCUMENT_NOT_ACCEPTEDThe document is not accepted; it doesn’t fit the verification requirements outlined by us.Check the Requirements overview to know if the Shareholder Declaration is needed in your case.
DOCUMENT_DO_NOT_MATCH_USER_DATAThe entity indicated on the document doesn’t correspond to the one registered, or the information is not consistent with the articles of association (if applicable).Check the consistency of the information registered for the entity, in the articles of association, and in the Shareholder Declaration.
DOCUMENT_HAS_EXPIREDNot applicable.-
DOCUMENT_FALSIFIEDThe document seems to be fraudulent or contains inconsistent information.-
SPECIFIC_CASESpecific issue.Please refer to the RefusedReasonMessage for more information about the issue from Mangopay’s teams.
UNDERAGE_PERSONNot applicable.-

Was this page helpful?

ID best practicesCompany number