> 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/fund-oversight.md).

# Fund Oversight

Connect DOKU e-Wallet user accounts directly to your Merchant Dashboard to disburse petty cash, monitor balances, and track transactions in real time.

***

## Overview

**Account Linking** is a DOKU e-Wallet feature that creates a direct connection between a user's wallet account and your **Merchant Dashboard (WaaS)**. Once a user account is linked to your business, your Owner or Finance team can top-up balances, monitor mutations, and manage operational funds across branches — all from a single dashboard.

Account Linking serves two sides of the same ecosystem:

* **For merchants (B2B):** Replace manual, report-based petty cash distribution with a precise, real-time, and auditable workflow.
* **For end-users (B2C):** Give staff and employees full visibility into which businesses are connected to their wallet, what data is shared, and the ability to disconnect at any time.

{% hint style="info" %}
**Who is this for?** Growing businesses with multiple branches, agents, or field staff that need to disburse and reconcile operational funds (petty cash) at scale. For example, F\&B chains, logistics operators, and retail networks.
{% endhint %}

***

## Why Account Linking

| Before Account Linking                                     | With Account Linking                                       |
| ---------------------------------------------------------- | ---------------------------------------------------------- |
| Petty cash distributed via manual reports and spreadsheets | Top-ups disbursed directly from the Merchant Dashboard     |
| Weak monitoring of branch-level spending                   | Real-time visibility into balances and transaction history |
| Imprecise budget control across branches                   | Sub-account tagging for clean per-branch reporting         |
| No audit trail for staff wallet activity                   | Full auditable history from the moment of linking onward   |

***

## How It Works

Account Linking is built on three core components that work together across the user app and the merchant dashboard.

### 1. Merchant Dashboard (WaaS)

A web-based platform where your Owner or Finance team manages the full linking lifecycle: adding customers (single or bulk), reviewing connection status, approving or rejecting requests, monitoring mutations, and disconnecting accounts when needed.

### 2. DOKU e-Wallet App (DWM)

The end-user mobile app. Users initiate linking requests, approve incoming requests from merchants, view the list of connected merchants along with the permissions granted, and submit unlink requests when they no longer wish to be connected.

### 3. Referral Code Sub-Account

A unique alphanumeric code generated for each of your sub-accounts (typically representing a branch, agent, or store). The Referral Code serves three purposes:

* **Identity & tracking** — determines which sub-account or branch a user is connected to (for example, `TOMOROJKTBAR` for Tomoro Jakarta Barat).
* **Tagging** — provides the foundation for future loyalty and referral programs.
* **Validation** — acts as the primary input for the User-Initiated linking flow.

***

## Use Case: Tomoro Coffee

### The Challenge

Tomoro Coffee operates many branches across multiple regions, and each branch has unique petty cash needs for daily operations. The Finance team distributed funds based on manual reports, which led to weak monitoring and imprecise budget control.

### The Solution

By integrating Account Linking, Tomoro Coffee's Finance Manager can:

* Connect each staff member's DOKU e-Wallet directly to a branch sub-account.
* Top-up petty cash to any branch in real time, straight from the Merchant Dashboard.
* Monitor every transaction tied to that staff member from the moment of linking onward.

In parallel, Tomoro staff retain full control through the DOKU e-Wallet app — they can see which merchant is connected, what is shared, and disconnect whenever appropriate.

***

## Access Permissions

When a user links their account to your business, they explicitly consent, via a checkbox-driven Terms & Conditions screen in the DOKU e-Wallet app, to share the following data with your dashboard:

| Data                    | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| **User Profile**        | Name, Phone Number, Email, Account Status, Account Type                                      |
| **Balance**             | Last wallet balance                                                                          |
| **Transaction History** | All transactions **from the moment of linking onward** (no historical data prior to linking) |
| **Payment Methods**     | All payment methods connected within the user's DOKU e-Wallet app                            |

{% hint style="warning" %}
**Important:** Merchants **cannot** access transaction history that occurred before the account was linked. After an account is unlinked, no new transaction data is visible to the merchant. Historical data while linked follows DOKU's standard data retention policy.
{% endhint %}

***

## Integration Guide

### Prerequisites

Before you start using Account Linking, make sure you have:

1. An active **Merchant Dashboard (WaaS)** account with Owner or Finance role permissions.
2. At least one **Sub-Account** created for your business (for example, one per branch or region).
3. A **Referral Code** generated for each sub-account.
4. End-users with active DOKU e-Wallet accounts (registered and logged in).

### Two Ways to Link an Account

There are two flows for creating a link, depending on who initiates the request.

| Flow                   | Description                                                                                                       | Best For                                                                                                       |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **User-Initiated**     | The end-user starts the connection from the DOKU e-Wallet app by entering your Referral Code.                     | **Self-service onboarding**, where staff add themselves using a code shared by your Finance or HR team.        |
| **Merchant-Initiated** | Your team starts the connection from the Merchant Dashboard, either one user at a time or in bulk via CSV import. | **Mass onboarding**, where you already have a list of staff phone numbers and want to invite them all at once. |

