Integration Guide

All new integrations should use V2 for the latest capabilities and best experience.

Register Sub Account

post

https://api-sandbox.doku.comhttps://api.doku.com

/sub-account/v2.0/register

Creates a new sub-account for each party that will receive payments on your platform.

Once created, the sub-account receives:

• A unique Profile ID

• One or more Account Numbers (IDR, Pending IDR, Points)

A webhook notification is sent to your callback URL when registration is complete (see Webhook: Register Sub Account below).

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-SIGNATUREstringRequired

Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering.

Example: a1b2c3d4e5f6...

X-EXTERNAL-IDstringRequired

Numeric string used as a request reference. Must be unique within the same day (resets daily). Used by DOKU to detect and reject duplicate requests.

Example: 20240115001

Body

application/json

partnerReferenceNostring · max: 64Required

Your merchant-assigned reference number

Example: REG-20240115-001

parentProfileIdstring · max: 128Optional

Parent Profile ID for hierarchical accounts

Example: PROF-PARENT-001

referralCodestring · max: 64Optional

Referral code. DOKU auto-generates if omitted

typestring · max: 10Required

Sub-account type. Use DEFAULT for standard sub-accounts.

Example: DEFAULT

emailstring · email · max: 25Required

Email address of the account holder. Email address of the account holder.

Example: [e-mail]

namestring · max: 128Required

Name of the account holder

Example: Toko Makmur

phoneNostring · max: 15Optional

Phone number of the account holder (e.g., 081234567890)

Example: 081234567890

countryCodestring · max: 3Optional

ISO 3166-1 alpha-2 country code (e.g., ID for Indonesia)

Example: ID

Responses

200

Sub-account registered successfully

application/json

responseCodestring · max: 7OptionalExample: 2000000

responseMessagestring · max: 128OptionalExample: Successful

parentProfileIdstring · max: 128OptionalExample: PROF-PARENT-001

profileIdstring · max: 128Optional

Newly created Profile ID. Use this to reference the sub-account in future API calls (e.g., Balance Inquiries).

Example: PROF-00123

400

Bad Request

application/json

401

Unauthorized

application/json

409

Duplicate partnerReferenceNo

application/json

post/sub-account/v2.0/register

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/register HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-SIGNATURE: text
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 210

{
  "partnerReferenceNo": "REG-20240115-001",
  "parentProfileId": "PROF-PARENT-001",
  "referralCode": "text",
  "type": "DEFAULT",
  "email": "[e-mail]",
  "name": "Toko Makmur",
  "phoneNo": "081234567890",
  "countryCode": "ID"
}

{
  "responseCode": "2000000",
  "responseMessage": "Successful",
  "parentProfileId": "PROF-PARENT-001",
  "profileId": "PROF-00123",
  "accounts": [
    {
      "type": "DOKU_MERCHANT_IDR",
      "currency": "IDR",
      "accountNo": "1234567890"
    }
  ]
}

Transfer Inquiry

post

https://api-sandbox.doku.comhttps://api.doku.com

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

Validate and retrieve beneficiary details before executing a transfer. This ensures the destination account is valid and the details are correct.

The response includes a referenceNo that must be used in the Transfer Payment request.

Supports three transfer types:

• BANK_ACCOUNT — To any of 100+ Indonesian banks

• DOKU_SUB_ACCOUNT — Between sub-accounts on your platform

• DOKU_WALLET — To a DOKU e-wallet

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-SIGNATUREstringRequired

Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering.

Example: a1b2c3d4e5f6...

X-EXTERNAL-IDstringRequired

Numeric string used as a request reference. Must be unique within the same day (resets daily). Used by DOKU to detect and reject duplicate requests.

Example: 20240115001

Body

application/json

partnerReferenceNostring · max: 64Required

Unique transaction identifier. Must be unique per request

Example: TRF-20240115-001

typestring · enum · max: 20Required

Transfer destination type: BANK_ACCOUNT (external bank), DOKU_SUB_ACCOUNT (between sub-accounts), DOKU_WALLET (e-wallet)

Example: BANK_ACCOUNTPossible values:

channelstring · enum · max: 22Optional

Transfer channel. Defaults to BI_FAST

Example: BI_FASTPossible values:

fromAccountstring · max: 22Required

Source sub-account number

Example: 1234567890

beneficiaryBankCodestring · max: 16Optional

Destination bank code (see Supported Banks). Required for BANK_ACCOUNT type. Not needed for DOKU_SUB_ACCOUNT.

Example: CENAIDJA

beneficiaryAccountNumberstring · max: 22Required

Destination account number

Example: 0987654321

remarkstring · max: 256Optional

Transfer remarks

Example: Seller payout January

Responses

200

