Multi-session PSC flow for Legal Users

This page presents the user steps and validation checks for the hosted IDV flow for the Business, Organization, and Partnership user types, where every declared Person of Significant Control (PSC) completes their own liveness check.

What is a PSC?

A PSC is a person or entity that must be individually verified as part of Business, Organization, or Partnership verification. At least one beneficial owner (UBO) (owning 25% or more of the company) and at least one legal representative must be declared.

Where possible, Mangopay retrieves the list of PSCs from publicly available registries. The data can be confirmed in the hosted session, and an email address must be provided for each so that they can receive the link for their liveness check.

In the frontend session, the PSC is declared as one of the following (identified in the API as PSC_TYPE):

• UBO – A beneficial owner
• LEGAL_REP – A legal representative
• LEGAL_REP_AND_UBO – An individual who is both a legal representative and a UBO

A PSC can be declared as:

• An individual
• A business, in cases of complex or indirect ownership structures. In this case, details of all intermediary companies must be provided and the individual beneficiary of that business must also be identified

Prerequisites

Before launching a hosted IDV Session for a Business, Organization, or Partnership, the individual completing the main session needs to 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 PSCs (definition here)
• Each PSC has access to their own email address, or your platform is prepared to manage communication of their PSC Session link directly (see notifying PSCs)
• The ID proof each PSC will use is accepted by Mangopay

Flow description

When POST Create an IDV Session is called for a Legal Business, Organization, or Partnership:

1. The session Status is PENDING, indicating that it has been created and is available via the HostedUrl, regardless of whether the user has started or submitted it. 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 entity details
   • That they will need to declare the entity’s PSCs
   • 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)
3. The form is pre-filled with information from the Legal User object for the individual to confirm:
   • Country of incorporation
   • Registration number provided by the relevant national authority
   • Registered entity name
   • Registered entity address
4. Mangopay performs registry lookup using the entity details (BUSINESS_VERIFICATION).
5. The PSC declaration form is presented, depending on the registry lookup outcome:
   • If the company number, tax number, and/or business name return a match, the form is pre-filled with the PSCs found in the registry. The user completes any missing data and can add, edit, or remove PSCs.
   • If there is no match, the user fills in the PSC form from scratch.
6. If the user modifies the pre-filled PSC form (adding, editing, or removing a PSC), they are asked to provide supporting documentation to justify the change.
7. The user uploads KYB documents, depending on the registry lookup outcome:
   • If there is a match, the Registration Proof is required (and a supporting document if the PSC form was altered).
   • If there is no match, the Registration Proof and Articles of Association are both required.
8. Once submitted, the session is redirected to the ReturnUrl.
9. Mangopay runs the checks applicable to the main session, including PSC_ROLE_CHECK and PSC_CONSISTENCY_CHECK.
10. Separately, for each declared PSC, a PSC Session is created:
    • If an existing PSC has the same normalized name and date of birth, and the same role, the new declaration is treated as a duplicate and skipped.
    • If an existing PSC has the same normalized name and date of birth but a different role, a new PSC Session is created for the new role. The previous PSC Session is not automatically closed – Mangopay reviews and, if appropriate, abandons it (Status becomes ABANDONED).
    • Otherwise, a new PSC Session is created.
    • The PSC is notified of their PSC Session, either by email (using the address declared in the main session) or directly by your platform – see notifying PSCs. This emits the IDENTITY_VERIFICATION_PENDING_PSC_ACTION webhook (on the main session) and the IDENTITY_VERIFICATION_PSC_PENDING webhook (on the PSC) – see webhooks.
    • If the supporting documentation indicates that an additional PSC should have been declared, Mangopay may add one on the platform’s behalf, creating a new PSC Session for them.
