Hosted IDV for KYC/KYB

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.

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.

Read more about the Soletrader flow →

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 →

Transition to hosted IDV

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.

Session language

The hosted KYC/KYB experience is available in the following languages:

Your platform can set the initial language of the session by sending the SessionLanguage parameter on the POST Create an IDV Session endpoint. This adds the lng query parameter to the HostedUrl in the response.

The user can change the language in the session thanks to a dropdown component. This preference is saved in case they close and re-open the session, or for any future sessions.

If not specified using SessionLanguage, then the session takes the language of the user’s browser (if one of those listed above), otherwise English.

Branding

The hosted KYC/KYB session automatically reflects your platform’s branding by using:

• Your platform’s trading name, which can be modified by contacting Mangopay via the Dashboard.

• Your platform’s logo, which can be added or modified by sending a new file on the PUT Update a Client Logo endpoint or by contacting Mangopay. To remove the logo entirely, contact Mangopay.

• Your platform’s primary color (PrimaryThemeColour) and CTA color (PrimaryButtonColour), which can be set via PUT Update a Client (note that updates may take up to an hour to appear).

Session autosave and validity

The hosted KYC/KYB session autosaves the progress made by the user on each screen, allowing it to be closed and re-opened.

By default, an IDV 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.

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 the Registration Proof and Articles of Association, the accepted documents depend on the legal status and country of registration or incorporation. More details on the accepted documents are listed in the KYB local page, and a certified sworn translation is required if the document is not in one of the accepted languages.

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.

QR code on desktop

If the session is opened on desktop and requires a liveness check, then a QR code is presented to the individual for them to continue with their mobile phone. Once the QR code is scanned, the desktop session tracks the progress on screen.

The mobile liveness experience automatically attempts to recognize the individual’s ID document and face. The individual can also choose to retry or take photos manually before submitting.

The language of the liveness check on mobile takes the setting of the session it was generated from.

Once the QR code is generated, the liveness check session must be completed within 1 hour.

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:

• Natural
• Soletrader
• Business and Organization
• Business - Legacy and Organization - Legacy

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.