Hosted KYC/KYB solution

Mangopay’s hosted identity verification session enables platforms to redirect users to a secure, Mangopay-hosted web experience, where they can submit the necessary data and documents for KYC/KYB verification.

Based on the data and documents of the session, Mangopay performs automated checks and determines an outcome. In the case of Legal users, the session may also require a manual review from Mangopay’s team before an outcome can be given.

​

Endpoints

The following endpoints let you initiate and manage IDV Session objects:

​

User prerequisites

Before initiating a hosted KYC/KYB session for a user, you should ensure the user meets the criteria below.

​

User must be Owner category

Requesting KYC/KYB verification is only available to Owners, so UserCategory must be OWNER.

​

User must be Natural or Legal Soletrader or Business

The hosted KYC/KYB solution only supports Natural users or Legal users who are Soletraders or Businesses (LegalPersonType is SOLETRADER or BUSINESS).

The other Legal user types, Organization and Partnership, are not yet supported.

​

Documents used must be accepted by Mangopay

Mangopay accepts forms of identity documents based on their country of issue. The individual must complete the session using a document listed as an accepted form of ID.

For Legal users, Mangopay the user may be requested to provide a registration proof. For Businesses, they may also be request to provide their articles of association. The requirements for which specific document is required depend on the country of registration. These are available in the accepted KYB documents list, along with criteria for validity (for example, registry extracts must be dated within the last 3 months).

​

User data must be consistent with identity document

The hosted session analyzes the individual’s identity document and extracts its first name and last name. These three data points must correspond to data that is already present in the user object before the session is initiated. When a session is successful, these verified data points are overwritten in the user object (see verified data for details).

For Natural users, the first name and last name of the identity document must match the FirstName and LastName of the Natural object.

For Legal Soletrader users, then the first name and last name of the identity document must match the FirstName and LastName of the LegalRepresentative object of the corresponding Legal user.

For Legal Business users, the person completing the identity document check does not have to be the declared legal representative in the user object. However, they must be an individual listed as a company director in the relevant national registry.

​

Integration flow

​

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_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.
• 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.

​

User flows and checks performed

The type of session presented to the user depends on their type (PersonType and, if LEGAL, their LegalPersonType).

This section describes the actions taken by the user and the checks performed by Mangopay.

​

Natural user flow

1. User sees welcome screen explaining that they will need to take photos of their ID using their phone and linking to the accepted documents
2. 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
3. Session is redirected to ReturnUrl

​

Natural user checks performed

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.

​

Soletrader user flow

1. User sees welcome screen explaining the steps of the process, documents that may be required (with links to the accepted documents), and that they will need to take photos of their ID using their phone
2. User enters details of their sole proprietorship:
   • Country of registration
   • Registered business name
   • Registered business address and residential address
   • Registration number provided by the relevant national authority (if available)
3. Mangopay uses business details to attempt a lookup in relevant national registry (check type BUSINESS_VERIFICATION)
4. If the lookup was unsuccessful, the user must upload and submit an accepted registration proof and the session will be sent for manual review (Status value will be REVIEW)
5. 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
6. Session is redirected to ReturnUrl

​

Soletrader user checks performed

Type	Description
BUSINESS_VERIFICATION	Looks up the business details entered by the user during the session in the national registry to find a match. If not successful, the user is asked to upload a registration proof document and the session status will be REVIEW.
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 LegalRepresentative of the Legal user object. Only performed if IDENTITY_DOCUMENT_VERIFICATION is successful.
IDV_AGE_CHECK	Checks whether the individual on the ID document meets the minimum age requirement for Mangopay users (age 18). Only performed if IDENTITY_DOCUMENT_VERIFICATION is successful.
BUSINESS_NAME_MATCH	Checks whether the name on the identity document is present in the name of the registered sole proprietor in the relevant national registry. This check is performed manually if BUSINESS_VERIFICATION is unsuccessful.

​

Business user flow

1. User sees welcome screen explaining that they will need to take photos of their ID using their phone and linking to the accepted documents
2. User enters business details:
   • Country of incorporation
   • Registered business name
   • Registered business address and residential address
   • Registration number provided by the relevant national authority
3. User declares one or more beneficial owners as persons of significant control (PSC)
4. Mangopay uses business and PSC details to attempt a lookup in relevant national registry (check type BUSINESS_VERIFICATION)
5. There are three outcomes as a result of the registry lookup:
   1. 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.
   2. There is a match but the PSC data from the registry is not coherent with the PSC data declared in the session (may also be the outcome if businesses are listed in the national registry). In this case, the user must upload an accepted registration proof and the session is sent for manual review.
   3. There is a match and the PSC data from the registry is coherent with the PSC data declared in the session. In this case, no documents are required from the user and the session may be validated automatically (if the ID check is successful).
6. 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
7. Session is redirected to ReturnUrl

​

Business user checks performed

Type	Description
BUSINESS_VERIFICATION	Looks up the business details entered by the user during the session in the national registry to find a match. If not successful, the user is asked to upload a registration proof document and the session status will be REVIEW.
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_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.
BUSINESS_INSIGHTS_MATCH	Checks whether the name on the ID document matches one of the directors listed in the national registry, and whether the PSC data declared in the session is coherent with the PSC data in the registry. This check is performed manually if BUSINESS_VERIFICATION is unsuccessful.

