Create a Legal User

Read more about the Legal User object →

Note – Country-based restrictions apply to users

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

For Legal Users, the following parameters are concerned:

Country of the HeadquartersAddress
LegalRepresentativeNationality
LegalRepresentativeCountryOfResidence
Country of the LegalRepresentativeAddress

For more information, see the Country restrictions article.

Body parameters

HeadquartersAddress

object

Required if UserCategory is OWNER. Child parameters returned null if UserCategory is PAYER.

The legally registered address of the entity’s administrative center.

LegalRepresentativeAddress

object

The address of the entity’s legal representative.

Name

string

required

Max. length: 255 characters

The registered legal name of the entity. The Name value should be the one registered with the relevant national authority.

LegalPersonType

string

required

Allowed values: BUSINESS, PARTNERSHIP, ORGANIZATION, SOLETRADER

The type of legal user. For information on which LegalPersonType to use for a particular local legal structure, see the verification requirements.

Caution: Modification of the LegalPersonType may result in a verification downgrade.

LegalRepresentativeFirstName

string

required

Max. length: 100 characters

The first name of the entity’s legal representative.

LegalRepresentativeLastName

string

required

Max. length: 100 characters

The last name of the entity’s legal representative.

LegalRepresentativeEmail

string

Format: A valid email address

The email address of the entity’s legal representative.

Returned null if UserCategory is PAYER.

LegalRepresentativeBirthday

timestamp

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

The date of birth of the entity’s legal representative.

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

LegalRepresentativeNationality

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 entity’s legal representative.

LegalRepresentativeCountryOfResidence

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 entity’s legal representative.

CompanyNumber

string

Required if UserCategory is OWNER and LegalPersonType is BUSINESS. Returned null if UserCategory is PAYER.

The registration number of the entity, assigned by the relevant national authority. For information on the expected format for a specific country, see the Company number guide. To validate the format of a number before submitting documents for verification, use POST Validate the format of User data.

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 for the entity.

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

HeadquartersAddress

object

The legally registered address of the entity’s administrative center.
This object’s sub-parameters are null if the UserCategory is PAYER.

LegalRepresentativeAddress

object

The address of the entity’s legal representative.

Name

string

Max. length: 255 characters

The registered legal name of the entity. The Name value should be the one registered with the relevant national authority.

LegalPersonType

string

Returned values: BUSINESS, PARTNERSHIP, ORGANIZATION, SOLETRADER

The type of legal user. For information on which LegalPersonType to use for a particular local legal structure, see the verification requirements.

Caution: Modification of the LegalPersonType may result in a verification downgrade.

LegalRepresentativeFirstName

string

Max. length: 100 characters

The first name of the entity’s legal representative.

LegalRepresentativeLastName

string

Max. length: 100 characters

The last name of the entity’s legal representative.

LegalRepresentativeEmail

string

Format: A valid email address

The email address of the entity’s legal representative.

Returned null if UserCategory is PAYER.

LegalRepresentativeBirthday

timestamp

The date of birth of the entity’s legal representative.

Returned null if UserCategory is PAYER.

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

LegalRepresentativeNationality

string

Returned null if UserCategory is PAYER.

The nationality of the entity’s legal representative.

LegalRepresentativeCountryOfResidence

string

Returned null if UserCategory is PAYER.

The country of residence of the entity’s legal representative.

ProofOfRegistration

string

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

ShareholderDeclaration

string

The Id of the KYC Document whose Type is SHAREHOLDERS_DECLARATION if validated for the user. If no Shareholder Declaration is validated, then this value is null.

Statute

string

The Id of the KYC Document whose Type is ARTICLES_OF_ASSOCIATION if validated for the user. If no articles of association document is validated, then this value is null.

LegalRepresentativeProofOfIdentity

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.

CompanyNumber

string

Required if UserCategory is OWNER and LegalPersonType is BUSINESS. Returned null if UserCategory is PAYER.

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 for the entity.

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