POST
/
v2.01
/
{ClientId}
/
users
/
natural
{
    "UserCategory": "PAYER",
    "TermsAndConditionsAccepted": false,
    "Address": {
        "AddressLine1": "3 rue de la Cité",
        "AddressLine2": "Appartement 7",
        "City": "Paris",
        "Region": "Île-de-France",
        "PostalCode": "75004",
        "Country": "FR"
    },
    "FirstName": "Alex",
    "LastName": "Smith",
    "Email": "alex.smith@example.com",
    "Tag": "Created using Mangopay API Postman collection"
}

{
    "Address": {
        "AddressLine1": "3 rue de la Cité",
        "AddressLine2": "Appartement 7",
        "City": "Paris",
        "Region": "Île-de-France",
        "PostalCode": "75004",
        "Country": "FR"
    },
    "FirstName": "Alex",
    "LastName": "Smith",
    "Birthday": null,
    "Nationality": null,
    "CountryOfResidence": null,
    "Occupation": null,
    "IncomeRange": null,
    "ProofOfIdentity": null,
    "ProofOfAddress": null,
    "Capacity": "NORMAL",
    "PhoneNumber": null,
    "PhoneNumberCountry": null,
    "Id": "user_m_01JHX2YFX51HSR8R2HJ8ABSEFF",
    "Tag": "Created using Mangopay API Postman collection",
    "CreationDate": 1737216704,
    "PersonType": "NATURAL",
    "Email": "alex.smith@example.com",
    "KYCLevel": "LIGHT",
    "TermsAndConditionsAccepted": false,
    "TermsAndConditionsAcceptedDate": null,
    "UserCategory": "PAYER",
    "UserStatus": "ACTIVE"
}

Note – Country-based restrictions apply to users

Due to Mangopay’s country restrictions, it is not possible to use blocked countries as the following:

  • Nationality
  • CountryOfResidence
  • Address.Country

​
Body parameters

​
UserCategory
string
required

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.
​
TermsAndConditionsAccepted
boolean
required

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.

​
FirstName
string
required

Min. length: 1; max. length: 100

The first name of the individual.

​
LastName
string
required

Min. length: 1; max. length: 100

The last name of the individual.

​
Email
string
required

Format: A valid email address

The email address of the user.

​
Birthday
Unix timestamp

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

The date of birth of the individual.

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
string

Format: 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

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.

​
Address
object

The postal address of the user.

​
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
​
Tag
string

Max. length: 255 characters

Custom data that you can add to this object.

​
Responses

{
    "Address": {
        "AddressLine1": "3 rue de la Cité",
        "AddressLine2": "Appartement 7",
        "City": "Paris",
        "Region": "Île-de-France",
        "PostalCode": "75004",
        "Country": "FR"
    },
    "FirstName": "Alex",
    "LastName": "Smith",
    "Birthday": null,
    "Nationality": null,
    "CountryOfResidence": null,
    "Occupation": null,
    "IncomeRange": null,
    "ProofOfIdentity": null,
    "ProofOfAddress": null,
    "Capacity": "NORMAL",
    "PhoneNumber": null,
    "PhoneNumberCountry": null,
    "Id": "user_m_01JHX2YFX51HSR8R2HJ8ABSEFF",
    "Tag": "Created using Mangopay API Postman collection",
    "CreationDate": 1737216704,
    "PersonType": "NATURAL",
    "Email": "alex.smith@example.com",
    "KYCLevel": "LIGHT",
    "TermsAndConditionsAccepted": false,
    "TermsAndConditionsAcceptedDate": null,
    "UserCategory": "PAYER",
    "UserStatus": "ACTIVE"
}

{
    "UserCategory": "PAYER",
    "TermsAndConditionsAccepted": false,
    "Address": {
        "AddressLine1": "3 rue de la Cité",
        "AddressLine2": "Appartement 7",
        "City": "Paris",
        "Region": "Île-de-France",
        "PostalCode": "75004",
        "Country": "FR"
    },
    "FirstName": "Alex",
    "LastName": "Smith",
    "Email": "alex.smith@example.com",
    "Tag": "Created using Mangopay API Postman collection"
}