Host to Host Integration

Integration Steps

Overview of integration process with KKI Integration

1. Payment

Merchant can request for payment by requesting this API

Payment Flow

API Endpoint

Environment

Endpoint

HTTP Method

POST

API Sandbox

https://api-sandbox.doku.com

API Production

https://api.doku.com

Path

.../direct-debit/core/v1/debit/payment-host-to-host

Sample of Request Header, Request Body and Response Body

Notes:

Parameter with (*) is mandatory

Paramater without (*) is optional/conditional

Request Payment with CPAN without Tokenization From Merchant for KKI

post

Header parameters

X-TIMESTAMPstring · utc timestampRequired

Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format

Example: 2020-12-21T07:56:11.000Z

X-SIGNATUREstringRequired

Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)

Example: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

X-PARTNER-IDstringRequired

Unique ID for a partner (DOKU'S Client ID)

Example: 821508239190

X-EXTERNAL-IDstringRequired

Numeric String. Reference number that should be unique in the same day (request-id)

Example: 418075533589

Authorization-customerstringRequired

Access token obtained from B2B2C API

Example: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a

AuthorizationstringRequired

Access Token obtained from Get B2B Token API

Example:

Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ

Body

partnerReferenceNostringRequired

Reference No From Partner | max: 32 | Optional

Example: INV-0001

bankCardTokenstringOptional

Token From DOKU | max: 64 | Conditional if merchant customer already has token from DOKU

Example: de52e5820f4c381db88a1cf91d57b73e

chargeTokenstringRequired

Customer CPAN | max: 20 | Optional

Example: 9360001609987000000

otpstringRequired

Customer OTP | min: 8 max: 8 | Optional

Example: 12345678

Responses

200

Successful

application/json

responseCodestringRequired

Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/response-code/http-status-and-case-code#id-4.-direct-debit | Mandatory | min length: 1 | max length: 7.

Example: 2005400

responseMessagestringRequired

Response Description. | min length: 1 | max length: 150

Example: Successful

referenceNostringOptional

DOKU Reference No

Example: REF-DOKU-0001

post

/direct-debit/core/v1/debit/payment-host-to-host

POST /direct-debit/core/v1/debit/payment-host-to-host HTTP/1.1
Host: {api-domain}
X-TIMESTAMP: 2020-12-21T07:56:11.000Z
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
X-PARTNER-ID: 821508239190
X-EXTERNAL-ID: 418075533589
Authorization-customer: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ
Content-Type: application/json
Accept: */*
Content-Length: 410

{
  "partnerReferenceNo": "INV-0001",
  "bankCardToken": "de52e5820f4c381db88a1cf91d57b73e",
  "chargeToken": 9360001609987000000,
  "otp": 12345678,
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "additionalInfo": {
    "channel": "KARTU_KREDIT_INDONESIA",
    "isBindAndPay": "N",
    "paymentType": "RECURRING",
    "customer": {
      "customerId": "CUST-001",
      "customerName": "DOKU Merchant"
    },
    "lineItems": [
      {
        "name": "masker",
        "price": "5000.00",
        "quantity": 1
      }
    ]
  }
}

200

Successful

{
  "responseCode": "2005400",
  "responseMessage": "Successful",
  "referenceNo": "REF-DOKU-0001"
}

Request Payment and Tokenization From Merchant for KKI

post

Header parameters

X-TIMESTAMPstring · utc timestampRequired

Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format

Example: 2020-12-21T07:56:11.000Z

X-SIGNATUREstringRequired

Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)

Example: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

X-PARTNER-IDstringRequired

Unique ID for a partner (DOKU'S Client ID)

Example: 821508239190

X-EXTERNAL-IDstringRequired

Numeric String. Reference number that should be unique in the same day (request-id)

Example: 418075533589

Authorization-customerstringRequired

Access token obtained from B2B2C API

Example: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a

AuthorizationstringRequired

Access Token obtained from Get B2B Token API

Example:

Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ

Body

partnerReferenceNostringRequired

Reference No From Partner | max: 32 | Optional

Example: INV-0001

bankCardTokenstringOptional

Token From DOKU | max: 64 | Conditional if merchant customer already has token from DOKU

Example: de52e5820f4c381db88a1cf91d57b73e

chargeTokenstringRequired

Customer CPAN | max: 20 | Optional

Example: 9360001609987000000

otpstringRequired

Customer OTP | min: 8 max: 8 | Optional

Example: 12345678

Responses

200

Successful

application/json

responseCodestringRequired

Example: 2005400

responseMessagestringRequired

Response Description. | min length: 1 | max length: 150

Example: Successful

referenceNostringOptional

DOKU Reference No

Example: REF-DOKU-0001

post

/direct-debit/core/v1/debit/payment-host-to-host

POST /direct-debit/core/v1/debit/payment-host-to-host HTTP/1.1
Host: {api-domain}
X-TIMESTAMP: 2020-12-21T07:56:11.000Z
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
X-PARTNER-ID: 821508239190
X-EXTERNAL-ID: 418075533589
Authorization-customer: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ
Content-Type: application/json
Accept: */*
Content-Length: 405

{
  "partnerReferenceNo": "INV-0001",
  "bankCardToken": "de52e5820f4c381db88a1cf91d57b73e",
  "chargeToken": 9360001609987000000,
  "otp": 12345678,
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "additionalInfo": {
    "channel": "KARTU_KREDIT_INDONESIA",
    "isBindAndPay": "Y",
    "paymentType": "SALE",
    "customer": {
      "customerId": "CUST-001",
      "customerName": "DOKU Merchant"
    },
    "lineItems": [
      {
        "name": "masker",
        "price": "5000.00",
        "quantity": 1
      }
    ]
  }
}

200

Successful

{
  "responseCode": "2005400",
  "responseMessage": "Successful",
  "referenceNo": "REF-DOKU-0001"
}

Request Payment with Token From Merchant for KKI

post

Header parameters

X-TIMESTAMPstring · utc timestampRequired

Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format

Example: 2020-12-21T07:56:11.000Z

X-SIGNATUREstringRequired

Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)