Inquiry successful

application/json

responseCodestring · max: 7OptionalExample: 2000000

responseMessagestring · max: 128OptionalExample: Successful

referenceNostring · max: 64Optional

DOKU-generated reference number. You MUST pass this value as referenceNo in the Transfer Payment request to execute this transfer.

Example: DOKU-REF-00456

partnerReferenceNostring · max: 64OptionalExample: TRF-20240115-001

typestring · max: 20OptionalExample: BANK_ACCOUNT

channelstring · max: 22Optional

Transfer channel (BI_FAST or ONLINE)

Example: BI_FAST

fromAccountstring · max: 22Optional

Source sub-account number

Example: 2010370282

beneficiaryAccountNumberstring · max: 22OptionalExample: 0987654321

beneficiaryAccountNamestring · max: 256Optional

Account holder name as registered at the destination bank. Display this to the user for confirmation before calling Transfer Payment.

Example: JOHN DOE

beneficiaryBankCodestring · max: 16OptionalExample: CENAIDJA

400

Bad Request

application/json

401

Unauthorized

application/json

404

Account not found

application/json

post/sub-account/v2.0/transfer-inquiry

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/transfer-inquiry HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-SIGNATURE: text
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 264

{
  "partnerReferenceNo": "TRF-20240115-001",
  "type": "BANK_ACCOUNT",
  "amount": {
    "value": "500000.00",
    "currency": "IDR"
  },
  "channel": "BI_FAST",
  "fromAccount": "1234567890",
  "beneficiaryBankCode": "CENAIDJA",
  "beneficiaryAccountNumber": "0987654321",
  "remark": "Seller payout January"
}

{
  "responseCode": "2000000",
  "responseMessage": "Successful",
  "referenceNo": "DOKU-REF-00456",
  "partnerReferenceNo": "TRF-20240115-001",
  "type": "BANK_ACCOUNT",
  "channel": "BI_FAST",
  "fromAccount": "2010370282",
  "beneficiaryAccountNumber": "0987654321",
  "beneficiaryAccountName": "JOHN DOE",
  "beneficiaryBankCode": "CENAIDJA",
  "amount": {
    "value": "500000.00",
    "currency": "IDR"
  }
}

Transfer Payment

post

https://api-sandbox.doku.comhttps://api.doku.com

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

Execute a fund transfer after a successful Transfer Inquiry.

Requires the referenceNo from the inquiry response. Once processed:

• Funds are deducted from the source sub-account

• Funds are delivered to the destination

• A webhook notification is sent to your callback URL (see Webhook: Transfer Payment below)

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-SIGNATUREstringRequired

Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering.

Example: a1b2c3d4e5f6...

X-EXTERNAL-IDstringRequired

Numeric string used as a request reference. Must be unique within the same day (resets daily). Used by DOKU to detect and reject duplicate requests.

Example: 20240115001

Body

application/json

partnerReferenceNostring · max: 64Required

Unique transaction identifier. Must be unique per request

Example: TRF-20240115-002

referenceNostring · max: 64Required

DOKU reference number from Transfer Inquiry

Example: DOKU-REF-00456

typestring · enum · max: 20RequiredExample: BANK_ACCOUNTPossible values:

channelstring · enum · max: 22Optional

Transfer channel. BI_FAST = real-time national payment rail, ONLINE = standard bank transfer. Defaults to BI_FAST if omitted.

Example: BI_FASTPossible values:

fromAccountstring · max: 22Required

Source sub-account number

Example: 1234567890

beneficiaryBankCodestring · max: 16Required

Destination bank code

Example: CENAIDJA

beneficiaryAccountNumberstring · max: 22Required

Destination account number

Example: 0987654321

beneficiaryAccountNamestring · max: 256Optional

Destination account holder name

Example: JOHN DOE

Responses

200

Transfer executed successfully

application/json

responseCodestring · max: 7OptionalExample: 2000000

responseMessagestring · max: 256OptionalExample: Successful

referenceNostring · max: 64OptionalExample: DOKU-REF-00456

partnerReferenceNostring · max: 64OptionalExample: TRF-20240115-002

typestring · max: 20OptionalExample: BANK_ACCOUNT

channelstring · max: 22Optional

Transfer channel (BI_FAST or ONLINE)

Example: BI_FAST

referenceNumberstring · max: 64Optional

Bank reference number

Example: DK062747488

transactionDatestring · date-timeOptionalExample: 2024-01-15T10:35:00+07:00

beneficiaryBankCodestring · max: 16OptionalExample: CENAIDJA

beneficiaryAccountNumberstring · max: 10OptionalExample: 0987654321

beneficiaryAccountNamestring · max: 22OptionalExample: JOHN DOE

