CIMB Direct Debit

Integration Steps

Here is the overview of how to integrate with CIMB Direct Debit ::

Account Binding

Merchant can binding CIMB account to customer id, each account can only binding to one customer on one merchant. Customer need to verify OTP and input PIN on CIMB page.

Here is the flow for Account Binding :

API Endpoint

Environment

Endpoint

HTTP Method

POST

API Sandbox

https://api-sandbox.doku.com

API Production

https://api.doku.com

Path

/direct-debit/allo/v1.0/registration-account-binding

Here is the sample request header, request body and response body for Account Binding - CIMB

Register a merchant account for direct debit

post

Authorizations

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-DEVICE-IDstringRequired

Device identification on which the API services are currently being accessed by the end user (customer). Can’t contain symbols

Example: 95221

X-IP-ADDRESSstringOptional

conditional. IP address of the end user (customer) using IPv4 format

Example: 95221

AuthorizationstringRequired

Access Token obtained from Get B2B Token API

Example: 95221

Body

phoneNostringRequired

Account phone number | min length: 9 | max length: 16

Example: 62857957868761

Responses

200

Successful registration

application/json

400

Invalid Field Format

application/json

401

Invalid Token (B2B)

application/json

post

/direct-debit/merchant/cimb/v1.0/registration-account-binding

