CIMB Direct Debit Guide

DOKU has partnered with various banks and one of them is CIMB to provide Direct Debit Payment. Learn more about how DOKU can help you integrate with CIMB Direct Debit here.

Requirements

Before start integration, you must have retrieved credentials from CIMB.

If you don't have the credentials yet, we can help to facilitate you to get one. Here is the flow to get CIMB credentials:

Direct API - CIMB Direct Debit Activation

Direct API - CIMB Direct Debit Credential Request Step 1

Direct API - CIMB Direct Debit Credential Request Step 2

Login to DOKU Back Office
Go to Configuration > Direct Debit
Select CIMB Direct Debit and click Activate button
Input Key
Input Secret
Click Activate button

Congratulations! You are now ready for the integration.

Integration steps

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

Register Debit card (tokenization)
Get token list
Create payment using the token
Acknowledge payment result

Optional but recommended to have:

Resend OTP for payment
Delete token

Advanced Features:

Create Refund

1. Register Debit card (tokenization)

Here is the flow for registering card:

Direct API - CIMB Direct Debit Register Card Sequence Diagram

Direct API - CIMB Direct Debit Register Card Flow

To register the card, you will need to hit this API through your Backend:

API Request

Type	Value
HTTP Method	POST
API endpoint (Sandbox)	`https://api-sandbox.doku.com/cimb-direct-debit/v1/token`
API endpoint (Production)	`https://api.doku.com/cimb-direct-debit/v1/token`

Here is the sample of request header to register the debit card:

Client-Id: MCH-0001-10791114622547
Request-Id: 672118bb-9963-43ce-93b2-26d4fd0732a3
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=

Request Header Explanation

Parameter	Description
Client-Id	Client ID retrieved from DOKU Back Office
Request-Id	Unique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-Timestamp	Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z
Signature	Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample of request body to register the debit card:

{
  "customer": {
    "id": "DOKUxCIMB_UAT_01",
    "name": "TEST",
    "email": "wtd@mail.com",
    "phone": "6281394130621",
    "id_card": "18291829918778",
    "country": "Indonesia",
    "address": "Jl. Menara Mulia",
    "date_of_birth": "01-12-2000",
    "additional_info": "None"
  },
  "debit_card": {
    "account_email": "anton@example.com",
    "account_mobile_phone":"6281394130621",
    "success_registration_url":"https://jokul.doku.com/bo/login",
    "failed_registration_url":"https://jokul.doku.com/bo/logixxx"
  }
}

Request Body Explanation

Parameter	Type	Mandatory	Description
`customer.id`	`string`	Mandatory	Unique customer identifier generated by merchant. Required to generate payment token. Allowed chars: `alphabetic, numeric, special chars` Max Length: `128`
`customer.name`	`string`	Optional	Customer name Allowed chars: `alphabetic` Max Length: `64`
`customer.email`	`string`	Optional	Customer email Allowed chars: `alphabetic, numeric, special chars` Max Length: `64`
`customer.phone`	`string`	Optional	Customer phone number. Format: `{calling_code}{phone_number}`. Example: 6281122334455 Allowed chars: `numeric` Max Length: `32`
`customer.address`	`string`	Optional	Customer address Allowed chars: `alphabetic, numeric, special chars` Max Length: `256`
`customer.country`	`string`	Optional	2 alphabetic country code ISO 3166-1 Allowed chars: `alphabetic` Min-max Length: `3`
`customer.id_card`	`string`	Optional	Customer Identity Card number (KTP) for our risk engine assessment Allowed chars: `alphabetic, numeric, special chars` Max length: `32`
`customer.date_of_birth`	`string`	Optional	Customer date of birth for our risk engine assesment Format: `dd-MM-yyyy`
`customer.additional_info`	`string`	Optional	Customer additional info Max Length: `256`
`debit_card.account_email`	`string`	Optional	Registered email on the CIMB
`debit_card.account_mobile_phone`	`string`	Mandatory	Registered phone number on the CIMB. Format: `{calling_code}{phone_number}`.Example: 6281122334455 Max Length: `20`
`debit_card.success_registration_url`	`string`	Optional	URL for direct page after success register
`debit_card.failed_registration_url`	`string`	Optional	URL for direct page after failed register