fromAccountstring · max: 22OptionalExample: 1234567890

400

Bad Request

application/json

401

Unauthorized

application/json

403

Exceeds transaction amount limit

application/json

409

Duplicate partnerReferenceNo

application/json

post/sub-account/v2.0/transfer-payment

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/transfer-payment HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-SIGNATURE: text
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 298

{
  "partnerReferenceNo": "TRF-20240115-002",
  "referenceNo": "DOKU-REF-00456",
  "type": "BANK_ACCOUNT",
  "channel": "BI_FAST",
  "amount": {
    "value": "500000.00",
    "currency": "IDR"
  },
  "fromAccount": "1234567890",
  "beneficiaryBankCode": "CENAIDJA",
  "beneficiaryAccountNumber": "0987654321",
  "beneficiaryAccountName": "JOHN DOE"
}

{
  "responseCode": "2000000",
  "responseMessage": "Successful",
  "referenceNo": "DOKU-REF-00456",
  "partnerReferenceNo": "TRF-20240115-002",
  "type": "BANK_ACCOUNT",
  "channel": "BI_FAST",
  "amount": {
    "value": "500000.00",
    "currency": "IDR"
  },
  "referenceNumber": "DK062747488",
  "transactionDate": "2024-01-15T10:35:00+07:00",
  "beneficiaryBankCode": "CENAIDJA",
  "beneficiaryAccountNumber": "0987654321",
  "beneficiaryAccountName": "JOHN DOE",
  "fromAccount": "1234567890"
}

Create Split Rules

post

https://api-sandbox.doku.comhttps://api.doku.com

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

Create automated fund distribution rules for transactions. Once active, the rule applies automatically to all matching transactions — no batch, no manual intervention.

Supports two rule types:

• PERCENTAGE — each party gets a percentage of the total

• FLAT — each party gets a fixed amount

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-SIGNATUREstringRequired

Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering.

Example: a1b2c3d4e5f6...

X-EXTERNAL-IDstringRequired

Numeric string used as a request reference. Must be unique within the same day (resets daily). Used by DOKU to detect and reject duplicate requests.

Example: 20240115001

Body

application/json

transactionTypestring · max: 64Required

The transaction type this rule will match against. Use PAYMENT for split rules applied to incoming payments.

Example: PAYMENT

Responses

200

Split rule created

application/json

responseCodestringOptionalExample: 2000000

responseMessagestringOptionalExample: Successful

splitRuleIdstring · max: 36Optional

Unique ID for this split rule

Example: SR-a1b2c3d4-e5f6-7890

transactionTypestring · max: 64OptionalExample: MARKETPLACE_SALE

400

Bad Request

application/json

401

Unauthorized

application/json

post/sub-account/v2.0/split-rules

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/split-rules HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-SIGNATURE: text
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 158

{
  "transactionType": "PAYMENT",
  "rules": [
    {
      "type": "PERCENTAGE",
      "value": 95,
      "accountNumber": 1234567890
    },
    {
      "type": "PERCENTAGE",
      "value": 5,
      "accountNumber": 1234567892
    }
  ]
}

Percentage split (marketplace)Flat amount (service fee)

{
  "responseCode": "2000000",
  "responseMessage": "Successful",
  "splitRuleId": "SR-a1b2c3d4-e5f6-7890",
  "transactionType": "MARKETPLACE_SALE",
  "rules": [
    {
      "type": "PERCENTAGE",
      "value": 70,
      "currency": "IDR",
      "accountNumber": 1234567890
    }
  ]
}

Balance Inquiries

post

https://api-sandbox.doku.comhttps://api.doku.com

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

Retrieve the current balance information for a sub-account.

Returns available and reserved balances for each account type (IDR, Pending IDR, Points).

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-SIGNATUREstringRequired

Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering.

Example: a1b2c3d4e5f6...

X-EXTERNAL-IDstringRequired

Numeric string used as a request reference. Must be unique within the same day (resets daily). Used by DOKU to detect and reject duplicate requests.

Example: 20240115001

Body

application/json

profileIdstring · max: 22Required

Profile ID of the sub-account

Example: PROF-00123

accountsstring[] · max: 10Optional

Specific account numbers to query. Omit to get all

Example: ["1234567890"]

Responses

200

Balance retrieved

application/json

responseCodestring · max: 7OptionalExample: 2000000

responseMessagestring · max: 128OptionalExample: Successful

namestring · max: 128Optional

Account holder name

Example: Toko Makmur

profileIdstring · max: 128OptionalExample: PROF-00123

400

Bad Request

application/json

401

Unauthorized

application/json

post/sub-account/v2.0/balance-inquiries

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/balance-inquiries HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-SIGNATURE: text
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 52

