📘 Multiple Profile and Multi-Wallet User Guide

1. Introduction

The Multi-Profile / Multi-Wallet feature allows a single verified Account to:

• Hold multiple profiles (e.g., Donor, Investor, Merchant, Project Holder)
• Have multiple wallets per profile, each representing separate financial flows

This lets end-users to perform several activities on your platform(s) under one identity and manage funds separately for each activity.

2. Key concepts to understand

Account

The end-user’s unique identity on your platform.

Profile

Represents the user’s role or activity on your platform. Examples:

• Donor
• Project Holder
• Investor
• Merchant

📘

Note

A single account may have several profiles.

Wallet

A financial container attached to a profile. Each profile must have at least one wallet and may have multiple.

3. When to Use Multi-Profile / Multi-Wallet

3.1 Multiple wallets for the same profile

Use this when a user needs separate financial flows within the same activity:

• A merchant with several shops
• A project holder managing multiple projects
• A seller needing separate payout workflows

📘

Note

All profiles except Project Holder can add wallets without additional information.

3.2 Multiple profiles for the same account

This feature is available for when a user performs several roles on your platform:

• A Donor who wants or is also a Project Holder
• An Investor who also creates their own investment project

Each added profile will receive its own wallet.

📘

Note

Multi-currency wallets are currently not supported. Additional wallets inherit the envoirnment's currency.

4. How to Add a New Profile to an Account

To add additional new profiles to an existing account using the Lemonway API, use the following end-points, specifiying the accountId:

API (Individuals)

POST /accounts/individual/{accountId}/profiles
{
  "profile": "DONOR",
  "walletId": "unique-wallet-id"
}

API (Legal Entities)

POST /accounts/legal-entity/{accountId}/profiles
{
  "profile": "MERCHANT",
  "walletId": "unique-wallet-id"
}

Response examples

User-type profile

{
    "id": "66bb735b-53d8-4d94-9809-b808876c6fe1",
    "status": "CREATED",
    "internalId": 15640
}

Business Relationship profile

201 Created
{
 "id": "profile-id",
 "status": "AWAITING_INFORMATION"
}

Profiles requiring additional information (for example Project Holders, Merchant, Investor...) must complete an Online Onboarding flow i.e. POST /onboardings/individual or /onboardings/company and so on. Once the profile is validated, the wallet associated to this profile will be created.

5. Add a New Wallet to an Existing Profile

To add new wallet to an existing profile using the Lemonway API use the following end-points, specifiying the project type , accountId and profileID:

POST /accounts/{type}/{accountId}/profiles/{profileId}/wallets
{
  "walletId": "unique-wallet-id"
}

Response:

{
    "id": "66bb735b-53d8-4d94-9809-b808876c6fe1",
    "status": "CREATED",
    "internalId": 15640
}

📘

Note

This for all cases except for Project holders as there are addition steps required. See: Additional Required Information .

5.1 Additional Wallet for Project Holder Profiles

Important: For Project Holders, additional project information is required. Note, that the payload will vary according to the project type.

Individuals

{
 "walletId": "unique-wallet-id",
 "project": {
   "type": "WEDDING",
   "weddingRelation": "BRIDE_GROOM",
   "beneficiary": {
     "firstName": "John",
     "lastName": "Doe",
     "birthDate": "1951-01-09"
   },
   "description": "lorem ipsum",
   "website": "example.com"
 }
}

{
    "walletId": "{{$randomUUID}}",
    "project": {
            "type": "NEW_BORN",
            "beneficiary": {
                "firstName": "John",
                "lastName": "Doe",
                "birthDate": "1951-01-09"
            }
        }
    }

{
  "walletId": "78789085",
  "project": {
    "type": "CHARITY",
    "description": "Food assistance program supporting low-income families",
    "website": "https://hopefoundation2.org"
  }
}

Legal Entities

{
 "walletId": "unique-wallet-id",
 "project": {
   "description": "Project description",
   "website": "example.com"
 }
}

Response:

201 Created
{
 "id": "wallet-id",
 "status": "UNDER_ANALYSIS"
}

5.2 Multi-Activity Use Cases

If your environment supports multiple activities (for example, Crowdfunding and Crowdlending), you must include the activity field:

{
  "profile": "DONOR",
  "activity": "CROWDFUNDING_DONATION",
  "walletId": "unique-wallet-id"
}

6. Notifications

You can receive notifications when significant events occur. See: Webhooks Statues

7. Error Handling

8. FAQ