KYC/KYB integration

This guide explains how to integrate Mangopay’s hosted KYC/KYB verification solution, which you to redirect your users to a secure, Mangopay-hosted web experience where they can complete all the necessary steps.

​

Prerequisites

Before launching a session for a Natural User or Legal User in Production, ensure the following prerequisites are met.

​

User category must be Owner

To request identity verification, a User must have the UserCategory of OWNER. The OWNER category requires the user to provide additional basic information and enroll in Mangopay’s SCA (in Sandbox, you can bypass SCA by including the word accept in the Email or LegalRepresentative.Email). The hosted IDV solution is available for the following User types:

• Natural User
• Legal Business
• Legal Soletrader
• Legal Organization

The hosted solution is not available for the Legal Partnership type, which is only relevant for a specific legal entity (GbR) Germany (read more). If you’re integrating the hosted solution and you work with Partnership users, contact Mangopay via the Dashboard.

​

User data must match ID

The hosted IDV session verifies that the ID document used during the liveness check is for the registered user (and not someone else). Therefore, the following data points must match the ID that will be used. For a Natural User:

• FirstName
• LastName

For a Legal Soletrader and Legal Organization:

• LegalRepresentative.FirstName
• LegalRepresentative.LastName

For these user types, ensure you retrieve the user object data using GET View a User (SCA) and ask the user to verify that it matches their identity document. For Legal Business, the individual completing the liveness check does not have to be the pre-declared LegalRepresentative, but they do have to feature on the national registry of directors.

​

Documents must conform to requirements

The documents used or uploaded through the IDV session must conform to Mangopay’s requirements:

• ID proof – For Natural Users and individuals performing liveness checks, the identity document used must correspond to the forms of ID accepted by Mangopay.
• KYB documents – For Legal Soletrader, Business, and Organization, the Registration Proof and (if applicable) the Articles of Association must correspond to those listed in the KYB local reference, and translations must also be submitted where necessary.

The session provides links to these pages, but for legal users especially we recommend that you guide users in preparing their documents before initiating the session.

​

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

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. Mangopay’s Postman collection contains the endpoints you need create a User and launch their KYC/KYB session.

​

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:

​

Webhooks

In all cases, the hosted KYC/KYB verification feature takes time for the user to complete. You are strongly recommended to implement all 4 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:

• IDENTITY_VERIFICATION_PENDING – The IDV Session’s Status changed to PENDING and the session is available and hasn’t been completed. The session may or may not have been started and is valid for 24 hours from creation.
• 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_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.

​

Status and outcomes

The Status value of the IDV Session object indicates the outcome.

​

Success (automated)

If all the checks could be validated automatically, then the Status becomes VALIDATED. When the VALIDATED status is returned automatically:

• Verified data from the session is overwritten in the User object:
• The user’s KYC/KYB verification status is updated (user object’s KYCLevel becomes REGULAR)

​

Refusal (automated)

If the IDENTITY_DOCUMENT_VERIFICATION, IDV_NAME_MATCH_CHECK, or IDV_AGE_CHECK check are refused automatically then the session is automatically refused and the Status becomes REFUSED. When the REFUSED value is returned automatically:

• Verified data may be returned but no action is taken with it
• The user’s KYC/KYB verification status is not updated (user object’s KYCLevel remains LIGHT)
• The Checks.CheckStatus shows which checks were REFUSED and the Checks.Reasons shows the refusal reasons (Type and preset Value)

​

Review (manual)

Manual review is only possible for Legal users. If the BUSINESS_VERIFICATION returned no match or a partial match or the BUSINESS_INSIGHTS_MATCH (Business) or BUSINESS_NAME_CHECK (Soletrader) was not validated automatically, then the session must be reviewed manually by Mangopay and the Status becomes REVIEW. When the REVIEW status is returned:

• 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

​

Success (manual)

If the manual review is successful, then the status changes to VALIDATED. When the VALIDATED status is returned following manual review:

• Verified data from the session is overwritten in the User object
• The user’s KYC/KYB verification status is updated (user object’s KYCLevel becomes REGULAR)
• The Checks.CheckStatus and Checks.Reasons are not updated, so they may still show as REFUSED

​

Refusal (manual)

If the manual review is unsuccessful, then the status changes to REFUSED. When the VALIDATED status is returned following manual review:

• Verified data may be returned but no action is taken with it
• The user’s KYC/KYB verification status is not updated (user object’s KYCLevel remains LIGHT)
• The Checks.CheckStatus and Checks.Reasons are updated to provide the Type and a custom message in the Value

A refused session must be retried in full even if some of the Checks were successful. For example for businesses, if the session was refused due to the PSC data, registration proof or articles of association, then the entire session must be retried even if the IDENTITY_DOCUMENT_VERIFICATION check was validated.

​

Downgrade

Finally, the Status may also change to OUT_OF_DATE, which indicates that the user’s KYC/KYB verification status was downgraded. The user object’s KYCLevel was changed from REGULAR to LIGHT. For more information about this mechanism, see KYC/KYB downgrade. In this case, you need to create another IDV Session object for the user to go through the verification process again.

​

Verified data

The hosted KYC/KYB session gathers user data which is then verified as part of the process. This data, which is verified during automated checks, 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 be returned if the status is REFUSED or REVIEW. As part of the IDENTITY_DOCUMENT_VERIFICATION, 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 in the case of a Business user, the data below 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.

Data.Type value extracted from ID	User object property overwritten if Status is VALIDATED
FIRST_NAME	FirstName
LAST_NAME	LastName
BIRTHDATE	Birthday
LEGAL_REPRESENTATIVE_FIRST_NAME	LegalRepresentative.FirstName (or LegalRepresentativeFirstName on non-SCA object)
LEGAL_REPRESENTATIVE_LAST_NAME	LegalRepresentative.LastName (or LegalRepresentativeFirstName on non-SCA object)
LEGAL_REPRESENTATIVE_BIRTHDATE	LegalRepresentative.Birthday (or LegalRepresentativeBirthday on non-SCA object)

As part of the BUSINESS_VERIFICATION, 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.

Data.Type value entered by user	User object property overwritten if Status is VALIDATED
COMPANY_NAME	CompanyName
COMPANY_NUMBER	CompanyNumber

​

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.