{
  "profileId": "PROF-00123",
  "accounts": [
    "1234567890"
  ]
}

{
  "responseCode": "2000000",
  "responseMessage": "Successful",
  "name": "Toko Makmur",
  "profileId": "PROF-00123",
  "accounts": [
    {
      "type": "DOKU_MERCHANT_IDR",
      "currency": "IDR",
      "accountNo": "1234567890",
      "balance": {
        "available": "850000.00",
        "reserved": "150000.00"
      }
    }
  ]
}

Transaction Status

post

https://api-sandbox.doku.comhttps://api.doku.com

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

Check the real-time status of any Sub-Account transaction.

Returns the current status and, for cancelled debit transactions, the complete debit cancel history.

Status codes:

Code	Status
00	Success
03	Pending
04	Refunded
06	Failed

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-SIGNATUREstringRequired

Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering.

Example: a1b2c3d4e5f6...

X-EXTERNAL-IDstringRequired

Numeric string used as a request reference. Must be unique within the same day (resets daily). Used by DOKU to detect and reject duplicate requests.

Example: 20240115001

Body

application/json

partnerReferenceNostring · max: 64Required

Your unique transaction identifier

Example: PUR-20240115-001

Responses

200

Status retrieved

application/json

responseCodestring · max: 7OptionalExample: 2000000

responseMessagestring · max: 128OptionalExample: Successful

partnerReferenceNostring · max: 64OptionalExample: PUR-20240115-001

transactionTypestring · max: 16OptionalExample: PURCHASE

latestTransactionStatusstringOptional

00 = Success, 03 = Pending, 04 = Refunded, 06 = Failed. May be absent for voided transactions.

Example: 00

latestTransactionDescstring · max: 32Optional

Status description (e.g., success, void, pending)

Example: success

transactionDatestring · date-timeOptionalExample: 2024-01-15T10:40:00+07:00

400

Bad Request

application/json

401

Unauthorized

application/json

404

Transaction not found

application/json

post/sub-account/v2.0/transactions-status

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/transactions-status HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-SIGNATURE: text
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "partnerReferenceNo": "PUR-20240115-001"
}

{
  "responseCode": "2000000",
  "responseMessage": "Successful",
  "partnerReferenceNo": "PUR-20240115-001",
  "transactionType": "PURCHASE",
  "latestTransactionStatus": "00",
  "latestTransactionDesc": "success",
  "transactionDate": "2024-01-15T10:40:00+07:00",
  "amount": {
    "value": "500000.00",
    "currency": "IDR"
  },
  "refundHistory": [
    {
      "refundNo": "DOKU-REFUND-00123",
      "refundStatus": "00",
      "transactionDate": "2024-01-15T11:00:00+07:00",
      "reason": "Customer returned 1x Widget Pro",
      "refundAmount": {
        "value": "500000.00",
        "currency": "IDR"
      }
    }
  ]
}

Transaction History

post

https://api-sandbox.doku.comhttps://api.doku.com

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

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

Use this for reconciliation, generating statements, and compliance reporting.

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-SIGNATUREstringRequired

Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering.

Example: a1b2c3d4e5f6...

X-EXTERNAL-IDstringRequired

Numeric string used as a request reference. Must be unique within the same day (resets daily). Used by DOKU to detect and reject duplicate requests.

Example: 20240115001

Body

application/json

accountNostring · max: 10Required

Sub-account number

Example: 1234567890

fromDateTimestring · max: 25Required

Start date in ISO 8601 format

Example: 2024-01-01T00:00:00+07:00

toDateTimestring · max: 25Required

End date in ISO 8601 format

Example: 2024-01-31T23:59:59+07:00

pageSizestring · max: 3Required

Items per page

Example: 20

pageNumberstring · max: 3Required

Page number (starts from 0). Use 0 for the first page.

Example: 0

Responses

200

History retrieved

application/json

responseCodestring · max: 7OptionalExample: 2001200

responseMessagestring · max: 128OptionalExample: Request has been processed successfully

400

Bad Request

application/json

401

Unauthorized

application/json

post/sub-account/v2.0/transaction-history-list

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/transaction-history-list HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-SIGNATURE: text
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 143

{
  "accountNo": "1234567890",
  "fromDateTime": "2024-01-01T00:00:00+07:00",
  "toDateTime": "2024-01-31T23:59:59+07:00",
  "pageSize": "20",
  "pageNumber": "0"
}

