Users

Overview

The Users API allows you to create and manage both natural (individual) and legal (business) users in your Mangopay platform. Users are the foundation of your payment system and can hold wallets, make transactions, and own payment methods. Mangopay supports two types of users:

Natural Users: Individual persons
Legal Users: Businesses, organizations, or other legal entities

Both types come in standard and SCA (Strong Customer Authentication) variants for enhanced security.

Methods

Create

Create a new user (natural or legal).

public function Create($user, $idempotencyKey = null)

user

UserLegal|UserNatural|UserNaturalSca|UserLegalSca

required

The user object to create. Pass either a UserNatural, UserNaturalSca, UserLegal, or UserLegalSca instance.

idempotencyKey

string

Optional idempotency key to ensure request uniqueness

Returns: UserLegal|UserNatural|UserNaturalSca|UserLegalSca - The created user object Example:

$api = new MangoPay\MangoPayApi();

// Create a natural user
$user = new MangoPay\UserNatural();
$user->FirstName = 'John';
$user->LastName = 'Doe';
$user->Email = '[email protected]';
$user->Birthday = mktime(0, 0, 0, 12, 21, 1985);
$user->Nationality = 'GB';
$user->CountryOfResidence = 'GB';
$user->Tag = 'Custom tag';

$createdUser = $api->Users->Create($user);

Get

Retrieve a user by their ID.

public function Get($userId)

userId

string

required

The unique identifier of the user

Returns: UserLegal|UserNatural - The user object Example:

$user = $api->Users->Get('user_123456');

GetSca

Retrieve an SCA user by their ID.

public function GetSca($userId)

userId

string

required

The unique identifier of the user

Returns: UserNaturalSca|UserLegalSca - The SCA user object Example:

$user = $api->Users->GetSca('user_123456');

GetNatural

Retrieve a natural user by their ID.

public function GetNatural($userId)

userId

string

required

The unique identifier of the natural user

Returns: UserNatural - The natural user object Example:

$user = $api->Users->GetNatural('user_123456');

GetNaturalSca

Retrieve an SCA natural user by their ID.

public function GetNaturalSca($userId)

userId

string

required

The unique identifier of the natural user

Returns: UserNaturalSca - The SCA natural user object

GetLegal

Retrieve a legal user by their ID.

public function GetLegal($userId)

userId

string

required

The unique identifier of the legal user

Returns: UserLegal - The legal user object Example:

$user = $api->Users->GetLegal('user_123456');

GetLegalSca

Retrieve an SCA legal user by their ID.

public function GetLegalSca($userId)

userId

string

required

The unique identifier of the legal user

Returns: UserLegalSca - The SCA legal user object

GetAll

Retrieve all users with pagination and sorting.

public function GetAll(& $pagination = null, $sorting = null)

pagination

Pagination

Pagination object (passed by reference, updated with total count)

sorting

Sorting

Sorting configuration object

Returns: UserLegal[]|UserNatural[] - Array of user objects Example:

$pagination = new MangoPay\Pagination(1, 10);
$users = $api->Users->GetAll($pagination);

Update

Update an existing user.

public function Update($user)

user

UserLegal|UserNatural

required

The user object with updated properties. Must include the user’s ID.

Returns: UserLegal|UserNatural - The updated user object Example:

$user = $api->Users->Get('user_123456');
$user->Email = '[email protected]';
$updatedUser = $api->Users->Update($user);

UpdateSca

Update an existing SCA user.

public function UpdateSca($user)

user

UserLegalSca|UserNaturalSca

required

The SCA user object with updated properties. Must include the user’s ID.

Returns: UserLegalSca|UserNaturalSca - The updated SCA user object

Categorize

Transition a Natural/Legal Payer to Owner (SCA). Some parameters may be required based on the kind of transition.

public function Categorize($user)

user

UserLegalSca|UserNaturalSca|UserLegal|UserNatural

required

The user object to categorize

Returns: UserLegalSca|UserNaturalSca|UserLegal|UserNatural - The categorized user object

Close

Close a user (change status to CLOSED). The resource remains available for historical purposes.

public function Close($user)

user

UserLegal|UserNatural|UserLegalSca|UserNaturalSca

required

The user object to close. Must include the user’s ID.

Returns: void Example:

$user = $api->Users->Get('user_123456');
$api->Users->Close($user);

Bank Accounts

CreateBankAccount

Create a bank account for a user.

public function CreateBankAccount($userId, $bankAccount, $idempotencyKey = null)

userId

string

required

The user ID

bankAccount

BankAccount

required

The bank account object to create

idempotencyKey

string

Optional idempotency key

Returns: BankAccount - The created bank account Example:

$bankAccount = new MangoPay\BankAccount();
$bankAccount->OwnerName = 'John Doe';
$bankAccount->Type = 'IBAN';
$bankAccount->OwnerAddress = new MangoPay\Address();
$bankAccount->OwnerAddress->AddressLine1 = '1 London Road';
$bankAccount->OwnerAddress->City = 'London';
$bankAccount->OwnerAddress->PostalCode = 'SW1A 1AA';
$bankAccount->OwnerAddress->Country = 'GB';

