> For the complete documentation index, see [llms.txt](https://docs.doku.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.doku.com/wallet-as-a-service/sub-account/account-management.md).

# Account Management

Sub-accounts are the building blocks of your payment infrastructure. Each sub-account represents a party in your ecosystem that needs to hold and manage funds.

***

## What is a Sub-Account?

A sub-account is a digital balance container with:

* A unique **Profile ID,** identifies the account holder
* One or more **Account Numbers,** each tied to an account type and currency
* A **Name** and optional contact details (email, phone)
* An optional **Parent,** for hierarchical structures

Each sub-account holds up to **three types of accounts**:

| Account Type    | Code                  | Currency | Withdrawable  | Purpose                                                                                                                     |
| --------------- | --------------------- | -------- | ------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **IDR Cash**    | `DOKU_MERCHANT_IDR`   | IDR      | Yes           | Main balance, real money for spending and payouts                                                                           |
| **Pending IDR** | `DOKU_PENDING_IDR`    | IDR      | No (held)     | Funds awaiting settlement from Checkout API / Direct API land here first, then move to DOKU\_MERCHANT\_IDR after settlement |
| **Points**      | `DOKU_MERCHANT_POINT` | POINT    | No (non-cash) | Non-cash value: loyalty points, credits, cash-in-hand tracking                                                              |

```
Seller receives payment of Rp 500,000 via Checkout / Direct API
        │
        ▼
Rp 500,000 lands in DOKU_PENDING_IDR (held until settlement)
        │
        ▼
Settlement completes
        │
        ▼
Rp 500,000 moves to DOKU_MERCHANT_IDR (now withdrawable)
        │
        ▼
Seller requests payout from DOKU_MERCHANT_IDR
```

***

## Account Hierarchy

Sub-accounts can be organized in parent-child relationships with **unlimited levels**:

```
Platform (Level 1 - Merchant)
├── Region A (Level 2 - Sub)
│   ├── Branch 1 (Level 3 - Sub)
│   │   ├── Agent 001 (Level 4 - Sub)
│   │   └── Agent 002 (Level 4 - Sub)
│   └── Branch 2 (Level 3 - Sub)
└── Region B (Level 2 - Sub)
    └── Branch 3 (Level 3 - Sub)
```

This is useful for:

* **Franchise operations** — HQ oversees regional and branch-level accounts
* **Agent networks** — Distributors manage sub-agents with different commission tiers
* **Logistics** — Company → branch → courier → shipper
* **Marketplace tiers** — Platform manages vendor categories

***

## Creating a Sub-Account

To create a sub-account, call the **Register Sub Account** API with:

1. A **reference number** you generate (for your own tracking)
2. The **name** of the account holder
3. The **type** of account (e.g., `DEFAULT`)
4. Optionally, a **parent Profile ID** to place it in a hierarchy
5. Optionally, **email** and **phone** for the account holder

Once created, DOKU returns:

* A **Profile ID:** use this to reference the account
* **Account Numbers:** one per account type, used for transactions

> You'll receive a notification webhook when the account registration is complete.

***

## Internal Transfer (Between Sub-Accounts)

Move funds between sub-accounts on your platform using the `DOKU_SUB_ACCOUNT` transfer type. This is available across **Collect & Route**, **Deposit System**, and **Unified Ledger**.

Every internal transfer follows a **two-step process**:

```
Step 1: Inquiry          Step 2: Payment
┌─────────────────┐      ┌─────────────────┐
│ Validate details│ ──▶  │ Execute transfer│
│                 │      │                 │
│ • Check account │      │ • Move funds.   │
│ • Verify amount │      │ • Record txn.   │
│ • Confirm name  │      │ • Send notif.   │
└─────────────────┘      └─────────────────┘
```

**Step 1: Transfer Inquiry:** Validate the destination sub-account, account name, and amount. The inquiry returns a **reference number** that you use in Step 2.

**Step 2: Transfer Payment:** Execute the transfer using the reference number from the inquiry. Once processed, funds are deducted from the source and credited to the destination sub-account. A transfer notification is sent to your webhook.

{% hint style="warning" %}
**Important:** The `partnerReferenceNo` must be the same in both the inquiry and payment requests.
{% endhint %}

***

## Monitoring

{% tabs %}
{% tab title="Balance Inquiry" %}
Check the current funds in any sub-account at any time. Each account shows two balance types:

| Balance Type  | Meaning                                                 |
| ------------- | ------------------------------------------------------- |
| **Available** | Funds that can be spent or transferred right now        |
| **Reserved**  | Funds held for pending transactions (not yet available) |

You can query **all accounts** under a profile for a complete financial snapshot, or **specific accounts** by account number.
{% endtab %}

{% tab title="Transaction History" %}
Pull a paginated list of all transactions for a sub-account within a date range. Each record includes reference numbers, transaction type, channel, amount, currency, status, timestamp, and remarks.

Use this for:

* Reconciliation with your internal records
* Generating statements for account holders
* Auditing and compliance reporting
  {% endtab %}

{% tab title="Transaction Status" %}
Check the real-time status of any individual transaction using your reference number. For cancelled debit transactions, you also get the **debit cancel history** — each cancellation with its amount, status, date, and reason.
{% endtab %}
{% endtabs %}

***

## Points Ledger (Unified Ledger)

`DOKU_MERCHANT_POINT` tracks non-cash values like loyalty points, credits, or cash-in-hand. PTS credit and debit are **not automatic,** your platform calls the API to update them.

| Operation            | API                                                 | Description                           |
| -------------------- | --------------------------------------------------- | ------------------------------------- |
| **PTS Credit**       | `POST /transfer-inquiry` → `POST /transfer-payment` | Credit points to a sub-account        |
| **PTS Debit**        | `POST /sub-account/v2.0/debit`                      | Debit points from a sub-account       |
| **PTS Debit Cancel** | `POST /sub-account/v2.0/debit/cancel`               | Reverse a PTS debit (full or partial) |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.doku.com/wallet-as-a-service/sub-account/account-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.