{
  "responseCode": "2001200",
  "responseMessage": "Request has been processed successfully",
  "detailData": [
    {
      "mutationType": "DEBIT",
      "transactionType": "PAYOUT",
      "amount": 11000,
      "currency": "IDR",
      "status": "SUCCESS",
      "dateTime": "2026-06-19T17:03:32+07:00",
      "remark": "Transfer to Bank Transfer Bank to CIMB",
      "partnerReferenceNo": "TRF-BANK-013",
      "referenceNo": "85da590e22f746869421f12015daeae2",
      "channel": "BI_FAST"
    }
  ]
}

Debit

post

https://api-sandbox.doku.comhttps://api.doku.com

/sub-account/v2.0/debit

Process a debit transaction on a sub-account.

A webhook notification is sent to your callback URL when the transaction status updates (see Webhook: Debit below).

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-SIGNATUREstringRequired

Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering.

Example: a1b2c3d4e5f6...

X-EXTERNAL-IDstringRequired

Numeric string used as a request reference. Must be unique within the same day (resets daily). Used by DOKU to detect and reject duplicate requests.

Example: 20240115001

Body

application/json

partnerReferenceNostring · max: 64Required

Unique transaction identifier. Must be unique per request

Example: PUR-20240115-001

fromAccountstring · max: 10Required

Sub-account number to debit

Example: 1234567890

transactionTypestring · max: 16Required

A merchant-defined label to categorize the transaction (e.g., PURCHASE, SERVICE_FEE). Used for filtering and split rule matching.

Example: PURCHASE

descriptionstring · max: 128Optional

Transaction description

Example: Purchase of 3x Widget Pro

Responses

200

Debit processed

application/json

responseCodestring · max: 7OptionalExample: 2000000

responseMessagestring · max: 128OptionalExample: Successful

partnerReferenceNostring · max: 64OptionalExample: PUR-20240115-001

referenceNostring · max: 64OptionalExample: DOKU-REF-00789

transactionTypestring · max: 16OptionalExample: PURCHASE

fromAccountstring · max: 10OptionalExample: 1234567890

descriptionstring · max: 128OptionalExample: Purchase of 3x Widget Pro

latestTransactionStatusstringOptional

00 = Success, 03 = Pending, 04 = Refunded, 06 = Failed

Example: 00

transactionStatusDescstring · max: 128OptionalExample: Success

transactionDatestring · date-timeOptionalExample: 2024-01-15T10:40:00+07:00

400

Bad Request

application/json

401

Unauthorized

application/json

409

Duplicate partnerReferenceNo

application/json

post/sub-account/v2.0/debit

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/debit HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-SIGNATURE: text
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 187

{
  "partnerReferenceNo": "PUR-20240115-001",
  "fromAccount": "1234567890",
  "transactionType": "PURCHASE",
  "amount": {
    "value": "500000.00",
    "currency": "IDR"
  },
  "description": "Purchase of 3x Widget Pro"
}

{
  "responseCode": "2000000",
  "responseMessage": "Successful",
  "partnerReferenceNo": "PUR-20240115-001",
  "referenceNo": "DOKU-REF-00789",
  "transactionType": "PURCHASE",
  "fromAccount": "1234567890",
  "amount": {
    "value": "500000.00",
    "currency": "IDR"
  },
  "description": "Purchase of 3x Widget Pro",
  "latestTransactionStatus": "00",
  "transactionStatusDesc": "Success",
  "transactionDate": "2024-01-15T10:40:00+07:00"
}

Debit Cancel

post

https://api-sandbox.doku.comhttps://api.doku.com

/sub-account/v2.0/debit/cancel

Process a full or partial cancellation for a previous debit transaction.

References the original debit by originalPartnerReferenceNo. The cancellation amount can be equal to or less than the original debit amount.

A webhook notification is sent to your callback URL when the debit cancellation is processed (see Webhook: Debit Cancel below).

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-SIGNATUREstringRequired

Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering.

Example: a1b2c3d4e5f6...

X-EXTERNAL-IDstringRequired

Numeric string used as a request reference. Must be unique within the same day (resets daily). Used by DOKU to detect and reject duplicate requests.

Example: 20240115001

Body

application/json

partnerReferenceNostring · max: 64Required

Unique identifier for this debit cancel request

Example: REF-20240115-001

originalPartnerReferenceNostring · max: 64Required

partnerReferenceNo from the original debit

Example: PUR-20240115-001

originalReferenceNostring · max: 64Optional

referenceNo from the original debit

Example: DOKU-REF-00789

transactionTypestring · max: 16Required

Use REFUND_PURCHASE for cancelling a debit transaction.

Example: REFUND_PURCHASE

reasonstring · max: 128Optional

Reason for the debit cancellation

Example: Customer returned 1x Widget Pro

Responses

200

Debit cancellation processed

application/json

responseCodestring · max: 7OptionalExample: 2000000

responseMessagestring · max: 128OptionalExample: Successful

