Skip to main content

​
Overview

Users are the foundation of the Mangopay platform. They represent individuals or legal entities that can hold wallets, make payments, and perform other financial operations.

​
User Types

Mangopay supports two main types of users:

Natural Users

Individual persons (consumers, freelancers)

Legal Users

Organizations and businesses

​
Natural Users

Natural users represent individual persons. The UserNatural class includes: 
use MangoPay\UserNatural;
use MangoPay\Address;

$user = new UserNatural();
$user->FirstName = "John";
$user->LastName = "Doe";
$user->Email = "[email protected]";
$user->Birthday = mktime(0, 0, 0, 12, 21, 1990);
$user->Nationality = "FR";
$user->CountryOfResidence = "FR";
$user->Occupation = "Programmer";
$user->IncomeRange = 3;
$user->TermsAndConditionsAccepted = true;

// Address is required
$address = new Address();
$address->AddressLine1 = "123 Main Street";
$address->City = "Paris";
$address->PostalCode = "75001";
$address->Country = "FR";
$user->Address = $address;

$createdUser = $api->Users->Create($user);
Reference: ~/workspace/source/MangoPay/UserNatural.php:8

​
Key Properties

  • FirstName / LastName - User’s legal name
  • Email - Contact email (required)
  • Birthday - Unix timestamp of birth date
  • Nationality - ISO 3166-1 alpha-2 country code
  • CountryOfResidence - ISO 3166-1 alpha-2 country code
  • Address - Residential address
  • Occupation - Professional activity
  • IncomeRange - Income bracket (1-6)
Legal users represent companies and organizations: 
use MangoPay\UserLegal;
use MangoPay\LegalPersonType;
use MangoPay\Address;

$legalUser = new UserLegal();
$legalUser->Name = "Tech Startup Inc";
$legalUser->Email = "[email protected]";
$legalUser->LegalPersonType = LegalPersonType::Business;
$legalUser->CompanyNumber = "123456789";
$legalUser->TermsAndConditionsAccepted = true;

// Headquarters address
$headquarters = new Address();
$headquarters->AddressLine1 = "456 Business Avenue";
$headquarters->City = "Paris";
$headquarters->PostalCode = "75002";
$headquarters->Country = "FR";
$legalUser->HeadquartersAddress = $headquarters;

// Legal representative information
$legalUser->LegalRepresentativeFirstName = "Jane";
$legalUser->LegalRepresentativeLastName = "Smith";
$legalUser->LegalRepresentativeEmail = "[email protected]";
$legalUser->LegalRepresentativeBirthday = mktime(0, 0, 0, 5, 15, 1985);
$legalUser->LegalRepresentativeNationality = "FR";
$legalUser->LegalRepresentativeCountryOfResidence = "FR";

$repAddress = new Address();
$repAddress->AddressLine1 = "789 Rep Street";
$repAddress->City = "Paris";
$repAddress->PostalCode = "75003";
$repAddress->Country = "FR";
$legalUser->LegalRepresentativeAddress = $repAddress;

$createdLegalUser = $api->Users->Create($legalUser);
Reference: ~/workspace/source/MangoPay/UserLegal.php:8

​
Key Properties

  • Name - Legal entity name
  • LegalPersonType - Either BUSINESS or ORGANIZATION
  • HeadquartersAddress - Company address
  • CompanyNumber - Official registration number
  • LegalRepresentative* - Information about the person representing the entity

​
User Categories

Users can be categorized as:
  • PAYER - Can only pay-in funds (simplified KYC requirements)
  • OWNER - Can receive funds and transfer (requires full KYC)
Reference: ~/workspace/source/MangoPay/User.php:44

​
CRUD Operations

​
Create a User

// The Create method automatically detects the user type
$user = $api->Users->Create($userNatural);
$legalUser = $api->Users->Create($userLegal);
Reference: ~/workspace/source/MangoPay/ApiUsers.php:16

​
Get a User

// Get any user type
$user = $api->Users->Get($userId);

// Get specific user type
$naturalUser = $api->Users->GetNatural($userId);
$legalUser = $api->Users->GetLegal($userId);
Reference: ~/workspace/source/MangoPay/ApiUsers.php:59

​
Update a User

$user = $api->Users->Get($userId);
$user->Email = "[email protected]";
$user->Occupation = "Designer";

