User verificationIDV sessions

Create an IDV Session

Initiate a hosted KYC/KYB session and obtain a unique URL for the hosted fronted experience.

The redirection link (HostedUrl) for the hosted KYC/KYB session must be completed and submitted within 7 days of creation.

Read more about hosted KYC/KYB →

Authentication

AuthorizationBearer
Bearer authentication of the form `Bearer <token>`, where token is your auth token. If your platform is using a [proxy](/guides/sca/proxy-management) to take SCA-triggering action on behalf of users, you also need to integrate [mTLS authentication](/guides/sca/platform) and use the `api-mtls` base URL.

Path parameters

ClientIdstringRequired
Platform's API account identifier, associated with the API key.
UserIdstringRequired
The unique identifier of the user.

Request

This endpoint expects an object.
ReturnUrlstringRequired

Max. length: 50

The URL to which the user is returned after the hosted identity verification session, regardless of the outcome.

TagstringOptional

Max. length: 255 characters

Custom data that you can add to this object.

Response

Success
Idstring

Max length: 128 characters (see data formats for details)

The unique identifier of the object.

Tagstring

Max. length: 255 characters

Custom data that you can add to this object.

CreationDateinteger

Unix timestamp (UTC) of the date and time the object was created.

HostedUrlstring
The URL to redirect the user to for the hosted identity verification session.
Statusstring

The status of the overall IDV Session:

  • PENDING – The unique HostedUrl for the session has not yet been submitted by the user. This temporary state can transition to VALIDATED, REFUSED, REVIEW, or EXPIRED.
  • REVIEW – One or more automated checks was neither successful nor refused, so the session was sent for manual review by Mangopay’s teams. This temporary state is only applicable to Legal users and can transition to REFUSED or VALIDATED.
  • VALIDATED – - The session was validated and the User became KYC/KYB verified (indicated by the User object’s KYCLevel). When the Status changes to VALIDATED, the verified data in Checks.Data is used to replace existing data in the User object.
  • REFUSED – The session was refused and the User is not KYC/KYB verified. The Checks.CheckStatus shows which checks were REFUSED and the Checks.Reasons shows the refused reason types and comment (which is custom text in the case of manual review for Legal users).
  • EXPIRED – The session was not submitted within 7 days of the CreationDate and no longer can be. Note however that the HostedUrl link remains accessible.
  • OUT_OF_DATE – The session is not valid because the user’s KYC/KYB verification status was downgraded by Mangopay.
ReturnUrlstring
The URL to which the user is returned after the hosted identity verification session, regardless of the outcome.

Errors

400
Bad Request Error
403
Forbidden Error