API Response

After hitting the above API request, DOKU will give the response.

Type	Value
HTTP Status	201
Result	CREATED

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: 672118bb-9963-43ce-93b2-26d4fd0732a3
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

Parameter	Description
Client-Id	Same as the request
Request-Id	Same as the request
Response-Timestamp	Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU
Signature	Signature generated by DOKU based on the response body

Here is the sample of response body:

{
    "customer": {
        "email": "wtd@mail.com",
        "phone": "6281394130621",
        "id_card": "18291829918778",
        "country": "Indonesia",
        "address": "Jl. Menara Mulia",
        "date_of_birth": "01-12-2000",
        "additional_info": "None",
        "id": "DOKUxCIMB_36",
        "name": "CIMB_DIRECTDEBIT08"
    },
    "debit_card": {
        "cimb_registration_url": "https://alphaoctocash.cimbniaga.co.id/api-manager-external/alpha/direct-debit-web/register/a9e4c88c-a4ae-11ea-9682-0a1987d200002663",
        "status": "PENDING",
        "message": "Waiting for validated by CIMB"
    }
}

Response Body Explanation

Parameter	Type	Mandatory	Description
`customer.id`	`string`	Mandatory	Same as the request
`customer.name`	`string`	Optional	Same as the request
`customer.email`	`string`	Optional	Same as the request
`customer.phone`	`string`	Optional	Same as the request
`customer.address`	`string`	Optional	Same as the request
`customer.country`	`string`	Optional	Same as the request
`customer.id_card`	`string`	Optional	Same as the request
`customer.date_of_birth`	`string`	Optional	Same as the request
`customer.additional_info`	`string`	Optional	Same as the request
`debit_card.cimb_registration_url`	`string`	Mandatory	url from CIMB for input rekening number
`debit_card.status`	`string`	Mandatory	Token status. In this state, it should be `PENDING`
`debit_card.message`	`string`	Mandatory	The token message according to `debit.card.status`

2. Get token list

After the card is registered, you can show the token saved for your customer. This API also used to list down all the registered card, so that your customer does not need to register the card for the future payments.

To get the token list, you will to hit this API from your Backend:

API Request

Type	Value
HTTP Method	POST
API endpoint (Sandbox)	`https://api-sandbox.doku.com/cimb-direct-debit/v1/tokens`
API endpoint (Production)	`https://api.doku.com/cimb-direct-debit/v1/tokens`

Here is the sample of request header to get the token list:

Client-Id: MCH-0001-10791114622547
Request-Id: 415f8064-ce1c-4c94-84b8-167201fd47cb
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=

Request Header Explanation

Parameter	Description
Client-Id	Client ID retrieved from DOKU Back Office
Request-Id	Unique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-Timestamp	Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z
Signature	Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample of request body to get the token list:

{
    "customer": {
        "id": "CIMBXDOKU112",
        "name": "testing"
    }
}

Request Body Explanation

Parameter	Type	Mandatory	Description
`customer.id`	`string`	Mandatory	The customer ID that has been registered to DOKU Allowed chars: `alphabetic, numeric, special chars` Max Length: `50`
`customer.name`	`string`	Optional	The customer name that has been registered to DOKU Allowed chars: `alphabetic` Max Length: `70`

API Response

After hitting the above API request, DOKU will give the response.

Type	Value
HTTP Status	200
Result	SUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: 415f8064-ce1c-4c94-84b8-167201fd47cb
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

Parameter	Description
Client-Id	Same as the request
Request-Id	Same as the request
Response-Timestamp	Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU
Signature	Signature generated by DOKU based on the response body

Here is the sample of response body:

[
    {
        "customer": {
            "id": "TEST-CIMBXDOKU-05",
            "name": "DOKUXCIMB"
        },
        "debit_card": {
            "token_id": "1614dc147e404f41f6d2de877fda1f94",
            "account_no": "XXXXXXXX2800"
        }
    }
]

Response Body Explanation

Parameter	Type	Mandatory	Description
`customer.id`	`string`	Mandatory	Same as the request
`customer.name`	`string`	Optional	Same as the request
`debit_card.token_id`	`string`	Mandatory	Token generated by DOKU for the Debit card to use when do payment Max length: `128`
`debit_card.account_no`	`string`	Mandatory	Last 4 digit of the Debit Card number

3. Create payment using the token

Here is the flow for creating payment using the token:

Direct API - CIMB Direct Debit Payment Sequence Diagram

Direct API - CIMB Direct Debit Register Payment Flow

To create the payment, you will need to hit this API through your Backend:

API Request

Type	Value
HTTP Method	POST
API endpoint (Sandbox)	`https://api-sandbox.doku.com/cimb-direct-debit/v1/payment`
API endpoint (Production)	`https://api.doku.com/cimb-direct-debit/v1/payment`

Here is the sample of request header to create the payment:

Client-Id: MCH-0001-10791114622547
Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22e
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=

Request Header Explanation

Parameter	Description
Client-Id	Client ID retrieved from DOKU Back Office
Request-Id	Unique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-Timestamp	Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z
Signature	Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample of request body to create the payment:

{
    "customer": {
        "id": "DOKUxCIMB_UAT_05",
        "name": "Robby",
        "phone": "628817219910",
        "email": "wtd@mail.com",
        "id_card": "18291829918778",
        "country": "Indonesia",
        "address": "Jl. Menara Mulia",
        "date_of_birth": "01-12-2000"
    },
    "additional_info": {
        "message": "no additional info",
        "test": "test"
    },
    "order": {
        "invoice_number": "INV_NUMBER_D005",
        "line_items": [
            {
                "name": "Vitamin C",
                "price": 40000,
                "quantity": 1
            },
            {
                "name": "Pensil Warna",
                "price": 50000,
                "quantity": 1
            }
        ],
        "amount": 20000,
        "session_id": "SESSION-ID-001"
    },
    "payment": {
        "token_id": "287a73836d2d611990affce3b1affc3a",
        "otp_expiration_timestamp": 360010
    }
}

Request Body Explanation

Parameter	Type	Mandatory	Description
`customer.id`	`string`	Mandatory	The customer ID that has been registered to DOKU Allowed chars: `alphabetic, numeric, special chars` Max Length: `50`
`customer.name`	`string`	Optional	The customer name that has been registered to DOKU Allowed chars: `alphabetic` Max Length: `70`
`customer.email`	`string`	Optional	Customer email Allowed chars: `alphabetic, numeric, special chars` Max Length: `64`
`customer.phone`	`number`	Optional	Customer phone number. Format: `{calling_code}{phone_number}`. Example: 6281122334455 Allowed chars: `numeric` Max Length: `20`
`customer.address`	`string`	Optional	Customer address Allowed chars: `alphabetic, numeric, special chars` Max Length: `255`
`customer.country`	`string`	Optional	2 alphabetic country code ISO 3166-1 Allowed chars: `alphabetic` Min-max Length: `60`
`customer.id_card`	`string`	Optional	Customer Identity Card number (KTP) for our risk engine assessment Allowed chars: `alphabetic, numeric, special chars` Max length: `20`
`customer.date_of_birth`	`string`	Optional	Customer date of birth for our risk engine assesment Format: `dd-MM-yyyy`
`additional_info.message`	`string`	Optional	Additional info message
`additional_info.test`	`string`	Optional	Additional info test
`order.invoice_number`	`string`	Mandatory	Generated by merchant to identify the order Allowed chars: `alphabetic, numeric, special chars` Max length: `64`
`order.line_items.name`	`string`	Optional	Name of the product item, privacy concern so optional, but if send will help our risk engine Allowed chars: `alphabetic, numeric, special chars`
`order.line_items.price`	`number`	Optional	Price of the product item, privacy concern so optional, but if send will help our risk engine Total price and quantity must match with the `order.amount` Allowed chars: `numeric`
`order.line_items.quantity`	`number`	Optional	Quantity of the product item, privacy concern so optional, but if send will help our risk engine Allowed chars: `numeric`
`order.amount`	`number`	Mandatory	In IDR Currency and without decimal, and converted total amount. Allowed chars: `numeric` Max length: `12`
`order.session_id`	`string`	Optional	Transaction session id Allowed chars: `Alphabetic,numeric, special chars` Max length: `50`
`payment.token_id`	`string`	Mandatory	The token that will be use for this transaction Max length: `128`
`payment.otp_expiration_timestamp`	`number`	Optional	OTP expiration time in minute Default: `10` minutes