$updatedUser = $api->Users->Update($user);
Reference: ~/workspace/source/MangoPay/ApiUsers.php:126

​
List All Users

use MangoPay\Pagination;
use MangoPay\Sorting;
use MangoPay\SortDirection;

$pagination = new Pagination(1, 50); // Page 1, 50 items per page
$sorting = new Sorting();
$sorting->AddField('CreationDate', SortDirection::DESC);

$users = $api->Users->GetAll($pagination, $sorting);
Reference: ~/workspace/source/MangoPay/ApiUsers.php:41

​
Close a User

// Closes the user account (changes status to CLOSED)
// The resource remains available for historical purposes
$api->Users->Close($user);
Reference: ~/workspace/source/MangoPay/ApiUsers.php:592

​
KYC and Verification

​
KYC Levels

  • LIGHT - Basic verification, limited transaction amounts
  • REGULAR - Full verification, no transaction limits
Reference: ~/workspace/source/MangoPay/User.php:26

​
Create KYC Document

use MangoPay\KycDocument;

$kycDocument = new KycDocument();
$kycDocument->Type = 'IDENTITY_PROOF';

$createdDoc = $api->Users->CreateKycDocument($userId, $kycDocument);

​
Upload KYC Page

// From file
$api->Users->CreateKycPageFromFile(
    $userId,
    $kycDocumentId,
    '/path/to/document.jpg'
);

// From base64 encoded content
use MangoPay\KycPage;

$kycPage = new KycPage();
$kycPage->File = base64_encode(file_get_contents('/path/to/document.jpg'));

$api->Users->CreateKycPage($userId, $kycDocumentId, $kycPage);
Reference: ~/workspace/source/MangoPay/ApiUsers.php:415

​
Submit KYC Document

$kycDocument->Status = 'VALIDATION_ASKED';
$api->Users->UpdateKycDocument($userId, $kycDocument);

​
Strong Customer Authentication (SCA)

For users requiring SCA, use the SCA-specific user types: 
use MangoPay\UserNaturalSca;
use MangoPay\UserLegalSca;
use MangoPay\UserCategory;

$scaUser = new UserNaturalSca();
$scaUser->FirstName = "John";
$scaUser->LastName = "Doe";
$scaUser->Email = "[email protected]";
$scaUser->UserCategory = UserCategory::Owner;
$scaUser->TermsAndConditionsAccepted = true;

$createdScaUser = $api->Users->Create($scaUser);

// Enroll user in SCA
$enrollmentResult = $api->Users->Enroll($createdScaUser->Id);
// Redirect user to: $enrollmentResult->PendingUserAction->RedirectUrl
Reference: ~/workspace/source/MangoPay/ApiUsers.php:557 Users can have associated resources:

​
Bank Accounts

use MangoPay\BankAccount;
use MangoPay\BankAccountDetailsIBAN;

$bankAccount = new BankAccount();
$bankAccount->OwnerName = "John Doe";
$bankAccount->OwnerAddress = $address;
$bankAccount->Type = 'IBAN';

$details = new BankAccountDetailsIBAN();
$details->IBAN = "FR7618829754160173622224154";
$details->BIC = "CMBRFR2BCME";
$bankAccount->Details = $details;

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

​
Wallets

// Get all wallets for a user
$wallets = $api->Users->GetWallets($userId, $pagination);
Reference: ~/workspace/source/MangoPay/ApiUsers.php:276

​
Transactions

use MangoPay\FilterTransactions;

$filter = new FilterTransactions();
$filter->Type = 'PAYIN';
$filter->Status = 'SUCCEEDED';

$transactions = $api->Users->GetTransactions($userId, $pagination, $filter);
Reference: ~/workspace/source/MangoPay/ApiUsers.php:290

​
Best Practices

Ensure email addresses are valid and belong to the user, as they’re used for important notifications.
Map Mangopay user IDs to your application’s user records in your database.
Guide users through KYC verification before they need to perform transactions that require it.
Choose PAYER for users who only need to make payments, OWNER for those who need to receive funds.
Regularly sync user information changes between your system and Mangopay.

​
Next Steps

Wallets

Learn how to create and manage wallets

Payment Flows

Understand payment operations

Build docs developers (and LLMs) love

Get started for freeTalk to us