Dealing with hosted IDV refusals

In the case of unsuccessful session (Status is REFUSED), further information on the refused checks is available in the IDV session object.

Note – IDV sessions available in the Dashboard

In the Mangopay Dashboard, your platform can:

See details of sessions, including the checks performed and refused reasons
Generate a new session link for a user

To access, navigate to a given User’s profile and click the KYV verification tab.

To retrieve the Checks performed, call the GET View an IDV Session endpoint.

For Checks that have CheckStatus of REFUSED, the reasons for the refusal are given in the Reasons array, containing one or more objects containing Type and Value fields.

This information helps you understand why the session was refused and guide the user in retrying a new session successfully.

All the Checks.Reasons.Type values are listed below by CheckType along with recommendations for resolution.

Note – Refer to custom comment for legal user reviews

For Legal user sessions that were manually reviewed, ensure you check the Checks.Reasons.Value field for the customized comment from the person who conducted the review.

The Value is preset if the session was automatically refused - which is always the case if a Natural user session was refused and may be the case for Legal users.

Refused reasons per check type

The following tables give guidance on how to deal with the refused reasons per CheckType.

Identity document verification

For the IDENTITY_DOCUMENT_VERIFICATION check, the following refused reasons may be returned:

Reason type	Issue	Recommendation
`DOCUMENT_NOT_ACCEPTED`	The document is not accepted; it doesn’t fit the verification requirements outlined by Mangopay.	Check the Accepted ID documents to know which document is accepted for the identity proof depending on the country of issue. Retry in a new IDV session with an accepted document.
`FACE_MATCH_FAIL`	The face on the selfie does not match the face of the document.	Retry in a new session, ensuring that the person of the ID is also taking the selfie.
`DOCUMENT_FALSIFIED`	The document seems to be fraudulent or contains inconsistent information.	Check that the document has not been altered by any means.
`DOCUMENT_UNREADABLE`	The document is not clear enough.	Check that the document used is accepted. Retry in a new session ensuring the photos taken are clear, readable, and not blurred.
`DOCUMENT_HAS_EXPIRED`	The document has passed its expiry date; it is no longer valid.	Check that the ID proof is not expired. Retry the session with an in-date accepted document.

IDV age check

For the IDV_AGE_CHECK check, the following refused reasons may be returned:

Reason type	Issue	Recommendation
`DOCUMENT_NOT_ACCEPTED`	The individual indicated on the document is under 18.	Mangopay Natural users must be 18 years old or older (same for legal representatives and beneficial owners).

IDV name match check

For the IDV_NAME_MATCH_CHECK check, the following refused reasons may be returned:

Reason type Issue Recommendation

Reason type	Issue	Recommendation
`DOCUMENT_NOT_ACCEPTED`	The first name and last name of the identity document did not match the User object data: For a Natural user, with the `FirstName` and `LastName` For a Legal Soletrader, with the `LegalRepresentative.FirstName` and `LegalRepresentative.LastName`	First, update the data of the user object to match the identity document. Then, retry the session using the same identity document.

DOCUMENT_NOT_ACCEPTED

The first name and last name of the identity document did not match the User object data:

For a Natural user, with the FirstName and LastName
For a Legal Soletrader, with the LegalRepresentative.FirstName and LegalRepresentative.LastName

First, update the data of the user object to match the identity document.

Then, retry the session using the same identity document.

Business verification

For the BUSINESS_VERIFICATION check, the following refused reasons may be returned:

Reason type	Issue	Recommendation
`DOCUMENT_NOT_ACCEPTED`	Generic refusal status. See the specific comment in the `Checks.Reasons.Value`.	Review the custom comment provided and respond accordingly.
`DOCUMENT_TYPE_NOT_SUPPORTED`	The document is for the country of registration or Legal User type.	Check the accepted local KYB documents to know which document is needed for the registration proof in your case. Retry in a new IDV session.
`DOCUMENT_HAS_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.
`DOCUMENT_UNREADABLE`	The document is not clear enough.	Check the clarity and readability of your file before retrying in a new session, submitting a clear and up-to-date accepted document.
`DOCUMENT_INCOMPLETE`	The document is incomplete or not sufficient on its own.	Ensure the file uploaded is dated, that all pages are present, and that it is in one of the supported languages or, if not, that a sworn translation was also uploaded. For most countries, declared legal representative should appear in the document(s). Generate a new session to retry.

Business insights match

For the BUSINESS_INSIGHTS_MATCH check, the following refused reasons may be returned:

Reason type	Issue	Recommendation
`BUSINESS_INSIGHTS_MATCH_FAILED`	For Business users, the name on the identity document is not in the list of business directors obtained from the national registry.	Review the custom comment provided and respond accordingly.

Business name check

For the BUSINESS_NAME_MATCH check, the following refused reasons may be returned:

Reason type	Issue	Recommendation
`BUSINESS_NAME_MATCH_FAILED`	For Soletrader users, the name on the identity document does not feature in the registered name of the sole proprietor.	Review the custom comment provided and respond accordingly.