Introduction to users

Introduction

In Mipise Payment Services (MPS), a User represents the holder of one or several payment accounts.
Each user is linked to at least one Person - which defines the actual individual(s) or organization related to the account.

Understanding User vs Person

In Mipise Payment Services (MPS), User and Person are distinct but linked API objects. To integrate successfully, you must distinguish between the digital account holder and the legal identity behind it.

Concept	Description	Role & Identifiers
User	The Digital Account Owner. It is the top-level entity that holds the payment accounts and the balance.	It holds the email and login credentials. All API actions are performed on behalf of a User.
Person	The Real-World Identity. It contains the specific legal data (name, address, DOB) required for regulatory verification.	It carries the KYC/AML data. A Person is always attached to a User to justify the legality of the account.

The Core Relationship

While every User must be linked to at least one Person, the complexity of this relationship depends on the type of account:

For Natural Persons (Individuals): It is a 1:1 relationship. The Person is the User. One digital account corresponds to one real-world individual.
For Legal Persons (Entities): It is a 1:N relationship. A single User (the Company/Association) represents the account holder, but it requires:
1. At least one Natural Person designated as the Legal Representative (flagged with user_representative: true).
2. UBO Declarations: Unlike the Representative, Ultimate Beneficial Owners (UBOs) may not be created as separate Person objects in the API but are declared through specific compliance documents.

Important: If a compliance issue is detected during the verification of any attached identity or document, the entire User account and its associated functions are typically blocked.

Business Example

Individual Case:
- User: [email protected] (holds the login and the funds).
- Person: John Doe (Natural Person, provides the ID card and address).
Business Case:
- User: [email protected] (The company's digital identity in MPS).
- Person (Entity): TechCorp Ltd (Legal Person, provides the registration/Kbis).
- Person (Rep): Jane Smith (Natural Person, Legal Representative with the power to operate the account).
- UBOs: Declared via articles of association and UBO forms provided as documents.

General Principles

Identifiers:
- platformUUID → unique identifier of the platform through which users are created and managed.
  - This one is always required for all API endpoints.
  - Check The Platforms page for more information about the platforms.
- userUUID → unique identifier of a User
  - The Mipise Payment Services (MPS) account holder.
  - Each user has a unique identifier, owns one or several payment accounts, and is linked to its person(s).
- personUUID → unique identifier of a Person
  - The legal or natural entity(ies) attached to a user (individual, company, association...).
User creation requires a complete person object corresponding to the person using the account :
- Persons::Natural → to define an individual.
- Persons::Legal → to define a legal entity.
Legal Person rule: Each Persons::Legal must include at least one child Persons::Natural with
"user_representative": true. This will be the legal representative.
Platform responsibility:
Agents (platforms) collect and send user data, but MPS performs the final KYC validation.

1. User Creation

Agents initiate user creation via the endpoint POST User Creation.

When creating a user, the Agent must include a person object with all relevant data according to the person type :

The fields required depend on the person type (Persons::Natural, Persons::Legal).
Each field in the endpoints pages explicitly mentions if it applies to Natural or Legal persons.

👍
Best practice: Always fill the person object as completely as possible, even if not all fields are strictly mandatory.

A Natural person 🧍 (individual) at least requires:

first_name
last_name
birth_date
nationality
address

A Legal person 🏢 (company, association, etc...) at least requires:

category (business category)
business_entity (company / association name)
nationality
address

⚠️
Important: If you create a user represented by a Persons::Legal, you must also attach at least one childPersons::Natural that represents the legal representative.
Inside this child object, set:
"user_representative": true

📘
The Agent is responsible for collecting complete and accurate information from the future account holder.
MPS performs final regulatory checks, including KYC validation and due diligence review.

2. User Consultation

Agents can retrieve:

The list of users on their platform → GET Users List
The details of one specific user → GET User Details

📘
Access is always limited to the Agent’s own platform scope.
Only the minimum necessary data is returned, following GDPR’s principle of least privilege.

3. User and Person Updates

Agents can propose updates through the endpoints POST User Update and POST Person Update.

Allowed modifications include:

Natural persons - email, contact details, civil information.
Legal persons - administrative information, legal representative assignment.

📘
Some updates - especially those involving identity verification or KYC documents - may trigger a Strong Customer Authentication (SCA) workflow or require manual validation by MPS.
Agents must ensure all submitted data is accurate and verifiable.

4. Agent Responsibilities

Data Accuracy
Agents must ensure all collected data matches the supporting documents.
Any inconsistency or missing element will suspend the onboarding process.

Regulatory Compliance
Before creating a user, Agents must gather all required consents (e.g., Terms of Use, GDPR).

Traceability
All API actions are logged and include Agent identification (creation, update, consultation).

Support Role
Agents are the first point of contact for end-users in case of issues or account errors before escalation to MPS.

5. Agent Limitations

Agents cannot bypass compliance or regulatory controls → all AML/KYC validations are performed by MPS.
Agents cannot delete a user - they may only request account closure.
Agent cannot access any sensitive information beyond their authorized scope, such as document scans, internal scoring, or validation notes.

Typical Workflow

The following diagram illustrates the standard User lifecycle within Mipise Payment Servicies (MPS):

flowchart TD
    %% --- Nodes ---
    A([User creation initiated<br/>via API]):::draft 
    B[Pending validation<br/>KYC checks]:::pending
    C[Active]:::active
    D[Requires update<br/>Rejected / Incomplete]:::update
    G[Data Update via API]:::draft
    E[Suspended<br/>Compliance issue]:::update
    F[Closed]:::closed

    %% --- Links ---
    A --> B
    B -->|Approved| C
    B -->|Issues found| D
    D --> G
    G --> B
    C -->|Flagged| E
    E -->|Resolved| C
    C -->|Requested| F

    %% --- Styles ---
    classDef draft fill:#fff0f6,stroke:#c41d7f,stroke-width:2px
    classDef pending fill:#e6f7ff,stroke:#1890ff,stroke-width:2px
    classDef active fill:#f6ffed,stroke:#52c41a,stroke-width:2px
    classDef update fill:#fffbe6,stroke:#faad14,stroke-width:2px
    classDef closed fill:#f0f0f0,stroke:#8c8c8c,stroke-width:1px

📘
Check the graph's legend here.

Want more ? Check our Swagger for technical information :

🔵 POST User Creation

Registers a new user on a platform.

🔵 POST User Update

Modifies the data of a user.

🔵 POST Person Update

Modifies the data of a person.

🟢 GET Users List

Returns the list of users registered on a platform.

🟢 GET User Details

Returns the details of a specific user.