$details = new MangoPay\BankAccountDetailsIBAN();
$details->IBAN = 'GB33BUKB20201555555555';
$bankAccount->Details = $details;

$createdAccount = $api->Users->CreateBankAccount('user_123456', $bankAccount);

GetBankAccount

Retrieve a specific bank account for a user.

public function GetBankAccount($userId, $bankAccountId)

userId

string

required

The user ID

bankAccountId

string

required

The bank account ID

Returns: BankAccount - The bank account object

GetBankAccounts

Retrieve all bank accounts for a user.

public function GetBankAccounts($userId, & $pagination = null, $sorting = null, $filter = null)

userId

string

required

The user ID

pagination

Pagination

Pagination object

sorting

Sorting

Sorting configuration

filter

FilterBankAccounts

Filter criteria

Returns: BankAccount[] - Array of bank account objects

UpdateBankAccount

Update a bank account.

public function UpdateBankAccount($userId, $bankAccount)

userId

string

required

The user ID

bankAccount

BankAccount

required

The bank account object with updated properties

Returns: BankAccount - The updated bank account

Wallets

GetWallets

Retrieve all wallets for a user.

public function GetWallets($userId, & $pagination = null, $sorting = null, $filter = null)

userId

string

required

The user ID

pagination

Pagination

Pagination object

sorting

Sorting

Sorting configuration

filter

Filter

Filter criteria

Returns: Wallet[] - Array of wallet objects Example:

$wallets = $api->Users->GetWallets('user_123456');

Transactions

GetTransactions

Retrieve all transactions for a user.

public function GetTransactions($userId, & $pagination = null, $filter = null, $sorting = null)

userId

string

required

The user ID

pagination

Pagination

Pagination object

filter

FilterTransactions

Transaction filter criteria

sorting

Sorting

Sorting configuration

Returns: Transaction[] - Array of transaction objects Example:

$transactions = $api->Users->GetTransactions('user_123456');

Cards

GetCards

Retrieve all cards for a user.

public function GetCards($userId, & $pagination = null, $filter = null, $sorting = null)

userId

string

required

The user ID

pagination

Pagination

Pagination object

filter

FilterCards

Card filter criteria

sorting

Sorting

Sorting configuration

Returns: Card[] - Array of card objects Example:

$cards = $api->Users->GetCards('user_123456');

KYC Documents

CreateKycDocument

Create a new KYC (Know Your Customer) document for a user.

public function CreateKycDocument($userId, $kycDocument, $idempotencyKey = null)

userId

string

required

The user ID

kycDocument

KycDocument

required

The KYC document object

idempotencyKey

string

Optional idempotency key

Returns: KycDocument - The created KYC document

GetKycDocument

Retrieve a specific KYC document.

public function GetKycDocument($userId, $kycDocumentId)

userId

string

required

The user ID

kycDocumentId

string

required

The KYC document ID

Returns: KycDocument - The KYC document object

GetKycDocuments

Retrieve all KYC documents for a user.

public function GetKycDocuments($userId, & $pagination = null, $sorting = null, $filter = null)

userId

string

required

The user ID

pagination

Pagination

Pagination object

sorting

Sorting

Sorting configuration

filter

FilterKycDocuments

KYC document filter criteria

Returns: KycDocument[] - Array of KYC document objects

UpdateKycDocument

Update a KYC document.

public function UpdateKycDocument($userId, $kycDocument)

userId

string

required

The user ID

kycDocument

KycDocument

required

The KYC document object with updated properties

Returns: KycDocument - The updated KYC document

CreateKycPage

Create a page for a KYC document.

public function CreateKycPage($userId, $kycDocumentId, $kycPage, $idempotencyKey = null)

userId

string

required

The user ID

kycDocumentId

string

required

The KYC document ID

kycPage

KycPage

required

The KYC page object containing base64 encoded file data

idempotencyKey

string

Optional idempotency key

Returns: true - Always returns true on success

CreateKycPageFromFile

Create a page for a KYC document from a file path.

public function CreateKycPageFromFile($userId, $kycDocumentId, $filePath, $idempotencyKey = null)

userId

string

required

The user ID

kycDocumentId

string

required

The KYC document ID

filePath

string

required

Path to the file to upload

idempotencyKey

string

Optional idempotency key

Returns: true - Always returns true on success Example:

$kycDocument = new MangoPay\KycDocument();
$kycDocument->Type = 'IDENTITY_PROOF';
$kycDocument = $api->Users->CreateKycDocument('user_123456', $kycDocument);

$api->Users->CreateKycPageFromFile('user_123456', $kycDocument->Id, '/path/to/id.jpg');

Mandates

GetMandates

Retrieve all mandates for a user.

public function GetMandates($userId, & $pagination = null, $filter = null, $sorting = null)

userId

string

required

The user ID

pagination

Pagination

Pagination object

filter

FilterTransactions

Filter criteria

sorting

Sorting

Sorting configuration

Returns: Mandate[] - Array of mandate objects

