User Management

📘 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), both User and Person are core API objects - they are related but describe different layers of identity and responsibility.

In other words:

A User = the digital account in MPS
A Person = the real-world entity behind that account

---

🧠 Key Principles

• A User always contains at least one Natural Person, even when acting on behalf of a Legal Person.
  For example, a company (Legal Person) is always represented by an individual (Natural Person) who acts as its legal representative.

• A User can aggregate multiple Persons if needed (e.g., a group account, multiple representatives, or associated individuals).

• A Person is always defined within a User - never the other way around.

• The User object is used for account management and access, while the Person object is used for identity verification and regulatory data (KYC/KYB).

---

🔎 Example

• User: The entity registered in MPS to hold and operate payment accounts.
  Example → [email protected].

• Person(s): The identity tied to that User.
  Example → John Smith as a Natural Person, representing himself.

A single User may therefore represent either an individual or a business, but in all cases, the relationship between the User and its Person(s) ensures proper identification and compliance.

---

⚙️ General Principles

1. Identifiers:

   • platformUUID → unique identifier of the platform through which users are created and managed.
     • This one is required for all API endpoints.
     • Check the Platform 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...).

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

3. Legal Person rule: Each Persons::Legal must include at least one child Persons::Natural with
   "user_representative": true. This will be the legal representative.

4. 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 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) requires:

• first_name
• last_name
• birth_date
• nationality
• address

A Legal person 🏢 (company, association, etc...) 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:

Code

"user_representative": true

📘

The Agent is responsible for collecting complete and accurate information from the client.

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 → Users List

• The details of one specific user → 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 User Update and 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. User Lifecycle

Each user progresses through controlled lifecycle states, managed by MPS :

📘

Agents may initiate actions such as modification requests or account closure requests, but cannot approve status changes - final decisions rest with MPS.

---

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

---

🚫 6. 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
    A([User creation initiated]):::draft --> B[Pending validation - KYC check]:::pending
    B -->|✅ Approved| C[Active]:::active
    B -->|❌ Rejected / incomplete| D[Requires update]:::update
    D --> G[Data Update]:::api
    G --> B
    C -->|⚠️ Compliance issue| E[Suspended]:::update
    E -->|✅ Issue resolved| C
    C -->|🗑️ User closed| F[Closed]:::closed

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

---

🗂️ Endpoints Overview

1. 🔵 Users List

GET /platforms/{platformUUID}/users

Retrieves the list of all users associated with the specified platform.

Only users belonging to the Agent’s perimeter are returned.

---

2. 🔵 User Details

GET /platforms/{platformUUID}/users/{userUUID}

Retrieves detailed information about a specific user.

Access is restricted to users managed under the Agent’s platform.

---

3. 🔵 User Creation

POST /platforms/{platformUUID}/users

Creates a new user.

All mandatory user and person fields must be provided according to the chosen entity type.

---

4. 🔵 User Update

POST /platforms/{platformUUID}/users/{userUUID}

Updates specified user data, including any attached persons.

Some updates may trigger additional verification (KYC or compliance checks).

---

5. 🔵 Person Update

POST /platforms/{platformUUID}/users/{userUUID}/persons/{personUUID}

Updates information of a specific person within a user.

Depending on the data, changes may require validation by MPS.

---

ℹ️

You can find full examples and response structures directly on each API reference page.