***

## Flow 1: User-Initiated Linking

In this flow, the end-user enters your Referral Code in the DOKU e-Wallet app to request a connection to your business.

{% stepper %}
{% step %}
User opens the DOKU e-Wallet app.
{% endstep %}

{% step %}
User navigates to **Akun** → **Akun Terhubung**, then taps **HUBUNGKAN AKUN**.
{% endstep %}

{% step %}
User enters the merchant's **Referral Code/Kode Referal** (for example, `TOMOROJKTBAR`).
{% endstep %}

{% step %}
The system validates the code; if invalid, an error message is displayed.
{% endstep %}

{% step %}
User reviews the four data permissions (Profile, Balance, Transactions, Payment Methods) on the consent screen.
{% endstep %}

{% step %}
User accepts the Terms & Conditions and taps **IZINKAN**.
{% endstep %}

{% step %}
The request is processed according to your configured approval mode (see Approval Modes below).
{% endstep %}

{% step %}
Both the user and the merchant receive a push notification confirming the connection.
{% endstep %}
{% endstepper %}

***

## Flow 2: Merchant-Initiated Linking

Available from end of June 2026, this flow lets your team initiate the linking request directly from the Merchant Dashboard — ideal for onboarding many staff members at once.

{% stepper %}
{% step %}
Log in to the Merchant Dashboard and navigate to **Account Linking**.
{% endstep %}

{% step %}
Click **+ Add Account** for a single user, or **Import** to upload a CSV for bulk onboarding.
{% endstep %}

{% step %}
Enter the user's **DOKU ID / Phone Number** and click **Search**.
{% endstep %}

{% step %}
The system validates and displays a masked preview of the user's data (Name, Email, Phone, Account Type).
{% endstep %}

{% step %}
Select the target **Sub-Account** and enter the **Referral Code**.
{% endstep %}

{% step %}
Click **Add Customer** to send the request.
{% endstep %}

{% step %}
The status changes to **Pending Confirmation**, and the user receives a push notification asking them to confirm.
{% endstep %}

{% step %}
Once the user approves in their app, the status becomes **Linked**.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**Validation rules for Merchant-Initiated requests:**

* The phone number must be registered as an active DOKU e-Wallet user.
* You cannot send a new linking request to a user who already has a pending request (Link Request or Pending Confirmation). Wait for the existing request to be resolved.
  {% endhint %}

***

## Approval Modes

Account Linking supports two approval modes for incoming linking requests. Your business can choose the mode that best fits your operational needs.

<table><thead><tr><th width="148.921875">Mode</th><th width="285.97265625">Behavior</th><th>Best For</th></tr></thead><tbody><tr><td><strong>Auto-Approve</strong></td><td>Every valid linking request is automatically approved by the system, with no manual action required from your team. The status moves directly to <strong>Linked</strong>.</td><td>High-volume onboarding where speed matters more than per-user vetting.</td></tr><tr><td><strong>Manual Approval</strong></td><td>Each incoming request appears in the dashboard with status <strong>Link Request</strong> or <strong>Pending Confirmation</strong>. Owner or Finance roles must <strong>Approve</strong> or <strong>Reject</strong> every request.</td><td>Businesses that need tighter control over which users can connect.</td></tr></tbody></table>

{% hint style="info" %}
**How to configure your approval mode:** The approval mode is set at the configuration level. To enable Auto-Approve or Manual Approval for your business — or to switch between the two — please contact the **DOKU team** through your account manager.
{% endhint %}

### In Manual Approval mode:

* When a user submits a request, the status appears as **Link Request** in your dashboard.
* Approving the request moves the status to **Linked**, and the user receives a confirmation notification.
* Rejecting the request moves the status to **Reject**, and the user is notified accordingly.

***

## Managing Linked Accounts

The **Account Linking** page in your dashboard is the central place to manage all connected accounts.

**Available columns:** Name, Phone Number, Status, Sub-Account, Referral Code

**Available controls:**

* **Search** by name or phone number
* **Filter** by Status (Pending Confirmation, Linked, Link Request, Unlink Request, Unlinked, Reject)
* **Filter** by Sub-Account
* **Sort** any column ascending or descending
* **Pagination** at 10 items per page (configurable)
* **Actions:** + Add Account, Import (CSV), Export

Click any row to open the detailed account view, where you can approve, reject, or unlink.

***

## Unlinking an Account

There are two ways an account can be disconnected.

{% stepper %}
{% step %}
The user opens the DOKU e-Wallet app and selects the connected merchant.
{% endstep %}

{% step %}
The user taps **PUTUSKAN SAMBUNGAN** and confirms the request.
{% endstep %}

{% step %}
The status changes to **Unlink Request**, awaiting the merchant's confirmation.
{% endstep %}

{% step %}
If the merchant **approves**, the status becomes **Unlinked** and the merchant immediately disappears from the user's "Akun Terhubung" list.
{% endstep %}