partnerReferenceNostring · max: 64OptionalExample: REF-20240115-001

originalPartnerReferenceNostring · max: 64OptionalExample: PUR-20240115-001

originalReferenceNostring · max: 64OptionalExample: DOKU-REF-00789

transactionTypestring · max: 16OptionalExample: REFUND_PURCHASE

refundNostring · max: 64Optional

DOKU-assigned debit cancel number

Example: DOKU-REFUND-00123

reasonstring · max: 128OptionalExample: Customer returned 1x Widget Pro

latestTransactionStatusstringOptional

00 = Success, 03 = Pending, 04 = Refunded, 06 = Failed

Example: 00

transactionStatusDescstring · max: 128OptionalExample: Success

transactionDatestring · date-timeOptionalExample: 2024-01-15T11:00:00+07:00

400

Bad Request

application/json

401

Unauthorized

application/json

404

Original transaction not found

application/json

post/sub-account/v2.0/debit/cancel

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/debit/cancel HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-SIGNATURE: text
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 261

{
  "partnerReferenceNo": "REF-20240115-001",
  "originalPartnerReferenceNo": "PUR-20240115-001",
  "originalReferenceNo": "DOKU-REF-00789",
  "transactionType": "REFUND_PURCHASE",
  "refundAmount": {
    "value": "500000.00",
    "currency": "IDR"
  },
  "reason": "Customer returned 1x Widget Pro"
}

{
  "responseCode": "2000000",
  "responseMessage": "Successful",
  "partnerReferenceNo": "REF-20240115-001",
  "originalPartnerReferenceNo": "PUR-20240115-001",
  "originalReferenceNo": "DOKU-REF-00789",
  "transactionType": "REFUND_PURCHASE",
  "refundNo": "DOKU-REFUND-00123",
  "refundAmount": {
    "value": "500000.00",
    "currency": "IDR"
  },
  "reason": "Customer returned 1x Widget Pro",
  "latestTransactionStatus": "00",
  "transactionStatusDesc": "Success",
  "transactionDate": "2024-01-15T11:00:00+07:00"
}

Webhook: BRI VA Top-Up

post

https://api-sandbox.doku.comhttps://api.doku.com

/sub-account/v2.0/topup/notification

Webhook sent by DOKU when a BRI VA top-up payment is successful.

Every sub-account is auto-assigned a static BRI VA (prefix 1392495 + DOKU_MERCHANT_IDR account number). When a payment is made to this VA, funds are credited to the sub-account's DOKU_MERCHANT_IDR balance in real-time.

DOKU sends this notification to your registered callback URL. Your system must respond with a responseCode and responseMessage to acknowledge receipt.

Key difference from Checkout/Direct API payments:

• BRI VA top-up → credited to DOKU_MERCHANT_IDR immediately (real-time)

• Checkout/Direct API → credited to DOKU_PENDING_IDR first, then moves to DOKU_MERCHANT_IDR after settlement

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-EXTERNAL-IDstringRequired

HMAC_SHA512 signature for verification

Body

application/json

referenceNostringOptional

DOKU-generated reference number for this top-up transaction

Example: 45af25e8c4dd5c1634e967a2ebfff3a4043e7fd6

partnerReferenceNostringOptional

Partner reference number for this transaction

Example: 3f97a11c4476420897f2224de1ccea73

transactionTypestringOptional

Transaction type. Always TOPUP for BRI VA top-up callbacks.

Example: TOPUP

toAccountnumberOptional

The DOKU_MERCHANT_IDR account number that received the top-up funds

Example: 2052010241

descriptionstringOptional

Description of the transaction

Example: topup account

latestTransactionStatusstringOptional

Transaction status: 00 = Success

Example: 00

transactionStatusDescstringOptional

Human-readable status description

Example: Success

partnerServiceIdstringOptional

Partner service identifier

Example: 77777

customerNostringOptional

Customer number portion of the VA number

Example: 0000000000001

trxDateTimestring · date-timeOptional

Transaction datetime in ISO 8601 format

Example: 2019-07-03T12:08:56+07:00

virtualAccountNostringOptional

Full BRI VA number that was paid (prefix 1392495 + DOKU_MERCHANT_IDR account number)

Example: 777770000000000001

virtualAccountNamestringOptional

Name registered to the virtual account (sub-account holder name)

Example: Toru Yamashita

trxIdstringOptional

Bank transaction ID from BRI

Example: 23219829713

paymentRequestIdstringOptional

Payment request identifier

Example: 12839218738127830

Responses

200

Notification acknowledged

application/json

responseCodestring · max: 7RequiredExample: 2000000

responseMessagestring · max: 128RequiredExample: Successful