API Response

After hitting the above API request, DOKU will give the response.

Type	Value
HTTP Status	201
Result	CREATED

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22e
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

Parameter	Description
Client-Id	Same as the request
Request-Id	Same as the request
Response-Timestamp	Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU
Signature	Signature generated by DOKU based on the response body

Here is the sample of response body:

{
    "customer": {
        "id": "DOKUxCIMB_30",
        "name": "CIMB_DIRECTDEBIT08",
        "email": "wtd@mail.com",
        "phone": "6281394130621",
        "id_card": "18291829918778",
        "country": "Indonesia",
        "address": "Jl. Menara Mulia",
        "date_of_birth": "01-12-2000",
        "additional_info": "None"
    },
    "order": {
        "invoice_number": "INV_NUMBER_D009",
        "line_items": [
            {
                "name": "Vitamin C",
                "price": "40000",
                "quantity": "1"
            },
            {
                "name": "Pensil Warna",
                "price": "50000",
                "quantity": "1"
            }
        ],
        "amount": "90000",
        "session_id": "SESSION-ID-001"
    },
    "payment": {
        "token": "M8L5TfWSxN6orwBlpqaZi3zMuElXH3J9xERWGqtT4",
        "status": "PENDING"
    }
}

Response Body Explanation

Parameter	Type	Mandatory	Description
`customer.id`	`string`	Mandatory	Same as the request
`customer.name`	`string`	Optional	Same as the request
`customer.email`	`string`	Optional	Same as the request
`customer.phone`	`string`	Optional	Same as the request
`customer.address`	`string`	Optional	Same as the request
`customer.country`	`string`	Optional	Same as the request
`customer.id_card`	`string`	Optional	Same as the request
`customer.date_of_birth`	`string`	Optional	Same as the request
`order.amount`	`number`	Mandatory	Same as the request
`order.session_id`	`string`	Optional	Transaction session id Allowed chars: `Alphabetic,numeric, special chars` Max length: `50`
`order.invoice_number`	`string`	Mandatory	Same as the request
`order.line_items.name`	`string`	Optional	Same as the request
`order.line_items.price`	`number`	Optional	Same as the request
`order.line_items.quantity`	`number`	Optional	Same as the request
`payment.token`	`string`	Mandatory	Payment token generated by DOKU specific for the transaction
`payment.status`	`string`	Mandatory	`PENDING` for successful token request (waiting for OTP verification) / `SUCCESS` if not need OTP

3.1. Validate payment OTP

Now the payment is created but the status is PENDING. CIMB will send the OTP to the customers and you will need to provide the form to let the customer input the OTP.

To validate the OTP, you will need to hit this API through your Backend:

API Request

Type	Value
HTTP Method	POST
API endpoint (Sandbox)	`https://api-sandbox.doku.com/cimb-direct-debit/v1/payment/validate`
API endpoint (Production)	`https://api.doku.com/cimb-direct-debit/v1/payment/validate`

Here is the sample of request header to validate the OTP:

