Create a Natural User - Mangopay docs

Overview

User management

User verification

User data format
KYC documents
UBO declarations

Wallets

User wallets
Client wallets

Cards

Card registrations
Cards
Metadata
Card validations

Card pay-ins

Direct card pay-ins
Recurring card pay-ins
Preauthorizations
Deposit preauthorizations
Web card pay-ins

Banking pay-ins

Bank wires
Virtual IBAN
Direct debits
Web direct debits

APM pay-ins

Apple Pay
Bancontact
BLIK
Giropay
Google Pay
iDEAL
Klarna
MB WAY
Multibanco
Payconiq
PayPal
Satispay
Swish
TWINT

Transfers

Transfers

Refunds

Refunds

Disputes

Disputes
Dispute documents
Repudiations
Dispute settlement

Payouts

Bank accounts
Payouts

FX conversions

Conversion rates
Quotes
Conversions

Transactions

Transactions

Helpers

API responses
Country authorizations
Webhooks
Events
Reports

Platform account

Client
Dashboard permissions

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.
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.

string

required

Format: A valid email address

The email address of the user.

Birthday

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

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

object

The postal address of the user.

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 individual.

Birthday

timestamp

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

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

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

Returned values: PAYER, OWNER, PLATFORM

The category of the user:

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.
PLATFORM – Value assigned only by Mangopay.

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
}  

{
    "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"
}

Was this page helpful?

The Natural User object Update a Natural User

{
    "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"
}

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