Create an IDV Session

{
    "ReturnUrl": "https://example.com",
    "Tag": "Created using the Mangopay API Postman collection"
}

import com.mangopay.MangoPayApi;
import com.mangopay.entities.IdentityVerification;

public class CreateIdentityVerification {
    public static void main(String[] args) throws Exception {
        MangoPayApi mangopay = new MangoPayApi();
        mangopay.getConfig().setClientId("your-client-id");
        mangopay.getConfig().setClientPassword("your-api-key");

        String userId = "user_m_01KMD8QZHCVY2VPYV020RDBZGA";
        IdentityVerification dto = new IdentityVerification()
            .setReturnUrl("https://example.com");
        
        // optional Tag
        dto.setTag("Created by the Java SDK");

        IdentityVerification result = mangopay.getIdentityVerificationApi().create(dto, userId);
    }
}

const mangopayInstance = require('mangopay4-nodejs-sdk');
const mangopay = new mangopayInstance({
    clientId: 'your-client-id',
    clientApiKey: 'your-api-key',
});

const dto = {
    "ReturnUrl": "https://example.com",
    // optional Tag
    "Tag": "Created using the NodeJS SDK"
};

const userId = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA';

const createIdentityVerification = async (userId) => {
    return await mangopay.IdentityVerifications.create(userId, dto)
        .then((response) => {
            console.info(response);
            return response;
        })
        .catch((err) => {
            console.log(err);
            return false;
        });
};

createIdentityVerification(userId);

require 'mangopay'

MangoPay.configure do |client|
  client.preproduction = true
  client.client_id = 'your-client-id'
  client.client_apiKey = 'your-api-key'
  client.log_file = File.join(Dir.pwd, 'mangopay.log')
end

def create_identity_verification(dto, user_id)
  begin
    response = MangoPay::IdentityVerification.create(dto, user_id)
    puts response
    return response
  rescue MangoPay::ResponseError => error
    puts "Failed to create IdentityVerification: #{error.message}"
    puts "Error details: #{error.details}"
    return false
  end
end

user_id = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA'

dto = {
  ReturnUrl: 'https://example.com',
  # optional Tag
  Tag: 'created by the Ruby SDK'
}

create_identity_verification(dto, user_id)

import mangopay

mangopay.client_id='your-client-id'
mangopay.apikey='your-api-key'

from mangopay.api import APIRequest
handler = APIRequest(sandbox=True)

from mangopay.resources import IdentityVerification

user_id = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA'

dto = IdentityVerification(
    return_url = "https://example.com",
    # optional Tag
    tag = "created by the Python SDK"
)

result = dto.create(user_id)

<?php

require_once 'vendor/autoload.php';

use MangoPay\IdentityVerification;
use MangoPay\Libraries\Exception as MGPException;
use MangoPay\Libraries\ResponseException as MGPResponseException;
use MangoPay\MangoPayApi;

$api = new MangoPayApi();

$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';
$api->Config->TemporaryFolder = 'tmp/';

try {
    $userId = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA';

    $dto = new IdentityVerification();
    $dto->ReturnUrl = "https://example.com";
    // optional Tag
    $dto->Tag = "Created by the PHP SDK";

    $response = $api->IdentityVerifications->Create($dto, $userId);

    print_r($response);
} catch (MGPResponseException $e) {
    print_r($e);
} catch (MGPException $e) {
    print_r($e);
}

using System.Threading.Tasks;
using MangoPay.SDK;
using MangoPay.SDK.Entities.POST;

class CreateIdentityVerification
{
    static async Task Main(string[] args)
    {
        MangoPayApi api = new MangoPayApi();

        api.Config.ClientId = "your-client-id";
        api.Config.ClientPassword = "your-api-key";

        var userId = "user_m_01KMD8QZHCVY2VPYV020RDBZGA";

        IdentityVerificationPostDto postDto = new IdentityVerificationPostDto
        {
            ReturnUrl = "https://example.com",
            // optional Tag
            Tag = "Created by the .NET SDK"
        };

        var result = await api.IdentityVerifications.CreateAsync(postDto, userId);
    }
}