Client-Id: MCH-0001-10791114622547
Request-Id: bce963fc-bb93-4ef2-948a-7838044b537e
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=

Request Header Explanation

Parameter	Description
Client-Id	Client ID retrieved from DOKU Back Office
Request-Id	Unique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-Timestamp	Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z
Signature	Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample of request body to validate the OTP:

{
    "payment":{
        "token":"xLvT3bQrGq65xbTrfhlaEP6R5qiazxJjkbsaxQ421Nc",
        "otp":"999999"
    }
}

Request Body Explanation

Parameter	Type	Mandatory	Description
`payment.token`	`string`	Mandatory	The token that generated by DOKU for the transaction Max length: `256`
`payment.otp`	`string`	Mandatory	The Payment OTP that sent by the CIMB to the customer Max length: `6` `Notes` : OTP from CIMB will expired in 5 minutes

API Response

After hitting the above API request, DOKU will give the response.

Type	Value
HTTP Status	200
Result	SUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: bce963fc-bb93-4ef2-948a-7838044b537e
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

Parameter	Description
Client-Id	Same as the request
Request-Id	Same as the request
Response-Timestamp	Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU
Signature	Signature generated by DOKU based on the response body

Here is the sample of response body:

{
    "customer": {
        "id": "DOKUxCIMB_30",
        "name": "CIMB_DIRECTDEBIT08",
        "email": "wtd@mail.com",
        "phone": "6281394130621",
        "id_card": "18291829918778",
        "country": "Indonesia",
        "address": "Jl. Menara Mulia",
        "date_of_birth": "01-12-2000",
        "additional_info": "None"
    },
    "order": {
        "invoice_number": "INV_NUMBER_D009",
        "line_items": [
            {
                "name": "Vitamin C",
                "price": "40000",
                "quantity": "1"
            },
            {
                "name": "Pensil Warna",
                "price": "50000",
                "quantity": "1"
            }
        ],
        "amount": "90000.00"
    },
    "payment": {
        "payment_id": "001194654652",
        "token": "xLvT3bQrGq65xbTrfhlaEP6R5qiazxJjkbsaxQ421Nc",
        "status": "SUCCESS"
    }
}

Response Body Explanation

Parameter	Type	Mandatory	Description
`customer.id`	`string`	Mandatory	Same as the request
`customer.name`	`string`	Optional	Same as the request
`customer.email`	`string`	Optional	Same as the request
`customer.phone`	`string`	Optional	Same as the request
`customer.address`	`string`	Optional	Same as the request
`customer.country`	`string`	Optional	Same as the request
`customer.id_card`	`string`	Optional	Same as the request
`customer.date_of_birth`	`string`	Optional	Same as the request
`customer.additional_info`	`string`	Optional	Same as the request
`order.amount`	`number`	Mandatory	Same as the request
`order.invoice_number`	`string`	Mandatory	Same as the request
`order.line_items.name`	`string`	Optional	Same as the request
`order.line_items.price`	`number`	Optional	Same as the request
`order.line_items.quantity`	`number`	Optional	Same as the request
`payment.payment_id`	`string`	Mandatory	Payment ID from the Bank
`payment.token`	`string`	Mandatory	Same as the request
`payment.status`	`string`	Mandatory	Payment status. In this state, it should be `SUCCESS` or `FAILED`

4. Acknowledge payment result

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:

Handling DOKU HTTP Notification

Additional Features

These are the feature that recommended to implement to make sure that you deliver a good payment experience for your customers.

1. Resend OTP for payment

If for some reasons, your customers didn't receive the OTP when doing a payment. You can use this API to resend new OTP.

To resend the new OTP for payment, you will need to hit this API through your Backend:

API Request

Type	Value
HTTP Method	POST
API endpoint (Sandbox)	`https://api-sandbox.doku.com/cimb-direct-debit/v1/payment-otp`
API endpoint (Production)	`https://api.doku.com/cimb-direct-debit/v1/payment-otp`

Here is the sample of request header to resend the OTP for payment:

