Hosted IDV for KYC/KYB | Mangopay docs

Mangopay provides a web-hosted identity verification (IDV) experience on which your users can complete all the steps necessary.

Your platform generates the frontend IDV Session URL via the same API endpoint in all cases, POST Create an IDV Session, but the user experience and integration differ depending on the User type.

Note – IDV sessions available in the Dashboard

In the Mangopay Dashboard, your platform can:

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

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

Experience overview by user type

Natural

The main IDV Session must be completed by the individual being verified. The session includes:

Personal data pre-filled from the Natural User object, for the individual to confirm.
A liveness check, where the individual takes photos of themselves and their accepted ID proof.

Read more about the Natural user flow →

Soletrader

The main IDV Session must be completed by the individual being verified. The session includes:

Personal and business data pre-filled from the Legal User object, for the individual to confirm.
A business registry lookup. If unsuccessful, the individual uploads an accepted Registration Proof document.
A liveness check, where the individual takes photos of themselves and their accepted ID proof.

Business and Organization

For Business, Organization, and Partnership Legal Users, the main IDV Session can be completed by any individual on behalf of the entity. The session includes:

Entity data pre-filled from the Legal User object, for the individual to confirm.
A business registry lookup. If unsuccessful, the individual uploads an accepted Registration Proof document.
A declaration of the entity’s Persons of Significant Control (PSCs), pre-filled if the registry lookup was successful. The individual completing the session can modify the declared PSCs, in which case a supporting document is required.

Once the main IDV Session is submitted, a separate PSC Session is generated for each declared PSC. By default, these are sent by email to the address declared in-session, but your platform can also manage this communication directly – see notifying PSCs. Each PSC Session must be completed by the individual declared as the PSC, and includes a liveness check. This is the multi-session PSC flow.

Read more about the Business and Organization flow →

Note – Previous flow still available during transition

There is also a legacy version of this flow, the legacy integrated flow, in which the liveness check is completed by a single individual within the main IDV Session, rather than through separate PSC Sessions. Platforms not yet migrated to the flow described above should refer to the Business - Legacy or Organization - Legacy guide.

Transition to hosted IDV

Note - Hosted KYC/KYB verification mandatory

All platforms are required to integrate Mangopay’s hosted KYC/KYB experience, relying on the POST Create an IDV Session endpoint.

Mangopay’s hosted KYC/KYB solution is becoming mandatory for all platforms.

Hosted KYC/KYB streamlines the verification process for your platform by providing a secure pre-built web experience.

On the HostedUrl returned by one API call, POST Create an IDV Session:

Natural Users can complete a liveness check – taking photos of themselves and their ID proof, which is handled via a QR code if opened on desktop
Legal Users can provide business information and, if applicable, declare PSCs, then pass the URL (or, for Business and Organization users, have Mangopay send separate URLs to each PSC) for the relevant liveness checks

Legacy solution

Mangopay’s legacy solution remains available during the transition to hosted IDV. The KYC Document and UBO Declaration endpoints continue to be supported for existing integrations.

In the eventuality that Mangopay requests additional documents, these cannot yet be submitted via the hosted IDV solution. In this case, your platform needs to be able to allow the user to transfer the documents to Mangopay via the legacy endpoint. Read more about submitting additional documents →

Common experience features

Pre-filled information

In all sessions, the individual must confirm personal and/or business data about their identity. To reduce friction, these data points are pre-filled from the Natural User and Legal User objects in the API.

Available languages

The default session language is English. On the welcome screen, the user can change this to one of the other available options: Dutch, French, German, Italian, Lithuanian, Polish, Portuguese, Romanian, Spanish.

There is no way to change the language used as the default language.

When the QR code is scanned (see below), the mobile experience to take photos inherits the language of the session.

Session autosave and validity

The hosted KYC/KYB session autosaves the progress made by the user on each screen.

