> 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_MERCHANT_PENDING_IDR` | IDR      | No (held)     | Funds awaiting settlement — payments 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                                                                        |

Your **merchant profile** holds one additional account that sub-accounts do not:

| Account Type      | Code                | Currency | Withdrawable  | Purpose                                                                                                                                              |
| ----------------- | ------------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **System Points** | `DOKU_SYSTEM_POINT` | POINT    | No (non-cash) | Funding source for all point top-ups. Carries a **negative** balance equal to the points outstanding across your sub-accounts. See Balance Inquiries |

```
Seller receives payment of Rp 500,000 via Checkout / Direct API
        │
        ▼
Rp 500,000 lands in DOKU_MERCHANT_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**.

```mermaid
sequenceDiagram
    participant Merchant
    participant DOKU

    Merchant->>DOKU: 1. Transfer Inquiry (validate destination)
    DOKU-->>Merchant: referenceNo + beneficiary name

    Merchant->>DOKU: 2. Transfer Payment (using referenceNo)
    DOKU-->>Merchant: Transfer success + webhook notification
```

**Step 1 — Transfer Inquiry:** Validate the destination sub-account, account name, and amount. Returns a **reference number** for Step 2.

**Step 2 — Transfer Payment:** Execute the transfer using the reference number. Funds are deducted from source and credited to destination.

> **Important:** The `partnerReferenceNo` must be the same in both the inquiry and payment requests.

***

### 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 on this account that are temporarily held and cannot be spent yet |

**Reserved is not the same as Pending IDR.** Reserved is a hold *within* an account — every account has an available and a reserved figure. `DOKU_MERCHANT_PENDING_IDR` is a *separate account* holding funds that are awaiting settlement.

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. Use `type: DOKU_NON_FIAT` to issue new points, or `type: DOKU_SUB_ACCOUNT` to move points between sub-accounts. Both with `currency: POINT` |
| **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)                                                                                                                                       |
| **PTS Top-Up Void**  | `POST /sub-account/v2.0/topup/void`                 | Reverse a point top-up in full                                                                                                                                              |

Points are **issued**, not funded — a `DOKU_NON_FIAT` top-up debits your `DOKU_SYSTEM_POINT` account and credits the sub-account, with no cash movement.

#### DOKU\_SYSTEM\_POINT

`DOKU_SYSTEM_POINT` is the account every point is issued *from*. It exists only on your merchant profile, never on a sub-account, and because every issued point is debited from it, its balance is **negative**. That is normal, not an error — it has no cash equivalent and does not block top-ups.

Its magnitude equals the points outstanding across your sub-accounts:

```
DOKU_SYSTEM_POINT  =  -(sum of all sub-account point balances)
```

That identity is a useful reconciliation check: if it does not hold, points have been created or lost outside the top-up flow.

> Two prerequisites, both easy to miss. Points need the **Unified Ledger** service activated — separate from Collect and Route / Deposit System / Fund Oversight, see Dashboard. And `DOKU_SYSTEM_POINT` must exist on your merchant profile. Check for it with a balance inquiry before your first point top-up; without it, no point balance can be created.

#### Voided top-ups

A point top-up can be reversed in full with **Void Topup**. A void does not create new ledger entries — the original top-up rows change status from `SUCCESS` to `VOID`, on both the sub-account and System Point, and stay in history as an audit trail.

**Voided rows are excluded from balances.** They remain visible in transaction history, so summing every row overstates the balance by the voided amount:

```
balance  =  sum of rows where status != VOID
```

This is the most common cause of "the balance does not match the history". When reconciling, filter out `VOID` rows — and reach far enough back in time, since a recent window may show only voided activity while the balance comes entirely from older rows.

***

### What You Can Do With a Sub-Account

| Action                    | Description                                              | Capability      |
| ------------------------- | -------------------------------------------------------- | --------------- |
| **Receive payments**      | Via Checkout / Direct API with automatic splitting       | Collect & Route |
| **Top up via BRI VA**     | Real-time balance top-up via built-in BRI VA             | Shared          |
| **Debit**                 | Debit the account for goods or services                  | Deposit System  |
| **Payout to bank**        | Transfer to 100+ bank accounts                           | Collect & Route |
| **E-wallet distribution** | Distribute funds to DOKU e-wallet                        | Fund Oversight  |
| **Internal transfer**     | Move between sub-accounts                                | Shared          |
| **Track points**          | Credit/debit non-cash value (PTS)                        | Shared          |
| **Monitor**               | Balance inquiry, transaction history, transaction status | Shared          |


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.