Client-Id: MCH-0001-10791114622547
Request-Id: ea41603d-8f77-43ba-9dc3-def0766fe69b
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=

Request Header Explanation

Parameter	Description
Client-Id	Client ID retrieved from DOKU Back Office
Request-Id	Unique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-Timestamp	Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z
Signature	Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample of request body to resend the OTP for payment:

{
    "payment": {
        "token":"?UiUVuLzrkuHzIZmKMkAMRU5yPI4x19utIF93ekkz0"
    }
}

Request Body Explanation

Parameter	Type	Mandatory	Description
`payment.token`	`string`	Mandatory	Payment token generated by DOKU specific for the transaction. The token valid for `2.5 minutes`

API Response

After hitting the above API request, DOKU will give the response.

Type	Value
HTTP Status	200
Result	SUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: ea41603d-8f77-43ba-9dc3-def0766fe69b
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

Parameter	Description
Client-Id	Same as the request
Request-Id	Same as the request
Response-Timestamp	Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU
Signature	Signature generated by DOKU based on the response body

Here is the sample of response body:

{
    "payment": {
        "token":"?UiUVuLzrkuHzIZmKMkAMRU5yPI4x19utIF93ekkz0"
    }
}

Response Body Explanation

Parameter	Type	Mandatory	Description
`payment.token`	`string`	Mandatory	Same as the request

2. Delete the token

If for some reasons, your cutomers want to remove the card from your application, then you will need to provide this feature.

To delete the token, you will need to hit this API through your Backend:

API Request

Type	Value
HTTP Method	POST
API endpoint (Sandbox)	`https://api-sandbox.doku.com/cimb-direct-debit/v1/token-delete`
API endpoint (Production)	`https://api.doku.com/cimb-direct-debit/v1/token-delete`

Here is the sample of request header to delete the token:

Client-Id: MCH-0001-10791114622547
Request-Id: c8154b5b-25fa-430d-9e5f-5a8a34d6d371
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=

Request Header Explanation

Parameter	Description
Client-Id	Client ID retrieved from DOKU Back Office
Request-Id	Unique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-Timestamp	Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z
Signature	Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample of request body to resend the OTP for payment:

{
    "customer": {
        "id": "CIMBXDOKU112",
        "name": "Anton Budiman"
    },
    "debit_card": {
        "token_id": "b21acc29d08750fa4d9f3eda77089352"
    }
}

Request Body Explanation

Parameter	Type	Mandatory	Description
`customer.id`	`string`	Mandatory	The customer ID that has been registered to DOKU Allowed chars: `alphabetic, numeric, special chars` Max Length: `50`
`customer.name`	`string`	Optional	The customer name that has been registered to DOKU Allowed chars: `alphabetic` Max Length: `70`
`debit_card.token_id`	`string`	Mandatory	Token generated by DOKU for the Debit card to use when do payment Max length: `128`

API Response

After hitting the above API request, DOKU will give the response.

Type	Value
HTTP Status	200
Result	SUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: c8154b5b-25fa-430d-9e5f-5a8a34d6d371
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

Parameter	Description
Client-Id	Same as the request
Request-Id	Same as the request
Response-Timestamp	Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU
Signature	Signature generated by DOKU based on the response body

Here is the sample of response body:

{
    "customer": {
        "id": "TEST-CIMBXDOKU-05",
        "name": "DOKUXCIMB"
    },
    "debit_card": {
        "token_id": "1614dc147e404f41f6d2de877fda1f94",
        "status": "SUCCESS",
        "message": "Success Unbinding Card"
    }
}

Response Body Explanation

Parameter	Type	Mandatory	Description
`customer.id`	`string`	Mandatory	Same as the request
`customer.name`	`string`	Optional	Same as the request
`debit_card.token_id`	`string`	Mandatory	Same as the request
`debit_card.status`	`string`	Mandatory	The unbinding card status Possible value: `SUCCESS`, `FAILED`
`debit_card.message`	`string`	Mandatory	The message to indicates that the card has been unbinded and merchant can safely revoke the card

