Skip to navigation
User KYC/KYB verificationHosted KYC/KYB

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.

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.

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 →

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.

Session language

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

LanguageSessionLanguage value
Chinese (Simplified)zh-Hans-CN
Englishen-US
Dutchnl-NL
Frenchfr-FR
Germande-DE
Italianit-IT
Portuguesept-PT
Spanishes-ES

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:

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

Tag-based session bypass

In Sandbox, you can also skip the HostedUrl flow entirely by setting the Tag parameter on POST Create an IDV Session to the Status value that you wish to simulate: VALIDATED, REFUSED, REVIEW, or EXPIRED.

Any other Tag value generates the HostedUrl as normal.

Note that the POST endpoint shows the value INCONCLUSIVE in its response. The correct value is REVIEW, as returned by the GET. This will be rectified as soon as possible.

Sending additional documents

The hosted IDV Session is sufficient for a user to obtain KYC/KYB verification (that is, moving from KYCLevel value of LIGHT to REGULAR). The hosted frontend allows users to provide all documents required as evidence, including the liveness check and declaring Persons of Significant Control (PSCs) where relevant.

However, Mangopay may also require documents from a Natural or Legal User separately from the KYC/KYB verification process. These requests may result from routine AML/CFT checks which are unrelated to the KYCLevel of the user.

In such cases, a user may also be blocked on a temporary basis until the user has provided the necessary evidence, Mangopay has reviewed the case, and all points of concern are addressed.

To provide additional documents as evidence – requested outside the context of an ongoing IDV Session – your platform needs to use the KYC Document endpoints or the Dashboard.

When submitting a document, whether via the Dashboard or KYC Document endpoints:

1

Use the correct document type

When submitting the file, respect the document Type:

  • For a Natural User, please use the ADDRESS_PROOF type only and in all cases, regardless of the nature of the document you’re sending.

    The IDENTITY_PROOF type should not be used, even for identity documents.

  • For a Legal User, please use the SHAREHOLDER_DECLARATION type only in all cases, regardless of the nature of the document you’re sending.

    The other types should not be used (IDENTITY_PROOF, REGISTRATION_PROOF, ARTICLES_OF_ASSOCIATION), even if they correspond to the document you’re sending.

2

Notify Mangopay once sent

When the document is uploaded or submitted, please notify Mangopay of this and reference the UserId.

Note: Once you submit the KYC Document, its Status becomes VALIDATION_ASKED automatically and then may also transition to VALIDATED or REFUSED, but this should be ignored. In all cases, the document will only be reviewed after you contact Mangopay to request it.