> For the complete documentation index, see [llms.txt](https://developers.doku.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.doku.com/wallet-as-a-service/sub-account/sub-account-v2.md).

# Sub Account V2

## Pre Condition

> Before you begin, make sure you have an active DOKU account with Sub Account service (Collect and Route / Deposit System / Fund Oversight) activated. [Contact Sales](https://www.doku.com/en-us/contact-sales) if you haven't activated yet.

***

### Flow Overview

```mermaid
sequenceDiagram
    participant Merchant
    participant DOKU
    participant Customer
    participant Bank

    rect rgb(240, 248, 255)
    Note over Merchant, DOKU: Setup
    Merchant->>DOKU: 1. Get Access Token
    DOKU-->>Merchant: accessToken
    Merchant->>DOKU: 2. Register Sub-Account
    DOKU-->>Merchant: profileId + accountNo + BRI VA
    Merchant->>DOKU: 3. Create Split Rule (optional)
    DOKU-->>Merchant: splitRuleId
    end

    rect rgb(240, 255, 240)
    Note over Merchant, Customer: Money In
    Merchant->>DOKU: 4. Create Payment (Checkout / Direct API)
    DOKU-->>Customer: Payment page / VA number
    Customer->>DOKU: Customer pays
    DOKU-->>Merchant: Payment notification (webhook)
    end

    rect rgb(255, 248, 240)
    Note over Merchant, DOKU: Monitoring
    Merchant->>DOKU: 5. Balance Inquiry
    DOKU-->>Merchant: Account balances
    Merchant->>DOKU: 6. Transaction History
    DOKU-->>Merchant: Transaction list
    Merchant->>DOKU: 7. Transaction Status
    DOKU-->>Merchant: Transaction detail
    end

    rect rgb(255, 240, 245)
    Note over Merchant, Bank: Money Out
    Merchant->>DOKU: 8. Transfer Inquiry
    DOKU-->>Merchant: referenceNo + beneficiary name
    Merchant->>DOKU: 9. Transfer Payment
    DOKU->>Bank: Payout
    DOKU-->>Merchant: Transfer notification (webhook)
    end
```

***

### Step-by-Step

#### 1. Get Access Token

Authenticate with the DOKU API to get a B2B access token. This token is required for all subsequent API calls.

See [Get Token B2B](https://developers.doku.com/accept-payments/direct-api/snap/integration-guide/get-token-api/b2b) for full documentation.

***

#### 2. Register Sub-Account

Create a sub-account for each party in your ecosystem (seller, agent, branch, etc.). Each sub-account gets three account types (IDR, Pending IDR, Points) and an auto-assigned static BRI VA.

```
POST /sub-account/v2.0/register
```

Save the `profileId` from the response, you'll use it in every subsequent call for this sub-account.

***

#### 3. Create Split Rule (optional)

Define how incoming payments should be automatically distributed across sub-accounts. You can create percentage-based or flat-amount rules.

```
POST /sub-account/v2.0/split-rules
```

Save the `splitRuleId` , pass it together with `profileId` in payment requests.

***

#### 4. Create Payment

Accept payments through **Checkout API** or **Direct API**. Include `additionalInfo.account.id` to route the payment to a sub-account, and optionally `additionalInfo.account.split_rule_id` to apply a split rule.

{% tabs %}
{% tab title="Checkout API" %}

```
POST /checkout/v1/payment
```

Returns a payment URL. Customer is redirected to the DOKU hosted payment page where they can choose from all active payment channels.
{% endtab %}

{% tab title="Direct API" %}

```
POST /virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va  (VA)
POST /credit-card/v1/payment-page  (Credit Card)
POST /direct-debit/core/v1/debit/payment-host-to-host  (E-Wallet)
etc
```

Merchant controls the payment UI. Each channel has its own endpoint.
{% endtab %}
{% endtabs %}

After payment, DOKU sends a **webhook notification** to your callback URL. Funds land in `DOKU_PENDING_IDR` (for Checkout/Direct API) or `DOKU_MERCHANT_IDR` (for BRI VA top-up).

See [Payment Channel Compatibility](https://docs.doku.com/wallet-as-a-service/sub-account#payment-method-compatibility) for which channels support Sub-Account routing.

***

#### 5. Balance Inquiry

Check the current balance of any sub-account at any time.

```
POST /sub-account/v2.0/balance-inquiries
```

Returns available and reserved balances across all three account types (IDR, Pending IDR, Points).

***

#### 6. Transaction History

Retrieve a paginated list of all transactions for a sub-account within a date range.

```
POST /sub-account/v2.0/transaction-history-list
```

Each record includes mutation type (CREDIT/DEBIT), transaction type, amount, channel, status, and timestamp.

***

#### 7. Transaction Status

Check the real-time status of any individual transaction.

```
POST /sub-account/v2.0/transactions-status
```

Returns the latest transaction status (`00` = Success, `03` = Pending, `06` = Failed) and refund history if applicable.

***

#### 8. Transfer Inquiry

Before sending money out, validate the destination account.

```
POST /sub-account/v2.0/transfer-inquiry
```

Returns a `referenceNo` and confirmed beneficiary name. You must use this `referenceNo` in the next step.

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

***

#### 9. Transfer Payment

Execute the payout using the `referenceNo` from Transfer Inquiry.

```
POST /sub-account/v2.0/transfer-payment
```

Supports three transfer types:

| Type               | Description                                              |
| ------------------ | -------------------------------------------------------- |
| `BANK_ACCOUNT`     | Payout to 100+ Indonesian banks (via BI\_FAST or ONLINE) |
| `DOKU_SUB_ACCOUNT` | Internal transfer between sub-accounts                   |
| `DOKU_WALLET`      | Transfer to DOKU e-wallet                                |

After transfer, DOKU sends a **webhook notification** with the transaction status.

***

#### Additional Operations

| Operation        | API                                   | Description                       |
| ---------------- | ------------------------------------- | --------------------------------- |
| **Debit**        | `POST /sub-account/v2.0/debit`        | Deduct funds from a sub-account   |
| **Debit Cancel** | `POST /sub-account/v2.0/debit/cancel` | Reverse a debit (full or partial) |