Introduction and types
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
The obligations for 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.
Types
Mangopay provides payment services to platforms that serve both consumers and businesses. Therefore, there are two types of user:
- Natural users, for individuals (i.e., natural persons) over the age of 18
- Legal users, for entities like companies, organizations, and sole proprietors (i.e., legal persons)
In the API, natural and legal users are registered on different endpoints. In the User object, the PersonType
property has the values NATURAL
or LEGAL
.
Legal entities are defined and governed by the national legislation where they are based. To simplify this, Mangopay differentiates 4 types of legal user:
- Business, like a company or corporation
- Partnership, which is usually an association of sole proprietors
- Organization, for non-profits and similar
- Soletrader, which is a sole proprietor
In the API, the type of Legal User is set in the LegalPersonType
property, which has the values BUSINESS
, ORGANIZATION
, PARTNERSHIP
, SOLETRADER
.
The legal structure of your user’s business or legal entity determines the type they need in Mangopay’s system. Legal structures differ by country: the list of legal structures per country grouped under each type is listed in the local KYB page.
Caution - Partnership type is only for specific structures
The partnership type is designed for a specific kind of legal entity which typically doesn’t have a company number (making the Business type unsuitable). It is usually an association of sole proprietors.
Only the following are considered under the Partnership type:
- Gesellschaft bürgerlichen Rechts (GbR) in Germany
If the legal entity is not one of those specified above, even if the local legal name includes the notion of a ‘partnership’, it should be considered a Business. Incorrect submission as a Partnership will result in verification refusal and a request to re-categorize the entity.
Natural persons
A natural person, or individual, can be registered with Mangopay as:
- A natural user
- The declared legal representative of legal users
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 these individuals.
The rule aims to prevent misuse of Mangopay’s system and applies to all types of user and both categories (PAYER
and OWNER
). The rule is only active in the Production environment, not Sandbox.
The rule targets the following types of values:
- 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
)
Calls including such data on POST and PUT endpoints return the following 400 error:
This rule applies to the following fields:
Natural users
FirstName
LastName
Legal users
LegalRepresentative.FirstName
LegalRepresentative.FirstName
LegalRepresentativeFirstName
(legacy object)LegalRepresentativeLastName
(legacy object)
The rule applies to the following endpoints