> For the complete documentation index, see [llms.txt](https://developers.doku.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.doku.com/wallet-as-a-service/sub-account/sub-account-v2/integration-guide.md). # Integration Guide {% hint style="info" %} All new integrations should use V2 for the latest capabilities and best experience. {% endhint %} ## Register Sub Account > 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).
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Account Management","description":"Create and manage sub-accounts"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"},"X-SIGNATURE":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering."},"X-EXTERNAL-ID":{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"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."}},"schemas":{"AccountInfo":{"type":"object","properties":{"type":{"type":"string","maxLength":32,"description":"Account type: DOKU_MERCHANT_IDR (withdrawable IDR), DOKU_PENDING_IDR (held/reserved), DOKU_MERCHANT_POINT (non-cash points)"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code (IDR) or POINT for non-cash accounts"},"accountNo":{"type":"string","maxLength":10,"description":"Unique account number assigned by DOKU. Use this in transaction APIs (transfers, debits, balance inquiries)."}}},"ErrorResponse":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/register":{"post":{"operationId":"registerSubAccount","tags":["Account Management"],"summary":"Register Sub Account","description":"Creates a new sub-account for each party that will receive payments on your platform.\n\nOnce created, the sub-account receives:\n- A unique **Profile ID**\n- One or more **Account Numbers** (IDR, Pending IDR, Points)\n\nA webhook notification is sent to your callback URL when registration is complete (see Webhook: Register Sub Account below).\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"$ref":"#/components/parameters/X-SIGNATURE"},{"$ref":"#/components/parameters/X-EXTERNAL-ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["partnerReferenceNo","type","name","email"],"properties":{"partnerReferenceNo":{"type":"string","maxLength":64,"description":"Your merchant-assigned reference number"},"parentProfileId":{"type":"string","maxLength":128,"description":"Parent Profile ID for hierarchical accounts"},"referralCode":{"type":"string","maxLength":64,"description":"Referral code. DOKU auto-generates if omitted"},"type":{"type":"string","maxLength":10,"description":"Sub-account type. Use DEFAULT for standard sub-accounts."},"email":{"type":"string","maxLength":25,"format":"email","description":"Email address of the account holder. Email address of the account holder."},"name":{"type":"string","maxLength":128,"description":"Name of the account holder"},"phoneNo":{"type":"string","maxLength":15,"description":"Phone number of the account holder (e.g., 081234567890)"},"countryCode":{"type":"string","maxLength":3,"description":"ISO 3166-1 alpha-2 country code (e.g., ID for Indonesia)"}}}}}},"responses":{"200":{"description":"Sub-account registered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128},"parentProfileId":{"type":"string","maxLength":128},"profileId":{"type":"string","maxLength":128,"description":"Newly created Profile ID. Use this to reference the sub-account in future API calls (e.g., Balance Inquiries)."},"accounts":{"type":"array","description":"List of accounts created for this sub-account. Each sub-account can have up to 3 account types: DOKU_MERCHANT_IDR (withdrawable), DOKU_PENDING_IDR (held), DOKU_MERCHANT_POINT (non-cash).","items":{"$ref":"#/components/schemas/AccountInfo"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Duplicate partnerReferenceNo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## 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]\(/api-reference/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
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Fund Transfers","description":"Validate and execute fund transfers"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"},"X-SIGNATURE":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering."},"X-EXTERNAL-ID":{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"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."}},"schemas":{"Amount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Amount as a string with 2 decimal places (e.g., \"500000.00\")"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code"}}},"ErrorResponse":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/transfer-inquiry":{"post":{"operationId":"transferInquiry","tags":["Fund Transfers"],"summary":"Transfer Inquiry","description":"Validate and retrieve beneficiary details before executing a transfer. This ensures the destination account is valid and the details are correct.\n\nThe response includes a `referenceNo` that **must be used** in the [Transfer Payment](/api-reference/transfer-payment) request.\n\nSupports three transfer types:\n- `BANK_ACCOUNT` — To any of 100+ Indonesian banks\n- `DOKU_SUB_ACCOUNT` — Between sub-accounts on your platform\n- `DOKU_WALLET` — To a DOKU e-wallet\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"$ref":"#/components/parameters/X-SIGNATURE"},{"$ref":"#/components/parameters/X-EXTERNAL-ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["partnerReferenceNo","type","amount","fromAccount","beneficiaryAccountNumber"],"properties":{"partnerReferenceNo":{"type":"string","maxLength":64,"description":"Unique transaction identifier. Must be unique per request"},"type":{"type":"string","maxLength":20,"enum":["BANK_ACCOUNT","DOKU_SUB_ACCOUNT","DOKU_WALLET"],"description":"Transfer destination type: BANK_ACCOUNT (external bank), DOKU_SUB_ACCOUNT (between sub-accounts), DOKU_WALLET (e-wallet)"},"amount":{"$ref":"#/components/schemas/Amount"},"channel":{"type":"string","maxLength":22,"enum":["BI_FAST","ONLINE"],"description":"Transfer channel. Defaults to BI_FAST"},"fromAccount":{"type":"string","maxLength":22,"description":"Source sub-account number"},"beneficiaryBankCode":{"type":"string","maxLength":16,"description":"Destination bank code (see Supported Banks). Required for BANK_ACCOUNT type. Not needed for DOKU_SUB_ACCOUNT."},"beneficiaryAccountNumber":{"type":"string","maxLength":22,"description":"Destination account number"},"remark":{"type":"string","maxLength":256,"description":"Transfer remarks"}}}}}},"responses":{"200":{"description":"Inquiry successful","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128},"referenceNo":{"type":"string","maxLength":64,"description":"DOKU-generated reference number. You MUST pass this value as referenceNo in the Transfer Payment request to execute this transfer."},"partnerReferenceNo":{"type":"string","maxLength":64},"type":{"type":"string","maxLength":20},"channel":{"type":"string","maxLength":22,"description":"Transfer channel (BI_FAST or ONLINE)"},"fromAccount":{"type":"string","maxLength":22,"description":"Source sub-account number"},"beneficiaryAccountNumber":{"type":"string","maxLength":22},"beneficiaryAccountName":{"type":"string","maxLength":256,"description":"Account holder name as registered at the destination bank. Display this to the user for confirmation before calling Transfer Payment."},"beneficiaryBankCode":{"type":"string","maxLength":16},"amount":{"$ref":"#/components/schemas/Amount"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Transfer Payment > Execute a fund transfer after a successful \[Transfer Inquiry]\(/api-reference/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)
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Fund Transfers","description":"Validate and execute fund transfers"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"},"X-SIGNATURE":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering."},"X-EXTERNAL-ID":{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"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."}},"schemas":{"Amount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Amount as a string with 2 decimal places (e.g., \"500000.00\")"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code"}}},"ErrorResponse":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/transfer-payment":{"post":{"operationId":"transferPayment","tags":["Fund Transfers"],"summary":"Transfer Payment","description":"Execute a fund transfer after a successful [Transfer Inquiry](/api-reference/transfer-inquiry).\n\nRequires the `referenceNo` from the inquiry response. Once processed:\n- Funds are deducted from the source sub-account\n- Funds are delivered to the destination\n- A webhook notification is sent to your callback URL (see Webhook: Transfer Payment below)\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"$ref":"#/components/parameters/X-SIGNATURE"},{"$ref":"#/components/parameters/X-EXTERNAL-ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["partnerReferenceNo","referenceNo","type","amount","fromAccount","beneficiaryBankCode","beneficiaryAccountNumber"],"properties":{"partnerReferenceNo":{"type":"string","maxLength":64,"description":"Unique transaction identifier. Must be unique per request"},"referenceNo":{"type":"string","maxLength":64,"description":"DOKU reference number from Transfer Inquiry"},"type":{"type":"string","maxLength":20,"enum":["BANK_ACCOUNT","DOKU_SUB_ACCOUNT","DOKU_WALLET"]},"channel":{"type":"string","maxLength":22,"enum":["BI_FAST","ONLINE"],"description":"Transfer channel. BI_FAST = real-time national payment rail, ONLINE = standard bank transfer. Defaults to BI_FAST if omitted."},"amount":{"$ref":"#/components/schemas/Amount"},"fromAccount":{"type":"string","maxLength":22,"description":"Source sub-account number"},"beneficiaryBankCode":{"type":"string","maxLength":16,"description":"Destination bank code"},"beneficiaryAccountNumber":{"type":"string","maxLength":22,"description":"Destination account number"},"beneficiaryAccountName":{"type":"string","maxLength":256,"description":"Destination account holder name"}}}}}},"responses":{"200":{"description":"Transfer executed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":256},"referenceNo":{"type":"string","maxLength":64},"partnerReferenceNo":{"type":"string","maxLength":64},"type":{"type":"string","maxLength":20},"channel":{"type":"string","maxLength":22,"description":"Transfer channel (BI_FAST or ONLINE)"},"amount":{"$ref":"#/components/schemas/Amount"},"referenceNumber":{"type":"string","maxLength":64,"description":"Bank reference number"},"transactionDate":{"type":"string","format":"date-time"},"beneficiaryBankCode":{"type":"string","maxLength":16},"beneficiaryAccountNumber":{"type":"string","maxLength":10},"beneficiaryAccountName":{"type":"string","maxLength":22},"fromAccount":{"type":"string","maxLength":22}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Exceeds transaction amount limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Duplicate partnerReferenceNo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Create 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
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Split Rules","description":"Configure automated fund distribution"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"},"X-SIGNATURE":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering."},"X-EXTERNAL-ID":{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"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."}},"schemas":{"SplitRuleItem":{"type":"object","required":["type","value","accountNumber"],"properties":{"type":{"type":"string","maxLength":20,"enum":["PERCENTAGE","FLAT"],"description":"PERCENTAGE = distribute a percentage of the transaction amount. FLAT = distribute a fixed amount regardless of transaction size."},"value":{"type":"number","description":"When type is PERCENTAGE, this is the percentage (e.g., 70 = 70%). When type is FLAT, this is the fixed amount in the specified currency (e.g., 5000 = IDR 5,000). Only numbers and decimal point (.) are allowed — no commas, spaces, or other characters."},"currency":{"type":"string","maxLength":6,"description":"ISO 4217 currency code. Required when type is FLAT to specify the currency of the flat amount. Ignored for PERCENTAGE type."},"accountNumber":{"type":"number","description":"The sub-account number that will receive this portion of the split. Must be an existing sub-account under your merchant."}}},"ErrorResponse":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/split-rules":{"post":{"operationId":"createSplitRules","tags":["Split Rules"],"summary":"Create Split Rules","description":"Create automated fund distribution rules for transactions. Once active, the rule applies automatically to all matching transactions — no batch, no manual intervention.\n\nSupports two rule types:\n- **PERCENTAGE** — each party gets a percentage of the total\n- **FLAT** — each party gets a fixed amount\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"$ref":"#/components/parameters/X-SIGNATURE"},{"$ref":"#/components/parameters/X-EXTERNAL-ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["transactionType","rules"],"properties":{"transactionType":{"type":"string","maxLength":64,"description":"The transaction type this rule will match against. Use PAYMENT for split rules applied to incoming payments."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/SplitRuleItem"}}}}}}},"responses":{"200":{"description":"Split rule created","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"},"splitRuleId":{"type":"string","maxLength":36,"description":"Unique ID for this split rule"},"transactionType":{"type":"string","maxLength":64},"rules":{"type":"array","items":{"$ref":"#/components/schemas/SplitRuleItem"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Balance Inquiries > Retrieve the current balance information for a sub-account.\ > \ > Returns \*\*available\*\* and \*\*reserved\*\* balances for each account type (IDR, Pending IDR, Points).
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Monitoring","description":"Check balances, transaction status, and history"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"},"X-SIGNATURE":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering."},"X-EXTERNAL-ID":{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"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."}},"schemas":{"Balance":{"type":"object","properties":{"available":{"type":"string","description":"Available balance (can be spent or transferred)"},"reserved":{"type":"string","description":"Reserved balance (held for pending transactions)"}}},"ErrorResponse":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/balance-inquiries":{"post":{"operationId":"balanceInquiries","tags":["Monitoring"],"summary":"Balance Inquiries","description":"Retrieve the current balance information for a sub-account.\n\nReturns **available** and **reserved** balances for each account type (IDR, Pending IDR, Points).\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"$ref":"#/components/parameters/X-SIGNATURE"},{"$ref":"#/components/parameters/X-EXTERNAL-ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileId"],"properties":{"profileId":{"type":"string","maxLength":22,"description":"Profile ID of the sub-account"},"accounts":{"type":"array","maxItems":10,"items":{"type":"string"},"description":"Specific account numbers to query. Omit to get all"}}}}}},"responses":{"200":{"description":"Balance retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128},"name":{"type":"string","maxLength":128,"description":"Account holder name"},"profileId":{"type":"string","maxLength":128},"accounts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","maxLength":32},"currency":{"type":"string","maxLength":3},"accountNo":{"type":"string","maxLength":10},"balance":{"$ref":"#/components/schemas/Balance"}}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Transaction 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 |
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Monitoring","description":"Check balances, transaction status, and history"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"},"X-SIGNATURE":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering."},"X-EXTERNAL-ID":{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"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."}},"schemas":{"Amount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Amount as a string with 2 decimal places (e.g., \"500000.00\")"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code"}}},"RefundHistoryItem":{"type":"object","properties":{"refundNo":{"type":"string","maxLength":64,"description":"DOKU-assigned debit cancel number"},"refundStatus":{"type":"string","maxLength":4,"description":"Debit cancel status code"},"transactionDate":{"type":"string","format":"date-time","description":"Debit cancel datetime"},"reason":{"type":"string","maxLength":128,"description":"Debit cancel reason"},"refundAmount":{"$ref":"#/components/schemas/Amount"}}},"ErrorResponse":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/transactions-status":{"post":{"operationId":"transactionStatus","tags":["Monitoring"],"summary":"Transaction Status","description":"Check the real-time status of any Sub-Account transaction.\n\nReturns the current status and, for cancelled debit transactions, the complete debit cancel history.\n\n**Status codes:**\n| Code | Status |\n|------|--------|\n| `00` | Success |\n| `03` | Pending |\n| `04` | Refunded |\n| `06` | Failed |\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"$ref":"#/components/parameters/X-SIGNATURE"},{"$ref":"#/components/parameters/X-EXTERNAL-ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["partnerReferenceNo"],"properties":{"partnerReferenceNo":{"type":"string","maxLength":64,"description":"Your unique transaction identifier"}}}}}},"responses":{"200":{"description":"Status retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128},"partnerReferenceNo":{"type":"string","maxLength":64},"transactionType":{"type":"string","maxLength":16},"latestTransactionStatus":{"type":"string","description":"00 = Success, 03 = Pending, 04 = Refunded, 06 = Failed. May be absent for voided transactions."},"latestTransactionDesc":{"type":"string","maxLength":32,"description":"Status description (e.g., success, void, pending)"},"transactionDate":{"type":"string","format":"date-time"},"amount":{"$ref":"#/components/schemas/Amount"},"refundHistory":{"type":"array","items":{"$ref":"#/components/schemas/RefundHistoryItem"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Transaction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Transaction History > Retrieve a paginated list of transactions for a sub-account within a date range.\ > \ > Use this for reconciliation, generating statements, and compliance reporting.
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Monitoring","description":"Check balances, transaction status, and history"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"},"X-SIGNATURE":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering."},"X-EXTERNAL-ID":{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"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."}},"schemas":{"TransactionHistoryItem":{"type":"object","properties":{"mutationType":{"type":"string","enum":["CREDIT","DEBIT"],"description":"CREDIT = money in, DEBIT = money out"},"transactionType":{"type":"string","maxLength":32,"description":"Transaction type: PAYMENT, TOPUP, TOPUP_FEE, PURCHASE, TRANSFER_P2P, PAYOUT, PAYOUT_CHARGE, SETTLEMENT, SETTLEMENT_FEE, SPLIT_TRANSACTION, REFUND_PURCHASE, REFUND_PAYMENT, VOID_PAYMENT, ADJUSTMENT_CREDIT, ADJUSTMENT_DEBIT"},"amount":{"type":"number","description":"Transaction amount"},"currency":{"type":"string","maxLength":3,"description":"Currency code (IDR or POINT)"},"status":{"type":"string","maxLength":16,"description":"Transaction status: SUCCESS, PENDING, or FAILED"},"dateTime":{"type":"string","format":"date-time","description":"Transaction datetime"},"remark":{"type":"string","maxLength":256,"description":"Transaction remarks"},"partnerReferenceNo":{"type":"string","maxLength":64,"description":"Your merchant reference"},"referenceNo":{"type":"string","maxLength":64,"description":"DOKU reference number"},"channel":{"type":"string","maxLength":64,"description":"Payment channel (e.g., VIRTUAL_ACCOUNT_BRI, CREDIT_CARD, BI_FAST, ONLINE, SAC_TRANSFER). May be empty for BRI VA top-ups and P2P transfers."}}},"ErrorResponse":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/transaction-history-list":{"post":{"operationId":"transactionHistory","tags":["Monitoring"],"summary":"Transaction History","description":"Retrieve a paginated list of transactions for a sub-account within a date range.\n\nUse this for reconciliation, generating statements, and compliance reporting.\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"$ref":"#/components/parameters/X-SIGNATURE"},{"$ref":"#/components/parameters/X-EXTERNAL-ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountNo","fromDateTime","toDateTime","pageSize","pageNumber"],"properties":{"accountNo":{"type":"string","maxLength":10,"description":"Sub-account number"},"fromDateTime":{"type":"string","maxLength":25,"description":"Start date in ISO 8601 format"},"toDateTime":{"type":"string","maxLength":25,"description":"End date in ISO 8601 format"},"pageSize":{"type":"string","maxLength":3,"description":"Items per page"},"pageNumber":{"type":"string","maxLength":3,"description":"Page number (starts from 0). Use 0 for the first page."}}}}}},"responses":{"200":{"description":"History retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128},"detailData":{"type":"array","items":{"$ref":"#/components/schemas/TransactionHistoryItem"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## 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).
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Debits","description":"Process debits and debit cancellations"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"},"X-SIGNATURE":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering."},"X-EXTERNAL-ID":{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"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."}},"schemas":{"Amount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Amount as a string with 2 decimal places (e.g., \"500000.00\")"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code"}}},"ErrorResponse":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/debit":{"post":{"operationId":"purchase","tags":["Debits"],"summary":"Debit","description":"Process a debit transaction on a sub-account.\n\nA webhook notification is sent to your callback URL when the transaction status updates (see Webhook: Debit below).\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"$ref":"#/components/parameters/X-SIGNATURE"},{"$ref":"#/components/parameters/X-EXTERNAL-ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["partnerReferenceNo","fromAccount","transactionType","amount"],"properties":{"partnerReferenceNo":{"type":"string","maxLength":64,"description":"Unique transaction identifier. Must be unique per request"},"fromAccount":{"type":"string","maxLength":10,"description":"Sub-account number to debit"},"transactionType":{"type":"string","maxLength":16,"description":"Transaction type for debit. Only PURCHASE is supported.","enum":["PURCHASE"]},"amount":{"$ref":"#/components/schemas/Amount"},"description":{"type":"string","maxLength":128,"description":"Transaction description"}}}}}},"responses":{"200":{"description":"Debit processed","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128},"partnerReferenceNo":{"type":"string","maxLength":64},"referenceNo":{"type":"string","maxLength":64},"transactionType":{"type":"string","maxLength":16},"fromAccount":{"type":"string","maxLength":10},"amount":{"$ref":"#/components/schemas/Amount"},"description":{"type":"string","maxLength":128},"latestTransactionStatus":{"type":"string","description":"00 = Success, 03 = Pending, 04 = Refunded, 06 = Failed"},"transactionStatusDesc":{"type":"string","maxLength":128},"transactionDate":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Duplicate partnerReferenceNo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## 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).
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Debits","description":"Process debits and debit cancellations"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"},"X-SIGNATURE":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Request signature generated using HMAC_SHA512(clientSecret, stringToSign). The stringToSign is constructed from request components to ensure integrity and prevent tampering."},"X-EXTERNAL-ID":{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"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."}},"schemas":{"Amount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Amount as a string with 2 decimal places (e.g., \"500000.00\")"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code"}}},"ErrorResponse":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/debit/cancel":{"post":{"operationId":"refundPurchase","tags":["Debits"],"summary":"Debit Cancel","description":"Process a full or partial cancellation for a previous debit transaction.\n\nReferences the original debit by `originalPartnerReferenceNo`. The cancellation amount can be equal to or less than the original debit amount.\n\nA webhook notification is sent to your callback URL when the debit cancellation is processed (see Webhook: Debit Cancel below).\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"$ref":"#/components/parameters/X-SIGNATURE"},{"$ref":"#/components/parameters/X-EXTERNAL-ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["partnerReferenceNo","originalPartnerReferenceNo","transactionType","refundAmount"],"properties":{"partnerReferenceNo":{"type":"string","maxLength":64,"description":"Unique identifier for this debit cancel request"},"originalPartnerReferenceNo":{"type":"string","maxLength":64,"description":"partnerReferenceNo from the original debit"},"originalReferenceNo":{"type":"string","maxLength":64,"description":"referenceNo from the original debit"},"transactionType":{"type":"string","maxLength":16,"description":"Use REFUND_PURCHASE for cancelling a debit transaction."},"refundAmount":{"$ref":"#/components/schemas/Amount"},"reason":{"type":"string","maxLength":128,"description":"Reason for the debit cancellation"}}}}}},"responses":{"200":{"description":"Debit cancellation processed","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128},"partnerReferenceNo":{"type":"string","maxLength":64},"originalPartnerReferenceNo":{"type":"string","maxLength":64},"originalReferenceNo":{"type":"string","maxLength":64},"transactionType":{"type":"string","maxLength":16},"refundNo":{"type":"string","maxLength":64,"description":"DOKU-assigned debit cancel number"},"refundAmount":{"$ref":"#/components/schemas/Amount"},"reason":{"type":"string","maxLength":128},"latestTransactionStatus":{"type":"string","description":"00 = Success, 03 = Pending, 04 = Refunded, 06 = Failed"},"transactionStatusDesc":{"type":"string","maxLength":128},"transactionDate":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Original transaction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Webhook: BRI VA Top-Up > 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
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Account Management","description":"Create and manage sub-accounts"},{"name":"Webhooks","description":"Callback specifications for notifications sent by DOKU to your registered URL"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"}},"schemas":{"Amount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Amount as a string with 2 decimal places (e.g., \"500000.00\")"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code"}}},"NotificationResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/topup/notification":{"post":{"operationId":"topupBrivaNotification","tags":["Account Management","Webhooks"],"summary":"Webhook: BRI VA Top-Up","description":"Webhook sent by DOKU when a BRI VA top-up payment is successful.\n\nEvery 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.\n\nDOKU sends this notification to your registered callback URL. Your system must respond with a `responseCode` and `responseMessage` to acknowledge receipt.\n\n**Key difference from Checkout/Direct API payments:**\n- BRI VA top-up → credited to `DOKU_MERCHANT_IDR` immediately (real-time)\n- Checkout/Direct API → credited to `DOKU_PENDING_IDR` first, then moves to `DOKU_MERCHANT_IDR` after settlement\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"HMAC_SHA512 signature for verification"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"referenceNo":{"type":"string","description":"DOKU-generated reference number for this top-up transaction"},"partnerReferenceNo":{"type":"string","description":"Partner reference number for this transaction"},"transactionType":{"type":"string","description":"Transaction type. Always TOPUP for BRI VA top-up callbacks."},"toAccount":{"type":"number","description":"The DOKU_MERCHANT_IDR account number that received the top-up funds"},"amount":{"$ref":"#/components/schemas/Amount"},"description":{"type":"string","description":"Description of the transaction"},"latestTransactionStatus":{"type":"string","description":"Transaction status: 00 = Success"},"transactionStatusDesc":{"type":"string","description":"Human-readable status description"},"partnerServiceId":{"type":"string","description":"Partner service identifier"},"customerNo":{"type":"string","description":"Customer number portion of the VA number"},"trxDateTime":{"type":"string","format":"date-time","description":"Transaction datetime in ISO 8601 format"},"virtualAccountNo":{"type":"string","description":"Full BRI VA number that was paid (prefix 1392495 + DOKU_MERCHANT_IDR account number)"},"virtualAccountName":{"type":"string","description":"Name registered to the virtual account (sub-account holder name)"},"trxId":{"type":"string","description":"Bank transaction ID from BRI"},"paymentRequestId":{"type":"string","description":"Payment request identifier"},"additionalInfo":{"type":"object","description":"Additional information about the payment channel","properties":{"channel":{"type":"string","description":"Payment channel. Always VIRTUAL_ACCOUNT_BRI for BRI VA top-ups."},"serviceCode":{"type":"string","description":"Service code for the transaction"}}}}}}}},"responses":{"200":{"description":"Notification acknowledged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationResponse"}}}}}}}}} ``` ## Webhook: Register Sub Account > 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
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Account Management","description":"Create and manage sub-accounts"},{"name":"Webhooks","description":"Callback specifications for notifications sent by DOKU to your registered URL"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"}},"schemas":{"AccountInfo":{"type":"object","properties":{"type":{"type":"string","maxLength":32,"description":"Account type: DOKU_MERCHANT_IDR (withdrawable IDR), DOKU_PENDING_IDR (held/reserved), DOKU_MERCHANT_POINT (non-cash points)"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code (IDR) or POINT for non-cash accounts"},"accountNo":{"type":"string","maxLength":10,"description":"Unique account number assigned by DOKU. Use this in transaction APIs (transfers, debits, balance inquiries)."}}},"NotificationResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/register/notification":{"post":{"operationId":"registerNotification","tags":["Account Management","Webhooks"],"summary":"Webhook: Register Sub Account","description":"Webhook sent by DOKU when a sub-account registration is complete.\n\nDOKU sends this notification to your registered callback URL. Your system must respond with a `responseCode` and `responseMessage` to acknowledge receipt.\n\n**Best practices:**\n- Respond quickly — return acknowledgment immediately, then process asynchronously\n- Be idempotent — you may receive the same notification more than once\n- Verify the `X-EXTERNAL-ID` signature to confirm authenticity\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"HMAC_SHA512 signature for verification"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"partnerReferenceNo":{"type":"string","description":"Your merchant reference number"},"parentProfileCode":{"type":"string","description":"Parent profile code"},"profileCode":{"type":"string","description":"New sub-account's profile code"},"referralCode":{"type":"string","description":"Assigned referral code"},"type":{"type":"string","description":"Sub-account type"},"email":{"type":"string","description":"Email address"},"name":{"type":"string","description":"Account holder name"},"status":{"type":"string","description":"Registration status"},"level":{"type":"string","description":"Account level in hierarchy"},"phoneNo":{"type":"string","description":"Phone number of the account holder"},"accounts":{"type":"array","description":"Created accounts","items":{"$ref":"#/components/schemas/AccountInfo"}}}}}}},"responses":{"200":{"description":"Notification acknowledged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationResponse"}}}}}}}}} ``` ## Webhook: Transfer Payment > Webhook sent by DOKU when a fund transfer status updates.\ > \ > Your system must respond with a \`responseCode\` and \`responseMessage\` to acknowledge receipt.
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Fund Transfers","description":"Validate and execute fund transfers"},{"name":"Webhooks","description":"Callback specifications for notifications sent by DOKU to your registered URL"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"}},"schemas":{"Amount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Amount as a string with 2 decimal places (e.g., \"500000.00\")"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code"}}},"NotificationResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/transfer/notification":{"post":{"operationId":"transferNotification","tags":["Fund Transfers","Webhooks"],"summary":"Webhook: Transfer Payment","description":"Webhook sent by DOKU when a fund transfer status updates.\n\nYour system must respond with a `responseCode` and `responseMessage` to acknowledge receipt.\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"HMAC_SHA512 signature for verification"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"referenceNo":{"type":"string","description":"DOKU reference number"},"partnerReferenceNo":{"type":"string","description":"Your merchant reference number"},"latestTransactionStatus":{"type":"string","description":"00 = Success, 03 = Pending, 06 = Failed"},"transactionStatusDesc":{"type":"string","description":"Status description"},"fromAccount":{"type":"string","description":"Source sub-account"},"amount":{"$ref":"#/components/schemas/Amount"}}}}}},"responses":{"200":{"description":"Notification acknowledged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationResponse"}}}}}}}}} ``` ## Webhook: Debit > Webhook sent by DOKU when a debit transaction status updates.\ > \ > Your system must respond with a \`responseCode\` and \`responseMessage\` to acknowledge receipt.
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Debits","description":"Process debits and debit cancellations"},{"name":"Webhooks","description":"Callback specifications for notifications sent by DOKU to your registered URL"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"}},"schemas":{"Amount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Amount as a string with 2 decimal places (e.g., \"500000.00\")"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code"}}},"NotificationResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/debit/notification":{"post":{"operationId":"purchaseNotification","tags":["Debits","Webhooks"],"summary":"Webhook: Debit","description":"Webhook sent by DOKU when a debit transaction status updates.\n\nYour system must respond with a `responseCode` and `responseMessage` to acknowledge receipt.\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"HMAC_SHA512 signature for verification"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"referenceNo":{"type":"string","description":"DOKU reference number"},"partnerReferenceNo":{"type":"string","description":"Your merchant reference number"},"transactionType":{"type":"string","description":"Merchant-defined transaction category matching the original request"},"fromAccount":{"type":"string","description":"Debited account"},"toAccount":{"type":"string","description":"Destination account"},"amount":{"$ref":"#/components/schemas/Amount"},"description":{"type":"string","description":"Transaction description"},"latestTransactionStatus":{"type":"string","description":"00 = Success, 03 = Pending, 06 = Failed"},"transactionStatusDesc":{"type":"string","description":"Status description"}}}}}},"responses":{"200":{"description":"Notification acknowledged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationResponse"}}}}}}}}} ``` ## Webhook: Debit Cancel > Webhook sent by DOKU when a debit cancellation is processed.\ > \ > Your system must respond with a \`responseCode\` and \`responseMessage\` to acknowledge receipt.
```json {"openapi":"3.0.3","info":{"title":"Sub-Account API","version":"2.0.0"},"tags":[{"name":"Debits","description":"Process debits and debit cancellations"},{"name":"Webhooks","description":"Callback specifications for notifications sent by DOKU to your registered URL"}],"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox"},{"url":"https://api.doku.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"B2B Token obtained from Get B2B Token API"}},"parameters":{"X-PARTNER-ID":{"name":"X-PARTNER-ID","in":"header","required":true,"schema":{"type":"string"},"description":"Your Partner ID (DOKU's Client ID)"},"X-TIMESTAMP":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Client's current local time in ISO 8601 format"}},"schemas":{"Amount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Amount as a string with 2 decimal places (e.g., \"500000.00\")"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code"}}},"NotificationResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","maxLength":7},"responseMessage":{"type":"string","maxLength":128}}}}},"paths":{"/sub-account/v2.0/debit/cancel/notification":{"post":{"operationId":"refundNotification","tags":["Debits","Webhooks"],"summary":"Webhook: Debit Cancel","description":"Webhook sent by DOKU when a debit cancellation is processed.\n\nYour system must respond with a `responseCode` and `responseMessage` to acknowledge receipt.\n","parameters":[{"$ref":"#/components/parameters/X-PARTNER-ID"},{"$ref":"#/components/parameters/X-TIMESTAMP"},{"name":"X-EXTERNAL-ID","in":"header","required":true,"schema":{"type":"string"},"description":"HMAC_SHA512 signature for verification"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"partnerReferenceNo":{"type":"string","description":"Your debit cancel reference number"},"originalReferenceNo":{"type":"string","description":"Original DOKU reference"},"originalPartnerReferenceNo":{"type":"string","description":"Original merchant reference"},"refundNo":{"type":"string","description":"DOKU-assigned debit cancel number"},"transactionType":{"type":"string","description":"Transaction type for debit cancellation"},"reason":{"type":"string","description":"Debit cancel reason"},"refundAmount":{"$ref":"#/components/schemas/Amount"},"refundTime":{"type":"string","format":"date-time","description":"Debit cancel timestamp"},"latestTransactionStatus":{"type":"string","description":"00 = Success, 03 = Pending, 06 = Failed"},"transactionStatusDesc":{"type":"string","description":"Status description"}}}}}},"responses":{"200":{"description":"Notification acknowledged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationResponse"}}}}}}}}} ```