> 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

```
Agent / Partner tops up via BRI VA
        │
        ▼
Balance credited to DOKU_MERCHANT_IDR (real-time)
        │
        ▼
Agent transacts (buys product, pays bill)
        │
        ▼
Platform calls Debit API — balance deducted instantly
        │
        ▼
Dashboard shows real-time balance and transaction history
```

***

## 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_PENDING_IDR` first     | No, must wait for settlement |

{% hint style="info" %}
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.
{% endhint %}

***

## 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).
{% endtab %}
{% endtabs %}

***

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