Mangopay’s hosted IDV Session allows platforms to redirect a user to a Mangopay-hosted digital experience in which the user provides details and documents to verify their identity.

Note – Beta for Natural users, Legal Soletraders and Businesses

The hosted identity verification feature is in beta and available for Natural users and Legal users whose LegalPersonType is SOLETRADER or BUSINESS. For more information about all user types, see the Introduction and Types guide.

The user must also be an Owner to request a new verification session. To verify a user, you need to create a session. Each session contains multiple checks depending on the user type.

​
Endpoints

The following endpoints let you initiate and manage IDV Session objects:

POST Create an IDV Session

Start an identity verification session and get a link for the hosted experience

GET View an IDV Session

See the status and basic details of an identity verification session

GET View Checks for an IDV Session

Obtain verified user data and results of each check performed

​
Webhooks

You can set up webhook notifications for the following event types:

​
IDV session

  • IDENTITY_VERIFICATION_VALIDATED – The identity verification session was successful.
  • IDENTITY_VERIFICATION_FAILED – The identity verification session was unsuccessful. You can retry the verification for the user.
  • IDENTITY_VERIFICATION_INCONCLUSIVE –
  • IDENTITY_VERIFICATION_OUTDATED – The identity verification session is no longer valid, likely due to expired documents used during the session.

The ResourceId of these webhooks corresponds to the IdvSessionId.

​
User KYC level

These event types complement the existing ones relating to the user’s KYC Level:

  • USER_KYC_REGULAR – The user has been successfully verified by Mangopay.
  • USER_KYC_LIGHT – The user has not been verified by Mangopay and is therefore subject to product limitations.

​
How it works

1

Initiate the IDV Session

Call the POST Create an IDV Session endpoint to obtain a HostedUrl for the hosted KYC/B session.

Define a ReturnUrl for the user to be returned to after their identity verification session.

2

Redirect the user

In the API response, the HostedUrl contains the URL to which you need to redirect the user to complete their session.

3

Let the user complete the session

On the URL, the user can submit the required data and complete a liveness check using their smartphone.

4

Handle the session outcome

The Status parameter indicates the progression of the verification session:

  • VALIDATED – The session was successful.
  • REJECTED – The session was unsuccessful.
  • OUTDATED – The session is no longer valid (likely due to expired documents used during the session).
  • TIMEOUT – The session timed out due to inactivity.
  • PENDING – The session is in progress and user action is required to complete it.
  • REVIEW – The session is under manual review by Mangopay.
  • ERROR – The session was not completed because an error occurred.

You should set up webhooks to be notified of the outcome.

5

See checks completed during a session

Call the GET View checks for an IDV Session to see the list of Checks carried out during the session, as well as the data points (Type and Value) of each check.

Refer to the verified data returned and refusal reasons for more information.

​
Verified data returned

For more details on refusal reasons and descriptions, see the Refusal reasons glossary.

​
Natural person

IDENTITY_DOCUMENT_VERIFICATION

  • FIRST_NAME - First name from the identity verification check.
  • LAST_NAME - Last name from the identity verification check.
  • BIRTHDATE - Birthdate as a unix timestamp.
  • NATIONALITY - Nationality as a country code.
  • RESIDENCY - Country as a country code.
  • REFUSAL_REASON - Reason for refusal, which can be:
    • FACE_MATCH_FAIL
    • DOCUMENT_NOT_ACCEPTED
    • DOCUMENT_FALSIFIED
    • DOCUMENT_UNREADABLE
    • DOCUMENT_HAS_EXPIRED
    • TIMEOUT
    • ERROR
    • EXPIRED_CREDENTIALS
  • REFUSAL_DESCRIPTION: Custom string with feedback from support agent.

BUSINESS_VERIFICATION

  • COMPANY_NAME - Company name.
  • COMPANY_NUMBER - Company number.
  • REFUSAL_REASON - Reason for refusal, which can be:
    • DOCUMENT_FALSIFIED
    • DOCUMENT_NOT_ACCEPTED
    • DOCUMENT_TYPE_NOT_SUPPORTED
    • DOCUMENT_EXPIRED, DOCUMENT_UNREADABLE
    • DOCUMENT_INCOMPLETE
    • TIMEOUT
    • ERROR
    • EXPIRED_CREDENTIALS
  • REFUSAL_DESCRIPTION - Custom string with feedback from support agent.

IDENTITY_DOCUMENT_VERIFICATION

  • LEGAL_REPRESENTATIVE_FIRST_NAME - First name from identity verification check.
  • LEGAL_REPRESENTATIVE_LAST_NAME - Last name from identity verification check.
  • LEGAL_REPRESENTATIVE_BIRTHDATE - Birthdate as a unix timestamp.
  • LEGAL_REPRESENTATIVE_NATIONALITY - Nationality as a country code.
  • LEGAL_REPRESENTATIVE_FIRST_RESIDENCY - Country as a country code.
  • REFUSAL_REASON - Reason for refusal, which can be:
    • FACE_MATCH_FAIL
    • DOCUMENT_NOT_ACCEPTED
    • DOCUMENT_FALSIFIED
    • DOCUMENT_UNREADABLE
    • DOCUMENT_HAS_EXPIRED
    • TIMEOUT
    • ERROR
    • EXPIRED_CREDENTIALS
  • REFUSAL_DESCRIPTION - Custom string with feedback from support agent.

PERSONS_SIGNIFICANT_CONTROL

  • REFUSAL_REASON - Reason for refusal, which can be:
    • PSC_MATCH_FAIL
    • PSC_NAME_FAIL
    • TIMEOUT
    • ERROR
    • EXPIRED_CREDENTIALS
  • REFUSAL_DESCRIPTION - Custom string with feedback from support agent.

​
Refusal reasons glossary

Check TypeRefusal ReasonReason description
BUSINESS_VERIFICATION, IDENTITY_DOCUMENT_VERIFICATION, PERSONS_SIGNIFICANT_CONTROLTIMEOUTThe session timed out due to inactivity by the user. They started but did not finish the KYC check.
EXPIRED_CREDENTIALSThe KYC check has become invalid due to changes in the user’s personal details, the expiration of a submitted document, or when their KYC status necessitates renewal.
ERRORA critical error occurred during the verification process and a new KYC session should be started.
BUSINESS_VERIFICATIONDOCUMENT_FALSIFIEDThe business document provided appears to be fraudulent or tampered with.
DOCUMENT_NOT_ACCEPTEDThe document submitted is not an acceptable form of verification for the business.
DOCUMENT_TYPE_NOT_SUPPORTEDThe type of business document provided is not currently supported.
DOCUMENT_EXPIREDThe business document provided has expired.
DOCUMENT_UNREADABLEThe information on the business document is illegible or cannot be processed.
DOCUMENT_INCOMPLETEThe business document is missing essential information or sections.
IDENTITY_DOCUMENT_VERIFICATIONFACE_MATCH_FAILThe selfie does not match the photo on the ID document.
DOCUMENT_NOT_ACCEPTEDThe provided document is not an acceptable form of identification for this verification.
DOCUMENT_FALSIFIEDThe provided document appears to be fraudulent or has been tampered with.
DOCUMENT_UNREADABLEThe information on the document is illegible or cannot be processed.
DOCUMENT_HAS_EXPIREDThe document provided has expired.
PERSONS_SIGNIFICANT_CONTROLPSC_MATCH_FAILThe individual’s information doesn’t match the criteria for a Person of Significant Control.
PSC_NAME_FAILThe individual’s name doesn’t match the records associated with the business.

Was this page helpful?