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.
Note – Activation requiredThe hosted KYC/KYB verification feature must be activated by Mangopay. Contact our teams via the Dashboard to get started.

​
Endpoints

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

POST Create an IDV Session

Initiate a hosted KYC/KYB session and get the unique link for the frontend experience

GET View an IDV Session

See details of a hosted KYC/KYB session, outcome of checks, and verified data

GET List IDV Session for a User

Retrieve key details of all hosted KYC/KYC sessions attempted for a user

​
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. 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.
Note – Mismatched data causes session to failIf data of the individual’s identity document does not match the user object, or match the national business registry (in the case of Business users), then the session will not be successful.For Natural and Soletrader users, 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.The document they use must correspond to the forms of ID accepted by Manogopay.

​
Integration flow

1

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.
2

Send the user to the hosted session

Redirect the user to the HostedUrl value received in the response.The unique session remains valid indefinitely and has no timeout, so it can used to redirect the user immediately or later via another channel, such as by email.There is also no way in Mangopay’s product to differentiate between a session that has been started or not – both have the status PENDING. However, on your side you can track whether the HostedUrl was accessed by the user.
3

Let the user complete the session

On the HostedUrl, the experience guides them through all the required steps for KYC/KYB verification to submit their data and take photos of their accepted ID document and a selfie.Soletrader users, who represent individuals, may also need to submit files of their accepted registration proof if the automated registry lookup fails.For Business users:
  • , another term for beneficial owner (also known as a UBO), must be identified and their details entered
  • Once that is complete, the legal representative declared in the User object must use the same unique session URL to complete the liveness and ID check
See the user flows section for more details.Once the session is completed, the HostedUrl redirects to the ReturnUrl and the Status is updated from PENDING.
4

Receive webhooks and handle outcomes

When the outcome of the session is known, the Status is updated. This event triggers a webhook notification and there is a dedicated event type for the relevant values.For Natural users, the session is always processed automatically and the Status value can change from PENDING to either VALIDATED or REFUSED.For Legal users, the session can be fully processed automatically but it may also be inconclusive. In this case, the status changes to REVIEW and the session is sent to Mangopay’s teams for a manual processing.
Best practice - Integrate webhooksIn 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, call GET View an IDV Session for more details about the Checks performed and their outcome.

​
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

TypeDescription
IDENTITY_DOCUMENT_VERIFICATIONVerifies the authenticity of the identity document, the liveness of the selfie, and that the selfie matches the identity document photo.
IDV_NAME_MATCH_CHECKChecks 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_CHECKChecks 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

TypeDescription
BUSINESS_VERIFICATIONLooks 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_VERIFICATIONVerifies the authenticity of the identity document, the liveness of the selfie, and that the selfie matches the identity document photo.
IDV_NAME_MATCH_CHECKChecks 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_CHECKChecks 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_MATCHChecks 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
  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

TypeDescription
BUSINESS_VERIFICATIONLooks 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_VERIFICATIONVerifies the authenticity of the identity document, the liveness of the selfie, and that the selfie matches the identity document photo.
IDV_AGE_CHECKChecks 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_MATCHChecks 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.
Note – Mobile session attempts ID check automaticallyIf the session is open on a phone, the user is invited to take photos of their ID and a selfie, even if they are not the declared legal representative.The LegalRepresentative declared in the user object must be the individual who does the ID check.

​
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.
Note – Session doesn’t prevent incorrect uploadsOn the welcome screen, the session notes that the ID document used must correspond to one of those accepted by Mangopay and provides a link to the full list. However, the session supports types of ID that are not accepted by Mangopay.

​
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 IDUser object property overwritten if Status is VALIDATED
FIRST_NAMEFirstName
LAST_NAMELastName
BIRTHDATEBirthday
LEGAL_REPRESENTATIVE_FIRST_NAMELegalRepresentative.FirstName (or LegalRepresentativeFirstName on non-SCA object)
LEGAL_REPRESENTATIVE_LAST_NAMELegalRepresentative.LastName (or LegalRepresentativeFirstName on non-SCA object)
LEGAL_REPRESENTATIVE_BIRTHDATELegalRepresentative.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 userUser object property overwritten if Status is VALIDATED
COMPANY_NAMECompanyName
COMPANY_NUMBERCompanyNumber

​
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.
Note – Refer to custom comment for legal user reviewsFor Legal user sessions that were manually reviewed, ensure you check the Checks.Reasons.Value field for the customized comment from the person who conducted the review.The Value is preset if the session was automatically refused. If a Natural user session is refused it is always automatic (manual review is not possible), and a Legal user session may also be automatically refused.
CheckTypeRefusal Reasons.TypeIssueRecommendation
IDENTITY_DOCUMENT_VERIFICATIONDOCUMENT_NOT_ACCEPTEDThe 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_FAILThe 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_FALSIFIEDThe 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_UNREADABLEThe 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_EXPIREDThe 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_CHECKDOCUMENT_NOT_ACCEPTEDThe age of the individual must be over 18.
IDV_NAME_MATCH_CHECKDOCUMENT_NOT_ACCEPTEDThe 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_VERIFICATIONDOCUMENT_NOT_ACCEPTEDGeneric refusal status. See the specific comment in the Checks.Reasons.Value.Review the custom comment provided and respond accordingly.
DOCUMENT_TYPE_NOT_SUPPORTEDThe 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_EXPIREDThe 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_UNREADABLEThe 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_INCOMPLETEThe 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_MATCHBUSINESS_INSIGHTS_MATCH_FAILEDFor 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_MATCHBUSINESS_NAME_MATCH_FAILEDFor 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.