Skip to main content

​
Overview

A Natural User represents an individual person in the Mangopay system. Natural users can create wallets, make payments, and perform other financial operations. Mangopay provides two variants:
  • UserNatural: Standard natural user
  • UserNaturalSca: Natural user with Strong Customer Authentication (SCA) support

​
UserNatural Properties

​
Base Properties (EntityBase)

​
Id
string
required
Unique identifier for the user (read-only)
​
Tag
string
Custom data for your own use
​
CreationDate
int
Unix timestamp of when the user was created (read-only)

​
User Properties

​
PersonType
string
required
Type of user. Always “NATURAL” for natural users (read-only)
​
Email
string
required
The user’s email address
​
KYCLevel
string
KYC (Know Your Customer) level. Values: “LIGHT” or “REGULAR” (read-only)
​
TermsAndConditionsAccepted
bool
Whether the user has accepted the MANGOPAY Terms and Conditions
​
TermsAndConditionsAcceptedDate
int
Unix timestamp of when the user accepted the Terms and Conditions (read-only)
​
UserCategory
string
Category of user. See UserCategory constants for possible values.
​
UserStatus
string
Status of the user (read-only)

​
Natural User Properties

​
FirstName
string
required
The user’s first name
​
LastName
string
required
The user’s last name
​
Address
Address
The user’s address object
​
Birthday
int
required
Unix timestamp of the user’s date of birth
​
Nationality
string
required
The user’s nationality (ISO 3166-1 alpha-2 country code)
​
CountryOfResidence
string
required
The user’s country of residence (ISO 3166-1 alpha-2 country code)
​
Occupation
string
The user’s occupation
​
IncomeRange
int
The user’s income range. See IncomeRange constants for possible values.
​
ProofOfIdentity
string
ID of the KYC document for proof of identity (read-only)
​
ProofOfAddress
string
ID of the KYC document for proof of address (read-only)
​
Capacity
string
Capacity of the user within MangoPay. See NaturalUserCapacity constants for possible values.

​
UserNaturalSca Properties

The UserNaturalSca class extends the standard UserNatural with additional SCA (Strong Customer Authentication) properties.

​
Additional SCA Properties

​
PhoneNumber
string
The user’s phone number in international format (E.164) or local format. Required if UserCategory is OWNER.Note: If UserCategory is OWNER, modifying this value requires the user to re-enroll via the PendingUserAction.RedirectUrl.
​
PhoneNumberCountry
string
Two-letter country code (ISO 3166-1 alpha-2) for the phone number. Required if PhoneNumber is in local format.Note: If UserCategory is OWNER, modifying this value requires the user to re-enroll via the PendingUserAction.RedirectUrl.
​
PendingUserAction
PendingUserAction
Information about required user action when UserStatus is PENDING_USER_ACTION. Otherwise null.Contains a RedirectUrl property where the user should be redirected for actions like SCA enrollment.
​
ScaContext
string
The SCA context for the user. Possible values: “USER_PRESENT”, “USER_NOT_PRESENT”

​
Example Usage

​
Creating a Standard Natural User

$api = new MangoPay\MangoPayApi();

$user = new MangoPay\UserNatural();
$user->FirstName = 'John';
$user->LastName = 'Doe';
$user->Email = '[email protected]';
$user->Birthday = mktime(0, 0, 0, 12, 21, 1985); // December 21, 1985
$user->Nationality = 'GB';
$user->CountryOfResidence = 'GB';
$user->Tag = 'Created from PHP SDK';

// Optional: Add address
$address = new MangoPay\Address();
$address->AddressLine1 = '1 London Road';
$address->City = 'London';
$address->PostalCode = 'SW1A 1AA';
$address->Country = 'GB';
$user->Address = $address;

$createdUser = $api->Users->Create($user);
echo 'User created with ID: ' . $createdUser->Id;

​
Creating an SCA Natural User

$api = new MangoPay\MangoPayApi();

$user = new MangoPay\UserNaturalSca();
$user->FirstName = 'Jane';
$user->LastName = 'Smith';
$user->Email = '[email protected]';
$user->Birthday = mktime(0, 0, 0, 5, 15, 1990);
$user->Nationality = 'FR';
$user->CountryOfResidence = 'FR';
$user->UserCategory = 'OWNER';
$user->PhoneNumber = '+33612345678';
$user->PhoneNumberCountry = 'FR';
$user->TermsAndConditionsAccepted = true;

$createdUser = $api->Users->Create($user);
echo 'SCA User created with ID: ' . $createdUser->Id;

​
Updating a Natural User

$api = new MangoPay\MangoPayApi();

// Get the existing user
$user = $api->Users->GetNatural('user_123456');

// Update properties
$user->Email = '[email protected]';
$user->Occupation = 'Software Engineer';
$user->IncomeRange = 3;

// Save the changes
$updatedUser = $api->Users->Update($user);
echo 'User updated successfully';

​
Retrieving a Natural User

$api = new MangoPay\MangoPayApi();

// Get a specific natural user
$user = $api->Users->GetNatural('user_123456');

echo 'User: ' . $user->FirstName . ' ' . $user->LastName;
echo 'Email: ' . $user->Email;
echo 'KYC Level: ' . $user->KYCLevel;

​
Working with SCA Users

$api = new MangoPay\MangoPayApi();

// Get an SCA natural user
$user = $api->Users->GetNaturalSca('user_123456');

// Check if user action is required
if ($user->UserStatus === 'PENDING_USER_ACTION' && $user->PendingUserAction) {
    $redirectUrl = $user->PendingUserAction->RedirectUrl;
    // Redirect the user to complete SCA enrollment
    echo 'Please complete enrollment at: ' . $redirectUrl;
}

​
Enrolling a User in SCA

$api = new MangoPay\MangoPayApi();

// Enroll an OWNER user in SCA
$enrollmentResult = $api->Users->Enroll('user_123456');

if (isset($enrollmentResult->PendingUserAction->RedirectUrl)) {
    $scaUrl = $enrollmentResult->PendingUserAction->RedirectUrl;
    // Add your return URL parameter
    $returnUrl = urlencode('https://yoursite.com/return');
    $fullUrl = $scaUrl . '?returnUrl=' . $returnUrl;
    
    // Redirect user to complete SCA
    header('Location: ' . $fullUrl);
}

​
Address Object

The Address object used in the Address property has the following structure: 
$address = new MangoPay\Address();
$address->AddressLine1 = 'Street address';
$address->AddressLine2 = 'Additional address info'; // Optional
$address->City = 'City name';
$address->Region = 'Region/State'; // Optional
$address->PostalCode = 'Postal code';
$address->Country = 'GB'; // ISO 3166-1 alpha-2 country code

​
Read-Only Properties

The following properties are read-only and cannot be modified:
  • Id
  • CreationDate
  • PersonType
  • TermsAndConditionsAcceptedDate
  • ProofOfIdentity
  • ProofOfAddress
  • KYCLevel
  • UserStatus

Build docs developers (and LLMs) love

Get started for freeTalk to us