Integration Guide

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": "test2@doku.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": "test2@doku.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”
    }
}

Response 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	Mandatory	string	Same as request
beneficiary.bank_account_name	Mandatory	string	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

---