​

Session notes

​

Available languages

The default session language is English. On the welcome screen, the user can change this to one of the other available options: Dutch, French, German, Italian, Polish, Portuguese, Spanish, Italian.

There is no way to change the default language.

When the QR code is scanned (see below), the mobile experience to take photos inherits the language of the session.

​

Session autosave and validity

The hosted KYC/KYB session autosaves the progress made by the user on each screen.

The session URL doesn’t expire.

Therefore, the session URL can be closed and re-opened before submission. So it can be sent to another individual to complete, which may particularly be helpful for Business users.

​

QR code on desktop

For steps that require the user to take a photo, if the URL is opened on a desktop browser then a QR code is presented on screen which the user must scan to open the session on their smartphone or tablet. Once scanned, the photo-taking progress is tracked on screen.

The experience attempts to automatically recognize the document or face in the screen and takes the photo. If this is unsuccessful, then the user can take a photo manually and choose to submit or retry.

​

Accepted documents

All documents submitted during the session must be those accepted by Mangopay.

For identity documents, this information is listed by country of issue in the accepted ID page.

For registration proof and articles of association, the accepted documents depend on the legal status and country of registration or incorporation and are listed in the KYB local page.

​

Persons of significant control (PSC)

For Business users, the individuals declared during the session as PSCs must be beneficial owners as defined by Mangopay here. The PSC language is used for technical reasons and alongside more familiar language of beneficial owners and UBOs.

PSC data entered by the user during a session is not made available to the platform directly. The UBO Declaration feature of the API is only relevant to the API-only KYC/KYB solution.

​

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

​

Refusals

In the case of unsuccessful session (Status is REFUSED), further information on the checks performed is in the Checks property. You can retrieve this using the GET View an IDV Session endpoint.

For Checks that have CheckStatus of REFUSED, the reasons for the refusal are given in the Reasons array, containing one or more objects containing Type and Value fields.

This information helps you understand why the session was refused and guide the user in retrying a new session successfully.

All the Checks.Reasons.Type values are listed below by CheckType along with recommendations for resolution.

CheckType	Refusal Reasons.Type	Issue	Recommendation
IDENTITY_DOCUMENT_VERIFICATION	DOCUMENT_NOT_ACCEPTED	The document is not in the list of accepted identity documents; it doesn’t fit the verification requirements outlined by Mangopay.	Check the Accepted ID documents to know whether your document is accepted based on its country of issue. Retry in a new session with your accepted document.
	FACE_MATCH_FAIL	The face on the selfie does not match the face of the document.	Retry in a new session, ensuring that the person who owns the ID is taking the selfie.
	DOCUMENT_FALSIFIED	The document seems to be fraudulent or contains inconsistent information.	Check that the document used is in line with the accepted documents and has not been altered by any means.
	DOCUMENT_UNREADABLE	The document is not clear enough.	Check that the document used is accepted. Retry the session ensuring the photos taken are clear and not blurred.
	DOCUMENT_HAS_EXPIRED	The document has passed its expiry date; it is no longer valid.	Check that your document is not expired. Retry the session with an in-date accepted document.
IDV_AGE_CHECK	DOCUMENT_NOT_ACCEPTED	The age of the individual must be over 18.
IDV_NAME_MATCH_CHECK	DOCUMENT_NOT_ACCEPTED	The first name and last name of the identity document did not match with the FirstName and LastName of the natural user or the declared LegalRepresentative in the user object.	First, update the data of the user object to match the identity document. Then, retry the session using the same identity document.
BUSINESS_VERIFICATION	DOCUMENT_NOT_ACCEPTED	Generic refusal status. See the specific comment in the Checks.Reasons.Value.	Review the custom comment provided and respond accordingly.
	DOCUMENT_TYPE_NOT_SUPPORTED	The document is not listed as accepted for the country of registration.	Check that the document corresponds to the requirements and retry the session.
	DOCUMENT_HAS_EXPIRED	The document is not valid or was issued more than 3 months ago.	Check that the document was issued within the last 3 months. For some countries, the requirements don’t include the 3-month rule but the document has a validity period which it has passed and/or it must be the latest up-to-date version of the document.
	DOCUMENT_UNREADABLE	The document is not clear enough.	Check the clarity and readability of your file before retrying the session, submitting a clear and up-to-date accepted document.
	DOCUMENT_INCOMPLETE	The document is incomplete or not sufficient on its own.	Ensure the document is dated and that all pages are present and in one of the supported languages (or along with a sworn translation). For most countries, declared legal representative should appear in the document(s).
BUSINESS_INSIGHTS_MATCH	BUSINESS_INSIGHTS_MATCH_FAILED	For Business users, the name on the identity document is not in the list of business directors obtained from the national registry.	Review the custom comment provided and respond accordingly.
BUSINESS_NAME_MATCH	BUSINESS_NAME_MATCH_FAILED	For Soletrader users, the name on the identity document does not feature in the registered name of the sole proprietor.	Review the custom comment provided and respond accordingly.