{
    "Id": "idnver_01JH2ZK1MKAMG5H2Q20M5K6020",
    "Tag": "Created using the Mangopay API Postman collection",
    "CreationDate": 1736340768,
    "HostedUrl": "https://user-verification.sandbox.mangopay.com/66ebfacebd780d434e8e6a9d?sessionId=677e75212400002f00a6edd0&redirectURL=https%3A%2F%2Fexample.com",
    "Status": "PENDING",
    "ReturnUrl": "https://example.com"
}

POST

v2.01

{ClientId}

users

{UserId}

identity-verifications

{
    "ReturnUrl": "https://example.com",
    "Tag": "Created using the Mangopay API Postman collection"
}

import com.mangopay.MangoPayApi;
import com.mangopay.entities.IdentityVerification;

public class CreateIdentityVerification {
    public static void main(String[] args) throws Exception {
        MangoPayApi mangopay = new MangoPayApi();
        mangopay.getConfig().setClientId("your-client-id");
        mangopay.getConfig().setClientPassword("your-api-key");

        String userId = "user_m_01KMD8QZHCVY2VPYV020RDBZGA";
        IdentityVerification dto = new IdentityVerification()
            .setReturnUrl("https://example.com");
        
        // optional Tag
        dto.setTag("Created by the Java SDK");

        IdentityVerification result = mangopay.getIdentityVerificationApi().create(dto, userId);
    }
}

const mangopayInstance = require('mangopay4-nodejs-sdk');
const mangopay = new mangopayInstance({
    clientId: 'your-client-id',
    clientApiKey: 'your-api-key',
});

const dto = {
    "ReturnUrl": "https://example.com",
    // optional Tag
    "Tag": "Created using the NodeJS SDK"
};

const userId = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA';

const createIdentityVerification = async (userId) => {
    return await mangopay.IdentityVerifications.create(userId, dto)
        .then((response) => {
            console.info(response);
            return response;
        })
        .catch((err) => {
            console.log(err);
            return false;
        });
};

createIdentityVerification(userId);

require 'mangopay'

MangoPay.configure do |client|
  client.preproduction = true
  client.client_id = 'your-client-id'
  client.client_apiKey = 'your-api-key'
  client.log_file = File.join(Dir.pwd, 'mangopay.log')
end

def create_identity_verification(dto, user_id)
  begin
    response = MangoPay::IdentityVerification.create(dto, user_id)
    puts response
    return response
  rescue MangoPay::ResponseError => error
    puts "Failed to create IdentityVerification: #{error.message}"
    puts "Error details: #{error.details}"
    return false
  end
end

user_id = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA'

dto = {
  ReturnUrl: 'https://example.com',
  # optional Tag
  Tag: 'created by the Ruby SDK'
}

create_identity_verification(dto, user_id)

import mangopay

mangopay.client_id='your-client-id'
mangopay.apikey='your-api-key'

from mangopay.api import APIRequest
handler = APIRequest(sandbox=True)

from mangopay.resources import IdentityVerification

user_id = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA'

dto = IdentityVerification(
    return_url = "https://example.com",
    # optional Tag
    tag = "created by the Python SDK"
)

result = dto.create(user_id)

<?php

require_once 'vendor/autoload.php';

use MangoPay\IdentityVerification;
use MangoPay\Libraries\Exception as MGPException;
use MangoPay\Libraries\ResponseException as MGPResponseException;
use MangoPay\MangoPayApi;

$api = new MangoPayApi();

$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';
$api->Config->TemporaryFolder = 'tmp/';

try {
    $userId = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA';

    $dto = new IdentityVerification();
    $dto->ReturnUrl = "https://example.com";
    // optional Tag
    $dto->Tag = "Created by the PHP SDK";

    $response = $api->IdentityVerifications->Create($dto, $userId);

    print_r($response);
} catch (MGPResponseException $e) {
    print_r($e);
} catch (MGPException $e) {
    print_r($e);
}

