Create a Natural User

Note – Country-based restrictions apply to users

Due to Mangopay’s , it is not possible to create or modify users using blocked countries.

For Natural Users, the following parameters are concerned:

Nationality
CountryOfResidence
Country of the Address

For more information, see the Country restrictions article.

Body parameters

Address

object

The postal address of the user.

FirstName

string

required

Max. length: 100 characters

The first name of the individual.

LastName

string

required

Max. length: 100 characters

The last name of the individual.

Birthday

timestamp

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

The date of birth of the individual.

Note: Ensure this Unix timestamp accounts for your timezone to avoid midnight being interpreted as the day before.

Nationality

string

Allowed values: Two-letter country code (ISO 3166-1 alpha-2 format).

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

The nationality of the individual.

CountryOfResidence

string

Allowed values: 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

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

Tag

string

Max. length: 255 characters

Custom data that you can add to this object.

string

required

Format: A valid email address

The email address of the user.

TermsAndConditionsAccepted

boolean

required

Default value: false

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.

UserCategory

string

required

Default value: PAYER

Allowed values: PAYER, OWNER

The category of the user:

PAYER – User who can only make pay-ins to their wallet and transfers to other wallets.
OWNER – User who can do everything a Payer can, plus receive transfers to their wallet. To request payouts, an Owner user’s KYCLevel must be REGULAR. For more information, see the Verification section.

Responses

Address

object

The postal address of the user.

FirstName

string

Max. length: 100 characters

The first name of the individual.

LastName

string

Max. length: 100 characters

The last name of the individual.

Birthday

timestamp

Returned null if UserCategory is PAYER.

The date of birth of the individual.

Note: Ensure this Unix timestamp accounts for your timezone to avoid midnight being interpreted as the day before.

Nationality

string

Returned null if UserCategory is PAYER.

The nationality of the individual.

CountryOfResidence

string

Returned null if UserCategory is PAYER.

The country of residence of the individual.

Occupation

string

Max. length: 255 characters

The occupation of the individual.

Returned null if UserCategory is PAYER.

IncomeRange

integer

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.

string

The unique identifier of the object.

Tag

string

Max. length: 255 characters

Custom data that you can add to this object.

CreationDate

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.

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

boolean

Default value: false

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

timestamp

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

Returned null if UserCategory is PAYER.

UserCategory

string

Default value: PAYER

Returned values: PAYER, OWNER, PLATFORM

The category of the user:

PAYER – User who can only make pay-ins to their wallet and transfers to other wallets.
OWNER – User who can do everything a Payer can, plus receive transfers to their wallet. To request payouts, an Owner user’s KYCLevel must be REGULAR. For more information, see the Verification section.

UserStatus

string

Returned values: ACTIVE, CLOSED

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

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "49616dff-19d6-4bec-b82e-0daf09529f52#1676551648",
    "Date": 1676551649.0,
    "errors": {
        "Nationality": "The Nationality used is blocked"
    }
}  

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "864a164a-cbb9-4e9d-b140-2b83c720e729",
    "Date": 1690291065.0,
    "errors": {
        "Email": "The field Email must match the regular expression '([a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*)@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?'."
    }
}  

{
  "Message": "User must accept the terms and conditions before account creation or modification.",
  "Type": "user_hasnt_accepted_terms_and_conditions",
  "Id": "dbbc752b-6f9f-4248-a4bb-04ee0ba7b4b7",
  "Date": 1730810728,
  "errors": null
}  

Overview

User management

User verification

Wallets

Cards

Card pay-ins

Banking pay-ins

APM pay-ins

Transfers

Refunds

Disputes

Payouts

FX conversions

Transactions

Helpers

Platform account

Body parameters

Responses

Overview

User management

User verification

Wallets

Cards

Card pay-ins

Banking pay-ins

APM pay-ins

Transfers

Refunds

Disputes

Payouts

FX conversions

Transactions

Helpers

Platform account

​Body parameters

​Responses

Body parameters

Responses