Therefore, the session URL can be closed and re-opened before submission – this may be necessary for Business and Organization flows where a registered director must be the one who performs the liveness check (on the same link).

By default, a session must be submitted within 7 days of its CreationDate, after which its Status changes to EXPIRED and it can no longer be submitted.

However, if the session contains a liveness check and that step has been opened (the QR code was generated), the session instead expires 1 hour after the liveness step started.

This means:

For Natural, Soletrader, and the legacy Business/Organization flows (the legacy integrated flow), where the liveness check is part of the main IDV Session, the 1-hour rule applies to the main session once the liveness step is opened.
For the Business and Organization multi-session PSC flow, the main IDV Session never contains a liveness check, so it always follows the 7-day rule. Each PSC Session’s own liveness check follows the same 7-day/1-hour rule independently.

QR code on desktop

For steps that require the user to take a photo, if the URL is opened on a desktop browser then a QR code is presented on screen which the user must scan to open the session on their smartphone or tablet. Once scanned, the photo-taking progress is tracked on screen.

The experience attempts to automatically recognize the document or face in the screen and takes the photo. If this is unsuccessful, then the user can take a photo manually and choose to submit or retry.

Note – Mobile session attempts ID check automatically

If the session is open on a phone, the user is invited to take photos of their ID and a selfie, even if they are not the declared legal representative or listed as a director on the national registry.

Accepted documents

All documents submitted during the session must be those accepted by Mangopay.

For the liveness check, the identity document must be one of those listed by country of issue in the accepted ID page.

For Registration Proof and Articles of Association, the accepted documents depend on the legal status and country of registration or incorporation and are listed in the KYB local page.

Note – Session doesn’t prevent incorrect uploads

On the welcome screen, the session notes that the ID document used must correspond to one of those accepted by Mangopay and provides a link to the full list. However, the session supports types of ID that are not accepted by Mangopay.

Persons of significant control (PSC)

For Business and Organization users, the individuals or entities declared during the session as PSCs must be legal representatives and/or beneficial owners as defined by Mangopay here.

PSC data entered by the user during a session is not made available to the platform directly.

The legacy UBO Declaration feature of the API does not have an equivalent in the hosted solution: everything is submitted by the user directly in the session.

For full details on how PSCs are declared, pre-filled from registry lookups, and individually verified, see the Business and Organization flow guide.

Testing

For the hosted IDV experience in Sandbox, Mangopay provides a simulator that lets you replicate:

The checks performed by Mangopay and their outcomes
The user’s liveness check

To use it, call the POST Create an IDV Session endpoint and follow the HostedUrl returned.

The guidance screens shown to the user are also included in Sandbox to give you the fullest picture of the experience without sensitive steps, and to understand the possible pathways.

In Sandbox, the simulation of checks performed retain their conditional logic, so some are only available depending on your previous selection. For the specific checks and conditions that apply to each user type, and how to simulate a manual review (REVIEW) outcome where applicable, see the dedicated guides:

Mangopay’s Postman collection contains the endpoints you need create a User and launch their KYC/KYB session.

Sending additional documents

The hosted solution allows the user to complete all the necessary steps to be verified, including the ID liveness check and, where relevant, declaring Persons of Significant Control (also known as beneficial owners).

However, in the event that additional documents are requested by Mangopay, these must be submitted via the API in the form of a legacy KYC Document object.

There are two Types of object that you may need to use:

IDENTITY_PROOF - For any additional ID documents requested
ADDRESS_PROOF - For any other additional documents requested that aren’t ID proofs (i.e. even if it’s not an address proof either)

Note that for the ADDRESS_PROOF document, the Status will become VALIDATED automatically. Please contact Mangopay to request that the document be reviewed.

For more guidance on integrating these endpoints, see information about document submission guide and how to submit a KYC document.

For platforms using the hosted experience, integration of the UBO Declaration endpoints is not necessary, as these individuals can be declared by the user through the frontend session.