using System.Threading.Tasks;
using MangoPay.SDK;
using MangoPay.SDK.Entities.POST;

class CreateIdentityVerification
{
    static async Task Main(string[] args)
    {
        MangoPayApi api = new MangoPayApi();

        api.Config.ClientId = "your-client-id";
        api.Config.ClientPassword = "your-api-key";

        var userId = "user_m_01KMD8QZHCVY2VPYV020RDBZGA";

        IdentityVerificationPostDto postDto = new IdentityVerificationPostDto
        {
            ReturnUrl = "https://example.com",
            // optional Tag
            Tag = "Created by the .NET SDK"
        };

        var result = await api.IdentityVerifications.CreateAsync(postDto, userId);
    }
}

{
    "Id": "idnver_01JH2ZK1MKAMG5H2Q20M5K6020",
    "Tag": "Created using the Mangopay API Postman collection",
    "CreationDate": 1736340768,
    "HostedUrl": "https://user-verification.sandbox.mangopay.com/66ebfacebd780d434e8e6a9d?sessionId=677e75212400002f00a6edd0&redirectURL=https%3A%2F%2Fexample.com",
    "Status": "PENDING",
    "ReturnUrl": "https://example.com"
}

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 →

Path parameters

string

required

The unique identifier of the user.

Body parameters

string

required

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

string

Max. length: 255 charactersCustom data that you can add to this object.

Responses

200 - Response parameters

string

Max length: 128 characters (see data formats for details)The unique identifier of the object.

string

Max. length: 255 charactersCustom data that you can add to this object.

Unix timestamp

The date and time at which the object was created.

string

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

string

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.

string

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

403 - Feature not activated

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3",
    "title": "Forbidden",
    "status": 403,
    "traceId": "00-046605fe21abece0903b78483c6dc5dd-099f889c8e09309c-01"
}

400 - User ID not valid

{
    "Message": "Missing or incorrect required parameter",
    "Type": "param_error",
    "Id": "6b5b73cd-6d4c-4ea5-8859-9447dfe2c5b2",
    "Date": 1746458497.0,
    "errors": {
        "UserId": "UserId is not valid"
    }
}

400 - User must be OWNER

{
    "Message": "This feature is only available for users categorised as Owner.",
    "Type": "invalid_action",
    "Id": "49377b80-01b4-4b68-ba8b-99920aaf47a9",
    "Date": 1736344654.0,
    "errors": null
}

400 - Hosted solution not available for PARTNERSHIP user type

PARTNERSHIP

{
    "Message": "The LegalUserType PARTNERSHIP is not currently supported in the identity verification process. An event will be skipped. PartnerId: {ClientId}/ UserExternalId: {UserId}",
    "Type": "invalid_action",
    "Id": "58148aa4-57bb-4d61-94e6-c1450116606e",
    "Date": 1746458611.0,
    "errors": null
}

{
    "Id": "idnver_01JH2ZK1MKAMG5H2Q20M5K6020",
    "Tag": "Created using the Mangopay API Postman collection",
    "CreationDate": 1736340768,
    "HostedUrl": "https://user-verification.sandbox.mangopay.com/66ebfacebd780d434e8e6a9d?sessionId=677e75212400002f00a6edd0&redirectURL=https%3A%2F%2Fexample.com",
    "Status": "PENDING",
    "ReturnUrl": "https://example.com"
}

{
    "ReturnUrl": "https://example.com",
    "Tag": "Created using the Mangopay API Postman collection"
}

import com.mangopay.MangoPayApi;
import com.mangopay.entities.IdentityVerification;

