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.

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

---

Monitoring

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.

Transaction History

Transaction Status

---

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)