DOKU DocsChangelogDOKU Github

Sub Account

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

Integration steps

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

  1. Create Account

  2. Accept Payment

  3. Send Payout

  4. Transfer Intra Sub Account

  5. Get Balance

1. Create Account

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

API Request

Type
Value

HTTP Method

POST

API endpoint (Sandbox)

https://api-sandbox.doku.com/sac-merchant/v1/accounts

API endpoint (Production)

https://api.doku.com/sac-merchant/v1/accounts

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

Parameter
Description

Client-Id

Client ID retrieved from DOKU Back Office

Request-Id

Unique random string (max 128 characters) generated from merchant side to protect duplicate request

Request-Timestamp

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

Signature

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 this section to generate the signature

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

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

Request Body Explanation

Parameter
Type
Mandatory
Description

account.email

string

Mandatory

Email identifier for your partner account Allowed chars: alphabetic, numeric, special chars Max Length: 40

account.type

string

Mandatory

Type of account. Available Values: Default, Standard Allowed chars: alphabetic Max Length: 20

account.name

string

Mandatory

Your partner name Allowed chars: alphabetic Max Length: 100

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:

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

Parameter
Description

Client-Id

Same as the request

Request-Id

Same as the request

Response-Timestamp

Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU

Signature

Signature generated by DOKU based on the response body

Here is the sample of response body:

{
    "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

Parameter
Type
Mandatory
Description

account.created_date

string

Mandatory

Timestamp when the account was created

account.updated_date

string

Mandatory

Timestamp when the account was updated

account.name

string

Mandatory

Same as the request

account.email

string

Mandatory

Same as the request

account.type

string

Mandatory

Same as the request

account.status

string

Mandatory

Sub Account status. In this state, it should be PENDING

account.id

string

Mandatory

ID of your Sub Account, use this id to create transactions on behalf of your Partner

2. Accept Payment

To accept payment add this additional_info.account object into your payment request.

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

Request Header Explanation

Parameter
Type
Mandatory
Description

additional_info.account

string

Mandatory

Include this object for routing the payment

additional_info.account.id

string

Mandatory

ID of your Account, use this to create transactions on behalf of your Account Allowed chars: alphabetic, numeric, special chars Max Length: 40

Sample Usage

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

{
    "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

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

Type
Value

HTTP Method

POST

API endpoint (Sandbox)

https://api-sandbox.doku.com/sac-merchant/v1/payouts

API endpoint (Production)

https://api.doku.com/sac-merchant/v1/payouts

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

Parameter
Description

Client-Id

Client ID retrieved from DOKU Back Office

Request-Id

Unique random string (max 128 characters) generated from merchant side to protect duplicate request

Request-Timestamp

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

Signature

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 this section to generate the signature

Here is the sample of request body for payouts:

{
    "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

Parameter
Type
Mandatory
Description

account.id

string

Mandatory

The source of the payout Allowed chars: alphabetic, numeric, special chars Max Length: 40

payout.amount

string

Mandatory

Payout amount Allowed chars: numeric Max Length: 12

payout.invoice_number

string

Mandatory

A unique reference for this Payout. Use this to reconcile your payout. Allowed chars: alphabetic, numeric, special chars Max Length: 100

beneficiary.bank_code

string

Mandatory

SWIFT CODE Bank Destination Allowed chars: alphabetic Max Length: 12

beneficiary.bank_account_number

string

Mandatory

Beneficiary Bank Account Number Allowed chars: numeric Max Length: 40

beneficiary.bank_account_name

string

Mandatory

Beneficiary Bank Account Name Allowed chars: alphabetic Max Length: 40

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

Parameter
Description

Client-Id

Same as the request

Request-Id

Same as the request

Response-Timestamp

Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU

Signature

Signature generated by DOKU based on the response body

Here is the sample of response body:

{
    "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

Parameter
Type
Mandatory
Description

account.id

string

Mandatory

Same as request

payout.amount

string

Mandatory

Same as request

payout.invoice_number

string

Mandatory

Same as request

payout.status

string

Mandatory

Payout status

payout.created

string

Mandatory

Timestamp when Payout was created

beneficiary.bank_code

string

Mandatory

Same as request

beneficiary.bank_account_number

string

Mandatory

Same as request

beneficiary.bank_account_name

string

Mandatory

Same as request

4. Transfer Intra Sub Account

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

API Request

Type
Value

HTTP Method

POST

API endpoint (Sandbox)

https://api-sandbox.doku.com/sac-merchant/v1/transfers

API endpoint (Production)

https://api.doku.com/sac-merchant/v1/transfers

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

Parameter
Description

Client-Id

Client ID retrieved from DOKU Back Office

Request-Id

Unique random string (max 128 characters) generated from merchant side to protect duplicate request

Request-Timestamp

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

Signature

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 this section to generate the signature

Here is the sample of request body for payouts:

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

Request Body Explanation

Parameter
Type
Mandatory
Description

transfer.origin

string

Mandatory

The source of the Transfer Allowed chars: alphabetic, numeric, special chars Max Length: 40

transfer.destination

string

Mandatory

The destination of the Transfer Allowed chars: alphabetic, numeric, special chars Max Length: 40

transfer.amount

string

Mandatory

Transfer amount Allowed chars: numeric Max Length: 12

transfer.invoice_number

string

Mandatory

A unique reference for this Payout. Use this to reconcile your payout. Allowed chars: alphabetic, numeric, special chars Max Length: 100

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

Parameter
Description

Client-Id

Same as the request

Request-Id

Same as the request

Response-Timestamp

Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU

Signature

Signature generated by DOKU based on the response body

Here is the sample of response body:

{
    "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

Parameter
Type
Mandatory
Description

transfer.invoice_number

string

Mandatory

Same as request

transfer.origin

string

Mandatory

Same as request

transfer.destination

string

Mandatory

Same as request

transfer.amount

string

Mandatory

Same as request

transfer.created

string

Mandatory

Timestamp when Payout was created

5. Get Balances

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

API Request

Type
Value

HTTP Method

GET

API endpoint (Sandbox)

https://api-sandbox.doku.com/sac-merchant/v1/balances/{account_id}

API endpoint (Production)

https://api.doku.com/sac-merchant/v1/balances/{account_id}

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

Parameter
Description

Client-Id

Client ID retrieved from DOKU Back Office

Request-Id

Unique random string (max 128 characters) generated from merchant side to protect duplicate request

Request-Timestamp

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

Signature

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 this section to generate the signature

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

Parameter
Description

Client-Id

Same as the request

Request-Id

Same as the request

Response-Timestamp

Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU

Signature

Signature generated by DOKU based on the response body

Here is the sample of response body:

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

Response Body Explanation

Parameter
Type
Mandatory
Description

balance.pending

string

Mandatory

The balance remaining in your pending balance

balance.available

string

Mandatory

The balance remaining in your available balance

PreviousLibraries and SDKNextPartner API

Last updated