public class CreateIdentityVerification {
    public static void main(String[] args) throws Exception {
        MangoPayApi mangopay = new MangoPayApi();
        mangopay.getConfig().setClientId("your-client-id");
        mangopay.getConfig().setClientPassword("your-api-key");

        String userId = "user_m_01KMD8QZHCVY2VPYV020RDBZGA";
        IdentityVerification dto = new IdentityVerification()
            .setReturnUrl("https://example.com");
        
        // optional Tag
        dto.setTag("Created by the Java SDK");

        IdentityVerification result = mangopay.getIdentityVerificationApi().create(dto, userId);
    }
}

const mangopayInstance = require('mangopay4-nodejs-sdk');
const mangopay = new mangopayInstance({
    clientId: 'your-client-id',
    clientApiKey: 'your-api-key',
});

const dto = {
    "ReturnUrl": "https://example.com",
    // optional Tag
    "Tag": "Created using the NodeJS SDK"
};

const userId = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA';

const createIdentityVerification = async (userId) => {
    return await mangopay.IdentityVerifications.create(userId, dto)
        .then((response) => {
            console.info(response);
            return response;
        })
        .catch((err) => {
            console.log(err);
            return false;
        });
};

createIdentityVerification(userId);

require 'mangopay'

MangoPay.configure do |client|
  client.preproduction = true
  client.client_id = 'your-client-id'
  client.client_apiKey = 'your-api-key'
  client.log_file = File.join(Dir.pwd, 'mangopay.log')
end

def create_identity_verification(dto, user_id)
  begin
    response = MangoPay::IdentityVerification.create(dto, user_id)
    puts response
    return response
  rescue MangoPay::ResponseError => error
    puts "Failed to create IdentityVerification: #{error.message}"
    puts "Error details: #{error.details}"
    return false
  end
end

user_id = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA'

dto = {
  ReturnUrl: 'https://example.com',
  # optional Tag
  Tag: 'created by the Ruby SDK'
}

create_identity_verification(dto, user_id)

import mangopay

mangopay.client_id='your-client-id'
mangopay.apikey='your-api-key'

from mangopay.api import APIRequest
handler = APIRequest(sandbox=True)

from mangopay.resources import IdentityVerification

user_id = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA'

dto = IdentityVerification(
    return_url = "https://example.com",
    # optional Tag
    tag = "created by the Python SDK"
)

result = dto.create(user_id)

<?php

require_once 'vendor/autoload.php';

use MangoPay\IdentityVerification;
use MangoPay\Libraries\Exception as MGPException;
use MangoPay\Libraries\ResponseException as MGPResponseException;
use MangoPay\MangoPayApi;

$api = new MangoPayApi();

$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';
$api->Config->TemporaryFolder = 'tmp/';

try {
    $userId = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA';

    $dto = new IdentityVerification();
    $dto->ReturnUrl = "https://example.com";
    // optional Tag
    $dto->Tag = "Created by the PHP SDK";

    $response = $api->IdentityVerifications->Create($dto, $userId);

    print_r($response);
} catch (MGPResponseException $e) {
    print_r($e);
} catch (MGPException $e) {
    print_r($e);
}

using System.Threading.Tasks;
using MangoPay.SDK;
using MangoPay.SDK.Entities.POST;

class CreateIdentityVerification
{
    static async Task Main(string[] args)
    {
        MangoPayApi api = new MangoPayApi();

        api.Config.ClientId = "your-client-id";
        api.Config.ClientPassword = "your-api-key";

        var userId = "user_m_01KMD8QZHCVY2VPYV020RDBZGA";

        IdentityVerificationPostDto postDto = new IdentityVerificationPostDto
        {
            ReturnUrl = "https://example.com",
            // optional Tag
            Tag = "Created by the .NET SDK"
        };

        var result = await api.IdentityVerifications.CreateAsync(postDto, userId);
    }
}

Overview

User management

User verification

Wallets

Cards

Card pay-ins

Banking pay-ins

APM pay-ins

Transfers

Refunds

Disputes

Payouts

FX conversions

Transactions

Echo

Helpers

Platform account

Path parameters

Body parameters

Responses

​Path parameters

​Body parameters

​Responses

Path parameters

Body parameters

Responses