CIMB Direct Debit

CIMB direct debit offers tokenization scheme that requires customer to input OTP and/or PIN to verify every payment.

Integration Steps

Overview of integration process with CIMB Direct Debit.

1. Account Binding

2. OTP Verification

3. Payment

4. Payment Notification

5. Additional Feature

---

1. Account Binding

Account Binding process should be done before payment can be made and processed. Merchant will send account binding request from customer to DOKU. The request includes customer's phone number that is registered to customer's CIMB account.

Each CIMB account can only be bind to one customer on one merchant. Customer needs to do verification for account binding process by inputting OTP and PIN.

Account Binding Flow

Account Binding Flow - CIMB Direct Debit

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/registration-account-binding

Sample of Request Header, Request Body and Response Body

Notes:

Parameter with (*) is mandatory

Paramater without (*) is optional/conditional

Register a merchant account for direct debit

POSThttps://{api-domain}/direct-debit/core/v1/registration-account-binding

Header parameters

Body

application/json

phoneNo*string

Phone Number Customer | Format: 628238748728423 | min length: 9 max length: 16 | Mandatory

Example: "628238748728423"

additionalInfo*AdditionalInfo (object)

Response

200

Successful

Body

application/json

responseCode*string

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: "2000700"

responseMessage*string

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

Example: "Successful"

referenceNostring

Reference Number

Example: "129260743966"

redirectUrl*string

Redirect URL to Merchant's page/platform for customer to input OTP/PIN

Example: "https://doku.com/direct-debit/ui/binding/2238230713001534401107183161486001168389"

additionalInfo*object

Request

JavaScriptCurlPython

const response = await fetch('https://{api-domain}/direct-debit/core/v1/registration-account-binding', {
    method: 'POST',
    headers: {
      "X-TIMESTAMP": "2020-12-21T07:56:11.000Z",
      "X-SIGNATURE": "85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5",
      "X-PARTNER-ID": "821508239190",
      "X-EXTERNAL-ID": "418075533589",
      "Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "phoneNo": "628238748728423",
      "additionalInfo": {
        "channel": "DIRECT_DEBIT_CIMB_SNAP",
        "custIdMerchant": "cust-001",
        "successRegistrationUrl": "https://merchant.doku.com/success",
        "failedRegistrationUrl": "https://www.merchant.com/failed"
      }
    }),
});
const data = await response.json();

Response

200

{
  "responseCode": "2000700",
  "responseMessage": "Successful",
  "referenceNo": "129260743966",
  "redirectUrl": "https://doku.com/direct-debit/ui/binding/2238230713001534401107183161486001168389",
  "additionalInfo": {
    "custIdMerchant": 12345679504,
    "status": "PENDING",
    "authCode": 2.23823090518282e+39
  }
}

2. Payment

After customer's account is bind/linked and customer has enough balance for payment, merchant can send payment request from customer to DOKU by bringing customer's token.

Payment Flow

Payment Flow - CIMB Direct Debit

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 From Merchant for Direct Debit CIMB

POSThttps://{api-domain}/direct-debit/core/v1/debit/payment-host-to-host

Header parameters

Body

application/json

partnerReferenceNo*string

Reference No From Partner | max: 12 | Mandatory

Example: "INV-0001"

amount*AmountObject (object)

additionalInfo*object

Response

200

Successful

Body

application/json

responseCode*string

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"

responseMessage*string

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

Example: "Successful"

webRedirectUrlstring

Redirect URL to Merchant's page/platform for customer to input OTP/PIN

Example: "https://app-uat.doku.com/link/283702597342040"

partnerReferenceNostring

Reference No From Partner

Example: "INV-0001"

Request

JavaScriptCurlPython

const response = await fetch('https://{api-domain}/direct-debit/core/v1/debit/payment-host-to-host', {
    method: 'POST',
    headers: {
      "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"
    },
    body: JSON.stringify({
      "partnerReferenceNo": "INV-0001",
      "amount": {
        "value": "10000.00",
        "currency": "IDR"
      },
      "additionalInfo": {
        "channel": "DIRECT_DEBIT_CIMB_SNAP",
        "successPaymentUrl": "www.merchant.com/success",
        "failedPaymentUrl": "www.merchant.com/failed",
        "remarks": "Remarks"
      }
    }),
});
const data = await response.json();

Response

200

{
  "responseCode": "2005400",
  "responseMessage": "Successful",
  "webRedirectUrl": "https://app-uat.doku.com/link/283702597342040",
  "partnerReferenceNo": "INV-0001"
}

3. OTP Verification

Once customer has submitted their payment request along with the OTP, merchant needs to verify the payment. Merchant can hit this API to verify the OTP.

OTP Verification Flow

OTP Verification Flow - CIMB Direct Debit

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/otp-verification

Sample of Request Header, Request Body and Response Body

Notes:

Parameter with (*) is mandatory

Paramater without (*) is optional/conditional

OTP Verification for Payment CIMB

POSThttps://{api-domain}/direct-debit/core/v1/otp-verification

Header parameters

Body

application/json

originalPartnerReferenceNo*string

Partner Reference No Payment | max: 36 | Mandatory

Example: "INV-0001"

otp*string

OTP sent to customer | min: 6 max: 6 | Mandatory

Example: "111000"

action*string

Value should always be otpPayment | Mandatory

Example: "otpPayment"

additionalInfoobject

Response

200

Successful

Body

application/json