11. Each PSC completes their own liveness check (via QR code or directly if the session is 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
12. Mangopay performs automated liveness validation checks on the PSC Session, including a name-match check against the PSC’s declared data.
13. Once all required checks for the main session have completed, the main session’s Status becomes VALIDATED, REFUSED, or REVIEW (for manual review), independently of the PSC Sessions. This emits the corresponding IDENTITY_VERIFICATION_VALIDATED, IDENTITY_VERIFICATION_FAILED, or IDENTITY_VERIFICATION_INCONCLUSIVE webhook.
14. Once a PSC Session’s checks are complete (or all its sub-sessions reach a terminal status), the PSC’s Status becomes VALIDATED or REJECTED. This emits the corresponding IDENTITY_VERIFICATION_PSC_VALIDATED or IDENTITY_VERIFICATION_PSC_REJECTED webhook.

Legal User verification criteria

A Business, Organization, or Partnership User becomes KYC/KYB verified (KYCLevel becomes REGULAR) when all of the following are true:

• The main session is VALIDATED, either automatically (Business only) or following manual review
• PSC_ROLE_CHECK and PSC_CONSISTENCY_CHECK have both passed
• Every declared PSC’s Status (in the PSCs array) is VALIDATED or ABANDONED

If any PSC’s Status is still PENDING_VALIDATION or REJECTED, the Legal User is not yet KYC/KYB verified.

See outcomes below for more details on the possible scenarios.

Notifying PSCs

Once a PSC Session is created, the PSC needs to receive its HostedUrl to complete their liveness check. By default, Mangopay uses the email declared in the main IDV Session to manage this, but your platform can opt to manage communications yourselves. Contact Mangopay via the Dashboard if you wish to do this.

Platform-managed communications

Your platform can communicate directly with the PSC – contact Mangopay via the Dashboard to deactivate the default emails. This may be preferable to optimmize engagement from PSCs who may be more familiar with your platform or the legal entity rather than Mangopay.

Listen for the IDENTITY_VERIFICATION_PENDING_PSC_ACTION webhook, then retrieve each PSC’s HostedUrl from the PSCs array via GET View an IDV Session and send it to the PSC yourself.

Mangopay emails

Unless your platform opts to manage PSC communications, Mangopay emails the PSC directly with the PSC Session link using the email address declared for them in the main session.

The email explains that the Legal User entity is in the process of verficiation, that the recipient has been identified as a PSC, and that they must complete their liveness check via the link provided for the entity’s verification to be completed.

If a PSC doesn’t complete their session, reminder emails are sent on the following schedule:

The email language is based on the main session’s language, falling back to English if not supported. The PSC can still change the language of their own session once they open the hosted link.

Checks performed

For Legal Business, Organization, and Partnership Users, the following checks are performed:

Testing

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

For this flow, the simulator allows you to simulate a match against the registry or no match, in which case the session goes to manual review.

When declaring PSCs in the main session, ensure you enter an email address to which you can receive Mangopay’s email containing the link (unless managing your own communications). You can also retrieve the PSC Session links from the GET View an IDV Session endpoint.

Each PSC Session can independently be simulated as VALIDATED or REJECTED.

Outcomes

Automated validation

For Business Users only, the main session’s Status becomes VALIDATED if all automated checks were successful. In this case:

• The verified data-equivalent data for the entity is overwritten in the User object: CompanyName, CompanyNumber
• The User’s KYCLevel becomes REGULAR once the Legal User verification criteria above is met

Organization and Partnership Users have no automated validation path – their main session is always sent for manual review.

Automated refusal

The main session’s Status becomes REFUSED if:

• BUSINESS_VERIFICATION fails outright
• PSC_ROLE_CHECK fails (no UBO and/or no legal representative declared) – this always results in refusal, since no supporting document can compensate for a missing role
• PSC_CONSISTENCY_CHECK fails and no supporting document was provided to justify the PSC form changes or a business-type PSC’s ownership structure

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 main session to retry

Manual review

Provided PSC_ROLE_CHECK passes, the main session’s Status becomes REVIEW if:

• The User is an Organization or Partnership (always, regardless of other check outcomes), or
• BUSINESS_VERIFICATION or BUSINESS_INSIGHTS_MATCH are not validated automatically (Business only), or
• PSC_CONSISTENCY_CHECK fails but a supporting document was provided to justify the PSC form changes or a business-type PSC’s ownership structure

In this case:

• Mangopay reviews the session data and documents manually.
• The Checks.CheckStatus shows which checks were REFUSED and triggered the manual review
• There is no impact on already-created PSC Sessions while the main session is under review

Validation or refusal after review

If the manual review is successful, the main session’s Status changes from REVIEW to VALIDATED, with the same effects as automated validation.

If the manual review is unsuccessful, the Status changes to REFUSED, with the same effects as automated refusal, except that Checks.Reasons.Value contains a custom message from the reviewer.

PSC Session outcomes

Each PSC Session resolves independently to one of:

• VALIDATED – the PSC’s liveness check and name-match check were successful
• REJECTED – one or more checks on the PSC Session failed, or the PSC did not complete their liveness check within the allowed timeframe (see session validity)
• ABANDONED – Mangopay abandoned the PSC Session, for example because it was a duplicate of another declared PSC. Your platform cannot trigger this directly.

A VALIDATED or REJECTED PSC Session can be retried using the PUT Retry a PSC Session endpoint, which generates a new hosted link for that PSC. If the PSC Session is still PENDING_VALIDATION, calling the retry endpoint returns the existing link instead of generating a new one. A PSC Session that is ABANDONED cannot be retried. To add a missing PSC, contact Mangopay via the Dashboard, who will create the new PSC and provide you with a session link.

Refusal reasons

In addition to the refusal reasons shared with other user types, the following are specific to the PSC checks in this flow:

• PSC_MISSING – returned on PSC_ROLE_CHECK
• PSC_FORM_ALTERED and UNVERIFIED_BUSINESS_PSC – returned on PSC_CONSISTENCY_CHECK
• PSC_MATCH_FAILED – returned on a PSC Session’s IDV_NAME_MATCH_CHECK

See the refusals guide for full descriptions and recommendations.

Webhooks

In addition to the main session webhooks, the following event types notify your platform about PSC Sessions specifically:

• IDENTITY_VERIFICATION_PENDING_PSC_ACTION – One or more PSCs have a hosted verification link ready to be completed. Use this event to retrieve each PSC’s HostedUrl from the PSCs array (via GET View an IDV Session) if you don’t rely on Mangopay to email PSCs directly.
• IDENTITY_VERIFICATION_PSC_PENDING, IDENTITY_VERIFICATION_PSC_VALIDATED, IDENTITY_VERIFICATION_PSC_REJECTED, IDENTITY_VERIFICATION_PSC_ABANDONED – notify your platform of PSC Session state changes. IDENTITY_VERIFICATION_PSC_REJECTED also fires if the PSC’s liveness check expires without being completed.

See the event types list for full descriptions.