Business - Legacy single-session flow

This page describes the previous hosted IDV flow for the Business user type (the legacy integrated flow), in which a single individual completes the liveness check within the main IDV Session.

If your platform has been migrated to the new flow (the multi-session PSC flow), where all Persons of Significant Control (PSCs) are verified individually through separate PSC Sessions, see the Business guide instead.

Prerequisites

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

• The Registration Proof they will need to upload conforms to the one expected by Mangopay
• The Articles of Association they may need to upload conforms to the one expected by Mangopay
• They have details about their business and all beneficial owners (definition here)
• An individual listed in the national registry is available to perform the liveness check (the link can be closed and reopened)
• The ID proof the individual will use is accepted by Mangopay

Flow description

Currently, when a hosted IDV session is generated for a Legal Business:

1. 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.
2. The user opens the session and sees a welcome screen explaining:
   • That they will need to provide business details
   • That they may need to provide Registration Proof (RP) and Articles of Association (AoA) documents (links to the KYB local page are provided later in the flow)
   • That a registered director (not necessarily the one listed in the LegalRepresentative fields) will need to complete the liveness check with their ID and smartphone, with a link to Mangopay’s accepted ID documents
3. The user enters business details:
   • Country of incorporation
   • Registration number provided by the relevant national authority
   • Registered business name
   • Registered business address
4. The user declares one or more beneficial owners (UBOs) as Persons of Significant Control (PSC)
5. Mangopay performs registry lookup using the business details:
   • BUSINESS_VERIFICATION
6. There are two possible outcomes from the registry lookup:
   • There is a match. In this case, the user must upload an accepted Registration Proof.
   • There is no match. In this case, the user must upload an accepted Registration Proof and Articles of Association, and the session is sent for manual review (Status will be REVIEW).
7. The session must then be opened by the registered director who will complete the liveness check (the session autosaves progress)
8. The registered director completes the liveness 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
9. The session is redirected to the ReturnUrl
10. Mangopay performs automated liveness validation checks:
    • IDENTITY_DOCUMENT_VERIFICATION
    • IDV_AGE_CHECK
11. If successful, Mangopay checks that the individual in the ID is listed in the registry (BUSINESS_INSIGHTS_MATCH).
    • If successful, the session’s status becomes VALIDATED
    • If unsuccessful, the session is reviewed manually (REVIEW) before the final outcome

Checks performed

Currently, for Legal Business Users, the following checks are performed in the order listed:

Outcomes

For a Business 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:
  • LegalRepresentative.FirstName (even if the fields previously referenced a different individual)
  • LegalRepresentative.LastName
  • LegalRepresentative.Birthday
  • CompanyName
  • CompanyNumber
• The User’s KYCLevel becomes REGULAR

Automated refusal

The Status becomes REFUSED if any of these checks fail:

• IDENTITY_DOCUMENT_VERIFICATION
• IDV_AGE_CHECK

This emits the IDENTITY_VERIFICATION_FAILED webhook. In this case:

• You can retrieve more information in the IDV Session’s:
  • Checks.CheckStatus - For which checks were REFUSED
  • Checks.Reasons – For the refusal reasons (Type and preset Value)
• You need to generate a new session to retry (even if some of the checks were validated)

Manual review

Provided the IDENTITY_DOCUMENT_VERIFICATION and IDV_AGE_CHECK are successful, the Status becomes REVIEW if either of the following checks fail:

• BUSINESS_VERIFICATION
• BUSINESS_INSIGHTS_MATCH

This emits the IDENTITY_VERIFICATION_INCONCLUSIVE webhook. In this case:

• Mangopay reviews the session data and documents manually.
• The Checks.CheckStatus shows which checks were REFUSED and triggered the manual review
• Automatically validated checks are returned, including verified data, but the User object data is only overwritten if the session is validated

Validation after review

If the manual review is successful, the Status changes from REVIEW to VALIDATED. In this case:

• The verified data is overwritten in the User object:
  • LegalRepresentative.FirstName (even if the fields previously referenced a different individual)
  • LegalRepresentative.LastName
  • LegalRepresentative.Birthday
  • Name
  • CompanyNumber
• The User’s KYCLevel becomes REGULAR

Refusal after review

If the manual review is unsuccessful, then the status changes to REFUSED.

In this case:

• Verified data may be returned in the IDV Session but no action is taken with it
• You can retrieve more information in the IDV Session’s:
  • Checks.CheckStatus - For which checks were REFUSED
  • Checks.Reasons – For the refusal reasons – Type and, in the case of a manual review, a custom message in the Value
• You need to generate a new session to retry (even if some of the checks were validated)

Testing

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

For this flow, the simulation of checks performed retain their conditional logic: BUSINESS_INSIGHTS_MATCH is only performed if BUSINESS_VERIFICATION is validated.

To simulate a REVIEW session, validate the IDV checks except any of BUSINESS_VERIFICATION or BUSINESS_INSIGHTS_MATCH.

Sequence diagram

The following diagram gives an overview of the integration flow:

Integration flow

State machine

The following diagram shows the statuses of the IDV Session object for this flow:

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 this flow:

• 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_INCONCLUSIVE – The IDV Session’s Status changed to REVIEW and the session is under manual review by Mangopay’s teams before an outcome can be given.
• 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 or REVIEW.

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. Note that this data is overwritten even if the individual who completed the session’s ID check is not the one previously entered in the LegalRepresentative of the user object.

As part of the BUSINESS_VERIFICATION check, the data in the next table is entered by the user and then validated against the national registry. If this check fails, then the session goes for manual review. If the session Status is ultimately VALIDATED, then the data entered is considered validated and overwritten in the user object. If the session outcome is REFUSED, no data is overwritten.