Natural users | Mangopay docs

For a Natural User, the hosted IDV solution presents the user with the liveness check.

Prerequisites

Before launching a hosted IDV Session for a Natural User, please ensure that:

The ID proof they will use is accepted by Mangopay
The data in the following Natural User object fields matches their ID proof:
- FirstName
- LastName

Flow description

When a hosted IDV session is opened for a Natural User:

The session Status is PENDING and can be submitted within 7 days, at which point it becomes EXPIRED. This emits the IDENTITY_VERIFICATION_PENDING webhook.
The user opens the session and sees a welcome screen explaining:
- That they will need to complete the liveness check with their ID and smartphone, with a link to Mangopay’s accepted ID documents
User completes live ID check (via QR code or directly if session opened on a phone) by:
- Taking a photo of their ID (or two photos if it’s a driver’s license or national ID card)
- Taking a selfie of their face
The session is redirected to the ReturnUrl
Mangopay performs automated liveness validation checks:
- IDENTITY_DOCUMENT_VERIFICATION
- IDV_NAME_MATCH_CHECK
- IDV_AGE_CHECK

Checks performed

For Natural Users, the following checks are performed in the order listed:

Type	Description
`IDENTITY_DOCUMENT_VERIFICATION`	Verifies the authenticity of the identity document, the liveness of the selfie, and that the selfie matches the identity document photo.
`IDV_NAME_MATCH_CHECK`	Checks whether the first name and last name of the identity document match the `FirstName` and `LastName` of the Natural user object. Only performed if `IDENTITY_DOCUMENT_VERIFICATION` is successful.
`IDV_AGE_CHECK`	Checks whether the individual on the identity document meets the minimum age requirement for Mangopay users (age 18). Only performed if `IDENTITY_DOCUMENT_VERIFICATION` is successful.

Outcomes

For a Natural User, the following outcomes are possible (from a PENDING status):

Automated validation

The Status becomes VALIDATED if all automated checks performed were successful. This emits the IDENTITY_VERIFICATION_VALIDATED webhook. In this case:

The verified data is overwritten in the User object:
- FirstName
- LastName
- Birthday
The User’s KYCLevel becomes REGULAR

Automated refusal

The Status becomes REFUSED if any of these checks fail:

IDENTITY_DOCUMENT_VERIFICATION
IDV_NAME_MATCH_CHECK
IDV_AGE_CHECK

This emits the IDENTITY_VERIFICATION_FAILED webhook. A manual review is not possible for a Natural user.

Testing

For general guidance on testing the hosted IDV experience in Sandbox, see Testing.

For a Natural User, the simulation of checks performed retain their conditional logic: IDV_NAME_MATCH_CHECK and IDV_AGE_CHECK are only performed if IDENTITY_DOCUMENT_VERIFICATION is validated.

Sequence diagram

The following diagram gives an overview of the integration flow:

Integration flow

Initiate the hosted session

Call the POST Create an IDV Session endpoint with the UserId to initiate a hosted KYC/KYB verification session.

You must include a ReturnUrl to which the session redirects once it is completed, before the outcome is known.

In the API response:

The HostedUrl value is the URL for the unique session, with your ReturnUrl encoded and appended.
The Status is PENDING, indicating that the session is available via the HostedUrl value, and the user has not successfully completed all the necessary steps.

The PENDING status emits the IDENTITY_VERIFICATION_PENDING webhook event type with the session Id (read more about setting up webhooks).

Redirect the user to the hosted session

Redirect the user to the HostedUrl value received in the response.

By default, the session can be submitted within 7 days, after which the Status changes to EXPIRED. If the liveness step has been opened (the QR code was generated), the session instead expires 1 hour after it started.

The object Status remains PENDING regardless of whether the session has been started or not. On your side you can track whether the HostedUrl was accessed by the user.

Let the user complete the session

On the HostedUrl, the experience guides the user through the ID liveness check using their smartphone. If the session is opened on desktop then a QR code is displayed for the user to scan.

Receive the user after completion

Once the session is completed, the HostedUrl redirects to the ReturnUrl.

The outcome of the session is not returned immediately, even though checks are performed automatically for Natural Users.

Listen to webhooks

When the outcome of the session is known, the Status is updated from PENDING and a webhook notification is emitted.

The PENDING value can change directly to one of:

`Status`	Webhook event type	Description
`VALIDATED`	`IDENTITY_VERIFICATION_VALIDATED`	The User became KYC/KYB verified: `KYCLevel` changed to `REGULAR` and verified data updated in the User object.
`REFUSED`	`IDENTITY_VERIFICATION_FAILED`	User was not KYC/KYB verified and a new session must be created for them to retry.

A manual review (REVIEW status) is not possible for a Natural user.

Handle outcomes

Once you receive a webhook, call GET View an IDV Session for more details about the session.

In a successful case, this endpoint returns the verified data points that are updated in the User object.

For REFUSED cases, the endpoint returns information about which Checks failed and for what reasons.

To see key details about all the sessions attempted for a user, call GET List IDV Session for a User.

State machine

The following diagram shows the statuses of the IDV Session object for a Natural user:

Webhooks

The hosted KYC/KYB verification feature takes time for the user to complete.

You are strongly recommended to implement webhooks for IDV Sessions and rely on them in your integration.

Once you receive a webhook notification, call GET View an IDV Session for more details.

The following event types are available for a Natural user:

IDENTITY_VERIFICATION_PENDING – The IDV Session’s Status is PENDING. The HostedUrl link is valid for completion and must be submitted within 7 days (or 1 hour after the liveness step is opened). The session may or may not have been started.
IDENTITY_VERIFICATION_VALIDATED – The IDV Session’s Status changed to VALIDATED and the User became KYC/KYB verified.
IDENTITY_VERIFICATION_FAILED – The IDV Session’s Status changed to REFUSED and the User was not KYC/KYB verified. A new session is needed for them to retry.
IDENTITY_VERIFICATION_EXPIRED – The IDV Session’s Status changed to EXPIRED. A new session is needed to retry.
IDENTITY_VERIFICATION_OUTDATED – The IDV Session’s Status changed to OUT_OF_DATE indicating that the user’s KYC/KYB verification status was downgraded. To regain KYC/KYB verified status, the user must complete a new IDV Session successfully.

Verified data

The hosted KYC/KYB session gathers user data which is then verified as part of the process. This data is returned in the session’s Checks.Data. You can retrieve it using the GET View an IDV Session endpoint.

These data points are overwritten if the session Status is VALIDATED, but the Data may still be returned if the status is REFUSED.

As part of the IDENTITY_DOCUMENT_VERIFICATION check, the data in the next table is extracted from the ID document. If this check fails, the session Status is REFUSED and no data is overwritten.

`Data.Type` value extracted from ID	User object property overwritten if `Status` is `VALIDATED`
`FIRST_NAME`	`FirstName`
`LAST_NAME`	`LastName`
`BIRTHDATE`	`Birthday`