post/sub-account/v2.0/topup/notification

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/topup/notification HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 611

{
  "referenceNo": "45af25e8c4dd5c1634e967a2ebfff3a4043e7fd6",
  "partnerReferenceNo": "3f97a11c4476420897f2224de1ccea73",
  "transactionType": "TOPUP",
  "toAccount": 2052010241,
  "amount": {
    "value": "1000.00",
    "currency": "IDR"
  },
  "description": "topup account",
  "latestTransactionStatus": "00",
  "transactionStatusDesc": "Success",
  "partnerServiceId": "77777",
  "customerNo": "0000000000001",
  "trxDateTime": "2019-07-03T12:08:56+07:00",
  "virtualAccountNo": "777770000000000001",
  "virtualAccountName": "Toru Yamashita",
  "trxId": "23219829713",
  "paymentRequestId": "12839218738127830",
  "additionalInfo": {
    "channel": "VIRTUAL_ACCOUNT_BRI",
    "serviceCode": "38"
  }
}

200

Notification acknowledged

{
  "responseCode": "2000000",
  "responseMessage": "Successful"
}

Webhook: Register Sub Account

post

https://api-sandbox.doku.comhttps://api.doku.com

/sub-account/v2.0/register/notification

Webhook sent by DOKU when a sub-account registration is complete.

DOKU sends this notification to your registered callback URL. Your system must respond with a responseCode and responseMessage to acknowledge receipt.

Best practices:

• Respond quickly — return acknowledgment immediately, then process asynchronously

• Be idempotent — you may receive the same notification more than once

• Verify the X-EXTERNAL-ID signature to confirm authenticity

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-EXTERNAL-IDstringRequired

HMAC_SHA512 signature for verification

Body

application/json

partnerReferenceNostringOptional

Your merchant reference number

Example: REG-20240115-001

parentProfileCodestringOptional

Parent profile code

Example: PROF-PARENT-001

profileCodestringOptional

New sub-account's profile code

Example: PROF-00123

referralCodestringOptional

Assigned referral code

Example: REF-AUTO-001

typestringOptional

Sub-account type

Example: DEFAULT

emailstringOptional

Email address

Example: [e-mail]

namestringOptional

Account holder name

Example: Toko Makmur

statusstringOptional

Registration status

Example: ACTIVE

levelstringOptional

Account level in hierarchy

Example: 2

phoneNostringOptional

Phone number of the account holder

Example: 081234567890

Responses

200

Notification acknowledged

application/json

responseCodestring · max: 7RequiredExample: 2000000

responseMessagestring · max: 128RequiredExample: Successful

post/sub-account/v2.0/register/notification

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/register/notification HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 342

{
  "partnerReferenceNo": "REG-20240115-001",
  "parentProfileCode": "PROF-PARENT-001",
  "profileCode": "PROF-00123",
  "referralCode": "REF-AUTO-001",
  "type": "DEFAULT",
  "email": "[e-mail]",
  "name": "Toko Makmur",
  "status": "ACTIVE",
  "level": "2",
  "phoneNo": "081234567890",
  "accounts": [
    {
      "type": "DOKU_MERCHANT_IDR",
      "currency": "IDR",
      "accountNo": "1234567890"
    }
  ]
}

200

Notification acknowledged

{
  "responseCode": "2000000",
  "responseMessage": "Successful"
}

Webhook: Transfer Payment

post

https://api-sandbox.doku.comhttps://api.doku.com

/sub-account/v2.0/transfer/notification

Webhook sent by DOKU when a fund transfer status updates.

Your system must respond with a responseCode and responseMessage to acknowledge receipt.

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-EXTERNAL-IDstringRequired

HMAC_SHA512 signature for verification

Body

application/json

referenceNostringOptional

DOKU reference number

Example: DOKU-REF-00456

partnerReferenceNostringOptional

Your merchant reference number

Example: TRF-20240115-002

latestTransactionStatusstringOptional

00 = Success, 03 = Pending, 06 = Failed

Example: 00

transactionStatusDescstringOptional

Status description

Example: Success

fromAccountstringOptional

Source sub-account

Example: 1234567890

Responses

200

Notification acknowledged

application/json

responseCodestring · max: 7RequiredExample: 2000000

responseMessagestring · max: 128RequiredExample: Successful

post/sub-account/v2.0/transfer/notification

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/transfer/notification HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 212

{
  "referenceNo": "DOKU-REF-00456",
  "partnerReferenceNo": "TRF-20240115-002",
  "latestTransactionStatus": "00",
  "transactionStatusDesc": "Success",
  "fromAccount": "1234567890",
  "amount": {
    "value": "500000.00",
    "currency": "IDR"
  }
}

200

Notification acknowledged

