Sub-Account

Overview

A sub-account represents an individual user that a business creates and manages under its own business account. Once a sub-account exists, the business can provision a sub-wallet for it using the returned _id as the subAccountId.

Create Sub-Account

Endpoint

POST /sub-account

Request Body

Field	Type	Required	Description
`name`	`string`	✓	Full name of the sub-account holder
`email`	`string`	✓	Email address of the sub-account holder
`dob`	`string`	✓	Date of birth, in `YYYY-MM-DD` format

Example Request

{
    "name": "John Doe",
    "email": "Johndoe@gmail.com",
    "dob": "1996-03-29"
}

Response

{
    "success": true,
    "message": "Sub-account created successfully!",
    "data": {
        "businessId": "6914b8de530486c362268f77",
        "globalId": "069032f2-7183-48fb-922b-358b6cde284a",
        "name": "John Doe",
        "email": "Johndoe@gmail.com",
        "dob": "1996-03-29T00:00:00.000Z",
        "type": "INDIVIDUAL",
        "_id": "6a60cb655a95c57344604053",
        "createdAt": "2026-07-22T13:53:41.447Z",
        "updatedAt": "2026-07-22T13:53:41.447Z",
        "__v": 0
    }
}

Use the _id from this response as the subAccountId when creating a sub-wallet for this sub-account.

Get All Sub-Accounts

Endpoint

GET /sub-accounts

Returns a paginated list of all sub-accounts created by the authenticated business. Query Parameters

Parameter	Type	Required	Description
`page`	`number`	—	Page number. Minimum `1`. Defaults to `1`
`limit`	`number`	—	Results per page. Between `1` and `100`. Defaults to `20`

Response

{
    "success": true,
    "message": "Sub-accounts fetched successfully!",
    "data": {
        "subAccounts": [
            {
                "_id": "6a5f6323acae291f105475db",
                "businessId": "690b476f530486c362268753",
                "globalId": "60891a16-2907-46f5-be99-4c06ab57a62f",
                "name": "John Doe",
                "email": "Johndoe@gmail.com",
                "dob": "1996-03-29T00:00:00.000Z",
                "type": "INDIVIDUAL",
                "createdAt": "2026-07-21T12:16:35.220Z",
                "updatedAt": "2026-07-21T12:16:35.220Z",
                "__v": 0
            }
        ],
        "pagination": {
            "total": 1,
            "page": 1,
            "limit": 5,
            "pages": 1
        }
    }
}

Get Single Sub-Account

Endpoint

GET /sub-account/:subAccountId

Fetches a single sub-account by its ID. The sub-account must belong to the authenticated business. Path Parameters

Parameter	Type	Required	Description
`subAccountId`	`string`	✓	ID of the sub-account (the `_id` returned when it was created)

Response

{
    "success": true,
    "message": "Sub-account fetched successfully!",
    "data": {
        "_id": "6a5f6323acae291f105475db",
        "businessId": "690b476f530486c362268753",
        "globalId": "60891a16-2907-46f5-be99-4c06ab57a62f",
        "name": "John Doe",
        "email": "Johndoe@gmail.com",
        "dob": "1996-03-29T00:00:00.000Z",
        "type": "INDIVIDUAL",
        "createdAt": "2026-07-21T12:16:35.220Z",
        "updatedAt": "2026-07-21T12:16:35.220Z",
        "__v": 0
    }
}

Exchange

Payment links

Wallet

Stable Wallet

Quick Reference

Overview

Create Sub-Account

Get All Sub-Accounts

Get Single Sub-Account

​Overview

​Create Sub-Account

​Get All Sub-Accounts

​Get Single Sub-Account

Overview

Create Sub-Account

Get All Sub-Accounts

Get Single Sub-Account