responseCode*string

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: 2000400

responseMessage*string

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

Example: "Successful"

originalReferenceNostring

Reference no from acquirer

Example: "GuJNX01wKYMdEGNUJ1k"

Request

JavaScriptCurlPython

const response = await fetch('https://{api-domain}/direct-debit/core/v1/otp-verification', {
    method: 'POST',
    headers: {
      "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"
    },
    body: JSON.stringify({
      "originalPartnerReferenceNo": "INV-0001",
      "otp": "111000",
      "action": "otpPayment"
    }),
});
const data = await response.json();

Response

200

{
  "responseCode": 2000400,
  "responseMessage": "Successful",
  "originalReferenceNo": "GuJNX01wKYMdEGNUJ1k"
}

4. Payment Notification

After payment is completed, DOKU will send HTTP Notification to merchant's defined Notification URL. Learn how to handle the notification from DOKU.

5. Additional Feature

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

Online Refund Flow - CIMB Direct Debit

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

POSThttps://{api-domain}/direct-debit/core/v1/debit/refund

Header parameters

Body

application/json

additionalInfoobject

originalPartnerReferenceNo*string

Partner Reference No Purchase Transaction | max: 12 | Mandatory

Example: "INV-0001"

originalExternalIdstring

External ID Purchase Transaction | max: 36 |

Example: "REQ-0001"

refundAmount*AmountObject (object)

reasonstring

Reason from customer | max: 255

Example: "Request by Customer"

partnerRefundNo*string

Partner Refund No| max: 12 | Mandatory

Example: "INV-REF-0001"

Response

200

Successful

Body

application/json

responseCode*string

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: "2000700"

responseMessage*string

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

Example: "Successful"

refundAmount*AmountObject (object)

originalPartnerReferenceNostring

Partner Reference No Purchase Transaction

Example: "Ra7o1bLJAh2oV9eb33129stQc5xFm5s7"

originalReferenceNostring

Reference No Purchase Transaction From DOKU To CIMB

Example: "Ra7o1bLJAh2oV9eb33129stQc5xFm5s7"

refundNostring

Refund No from DOKU To CIMB

Example: "Ra7o1bLJAh2oV9eb33129stQc5xFm5s7"

partnerRefundNostring

Partner Refund No

Example: "Ra7o1bLJAh2oV9eb33129stQc5xFm5s7"

refundTimestring

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

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

Request

JavaScriptCurlPython

const response = await fetch('https://{api-domain}/direct-debit/core/v1/debit/refund', {
    method: 'POST',
    headers: {
      "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"
    },
    body: JSON.stringify({
      "originalPartnerReferenceNo": "INV-0001",
      "refundAmount": {
        "value": "10000.00",
        "currency": "IDR"
      },
      "partnerRefundNo": "INV-REF-0001"
    }),
});
const data = await response.json();

Response

200

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

Account Unbinding

If a registered customer no longer wants their account/card to be bind/linked and wish to remove themself from DOKU's and merchant’s system, merchant can send account unbinding request that is initiated by customer.

API Endpoint

Environment	Endpoint
HTTP Method	POST
API Sandbox	https://api-sandbox.doku.com
API Production	https://api.doku.com
Path	.../direct-debit/v1/registration-account-unbinding

Sample of Request Header, Request Body and Response Body

Notes:

Parameter with (*) is mandatory

Paramater without (*) is optional/conditional

Unbinding process from Merchant

POSThttps://{api-domain}/direct-debit/core/v1/registration-account-unbinding

Header parameters

Body

application/json

tokenIdstring

format: Value from getTokenB2B2C | max: 2048 | Mandatory

Example: "eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTg4MjI3NTQsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjAyLTE2OTAyNzUzNTM3OTgiLCJhY2NvdW50SWQiOiJjZTBhZWIyM2YyMmZhOTgxZWViNTE1MjFmZmNkYmUzNyJ9.QZ2z0p2PoCYbuBSId7LleLqTUwNyNIeM1PUSaV4DwGKO05l7xQ3EbpdAPK62hxKNcczKqQqGY2Om6rzS78s2Tj88dkDD2vl46o3xEPd_plqQW8ayFqS74Z_HcFJfdo-egqFv9rAX7qgiE5AJHSx_hFolET9B3o3Jx82lmQutnXOjYb5gW9PV0FCPIZRWOaXppOSJSVcmTvXZxF0KUID9-2QVmQ5aPZroHjShYJKGyUu-1tCPClD_CbZMCi3TxhKLnI3e2oIoK7VjXEsrJjuil8O1zZTT7_aXAGgTu5UcPCrc0U9_3Nj-wQlEjDpedMVypKAWATWBUVpMo2MAsBRDAw"

additionalInfoobject

Response

200

Successful

Body

application/json

responseCode*string

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: "2000500"

responseMessage*string

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

Example: "Successful"

referenceNostring

Reference Number

Example: "UNB-0001"

Request

JavaScriptCurlPython

const response = await fetch('https://{api-domain}/direct-debit/core/v1/registration-account-unbinding', {
    method: 'POST',
    headers: {
      "X-TIMESTAMP": "2020-12-21T07:56:11.000Z",
      "X-SIGNATURE": "85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5",
      "X-PARTNER-ID": "821508239190",
      "X-EXTERNAL-ID": "418075533589",
      "Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "responseCode": "2000500",
  "responseMessage": "Successful",
  "referenceNo": "UNB-0001"
}