Skip to main content
Your platform has a community of users. If you are going to process payments with Mangopay for these users, your system needs to register them as users via the API. Processing payments for your platform is a highly regulated activity. Mangopay has a legal obligation to:
  • Establish the identity of your users
  • Verify their identity if they wish to exceed KYC/KYB limits, such as to pay money out to their bank account

​
Types

Mangopay provides payment services to platforms that serve both consumers and businesses. The regulatory obligations to identify and verify users depend on who they are and what actions they are going to want to carry out on your platform. For this reason, Mangopay has created a system of user types and categories. There are two basic types of Mangopay user API object: Natural User and Legal User. There are different endpoints to create each one: The PersonType response property is common to both and indicates the type. It is not possible to change the same UserId from one type to the other. Legal entities are defined and governed by the national legislation where they are based. To simplify this, Mangopay differentiates 4 sub-types of Legal User:
  • Business, for companies or corporations
  • Partnership, for the GbR legal entity in Germany only
  • Organization, for non-profits and similar
  • Soletrader, for sole proprietors and individuals providing services
See the dedicated sections below for more details about Natural Users and each Legal User type. In the API, the type of Legal User is set in the LegalPersonType property, which has the values BUSINESS, ORGANIZATION, PARTNERSHIP, SOLETRADER. The LegalPersonType change be changed, but if the user is already KYC/KYB verified then they will be downgraded and need to undergo the process again.
Best practice - Check Mangopay’s local KYB guidanceThe legal structure of your user’s business or legal entity determines the User type they need in Mangopay’s system.Mangopay has listed local legal entity structures in a large number of countries to clarify which entities should be onboarded under which type.Based on the typical legal structures of your Legal Users and the countries you operate in, check the local KYB page to see which type to use for each entity type.

​
Natural User

A Natural User is individual acting in a private capacity. They must be over the age of 18. If the user is providing registered professional services then they may need to be registered as a Soletrader, see the dedicated guidance below. A Business, with LegalPersonType of BUSINESS, is a formally registered company that exists as a separate legal entity from its owners or directors. Typical examples include the following (but see the local KYB information for details):
  • Private limited companies (Ltd, LLC, GmbH, etc.)
  • Corporations
  • Registered commercial entity with legal business structures
An Organization, with LegalPersonType of ORGANIZATION, is a legally recognized group or non-profit entity that is not run for commercial gain. These entities usually have a formal legal structure but focus on charitable, social, community, or similar missions rather than traditional business activities. Typical examples include the following (but see the local KYB information for details):
  • Associations
  • NGOs
  • Foundations
  • Clubs
A Partnership, with LegalPersonType of PARTNERSHIP, is a Gesellschaft bürgerlichen Rechts (GbR) in Germany. This is the only type of entity that should be onboarded to Mangopay as a Partnership.
Caution – Do not use Partnership for any other entityThe PARTNERSHIP value must not be used for any entity other than the GbR in Germany, even if the local legal name includes the notion of a “partnership”.
A Soletrader, with LegalPersonType of SOLETRADER, is an individual operating a business in their own name, without forming a separate company. Typical examples include the following (but see the local KYB information for details):
  • Freelancers
  • Self-employed service providers
  • Independent professionals
These individuals are usually registered in their national jurisdiction with the official trade registry. However, this varies depending on the country involved and its jurisdiction. Local national registration is not necessary if:
  • The individual is using their first and last name (and no legal name)
  • The individual’s annual revenue is not high enough for the local income threshold
As described above, in some cases an individual is not required to register their activity or project. To be registered as a Legal Soletrader object, the individual must be able to justify their activity by providing proof of registration. Therefore, there are two possible options:
1. The individual is providing services in a professional capacity and registers their activity according to local law
In this case, their Mangopay account must be a Legal Soletrader. The KYB local page lists the local legal structures that should be onboarded as Soletraders in each country. To be KYC/KYB verified, they will need to provide proof of their local registration in addition to their ID proof.
2. The individual is not obliged to register their activity locally
In this case, their Mangopay account must be a Natural User. To be KYC/KYB verified, they will need to provide their ID proof. Furthermore, they must not use business-related data in their Mangopay account – notably, their Email must be a generic domain such as @gmail.com or @outlook.com, as described below. Note that it is not possible to transform a Natural User into a Legal Soletrader user or vice versa – the PersonType of the object cannot be changed. Therefore, if a user has the inappropriate PersonType, then the user must be re-registered as the correct type (and the redundant one can be closed).

​
Rules on user data

​
Rule preventing non-generic email domains for Natural Users

To protect your platform and users, Mangopay implements rules to prevent the Natural User object being used for individuals whose activity should be registered and verified accordingly. The Email property of the Natural User object only accepts generic email domains such as @gmail.com or @outlook.com. The individual registering as a Natural User must not use a professional email domain, for example contact@john-doe.com, info@project-name.com. This rule applies to both user categories (PAYER and OWNER), and in both Production and Sandbox. This rule may result in an API 400 error at creation or modification, meaning the following endpoints: When this rule is triggered by one of the API calls above, the API returns this error:
400 - Data doesn't comply with anti-fraud policy
{
    "Message": "The data you provided does not comply with our anti-fraud policy",
    "Type": "fraud_policy",
    "Id": "51876239-4814-422e-8f4b-6986520414bb#1750420019",
    "Date": 1750420020,
    "errors": null
}

​
Rule preventing fake user names

The identity information of individuals registered with Mangopay must be correct even if they are only making pay-ins on your platform (and so categorized as PAYERS). Mangopay operates an anti-fraud rule in the Production environment to prevent fictitious or fake values being used as the first name and last name of any individual registered with Mangopay. The rule aims to prevent misuse of Mangopay’s system and applies to all types of user and both categories (PAYER and OWNER). This rule applies to natural persons, which means:
  • A Natural User, in the FirstName and LastName
  • The declared legal representative of a Legal User, in the LegalRepresentative.FirstName and LegalRepresentative.FirstName
The rule targets the following types of values being used in these name properties:
  • Fictitious and fake names (examples: Marilyn Monroe, Homer Simpson)
  • Gibberish and random sequences (examples: aeofinzef, ojenoiner)
  • Keywords identified as not real names (examples: test, undefined, unknown)
The rule is only active in the Production environment, not Sandbox. The rule applies at creation or modification of the User. Calls including such data on POST and PUT endpoints return the following 400 error:
400 - Data doesn't comply with anti-fraud policy
{
    "Message": "The data you provided does not comply with our anti-fraud policy",
    "Type": "fraud_policy",
    "Id": "51876239-4814-422e-8f4b-6986520414bb#1750420019",
    "Date": 1750420020,
    "errors": null
}
The following endpoints may return this error because of this rule: