> 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/deposit-system.md).

# Deposit System

Smart deposits for scaled operations. Partners top-up their balance upfront via BRI VA, transactions are deducted instantly via the Debit API, and fund movements are transparent in real time.

***

### How It Works

```mermaid
sequenceDiagram
    participant Agent
    participant Merchant
    participant DOKU

    Merchant->>DOKU: 1. Register Sub-Account
    DOKU-->>Merchant: profileId + BRI VA number

    Agent->>DOKU: 2. Top-up via BRI VA
    DOKU-->>Merchant: Balance credited to MERCHANT_IDR (real-time)

    Merchant->>DOKU: 3. Debit API (deduct per transaction)
    DOKU-->>Merchant: Balance deducted + webhook notification

    Merchant->>DOKU: 4. Debit Cancel (if needed)
    DOKU-->>Merchant: Balance reversed + webhook notification

    Merchant->>DOKU: 5. Balance Inquiry
    DOKU-->>Merchant: Real-time balance
```

***

### BRI VA Top-Up

Every sub-account created in V2 is **automatically assigned a static DOKU BRI VA**. No separate setup or API call required.

* When you call `POST /sub-account/v2.0/register`, a **static BRI VA number** is generated and linked to the sub-account
* The VA number is **permanent** — it does not change and can be reused for multiple top-ups
* When anyone pays to this VA, the funds are **credited to the sub-account's IDR balance in real time**
* No manual verification needed — the balance updates automatically

**VA Number Format:** `1392495` + `DOKU_MERCHANT_IDR` account number. For example, account `2010253470` → VA `13924952010253470`. You can predict the VA number from the account number — useful for generating payment instructions without an additional API call.

**VA Display Name:** When a customer pays via banking apps (e.g., CIMB Octo), the name displayed is **"Merchant Balance + \[Sub-Account Name]"**.

| Scenario                 | How the VA is used                                                       |
| ------------------------ | ------------------------------------------------------------------------ |
| **Agent top-up**         | Agent deposits cash via BRI VA → balance increases → agent can transact  |
| **PPOB / Bills payment** | Agent pre-funds their account via VA to pay bills on behalf of customers |
| **Franchise deposit**    | Branch tops up operating budget via VA → HQ sees balance in real time    |
| **Seller deposit**       | Seller adds funds to their account for promotional spending              |

**BRI VA vs. Checkout/Direct API:**

| Payment Source            | Where funds land                  | Available immediately?        |
| ------------------------- | --------------------------------- | ----------------------------- |
| **BRI VA top-up**         | `DOKU_MERCHANT_IDR` directly      | Yes — real-time, withdrawable |
| **Checkout / Direct API** | `DOKU_MERCHANT_PENDING_IDR` first | No — must wait for settlement |

> **Tip:** If your use case requires real-time balance and immediate payout (e.g., agent top-ups, PPOB pre-funding), use the built-in BRI VA instead of Checkout API / Direct API.

#### Topping Up in Sandbox

There is no real bank in sandbox, so pay the VA through DOKU's payment simulator:

1. Open the [DOKU Payment Simulator](https://sandbox.doku.com/integration/simulator/)
2. Choose **BRI Virtual Account**
3. Enter the VA number — `1392495` + the sub-account's `DOKU_MERCHANT_IDR` account number
4. Click **Inquiry**, check the details, then confirm the payment

The balance updates in real time and a top-up notification is sent to your callback URL, exactly as in production.

> **Use the `DOKU_MERCHANT_IDR` account number**, which starts with `2010`. Building the VA from the Pending IDR account (`2030…`) returns **"Invalid Bill/Virtual Account"** — a common cause of a simulator that appears broken.

***

### Debit & Debit Cancel

{% tabs %}
{% tab title="Debit" %}
A debit deducts funds from a sub-account. Use this when a sub-account holder buys goods, pays for services, or when you need to deduct funds programmatically. Provide the **source account**, **amount**, **transaction type**, and an optional **description**. Each debit returns a status immediately, and a debit notification is sent to your webhook.

Sub-Account uses a double-entry ledger. When the Debit API is called, the system can automatically credit the `DOKU_MERCHANT_IDR` of a Level 1 profile (the merchant/platform account).

```
Debit API called on sub-account
        │
        ├── Debit:  sub-account DOKU_MERCHANT_IDR  -150,000
        └── Credit: Level 1 profile DOKU_MERCHANT_IDR  +150,000
```

{% endtab %}

{% tab title="Debit Cancel" %}
Debit cancels reverse a debit — either fully or partially. You reference the original debit transaction and specify the cancel amount.

```
Full Cancel:    Original IDR 150,000 → Cancel IDR 150,000
Partial Cancel: Original IDR 150,000 → Cancel IDR 50,000
```

Provide the **original transaction reference**, **cancel amount** (equal to or less than original), and a **reason** (optional but recommended). A debit cancel notification is sent when processed.
{% endtab %}
{% endtabs %}

Three things to know:

* **A cancel moves money the other way** — the cancelled amount is debited from the Level 1 profile and credited back to the sub-account.
* **Cancels can be partial**, and repeated, up to the original amount. A debit of 150,000 can be cancelled as 50,000 now and 100,000 later.
* **A cancel does not rewrite the original.** Both the purchase and the cancellation stay in transaction history as separate entries.

Points work the same way — a point purchase and its cancellation use the same flow, with the points retired to your System Point account rather than moved to another sub-account.

***

### Step-by-Step Integration

1. **Register a Sub-Account** — `POST /sub-account/v2.0/register` → sub-account gets a BRI VA automatically
2. **Top Up** — Partner pays to the BRI VA → balance credited to `DOKU_MERCHANT_IDR` in real time
3. **Debit** — Platform calls `POST /sub-account/v2.0/debit` to deduct funds when partner transacts
4. **Debit Cancel (if needed)** — Platform calls `POST /sub-account/v2.0/debit/cancel` for full or partial reversals
5. **Monitor** — Check balances and transaction history via API or dashboard


---

# 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/deposit-system.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.