3. Refund

To request a refund, you will need to hit this API through your backend:

API Request

Type	Value
HTTP Method	POST
API endpoint (Sandbox)	`https://api-sandbox.doku.com/cimb-direct-debit/v1/payment-refund`
API endpoint (Production)	`https://api.doku.com/cimb-direct-debit/v1/payment-refund`

Here is the sample of request header to generate payment URL:

Client-Id: MCH-0001-10791114622547
Request-Id: 6cc9f8b1-d83d-4c24-b853-a3223f43a744
Request-Timestamp: 2020-08-12T09:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=

Request Header Explanation

Parameter	Description
Client-Id	Client ID retrieved from DOKU Back Office
Request-Id	Unique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-Timestamp	Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z
Signature	Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample request body to request a refund:

{
    "order": {
        "invoice_number": "INV_NUMBER_D006"
    },
    "payment": {
        "original_request_id":"2620"
    },
    "refund": {
        "amount":"2000",
        "reason":"Cancel Order"
    }
}

Request Body Explanation

Parameter	Type	Mandatory	Description
`order.invoice_number`	`string`	Mandatory	Invoice number of the transaction that being refunded
`payment.original_request_id`	`string`	Mandatory	Original Payment Request Id that want to refunded
`refund.amount`	`number`	Mandatory	Transaction amount that wants to be refunded
`refund.reason`	`string`	Optional	Get from payment notification response

API Response

After hitting the above API request, DOKU will give the response.

Type	Value
HTTP Status	201
Result	SUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: 6cc9f8b1-d83d-4c24-b853-a3223f43a744
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

Parameter	Description
Client-Id	Same as the request
Request-Id	Same as the request
Response-Timestamp	Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU
Signature	Signature generated by DOKU based on the response body

Here is the sample of response body:

{
    "order": {
        "invoice_number": "INV_NUMBER_D009"
    },
    "payment": {
        "original_request_id": "82014",
        "payment_id": "001799101960"
    },
    "refund": {
        "amount": 1000,
        "reason": "Cancel Order",
        "status": "SUCCESS",
        "message": "SUCCESS"
    }
}

Response Body Explanation

Parameter	Type	Mandatory	Description
`order.invoice_number`	`string`	Mandatory	Same as the request
`payment.original_request_id`	`string`	Same as the request
`refund.amount`	`number`	Mandatory	Same as the request
`refund.reason`	`string`	Optional	Same as the request
`refund.status`	`string`	Optional	Refund status Possible Value : `SUCCESS` or `FAILED`
`refund.message`	`string`	Optional	Reason if failed refund

Tokenization

Want to make your checkout experience faster? You can combine this integration with the Tokenization, so the next time your customer purchase, they don't need to input the debit card anymore.

Tokenization

Split Settlement

If you are a platform or a marketplace, you can use this feature to settle the funds to your sellers or partners programmatically, save many operational efforts.

Settlement

Explore the New API Documentation!

Requirements​

Integration steps​

1. Register Debit card (tokenization)​

API Request​

API Response​

2. Get token list​

API Request​

API Response​

3. Create payment using the token​

API Request​

API Response​

3.1. Validate payment OTP​

API Request​

API Response​

4. Acknowledge payment result​

Additional Features​

1. Resend OTP for payment​

API Request​

API Response​

2. Delete the token​

API Request​

API Response​

3. Refund​

API Request​

API Response​

Tokenization​

Split Settlement​

Requirements

Integration steps

1. Register Debit card (tokenization)

API Request

API Response

2. Get token list

API Request

API Response

3. Create payment using the token

API Request

API Response

3.1. Validate payment OTP

API Request

API Response

4. Acknowledge payment result

Additional Features

1. Resend OTP for payment

API Request

API Response

2. Delete the token

API Request

API Response

3. Refund

API Request

API Response

Tokenization

Split Settlement