POST /direct-debit/merchant/cimb/v1.0/registration-account-binding 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-DEVICE-ID: 95221
Authorization: 95221
Content-Type: application/json
Accept: */*
Content-Length: 332

{
  "phoneNo": "62857957868761",
  "additionalInfo": {
    "custIdMerchant": "TEST-123",
    "customerName": "John Doe",
    "email": "[email protected]",
    "idCard": "12345",
    "country": "Indonesia",
    "address": "Bali",
    "dateOfBirth": "19990101",
    "successRegistrationUrl": "https://sandbox.doku.com/bo/login/",
    "failedRegistrationUrl": "https://www.seleniumeasy.com/test"
  }
}

{
  "responseCode": "2000700",
  "responseMessage": "Successful",
  "referenceNo": "129260743966",
  "redirectUrl": "https://sandbox.doku.com/direct-debit/ui/binding/2238230713001534401107183161486001168389",
  "additionalInfo": {
    "custIdMerchant": "CUSTOMER_CIMBxDOKU",
    "accountStatus": "PENDING",
    "authCode": "1234123412341234"
  }
}

OTP Verification

Once a customer has linked their account through the CIMB platform, merchants needs to verify the account. Merchant can hit this API to verify the OTP :

Here is the flow for OTP Verification :

API Endpoint

Environment

Endpoint

HTTP Method

POST

API Sandbox

https://api-sandbox.doku.com

API Production

https://api.doku.com

Path

/direct-debit/merchant/cimb/v1.0/otp-verification

OTP Verification API

post

Authorizations

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-DEVICE-IDstringRequired

Device identification on which the API services are currently being accessed by the end user (customer). Can’t contain symbols

Example: 95221

X-IP-ADDRESSstringOptional

conditional. IP address of the end user (customer) using IPv4 format

Example: 95221

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

originalPartnerReferenceNostringOptionalExample: CIMB20000001

otpstringOptionalExample: 123456

typestringOptionalExample: PAYMENT

Responses

200

Successful OTP Verification

application/json

Responseone of

400

Invalid Field Format

application/json

401

Invalid Token (B2B)

application/json

post

/direct-debit/merchant/cimb/v1.0/otp-verification

POST /direct-debit/merchant/cimb/v1.0/otp-verification 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-DEVICE-ID: 95221
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: 123

{
  "originalPartnerReferenceNo": "CIMB20000001",
  "otp": "123456",
  "type": "PAYMENT",
  "additionalInfo": {
    "bankCardToken": "12341234"
  }
}

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

Payment

After merchant check the balance, merchant can hit this API to do payment. DOKU will deduct customer's balance.

Here is the flow for Payment CIMB :

API Endpoint

Environment

Endpoint

HTTP Method

POST

API Sandbox

https://api-sandbox.doku.com

API Production

https://api.doku.com

Path

...../direct-debit/merchant/allo/v1.0/payment/host-to-host

Payment API

post

Authorizations

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-DEVICE-IDstringRequired

Device identification on which the API services are currently being accessed by the end user (customer). Can’t contain symbols

Example: 95221

X-IP-ADDRESSstringOptional

conditional. IP address of the end user (customer) using IPv4 format

Example: 95221

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

Partner Reference Number as Invoice | min length: 1 | max length: 64

Example: SIM_20230829_0001

Responses

200

Successful Payment

application/json

400

Invalid Field Format

application/json

401

Invalid Token (B2B)

application/json

post

/direct-debit/merchant/cimb/v1.0/payment-host-to-host

POST /direct-debit/merchant/cimb/v1.0/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
X-DEVICE-ID: 95221
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: 424

{
  "partnerReferenceNo": "SIM_20230829_0001",
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "additionalInfo": {
    "lineItems": [
      {
        "name": "masker",
        "price": "5000.00",
        "quantity": 1
      },
      {
        "name": "aqua",
        "price": "5000.00",
        "quantity": 1
      }
    ],
    "remark": "belanja",
    "successPaymentUrl": "https://dribbble.com/shots/14575431-Payment-method-success/attachments/6265573?mode=media",
    "failedPaymentUrl": "https://dribbble.com/shots/4756331-Failed-Transaction"
  }
}

{
  "responseCode": "4035413",
  "responseMessage": "OTP Sent To Cardholder",
  "partnerReferenceNo": "L20230718003"
}

Acknowledge Payment Notification

After the payment is being made by your customer, DOKU will send HTTP Notification to your defined Notification URL. Learn how to handle the notification from DOKU .

Additional Feature

Online Refund

Merchant can refund the transaction to DOKU. Hit this API to refund the transaction. Currently DOKU Support Full Refund.

Here is the 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/merchant/cimb/v1.0/debit/refund

Refund API

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-DEVICE-IDstringRequired

Device identification on which the API services are currently being accessed by the end user (customer). Can’t contain symbols

Example: 95221

X-IP-ADDRESSstringOptional

conditional. IP address of the end user (customer) using IPv4 format

Example: 95221

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

Original Partner Reference Number | min length: 1 | max length: 64

Example: INV-592566712725

originalExternalIdstringRequired

External Id used on payment| min length: 1 | max length: 36

Example: 10052019

partnerRefundNostringRequired

Refund Number from merchant | min length: 1 | max length: 64

Example: 239850918204981205970

reasonstringOptional

Reason of refund | max length: 255

Example: Customer complain

Responses

200

Successful Refund

application/json

400

Invalid Field Format

application/json

401

Invalid Token (B2B)

application/json

post

/direct-debit/merchant/cimb/v1.0/debit/refund

POST /direct-debit/merchant/cimb/v1.0/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-DEVICE-ID: 95221
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: 205

{
  "originalPartnerReferenceNo": "INV-592566712725",
  "originalExternalId": "10052019",
  "partnerRefundNo": "239850918204981205970",
  "refundAmount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "reason": "Customer complain"
}

{
  "responseCode": "2005800",
  "responseMessage": "Successful",
  "originalPartnerReferenceNo": "L20230725005",
  "originalReferenceNo": "Sv6LFBnNOiCevHzLcgK",
  "refundNo": "9lCqroDiy27A",
  "partnerRefundNo": "123450002",
  "refundAmount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "refundTime": "2020-12-21T17:21:41+07:00"
}

Account Unbinding

In case you need to remove the customer data on DOKU, hit this API to unbinding the customer data.

API Endpoint

Environment

Endpoint

HTTP Method

POST

API Sandbox

https://api-sandbox.doku.com

API Production

https://api.doku.com

Path

...../direct-debit/cimb/v1.0/registration-account-unbinding

Unbinding process

post

Authorizations

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-DEVICE-IDstringRequired

Device identification on which the API services are currently being accessed by the end user (customer). Can’t contain symbols

Example: 95221

X-IP-ADDRESSstringOptional

conditional. IP address of the end user (customer) using IPv4 format

Example: 95221

AuthorizationstringRequired

Access Token obtained from Get B2B Token API

Example: 95221

Body

tokenIdstringRequired

DOKU Gateway token | Format : AN

Example: hdiwh3h832d832h382h3duh2

Responses

200

Successful Unbinding

application/json

400

Invalid Field Format

application/json

401

Invalid Token (B2B)

application/json

post

/direct-debit/cimb/v1.0/registration-account-unbinding

POST /direct-debit/cimb/v1.0/registration-account-unbinding 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-DEVICE-ID: 95221
Authorization: 95221
Content-Type: application/json
Accept: */*
Content-Length: 38

{
  "tokenId": "hdiwh3h832d832h382h3duh2"
}

{
  "responseCode": "4030913",
  "responseMessage": "OTP Sent To Cardholder"
}

PreviousDirect Debit NextBRI Direct Debit

Last updated 1 year ago

hashtagIntegration Steps

hashtagAccount Binding

hashtagRegister a merchant account for direct debit

hashtagOTP Verification

hashtagOTP Verification API

hashtagPayment

hashtagPayment API

hashtagAcknowledge Payment Notification

hashtagAdditional Feature

hashtagOnline Refund

hashtagRefund API

hashtagAccount Unbinding

hashtagUnbinding process

Integration Steps

Account Binding

Register a merchant account for direct debit

OTP Verification

OTP Verification API

Payment

Payment API

Acknowledge Payment Notification

Additional Feature

Online Refund

Refund API

Account Unbinding

Unbinding process