Example: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

X-PARTNER-IDstringRequired

Unique ID for a partner (DOKU'S Client ID)

Example: 821508239190

X-EXTERNAL-IDstringRequired

Numeric String. Reference number that should be unique in the same day (request-id)

Example: 418075533589

Authorization-customerstringRequired

Access token obtained from B2B2C API

Example: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a

AuthorizationstringRequired

Access Token obtained from Get B2B Token API

Example:

Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ

Body

partnerReferenceNostringRequired

Reference No From Partner | max: 32 | Optional

Example: INV-0001

bankCardTokenstringRequired

Token From DOKU | max: 64 | Conditional if merchant customer already has token from DOKU

Example: de52e5820f4c381db88a1cf91d57b73e

chargeTokenstringOptional

Customer CPAN | max: 20 | Optional

Example: 9360001609987000000

otpstringOptional

Customer OTP | min: 8 max: 8 | Optional

Example: 12345678

Responses

200

Successful

application/json

responseCodestringRequired

Example: 2005400

responseMessagestringRequired

Response Description. | min length: 1 | max length: 150

Example: Successful

referenceNostringOptional

DOKU Reference No

Example: REF-DOKU-0001

post

/direct-debit/core/v1/debit/payment-host-to-host

POST /direct-debit/core/v1/debit/payment-host-to-host HTTP/1.1
Host: {api-domain}
X-TIMESTAMP: 2020-12-21T07:56:11.000Z
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
X-PARTNER-ID: 821508239190
X-EXTERNAL-ID: 418075533589
Authorization-customer: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ
Content-Type: application/json
Accept: */*
Content-Length: 405

{
  "partnerReferenceNo": "INV-0001",
  "bankCardToken": "de52e5820f4c381db88a1cf91d57b73e",
  "chargeToken": 9360001609987000000,
  "otp": 12345678,
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "additionalInfo": {
    "channel": "KARTU_KREDIT_INDONESIA",
    "isBindAndPay": "N",
    "paymentType": "SALE",
    "customer": {
      "customerId": "CUST-001",
      "customerName": "DOKU Merchant"
    },
    "lineItems": [
      {
        "name": "masker",
        "price": "5000.00",
        "quantity": 1
      }
    ]
  }
}

200

Successful

{
  "responseCode": "2005400",
  "responseMessage": "Successful",
  "referenceNo": "REF-DOKU-0001"
}

Request Payment Recurring with Token From Merchant for KKI

post

Header parameters

X-TIMESTAMPstring · utc timestampRequired

Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format

Example: 2020-12-21T07:56:11.000Z

X-SIGNATUREstringRequired

Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)

Example: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

X-PARTNER-IDstringRequired

Unique ID for a partner (DOKU'S Client ID)

Example: 821508239190

X-EXTERNAL-IDstringRequired

Numeric String. Reference number that should be unique in the same day (request-id)

Example: 418075533589

Authorization-customerstringRequired

Access token obtained from B2B2C API

Example: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a

AuthorizationstringRequired

Access Token obtained from Get B2B Token API

Example:

Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ

Body

partnerReferenceNostringRequired

Reference No From Partner | max: 32 | Optional

Example: INV-0001

bankCardTokenstringRequired

Token From DOKU | max: 64 | Conditional if merchant customer already has token from DOKU

Example: de52e5820f4c381db88a1cf91d57b73e

chargeTokenstringOptional

Customer CPAN | max: 20 | Optional

Example: 9360001609987000000

otpstringOptional

Customer OTP | min: 8 max: 8 | Optional

Example: 12345678

Responses

200

Successful

application/json

responseCodestringRequired

Example: 2005400

responseMessagestringRequired

Response Description. | min length: 1 | max length: 150

Example: Successful

referenceNostringOptional

DOKU Reference No

Example: REF-DOKU-0001

post

/direct-debit/core/v1/debit/payment-host-to-host

POST /direct-debit/core/v1/debit/payment-host-to-host HTTP/1.1
Host: {api-domain}
X-TIMESTAMP: 2020-12-21T07:56:11.000Z
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
X-PARTNER-ID: 821508239190
X-EXTERNAL-ID: 418075533589
Authorization-customer: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ
Content-Type: application/json
Accept: */*
Content-Length: 410

{
  "partnerReferenceNo": "INV-0001",
  "bankCardToken": "de52e5820f4c381db88a1cf91d57b73e",
  "chargeToken": 9360001609987000000,
  "otp": 12345678,
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "additionalInfo": {
    "channel": "KARTU_KREDIT_INDONESIA",
    "isBindAndPay": "N",
    "paymentType": "RECURRING",
    "customer": {
      "customerId": "CUST-001",
      "customerName": "DOKU Merchant"
    },
    "lineItems": [
      {
        "name": "masker",
        "price": "5000.00",
        "quantity": 1
      }
    ]
  }
}

200

Successful

{
  "responseCode": "2005400",
  "responseMessage": "Successful",
  "referenceNo": "REF-DOKU-0001"
}

2. Binding

This endpoint is used to tokenize a customer's CPAN without charging any amount, compared to the payment with Tokenization API which need to charges some amount to the Customer.

Card Binding (Card Registration)

post

Registers a credit card for a customer under a merchant account.

Flow:

Merchant submits the encrypted card data along with customer information.
The system decrypts the card data, validates it against the ALTO/KKI network, and creates an AcquirerToken.
On success, a redirectUrl is returned (when CHANNEL-ID: DH) pointing to the OTP verification page.
The customer completes OTP verification, which finalises the binding and issues a bankCardToken.

Card Data Encryption: Encrypt the CardDataPayload JSON object using AES-CBC with the merchant's sharedKey. The resulting Base64-encoded ciphertext is submitted as the cardData field.

Authorizations

AuthorizationstringRequired

B2B access token obtained from the Get B2B Token API (/authorization/v1/access-token/b2b)

Header parameters

X-PARTNER-IDstring · max: 32Required

Merchant's client ID registered with DOKU

Example: merchant-client-id-001

X-EXTERNAL-IDstring · max: 36Required

Unique reference ID for this request (per-day uniqueness required). Used for idempotency and tracing.

Example: ext-bind-20260526-00001

AuthorizationstringRequired

B2B access token obtained from the Get B2B Token API

Example: Bearer eyJhbGciOiJSUzI1NiJ9...

X-TIMESTAMPstringRequired

Request timestamp in ISO 8601 format (yyyy-MM-ddTHH:mm:ss+07:00)

Example: 2026-05-26T10:00:00+07:00Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[+\-]\d{2}:\d{2}$

X-SIGNATUREstringRequired

HMAC-SHA512 asymmetric signature for request integrity verification

Example: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

CHANNEL-IDstring · enumOptional

Channel identifier determining the post-registration redirect behaviour.

DH (Direct Hosting, default): returns a redirectUrl pointing to the DOKU-hosted OTP page.
H2H (Host-to-Host): no redirect; merchant handles the OTP flow independently.

Default: DHExample: DHPossible values:

Body

Request body for card binding (registration)

partnerReferenceNostring · max: 64Optional

Merchant's unique reference number for this binding request

Example: BIND-REF-20260526-001

cardDatastringRequired

AES-CBC encrypted JSON of the card data, Base64-encoded. Encrypt the CardDataPayload object using the merchant's sharedKey provided by DOKU. See the CardDataPayload schema for the plaintext structure.

Example: U2FsdGVkX1+A1B2C3D4E5F6G7H8I9J0K...

custIdMerchantstring · max: 64Required

Merchant's unique identifier for the customer

Example: CUST001Pattern: ^[a-zA-Z0-9]+$

journeyIdstringOptional

Optional journey or session ID for tracking the binding flow end-to-end

Example: journey-bind-20260526-001

phoneNostringOptional

Customer's phone number (used for OTP delivery during OTP verification step)

Example: 08123456789

Responses

200

Card binding request accepted. The customer must complete OTP verification to finalise the binding. Use redirectUrl (DH flow) or additionalInfo.authCode (H2H flow) to proceed.

application/json

Response body for a successful card binding request

responseCodestringOptional

Response code: HTTP Status (3) + Service Code 01 (2) + Case Code (2). Example: 2000100 = HTTP 200 + service 01 + case 00 (Successful).

Example: 2000100

responseMessagestringOptional

Human-readable response message

Example: Successful

referenceNostringOptional

DOKU-generated reference number for this binding request

Example: REF-KKI-20260526-001

redirectUrlstringOptional

URL for OTP verification page hosted by DOKU. Only present when CHANNEL-ID: DH. Merchant must redirect the customer here to complete the binding via OTP entry.

Example: https://app.doku.com/direct-debit/kki/binding/SESSION-ABC123

bankCardTokenstringOptional

Reusable token representing the bound credit card. Present only after OTP verification is successfully completed (final binding state). Use this token for subsequent payment requests.

Example: eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UifQ...

chargeTokenstringOptional

Charge token from the ALTO network (from the decrypted card data), if applicable

Example: CHG-TOKEN-ABC123

202

Request in progress (timeout from ALTO network; may still succeed asynchronously)

application/json

400

Bad request — missing or invalid fields

application/json

401

Authentication failure — invalid token or card data decryption failed

application/json

403

Forbidden — transaction not permitted or card restrictions

application/json

404

Not found — merchant, card, or transaction record not found

application/json

409

Conflict — duplicate transaction or duplicate token

application/json

500

Internal server error or external system malfunction

application/json

post

/direct-debit/core/v1/registration-card-bind

POST /direct-debit/core/v1/registration-card-bind HTTP/1.1
Host: api.doku.com
Authorization: text
X-PARTNER-ID: text
X-EXTERNAL-ID: text
X-TIMESTAMP: text
X-SIGNATURE: text
Content-Type: application/json
Accept: */*
Content-Length: 504

{
  "partnerReferenceNo": "BIND-REF-20260526-001",
  "cardData": "U2FsdGVkX1+A1B2C3D4E5F6G7H8I9J0K...",
  "custIdMerchant": "CUST001",
  "journeyId": "journey-bind-20260526-001",
  "phoneNo": "08123456789",
  "additionalInfo": {
    "channel": "KARTU_KREDIT_INDONESIA",
    "customerName": "John Doe",
    "email": "john.doe@example.com",
    "address": "Jl. Sudirman No. 1, Jakarta",
    "dateOfBirth": "19900101",
    "successRegistrationUrl": "https://merchant.example.com/binding/success",
    "failedRegistrationUrl": "https://merchant.example.com/binding/failed"
  }
}

{
  "responseCode": "2000100",
  "responseMessage": "Successful",
  "referenceNo": "REF-KKI-20260526-001",
  "redirectUrl": "https://app.doku.com/direct-debit/kki/binding/SESSION-ABC123",
  "additionalInfo": {
    "custIdMerchant": "CUST001",
    "status": "PENDING",
    "authCode": "SESSION-ABC123"
  }
}

3. Unbinding

This endpoint is used to unbind a previously binded token compared to the payment with Tokenization API which need to charges some amount to the Customer.

Card Unbinding

post

Deactivates a previously bound credit card token for a customer under a merchant account.

Flow:

Merchant submits the tokenId (i.e., the bankCardToken from the binding response).
The system locates all active tokens for the card and marks them as PENDING for deactivation.
The unbinding is finalised asynchronously via the ALTO/KKI network.
A Kafka event is published for downstream systems.

The tokenId is the raw token value for KKI (not Base64-decoded, unlike other channels).

Authorizations

AuthorizationstringRequired

B2B access token obtained from the Get B2B Token API (/authorization/v1/access-token/b2b)

Header parameters

X-PARTNER-IDstring · max: 32Required

Merchant's client ID registered with DOKU

Example: merchant-client-id-001

X-EXTERNAL-IDstring · max: 36Required

Unique reference ID for this request (per-day uniqueness required)

Example: ext-unbind-20260526-00001

AuthorizationstringRequired

B2B access token obtained from the Get B2B Token API

Example: Bearer eyJhbGciOiJSUzI1NiJ9...

X-TIMESTAMPstringRequired

Request timestamp in ISO 8601 format (yyyy-MM-ddTHH:mm:ss+07:00)

Example: 2026-05-26T10:05:00+07:00Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[+\-]\d{2}:\d{2}$

X-SIGNATUREstringRequired

HMAC-SHA512 asymmetric signature for request integrity verification

Example: a1b2c3d4e5f6...

X-IP-ADDRESSstringOptional

IP address of the end customer's device

Example: 103.31.4.0

CHANNEL-IDstring · enumOptional

Channel identifier. Defaults to DH (Direct Hosting).

DH: may return a redirectUrl for redirect-based unbinding flows.
H2H: host-to-host; returns a plain success response without redirect.

Default: DHExample: DHPossible values:

Body

Request body for card unbinding

tokenIdstringRequired

The token to be deactivated. This is the bankCardToken value returned in the binding response (or from the token list). For KKI, this value is used as-is (no Base64 decoding is applied).

Example: TOKEN-KKI-ABC123XYZ

Responses

200

Unbinding request accepted. The token is now in PENDING deactivation state. Final deactivation is completed asynchronously via the ALTO/KKI network.

application/json

Response body for a successful card unbinding request

responseCodestringOptional

Response code: HTTP Status (3) + Service Code 05 (2) + Case Code (2). Example: 2000500 = HTTP 200 + service 05 + case 00 (Successful).

Example: 2000500

responseMessagestringOptional

Human-readable response message

Example: Successful

referenceNostringOptional

DOKU-generated reference number for this unbinding request

Example: REF-UNBIND-20260526-001

400

Bad request — missing or invalid fields

application/json

401

Authentication failure — invalid B2B token or token not found

application/json

403

Forbidden — transaction not permitted for the given card/account

application/json

404

Not found — active token not found for the given merchant and token ID

application/json

500

Internal server error

application/json

post

/direct-debit/core/v1/registration-card-unbind

POST /direct-debit/core/v1/registration-card-unbind HTTP/1.1
Host: api.doku.com
Authorization: text
X-PARTNER-ID: text
X-EXTERNAL-ID: text
X-TIMESTAMP: text
X-SIGNATURE: text
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "tokenId": "TOKEN-KKI-ABC123XYZ",
  "additionalInfo": {
    "channelId": "KARTU_KREDIT_INDONESIA"
  }
}

{
  "responseCode": "2000500",
  "responseMessage": "Successful",
  "referenceNo": "REF-UNBIND-20260526-001",
  "additionalInfo": {
    "custIdMerchant": "CUST001",
    "status": "PENDING"
  }
}

4. Refund

Online Refund

This endpoint is used to create refund request for previous successful payment. Merchant can request a transaction refund to DOKU. Full refund and partial refund are available to be requested

Online Refund Flow

API Endpoint

Environment

Endpoint

HTTP Method

POST

API Sandbox

https://api-sandbox.doku.com

API Production

https://api.doku.com

Path

.../direct-debit/core/v1/debit/refund

Sample of Request Header, Request Body and Response Body

Notes:

Parameter with (*) is mandatory

Paramater without (*) is optional/conditional

Request Refund From Merchant for Direct Debit Transaction

post

Header parameters

X-TIMESTAMPstring · utc timestampRequired

Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format

Example: 2020-12-21T07:56:11.000Z

X-SIGNATUREstringRequired

Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)

Example: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

X-PARTNER-IDstringRequired

Unique ID for a partner (DOKU'S Client ID)

Example: 821508239190

X-EXTERNAL-IDstringRequired

Numeric String. Reference number that should be unique in the same day (request-id)

Example: 418075533589

X-IP-ADDRESSstringRequired

IP Address Customer | min: 10 max: 15 | Mandatory

Example: 192.168.1.1

Authorization-customerstringRequired

Access token obtained from B2B2C API

Example: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a

AuthorizationstringRequired

Access Token obtained from Get B2B Token API

Example:

Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ

Body

originalPartnerReferenceNostringRequired

Reference No From Partner | AlphaNumeric | min: 32 max: 64 | Mandatory

Example: INV0001

originalExternalIdstringOptional

External ID Purchase Transaction | max: 36 |

Example: REQ-0001

reasonstringOptional

Reason from customer | max: 255

Example: Request by Customer

partnerRefundNostringRequired

Partner Refund No| max: 12 | Mandatory

Example: INV-REF-0001

Responses

200

Successful

application/json

responseCodestringRequired

Example: 2000700

responseMessagestringRequired

Response Description. | min length: 1 | max length: 150

Example: Successful

originalPartnerReferenceNostringOptional

Partner Reference No Purchase Transaction

Example: Ra7o1bLJAh2oV9eb33129stQc5xFm5s7

originalReferenceNostringOptional

Reference No Purchase Transaction From DOKU To Allo

Example: Ra7o1bLJAh2oV9eb33129stQc5xFm5s7

refundNostringOptional

Refund No from DOKU To Allo

Example: Ra7o1bLJAh2oV9eb33129stQc5xFm5s7

partnerRefundNostringOptional

Partner Refund No

Example: Ra7o1bLJAh2oV9eb33129stQc5xFm5s7

refundTimestringOptional

format: yyyy-MM-dd'T'HH:mm:ssXXX

Example: 2024-01-01T09:09:00.123

post

/direct-debit/core/v1/debit/refund

POST /direct-debit/core/v1/debit/refund HTTP/1.1
Host: {api-domain}
X-TIMESTAMP: 2020-12-21T07:56:11.000Z
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
X-PARTNER-ID: 821508239190
X-EXTERNAL-ID: 418075533589
X-IP-ADDRESS: 192.168.1.1
Authorization-customer: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ
Content-Type: application/json
Accept: */*
Content-Length: 243

{
  "additionalInfo": {
    "channel": "DIRECT_DEBIT_ALLO_SNAP"
  },
  "originalPartnerReferenceNo": "INV0001",
  "originalExternalId": "REQ-0001",
  "refundAmount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "reason": "Request by Customer",
  "partnerRefundNo": "INV-REF-0001"
}

200

Successful

{
  "responseCode": "2000700",
  "responseMessage": "Successful",
  "refundAmount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "originalPartnerReferenceNo": "Ra7o1bLJAh2oV9eb33129stQc5xFm5s7",
  "originalReferenceNo": "Ra7o1bLJAh2oV9eb33129stQc5xFm5s7",
  "refundNo": "Ra7o1bLJAh2oV9eb33129stQc5xFm5s7",
  "partnerRefundNo": "Ra7o1bLJAh2oV9eb33129stQc5xFm5s7",
  "refundTime": "2024-01-01T09:09:00.123"
}

PreviousKartu Kredit Indonesia Cepat Secure(KKI CPTS)NextQRIS

Last updated 15 days ago