User managementUsersNon-SCA endpoints

The Natural User object

Deprecated

Caution - Deprecated endpoints

The legacy User endpoints are deprecated. These endpoints will stop working and return an error after Dec 15, 2025.

These endpoints were made redundant by the equivalent SCA-enabled endpoints during the introduction of SCA.

The Natural User object represents an individual (natural person).

Mangopay users have one of two categories, indicated by UserCategory:

  • PAYER – User who can only make pay-ins to their wallets and transfers to other wallets.
  • OWNER – User who can also receive transfers to their wallets. Owners are able to request KYC verification, which if successful gives them the KYCLevel of REGULAR and the ability to request payouts.

Attributes

Address
objectRequired

The postal address of the beneficial owner.

AddressLine1
stringRequired

Max. length: 255 characters
The first line of the address.

AddressLine2
string

Max. length: 255 characters
The second line of the address.

City
stringRequired

Max. length: 255 characters
The city of the address.

Region
string

Max. length: 255 characters Required if Country is US, CA, or MX.

The region of the address.

PostalCode
stringRequired

Max. length: 255 characters
The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.

Country
stringRequired

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

The country of the address.

FirstName
string

Min. length: 1; max. length: 100

The first name of the individual.

LastName
string

Min. length: 1; max. length: 100

The last name of the user.

Birthday
Unix timestampRequired

The date of birth of the beneficial owner.

Note: This is a Unix timestamp in UTC. Ensure you convert your timezone to UTC to avoid midnight being interpreted as the day before.

Nationality
stringRequired

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

The nationality of the beneficial owner.

CountryOfResidence
string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

Required if UserCategory is OWNER. Returned null if UserCategory is PAYER.

The country of residence of the individual.

Occupation
string

Max. length: 255 characters
Returned null if UserCategory is PAYER.

The occupation of the individual.

IncomeRange
integer

Allowed values: 1, 2, 3, 4, 5, 6, null

Returned null if UserCategory is PAYER.

The bracket indicating the income of the individual. The brackets are:

  • 1: < 18K
  • 2: 18K - 30K
  • 3: 30K - 50K
  • 4: 50K - 80K
  • 5: 80K - 120K
  • 6: > 120K
ProofOfIdentity
string

The Id of the KYC Document whose Type is IDENTITY_PROOF if validated for the user. If no identity proof is validated, then this value is null.

ProofOfAddress
string

The Id of the KYC Document whose Type is ADDRESS_PROOF if validated for the user. If no address proof is validated, then this value is null.

Capacity
string

This is a deprecated parameter.

Id
string

The unique identifier of the object.

Tag
string

Custom data that can be added to this object.
In the case of the Card Registration, this parameter can be used to facilitate the link between the User object and its equivalent on your platform for instance. This value will be inherited by the Card object Tag parameter and will not be editable.

CreationDate
Unix timestamp

The date and time at which the object was created.

PersonType
string

Returned values: NATURAL, LEGAL

The type of the user:

  • NATURAL – Natural users are individuals (natural persons).
  • LEGAL – Legal users are legal entities (legal persons) like companies, non-profits, and sole proprietors.

The PersonType is defined by the endpoint used to create the user and can’t be modified.

Email
string

Format: A valid email address
The email address of the user.

KYCLevel
string

Default value: LIGHT

Returned values: LIGHT, REGULAR

The verification status of the user set by Mangopay:

  • LIGHT – Unverified, assigned by default to all users.
  • REGULAR – Verified, meaning the user has successfully completed the verification process and had the necessary documents validated by Mangopay. Only users whose UserCategory is OWNER can submit verification documents for validation. Only users whose KYCLevel is REGULAR can request payouts.
TermsAndConditionsAccepted
booleanRequired

Whether the user has accepted Mangopay’s terms and conditions (as defined by your contract, see the T&Cs guide for details).

Must be true if UserCategory is OWNER.

TermsAndConditionsAcceptedDate
Unix timestamp

The date and time at which the TermsAndConditionsAccepted value was set to true.

Returned null if UserCategory is PAYER.

UserCategory
stringRequired

Allowed values: PAYER, OWNER

The category of the user:

  • PAYER – User who can only make pay-ins to their wallets and transfers to other wallets (as well as refunds for pay-ins and transfers).
  • OWNER – User who can also receive transfers to their wallets. Owners are able to request KYC verification, which if successful gives them the KYCLevel of REGULAR and the ability to request payouts.
UserStatus
string

Returned values: ACTIVE, CLOSED

Internal use only. This field can only be used and updated by Mangopay teams.

Guide

Users – Introduction and types

Guide

Users – Categories