Skip to main content
The ApiIdentityVerification class provides methods to create and manage identity verification sessions, which allow users to verify their identity through a hosted verification flow.

​
Methods

​
Create

Creates a new identity verification session for a user. 
public function Create(
    $identityVerification,
    $userId,
    $idempotencyKey = null
)
​
return
\MangoPay\IdentityVerification
The created IdentityVerification object with the HostedUrl where the user should be redirected

​
Example

$api = new \MangoPay\MangoPayApi();
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';

$userId = '12345678';

$identityVerification = new \MangoPay\IdentityVerification();
$identityVerification->ReturnUrl = 'https://your-app.com/verification-complete';

$result = $api->IdentityVerification->Create(
    $identityVerification,
    $userId,
    'unique-idempotency-key-123'
);

echo "Verification ID: " . $result->Id . "\n";
echo "Redirect user to: " . $result->HostedUrl . "\n";
echo "Status: " . $result->Status . "\n";

​
Get

Retrieves a specific identity verification session by its identifier. 
public function Get($id)
​
return
\MangoPay\IdentityVerification
The IdentityVerification object returned from the API

​
Example

$api = new \MangoPay\MangoPayApi();
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';

$verificationId = '87654321';
$verification = $api->IdentityVerification->Get($verificationId);

echo "Status: " . $verification->Status . "\n";
echo "User ID: " . $verification->UserId . "\n";

if ($verification->Status === 'VALIDATED') {
    echo "Identity verification successful!\n";
} elseif ($verification->Status === 'REFUSED') {
    echo "Identity verification refused\n";
    // Check $verification->Checks for details
}

​
GetAll

Retrieves all identity verification sessions for a specific user. 
public function GetAll(
    $userId,
    $pagination = null,
    $filter = null,
    $sorting = null
)
​
return
\MangoPay\IdentityVerification[]
Array of IdentityVerification objects for the specified user

​
Example

$api = new \MangoPay\MangoPayApi();
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';

$userId = '12345678';
$pagination = new \MangoPay\Pagination(1, 50);

$verifications = $api->IdentityVerification->GetAll($userId, $pagination);

foreach ($verifications as $verification) {
    echo "ID: " . $verification->Id . "\n";
    echo "Status: " . $verification->Status . "\n";
    echo "Created: " . date('Y-m-d', $verification->CreationDate) . "\n";
    echo "---\n";
}

​
IdentityVerification Object

The IdentityVerification object represents an identity verification session.
​
Id
string
The unique identifier of the verification session
​
HostedUrl
string
The URL to redirect the user to for the hosted identity verification session. This URL is where users complete the verification process
​
Status
string
The current status of the identity verification session:
  • PENDING - The session is available on the HostedUrl, to which the user must be redirected to complete it
  • VALIDATED - The session was successful
  • REFUSED - The session was refused
  • REVIEW - The session is under manual review by Mangopay
  • OUT_OF_DATE - The session is no longer valid (likely due to expired documents used during the session)
  • TIMEOUT - The session timed out due to inactivity
  • ERROR - The session was not completed because an error occurred
​
ReturnUrl
string
The URL to which the user is returned after the hosted identity verification session, regardless of the outcome
​
UserId
string
The unique identifier of the user undergoing verification
​
LastUpdate
int
Unix timestamp of when the verification session was last updated
​
CreationDate
int
Unix timestamp of when the verification session was created
​
Checks
Check[]
Array of Check objects containing detailed verification results for different aspects of the identity verification process

​
Workflow

1

Create verification session

Call Create() with a user ID and return URL. The API returns a HostedUrl.
2

Redirect user

Redirect the user to the HostedUrl where they will complete the identity verification process.
3

User completes verification

The user uploads documents, takes selfies, or completes other verification steps as required.
4

User returns to your app

After completion (success or failure), the user is redirected to your ReturnUrl.
5

Check verification status

Use Get() to retrieve the session and check its Status and Checks to determine the verification outcome.

​
Best Practices

Always use the idempotencyKey parameter when creating verification sessions to prevent duplicate sessions if the request is retried.
Store the verification session ID in your database so you can check its status later. The user may not complete the verification immediately.

Build docs developers (and LLMs) love

Get started for freeTalk to us