{% step %}
If the merchant **rejects**, the status returns to **Linked** and the user is notified.
{% endstep %}
{% endstepper %}

### Unlink Initiated by the Merchant

The merchant can disconnect a user **unilaterally** from the dashboard — no user confirmation is required. The status changes directly to **Unlinked**, the user is notified, and the merchant immediately loses access to that user's Profile, Balance, Mutations, and Payment Methods.

***

## Status & Lifecycle

### Status Definitions

| Status                   | Action From | Description                                                                         |
| ------------------------ | ----------- | ----------------------------------------------------------------------------------- |
| **Link Request**         | User        | Linking request sent by the user from the DOKU e-Wallet app                         |
| **Pending Confirmation** | Merchant    | Linking request sent by the merchant from the dashboard                             |
| **Linked**               | —           | Final status when the linking request is approved by either party                   |
| **Unlink Request**       | User        | Disconnect request sent by the user, awaiting merchant confirmation                 |
| **Unlinked**             | —           | Final status when the unlink is approved by the merchant (or unilaterally executed) |
| **Reject**               | —           | Final status when the linking request is rejected by either party                   |

### Status Transitions

<table><thead><tr><th width="162.03515625">Initial Status</th><th>From</th><th>Actor</th><th>Action</th><th>End Status</th></tr></thead><tbody><tr><td>Link Request</td><td>User</td><td>Merchant</td><td>Approve</td><td>Link</td></tr><tr><td>Link Request</td><td>User</td><td>Merchant</td><td>Reject</td><td>Reject</td></tr><tr><td>Pending Confirmation</td><td>Merchant</td><td>User</td><td>Approve</td><td>Link</td></tr><tr><td>Pending Confirmation</td><td>Merchant</td><td>User</td><td>Reject</td><td>Reject</td></tr><tr><td>Unlink Request</td><td>User</td><td>Merchant</td><td>Approve</td><td>Unlink</td></tr><tr><td>Unlink Request</td><td>User</td><td>Merchant</td><td>Reject</td><td>Link</td></tr><tr><td>Linked</td><td>N/A</td><td>Merchant</td><td>Unlink</td><td>Unlink</td></tr></tbody></table>

***

## Rules & Limitations

{% hint style="info" %}
Please review these rules before integrating, as they directly affect how the linking flow behaves.
{% endhint %}

1. **One User Account, One Referral Code at a time.** A user can only be connected to a single Referral Code at any given time.
2. **Transaction history starts at linking.** Merchants can only see transactions that occurred from the moment of linking onward. Historical transactions before the link date are not accessible.
3. **No duplicate pending requests.** A merchant cannot send a new linking request to a user who already has a pending request (Link Request or Pending Confirmation). The existing request must be resolved first.
4. **No post-unlink visibility.** After an account is unlinked, the merchant cannot see any new transactions. Access to historical data while the account was linked follows DOKU's data retention policy.

***

## Frequently Asked Questions

<details>

<summary>What happens if another merchant tries to send a linking request while one is already pending?</summary>

The system blocks any second linking request from a different merchant while the user's status is still **Link Request** or **Pending Confirmation**. The second merchant must wait until the first request is resolved (Approve / Reject) or until the user unlinks from their current merchant.

</details>

<details>

<summary>Can a merchant send a new linking request after the user is Unlinked?</summary>

Yes. **Unlinked** is a final status that allows new linking requests from either side — User-Initiated or Merchant-Initiated. The user can re-enter the same Referral Code as in the original flow.

</details>

<details>

<summary>Can a merchant view transaction history after the account is unlinked?</summary>

No. Once the account is **Unlinked**, the merchant loses access to any new transactions. Access to historical data accumulated while the account was linked is governed by DOKU's data retention policy.

</details>

<details>

<summary>Can a single user be linked to two merchants at the same time (e.g., Tomoro and Maxim)?</summary>

No. Due to the **1 User Account = 1 Referral Code** rule, a user can only be linked to one merchant at any given time. To switch from Tomoro to Maxim, the user must first unlink from Tomoro and then enter Maxim's Referral Code.

</details>

<details>

<summary>What if a linking or unlinking request stays pending for too long?</summary>

Users are encouraged to contact the merchant directly (for example, the branch HR or Finance team) for manual confirmation.

</details>

<details>

<summary>If the user reinstalls the DOKU e-Wallet app, will the linking remain active?</summary>

Yes. The linking status is stored on DOKU's servers and is independent of device state. After the user logs back in, the "Akun Terhubung" list will reflect the latest status.

</details>

<details>

<summary>Can a merchant top-up balance to a linked user's account?</summary>

Yes. One of the primary use cases of Account Linking is enabling the Finance team to top-up petty cash directly to staff accounts from the Merchant Dashboard.

</details>

<details>

<summary>Does the user receive notifications for every status change?</summary>

Yes. Push Notifications are sent at every important transition: when a linking request is sent, when it is approved or rejected, and when an unlink request is sent, approved, or rejected.

</details>


---

# 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/fund-oversight.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.