GetMandatesForBankAccount

Retrieve mandates for a specific user and bank account.

public function GetMandatesForBankAccount($userId, $bankAccountId, & $pagination = null, $filter = null, $sorting = null)

userId

string

required

The user ID

bankAccountId

string

required

The bank account ID

pagination

Pagination

Pagination object

filter

FilterTransactions

Filter criteria

sorting

Sorting

Sorting configuration

Returns: Mandate[] - Array of mandate objects

PreAuthorizations

GetPreAuthorizations

Retrieve all pre-authorizations for a user.

public function GetPreAuthorizations($userId, $pagination = null, $filter = null, $sorting = null)

userId

string

required

The user ID

pagination

Pagination

Pagination object

filter

FilterPreAuthorizations

Pre-authorization filter criteria

sorting

Sorting

Sorting configuration

Returns: CardPreAuthorization[] - Array of pre-authorization objects

EMoney

GetEMoney

Retrieve the e-money for a user for a specific year or month.

public function GetEMoney($userId, $year = null, $month = null)

userId

string

required

The user ID

year

int

The year (defaults to current year if not provided)

month

int

The month (1-12). If not provided, returns yearly data.

Returns: EMoney - The e-money object Example:

// Get e-money for current year
$emoney = $api->Users->GetEMoney('user_123456');

// Get e-money for specific month
$emoney = $api->Users->GetEMoney('user_123456', 2024, 3);

Status and Compliance

GetBlockStatus

Retrieve the block status of a user.

public function GetBlockStatus($userId)

userId

string

required

The user ID

Returns: UserBlockStatus - The user block status object

GetRegulatory

Retrieve the regulatory block status of a user.

public function GetRegulatory($userId)

userId

string

required

The user ID

Returns: UserBlockStatus - The regulatory block status object

GetScaStatus

Retrieve the SCA status of a user.

public function GetScaStatus($userId)

userId

string

required

The user ID

Returns: ScaStatus - The SCA status object

ValidateTheFormatOfUserData

Check the validity of the format of user data and retrieve validation rules.

public function ValidateTheFormatOfUserData($companyNumberDetails)

companyNumberDetails

CompanyNumberDetails

required

The company number details to validate

Returns: CompanyNumberDetails - The validated company number details

SCA Enrollment

Enroll

Enroll an OWNER user in SCA (Strong Customer Authentication).

public function Enroll($userId, $idempotencyKey = null)

userId

string

required

The user ID (must be category OWNER)

idempotencyKey

string

Optional idempotency key

Returns: UserEnrollmentResult - Contains the redirect URL for SCA enrollment Example:

$result = $api->Users->Enroll('user_123456');
$redirectUrl = $result->PendingUserAction->RedirectUrl;
// Redirect user to this URL for SCA enrollment

ManageConsent

Manage user consent.

public function ManageConsent($userId, $idempotencyKey = null)

userId

string

required

The user ID

idempotencyKey

string

Optional idempotency key

Returns: UserConsent - The user consent object

Core

Wallets & Transfers

Payment Methods

Compliance & Verification

Banking Features

Disputes & Chargebacks

Webhooks & Events

Reporting

Client & Metadata

​Overview

​Methods

​Create

​Get

​GetSca

​GetNatural

​GetNaturalSca

​GetLegal

​GetLegalSca

​GetAll

​Update

​UpdateSca

​Categorize

​Close

​User-Related Operations

​Bank Accounts

​CreateBankAccount

​GetBankAccount

​GetBankAccounts

​UpdateBankAccount

​Wallets

​GetWallets

​Transactions

​GetTransactions

​Cards

​GetCards

​KYC Documents

​CreateKycDocument

​GetKycDocument

​GetKycDocuments

​UpdateKycDocument

​CreateKycPage

​CreateKycPageFromFile

​Mandates

​GetMandates

​GetMandatesForBankAccount

​PreAuthorizations

​GetPreAuthorizations

​EMoney

​GetEMoney

​Status and Compliance

​GetBlockStatus

​GetRegulatory

​GetScaStatus

​ValidateTheFormatOfUserData

​SCA Enrollment

​Enroll

​ManageConsent

​Related Resources

Build docs developers (and LLMs) love

Overview

Methods

Create

Get

GetSca

GetNatural

GetNaturalSca

GetLegal

GetLegalSca

GetAll

Update

UpdateSca

Categorize

Close

User-Related Operations

Bank Accounts

CreateBankAccount

GetBankAccount

GetBankAccounts

UpdateBankAccount

Wallets

GetWallets

Transactions

GetTransactions

Cards

GetCards

KYC Documents

CreateKycDocument

GetKycDocument

GetKycDocuments

UpdateKycDocument

CreateKycPage

CreateKycPageFromFile

Mandates

GetMandates

GetMandatesForBankAccount

PreAuthorizations

GetPreAuthorizations

EMoney

GetEMoney

Status and Compliance

GetBlockStatus

GetRegulatory

GetScaStatus

ValidateTheFormatOfUserData

SCA Enrollment

Enroll

ManageConsent

Related Resources