# Sub Account

Learn more about how DOKU Sub Account can help you Power up your online payments here.

### Integration steps <a href="#integration-steps" id="integration-steps"></a>

Here is the overview of how to integrate with DOKU Sub Account:

1. [Create Account](#id-1-create-account)
2. [Accept Payment](#id-2-accept-payment)
3. [Send Payout](#id-3-send-payout)
4. [Transfer Intra Sub Account](#id-4-transfer-intra-sub-account)
5. [Get Balance](#id-5-get-balances)

***

### 1. Create Account <a href="#id-1-create-account" id="id-1-create-account"></a>

To create the account, you will need to hit this API through your Backend:

**API Request**

<table><thead><tr><th width="248">Type</th><th>Value</th></tr></thead><tbody><tr><td><strong>HTTP Method</strong></td><td>POST</td></tr><tr><td><strong>API endpoint (Sandbox)</strong></td><td><code>https://api-sandbox.doku.com/sac-merchant/v1/accounts</code></td></tr><tr><td><strong>API endpoint (Production)</strong></td><td><code>https://api.doku.com/sac-merchant/v1/accounts</code></td></tr></tbody></table>

Here is the sample of request header to create the payment:

```json
Client-Id: MCH-0001-10791114622547
Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22e
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

#### Request Header Explanation

<table><thead><tr><th width="228">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong>Signature</strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="../get-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header">this section </a>to generate the signature</td></tr></tbody></table>

Here is the sample of request body to create the account:

```json
{
    "account": {
        "email": "yoursubcaccount@email.com",
        "type": "STANDARD",
        "name": "nama2"
    }
}
```

**Request Body Explanation**

<table><thead><tr><th>Parameter</th><th width="123">Type</th><th width="131">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>account.email</code></td><td><code>string</code></td><td>Mandatory</td><td>Email identifier for your partner account<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>40</code></td></tr><tr><td><code>account.type</code></td><td><code>string</code></td><td>Mandatory</td><td>Type of account. Available Values: Default, Standard<br>Allowed chars: <code>alphabetic</code><br>Max Length: <code>20</code></td></tr><tr><td><code>account.name</code></td><td><code>string</code></td><td>Mandatory</td><td>Your partner name<br>Allowed chars: <code>alphabetic</code><br>Max Length: <code>100</code></td></tr></tbody></table>

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 201     |
| **Result**      | CREATED |

Here is the sample response header:

```json
Client-Id: MCH-0001-10791114622547
Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22e
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

#### Response Header Explanation

<table><thead><tr><th width="221">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Request-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Response-Timestamp</strong></td><td>Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU</td></tr><tr><td><strong>Signature</strong></td><td>Signature generated by DOKU based on the response body</td></tr></tbody></table>

Here is the sample of response body:

```json
{
    "account": {
        "created_date": "2021-08-04T18:19:00.046085+07:00",
        "updated_date": "2021-08-04T18:19:00.046085+07:00",
        "name": "nama2",
        "email": "yoursubcaccount@email.com",
        "type": "STANDARD",
        "status": "PENDING",
        "id": "SAC-9914-1628075940045"
    }
}
```

#### Response Body Explanation

<table><thead><tr><th width="222">Parameter</th><th width="110">Type</th><th width="121">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>account.created_date</code></td><td><code>string</code></td><td>Mandatory</td><td>Timestamp when the account was created</td></tr><tr><td><code>account.updated_date</code></td><td><code>string</code></td><td>Mandatory</td><td>Timestamp when the account was updated</td></tr><tr><td><code>account.name</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>account.email</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>account.type</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>account.status</code></td><td><code>string</code></td><td>Mandatory</td><td>Sub Account status. In this state, it should be <code>PENDING</code></td></tr><tr><td><code>account.id</code></td><td><code>string</code></td><td>Mandatory</td><td>ID of your Sub Account, use this id to create transactions on behalf of your Partner</td></tr></tbody></table>

***

### 2. Accept Payment <a href="#id-2-accept-payment" id="id-2-accept-payment"></a>

To accept payment add this additional\_info.account object into your payment request.

```json
...
"additional_info": {
    "account": {
      "id": “SAC-11111111”
    }
  }
...
```

#### Request Header Explanation <a href="#sample-usage" id="sample-usage"></a>

<table><thead><tr><th>Parameter</th><th width="101">Type</th><th width="122">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>additional_info.account</code></td><td><code>string</code></td><td>Mandatory</td><td>Include this object for routing the payment</td></tr><tr><td><code>additional_info.account.id</code></td><td><code>string</code></td><td>Mandatory</td><td>ID of your Account, use this to create transactions on behalf of your Account<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>40</code></td></tr></tbody></table>

#### Sample Usage <a href="#sample-usage" id="sample-usage"></a>

Let's assume you are using the DOKU Direct integration. You can simply add these parameters into your API Initiate Payment:

```json
{
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "expired_time": 60,
        "reusable_status": false,
        "info1": "Merchant Demo Store",
        "info2": "Thank you for shopping",
        "info3": "on our store"
    },
    "customer": {
        "name": "Anton Budiman",
        "email": "anton@example.com"
    },
    "additional_info": {
        "account": {
           "id": “SAC-11111111”
    }
  }
}
```

***

### 3. Send Payout <a href="#id-3-send-payout" id="id-3-send-payout"></a>

You can request to send money from your accounts balance account for any disbursement purpose e.g: withdrawal, refund, paying vendor/supplier, etc

**API Request**

<table><thead><tr><th width="262">Type</th><th>Value</th></tr></thead><tbody><tr><td><strong>HTTP Method</strong></td><td>POST</td></tr><tr><td><strong>API endpoint (Sandbox)</strong></td><td><code>https://api-sandbox.doku.com/sac-merchant/v1/payouts</code></td></tr><tr><td><strong>API endpoint (Production)</strong></td><td><code>https://api.doku.com/sac-merchant/v1/payouts</code></td></tr></tbody></table>

Here is the sample of request header to create the payment:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22e
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

#### Request Header Explanation

<table><thead><tr><th width="205">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong>Signature</strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="../get-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header">this section </a>to generate the signature</td></tr></tbody></table>

Here is the sample of request body for payouts:

```json
{
    "account":
    {
        "id":"SAC-0000-0000000000001"
    },
    "payout":
    {
        "amount": 20000,
        "invoice_number":"INV/123/45"
    },
    "beneficiary":
    {
        "bank_code":"BNINIDJA",
        "bank_account_number":"712739123020001",
        "bank_account_name":"Ria Florensi"
    }
}
```

#### Request Body Explanation

<table><thead><tr><th>Parameter</th><th width="117">Type</th><th width="134">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>account.id</code></td><td><code>string</code></td><td>Mandatory</td><td>The source of the payout<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>40</code></td></tr><tr><td><code>payout.amount</code></td><td><code>string</code></td><td>Mandatory</td><td>Payout amount<br>Allowed chars: <code>numeric</code><br>Max Length: <code>12</code></td></tr><tr><td><code>payout.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>A unique reference for this Payout. Use this to reconcile your payout.<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>100</code></td></tr><tr><td><code>beneficiary.bank_code</code></td><td><code>string</code></td><td>Mandatory</td><td>SWIFT CODE Bank Destination<br>Allowed chars: <code>alphabetic</code><br>Max Length: <code>12</code></td></tr><tr><td><code>beneficiary.bank_account_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Beneficiary Bank Account Number<br>Allowed chars: <code>numeric</code><br>Max Length: <code>40</code></td></tr><tr><td><code>beneficiary.bank_account_name</code></td><td><code>string</code></td><td>Mandatory</td><td>Beneficiary Bank Account Name<br>Allowed chars: <code>alphabetic</code><br>Max Length: <code>40</code></td></tr></tbody></table>

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22e
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

#### Response Header Explanation

<table><thead><tr><th width="231">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Request-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Response-Timestamp</strong></td><td>Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU</td></tr><tr><td><strong>Signature</strong></td><td>Signature generated by DOKU based on the response body</td></tr></tbody></table>

Here is the sample of response body:

```json
{
    "account": {
        "id": "SAC-123-111111"
    },
    "payout":{
        "amount": 20000,
        "invoice_number": “INV/123/11”,
        "status": “SUCCESS”,
        "created":’2021-08-06 15:18:06.820153+07:00”
    },
    "beneficiary:{
        "bank_code": “BNINIDJA”,
        "bank_account_number": 1234567,
        "bank_account_name": “Ria Florensi”
    }
}
```

#### Request Body Explanation&#x20;

<table><thead><tr><th>Parameter</th><th width="126">Type</th><th width="140">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>account.id</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as request</td></tr><tr><td><code>payout.amount</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as request</td></tr><tr><td><code>payout.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as request</td></tr><tr><td><code>payout.status</code></td><td><code>string</code></td><td>Mandatory</td><td>Payout status</td></tr><tr><td><code>payout.created</code></td><td><code>string</code></td><td>Mandatory</td><td>Timestamp when Payout was created</td></tr><tr><td><code>beneficiary.bank_code</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as request</td></tr><tr><td><code>beneficiary.bank_account_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as request</td></tr><tr><td><code>beneficiary.bank_account_name</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as request</td></tr></tbody></table>

***

### 4. Transfer Intra Sub Account <a href="#id-4-transfer-intra-sub-account" id="id-4-transfer-intra-sub-account"></a>

The Transfers API allows you to transfer balances between your accounts.

**API Request**

<table><thead><tr><th width="243">Type</th><th>Value</th></tr></thead><tbody><tr><td><strong>HTTP Method</strong></td><td>POST</td></tr><tr><td><strong>API endpoint (Sandbox)</strong></td><td><code>https://api-sandbox.doku.com/sac-merchant/v1/transfers</code></td></tr><tr><td><strong>API endpoint (Production)</strong></td><td><code>https://api.doku.com/sac-merchant/v1/transfers</code></td></tr></tbody></table>

Here is the sample of request header to create the payment:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22e
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

#### Request Header Explanation&#x20;

<table><thead><tr><th width="205">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong>Signature</strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="../get-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header">this section </a>to generate the signature</td></tr></tbody></table>

Here is the sample of request body for payouts:

```json
{
    "transfer":
    {
        "origin" : "SAC-0000-0000000000001",
        "destination" : "SAC-8014-1628130619289",
        "amount" : 10000,
        "invoice_number" : "INV/7274812"
    }
}
```

**Request Body Explanation**

<table><thead><tr><th width="217">Parameter</th><th width="106">Type</th><th width="133">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>transfer.origin</code></td><td><code>string</code></td><td>Mandatory</td><td>The source of the Transfer<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>40</code></td></tr><tr><td><code>transfer.destination</code></td><td><code>string</code></td><td>Mandatory</td><td>The destination of the Transfer<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>40</code></td></tr><tr><td><code>transfer.amount</code></td><td><code>string</code></td><td>Mandatory</td><td>Transfer amount<br>Allowed chars: <code>numeric</code><br>Max Length: <code>12</code></td></tr><tr><td><code>transfer.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>A unique reference for this Payout. Use this to reconcile your payout.<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>100</code></td></tr></tbody></table>

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22e
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

#### Response Header Explanation

<table><thead><tr><th width="227">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Request-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Response-Timestamp</strong></td><td>Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU</td></tr><tr><td><strong>Signature</strong></td><td>Signature generated by DOKU based on the response body</td></tr></tbody></table>

Here is the sample of response body:

```json
{
    "transfer": {
        "invoice_number": "INV/7274812",
        "origin": "SAC-0000-0000000000001",
        "destination": "SAC-8014-1628130619289",
        "amount": 10000,
        "status": "SUCCESS",
        "created": "2021-08-06 15:18:06.820153+07:00"
    }
}
```

#### Response Body Explanation

<table><thead><tr><th>Parameter</th><th width="109">Type</th><th width="143">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>transfer.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as request</td></tr><tr><td><code>transfer.origin</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as request</td></tr><tr><td><code>transfer.destination</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as request</td></tr><tr><td><code>transfer.amount</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as request</td></tr><tr><td><code>transfer.created</code></td><td><code>string</code></td><td>Mandatory</td><td>Timestamp when Payout was created</td></tr></tbody></table>

***

### 5. Get Balances <a href="#id-5-get-balances" id="id-5-get-balances"></a>

Get Balance API allows you to retrieve the balance of your available and pending balance

**API Request**

<table><thead><tr><th width="262">Type</th><th>Value</th></tr></thead><tbody><tr><td><strong>HTTP Method</strong></td><td>GET</td></tr><tr><td><strong>API endpoint (Sandbox)</strong></td><td><code>https://api-sandbox.doku.com/sac-merchant/v1/balances/{account_id}</code></td></tr><tr><td><strong>API endpoint (Production)</strong></td><td><code>https://api.doku.com/sac-merchant/v1/balances/{account_id}</code></td></tr></tbody></table>

Here is the sample of request header to get balance:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22e
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

**Request Header Explanation**

<table><thead><tr><th width="205">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong>Signature</strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="../get-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header">this section </a>to generate the signature</td></tr></tbody></table>

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22e
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

#### Response Header Explanation

<table><thead><tr><th width="203">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Request-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Response-Timestamp</strong></td><td>Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU</td></tr><tr><td><strong>Signature</strong></td><td>Signature generated by DOKU based on the response body</td></tr></tbody></table>

Here is the sample of response body:

```json
{
    "balance": {
        "pending": "600000",
        "available": "1700500"
    }
}
```

#### Response Body Explanation

<table><thead><tr><th>Parameter</th><th width="111">Type</th><th width="124">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>balance.pending</code></td><td><code>string</code></td><td>Mandatory</td><td>The balance remaining in your pending balance</td></tr><tr><td><code>balance.available</code></td><td><code>string</code></td><td>Mandatory</td><td>The balance remaining in your available balance</td></tr></tbody></table>