{
  "responseCode": "2000000",
  "responseMessage": "Successful"
}

Webhook: Debit

post

https://api-sandbox.doku.comhttps://api.doku.com

/sub-account/v2.0/debit/notification

Webhook sent by DOKU when a debit transaction status updates.

Your system must respond with a responseCode and responseMessage to acknowledge receipt.

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-EXTERNAL-IDstringRequired

HMAC_SHA512 signature for verification

Body

application/json

referenceNostringOptional

DOKU reference number

Example: DOKU-REF-00789

partnerReferenceNostringOptional

Your merchant reference number

Example: PUR-20240115-001

transactionTypestringOptional

Merchant-defined transaction category matching the original request

Example: PURCHASE

fromAccountstringOptional

Debited account

Example: 1234567890

toAccountstringOptional

Destination account

Example: 0000000001

descriptionstringOptional

Transaction description

Example: Purchase of 3x Widget Pro

latestTransactionStatusstringOptional

00 = Success, 03 = Pending, 06 = Failed

Example: 00

transactionStatusDescstringOptional

Status description

Example: Success

Responses

200

Notification acknowledged

application/json

responseCodestring · max: 7RequiredExample: 2000000

responseMessagestring · max: 128RequiredExample: Successful

post/sub-account/v2.0/debit/notification

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/debit/notification HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 308

{
  "referenceNo": "DOKU-REF-00789",
  "partnerReferenceNo": "PUR-20240115-001",
  "transactionType": "PURCHASE",
  "fromAccount": "1234567890",
  "toAccount": "0000000001",
  "amount": {
    "value": "150000.00",
    "currency": "IDR"
  },
  "description": "Purchase of 3x Widget Pro",
  "latestTransactionStatus": "00",
  "transactionStatusDesc": "Success"
}

200

Notification acknowledged

{
  "responseCode": "2000000",
  "responseMessage": "Successful"
}

Webhook: Debit Cancel

post

https://api-sandbox.doku.comhttps://api.doku.com

/sub-account/v2.0/debit/cancel/notification

Webhook sent by DOKU when a debit cancellation is processed.

Your system must respond with a responseCode and responseMessage to acknowledge receipt.

Authorizations

BearerAuth

AuthorizationstringRequired

B2B Token obtained from Get B2B Token API

Header parameters

X-PARTNER-IDstringRequired

Your Partner ID (DOKU's Client ID)

Example: PARTNER-001

X-TIMESTAMPstring · date-timeRequired

Client's current local time in ISO 8601 format

Example: 2024-01-15T10:30:00+07:00

X-EXTERNAL-IDstringRequired

HMAC_SHA512 signature for verification

Body

application/json

partnerReferenceNostringOptional

Your debit cancel reference number

Example: REF-20240115-001

originalReferenceNostringOptional

Original DOKU reference

Example: DOKU-REF-00789

originalPartnerReferenceNostringOptional

Original merchant reference

Example: PUR-20240115-001

refundNostringOptional

DOKU-assigned debit cancel number

Example: DOKU-REFUND-00123

transactionTypestringOptional

Transaction type for debit cancellation

Example: REFUND_PURCHASE

reasonstringOptional

Debit cancel reason

Example: Customer returned 1x Widget Pro

refundTimestring · date-timeOptional

Debit cancel timestamp

Example: 2024-01-15T11:00:00+07:00

latestTransactionStatusstringOptional

00 = Success, 03 = Pending, 06 = Failed

Example: 00

transactionStatusDescstringOptional

Status description

Example: Success

Responses

200

Notification acknowledged

application/json

responseCodestring · max: 7RequiredExample: 2000000

responseMessagestring · max: 128RequiredExample: Successful

post/sub-account/v2.0/debit/cancel/notification

HTTPcURLJavaScriptPython

POST /sub-account/v2.0/debit/cancel/notification HTTP/1.1
Host: api-sandbox.doku.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-PARTNER-ID: text
X-TIMESTAMP: 2026-07-15T16:19:54.628Z
X-EXTERNAL-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 390

{
  "partnerReferenceNo": "REF-20240115-001",
  "originalReferenceNo": "DOKU-REF-00789",
  "originalPartnerReferenceNo": "PUR-20240115-001",
  "refundNo": "DOKU-REFUND-00123",
  "transactionType": "PURCHASE",
  "reason": "Customer returned 1x Widget Pro",
  "refundAmount": {
    "value": "50000.00",
    "currency": "IDR"
  },
  "refundTime": "2024-01-15T11:00:00+07:00",
  "latestTransactionStatus": "00",
  "transactionStatusDesc": "Success"
}

200

Notification acknowledged

{
  "responseCode": "2000000",
  "responseMessage": "Successful"
}