Skip to main content

CIMB Direct Debit Guide

Jokul has partnered with various banks and one of them is CIMB to provide Direct Debit Payment. Learn more about how Jokul 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:

Jokul Direct - CIMB Direct Debit ActivationJokul Direct CIMB Direct Debit Credential Request Step 1Jokul Direct CIMB Direct Debit Credential Request Step 2
  1. Login to Jokul Back Office
  2. Go to Configuration > Direct Debit
  3. Select CIMB Direct Debit and click Activate button
  4. Input Key
  5. Input Secret
  6. Click Activate button

Congratulations! You are now ready for the integration.


Integration steps#

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

  1. Register Debit card (tokenization)
  2. Get token list
  3. Create payment using the token
  4. Acknowledge payment result

Optional but recommended to have:

  1. Resend OTP for payment
  2. Delete token

Advanced Features:

  1. Create Refund

1. Register Debit card (tokenization)#

Here is the flow for registering card:

Jokul Direct - CIMB Direct Debit Register Card Sequence DiagramJokul Direct CIMB Direct Debit Register Card Flow

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

API Request#

TypeValue
HTTP MethodPOST
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-10791114622547Request-Id: 672118bb-9963-43ce-93b2-26d4fd0732a3Request-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
Request Header Explanation
ParameterDescription
Client-IdClient ID retrieved from Jokul Back Office
Request-IdUnique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-TimestampTimestamp 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
SignatureSecurity 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
ParameterTypeMandatoryDescription
customer.idstringMandatoryUnique customer identifier generated by merchant. Required to generate payment token.
Allowed chars: alphabetic, numeric, special chars
Max Length: 128
customer.namestringOptionalCustomer name
Allowed chars: alphabetic
Max Length: 64
customer.emailstringOptionalCustomer email
Allowed chars: alphabetic, numeric, special chars
Max Length: 64
customer.phonestringOptionalCustomer phone number. Format: {calling_code}{phone_number}. Example: 6281122334455
Allowed chars: numeric
Max Length: 32
customer.addressstringOptionalCustomer address
Allowed chars: alphabetic, numeric, special chars
Max Length: 256
customer.countrystringOptional2 alphabetic country code ISO 3166-1
Allowed chars: alphabetic
Min-max Length: 3
customer.id_cardstringOptionalCustomer Identity Card number (KTP) for our risk engine assessment
Allowed chars: alphabetic, numeric, special chars
Max length: 32
customer.date_of_birthstringOptionalCustomer date of birth for our risk engine assesment
Format: dd-MM-yyyy
customer.additional_infostringOptionalCustomer additional info
Max Length: 256
debit_card.account_emailstringOptionalRegistered email on the CIMB
debit_card.account_mobile_phonestringMandatoryRegistered phone number on the CIMB. Format: {calling_code}{phone_number}.Example: 6281122334455
Max Length: 20
debit_card.success_registration_urlstringOptionalURL for direct page after success register
debit_card.failed_registration_urlstringOptionalURL for direct page after failed register

API Response#

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

TypeValue
HTTP Status201
ResultCREATED

Here is the sample response header:

Client-Id: MCH-0001-10791114622547Request-Id: 672118bb-9963-43ce-93b2-26d4fd0732a3Response-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
Response Header Explanation
ParameterDescription
Client-IdSame as the request
Request-IdSame as the request
Response-TimestampTimestamp Response on UTC with format ISO8601 UTC+0 from Jokul
SignatureSignature generated by Jokul 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
ParameterTypeMandatoryDescription
customer.idstringMandatorySame as the request
customer.namestringOptionalSame as the request
customer.emailstringOptionalSame as the request
customer.phonestringOptionalSame as the request
customer.addressstringOptionalSame as the request
customer.countrystringOptionalSame as the request
customer.id_cardstringOptionalSame as the request
customer.date_of_birthstringOptionalSame as the request
customer.additional_infostringOptionalSame as the request
debit_card.cimb_registration_urlstringMandatoryurl from CIMB for input rekening number
debit_card.statusstringMandatoryToken status. In this state, it should be PENDING
debit_card.messagestringMandatoryThe 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#

TypeValue
HTTP MethodPOST
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-10791114622547Request-Id: 415f8064-ce1c-4c94-84b8-167201fd47cbRequest-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
Request Header Explanation
ParameterDescription
Client-IdClient ID retrieved from Jokul Back Office
Request-IdUnique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-TimestampTimestamp 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
SignatureSecurity 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
ParameterTypeMandatoryDescription
customer.idstringMandatoryThe customer ID that has been registered to Jokul
Allowed chars: alphabetic, numeric, special chars
Max Length: 50
customer.namestringOptionalThe customer name that has been registered to Jokul
Allowed chars: alphabetic
Max Length: 70

API Response#

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

TypeValue
HTTP Status200
ResultSUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547Request-Id: 415f8064-ce1c-4c94-84b8-167201fd47cbResponse-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
Response Header Explanation
ParameterDescription
Client-IdSame as the request
Request-IdSame as the request
Response-TimestampTimestamp Response on UTC with format ISO8601 UTC+0 from Jokul
SignatureSignature generated by Jokul 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
ParameterTypeMandatoryDescription
customer.idstringMandatorySame as the request
customer.namestringOptionalSame as the request
debit_card.token_idstringMandatoryToken generated by Jokul for the Debit card to use when do payment
Max length: 128
debit_card.account_nostringMandatoryLast 4 digit of the Debit Card number


3. Create payment using the token#

Here is the flow for creating payment using the token:

Jokul Direct - CIMB Direct Debit Payment Sequence DiagramJokul Direct CIMB Direct Debit Register Payment Flow

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

API Request#

TypeValue
HTTP MethodPOST
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-10791114622547Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22eRequest-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
Request Header Explanation
ParameterDescription
Client-IdClient ID retrieved from Jokul Back Office
Request-IdUnique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-TimestampTimestamp 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
SignatureSecurity 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
ParameterTypeMandatoryDescription
customer.idstringMandatoryThe customer ID that has been registered to Jokul
Allowed chars: alphabetic, numeric, special chars
Max Length: 50
customer.namestringOptionalThe customer name that has been registered to Jokul
Allowed chars: alphabetic
Max Length: 70
customer.emailstringOptionalCustomer email
Allowed chars: alphabetic, numeric, special chars
Max Length: 64
customer.phonenumberOptionalCustomer phone number. Format: {calling_code}{phone_number}. Example: 6281122334455
Allowed chars: numeric
Max Length: 20
customer.addressstringOptionalCustomer address
Allowed chars: alphabetic, numeric, special chars
Max Length: 255
customer.countrystringOptional2 alphabetic country code ISO 3166-1
Allowed chars: alphabetic
Min-max Length: 60
customer.id_cardstringOptionalCustomer Identity Card number (KTP) for our risk engine assessment
Allowed chars: alphabetic, numeric, special chars
Max length: 20
customer.date_of_birthstringOptionalCustomer date of birth for our risk engine assesment
Format: dd-MM-yyyy
additional_info.messagestringOptionalAdditional info message
additional_info.teststringOptionalAdditional info test
order.invoice_numberstringMandatoryGenerated by merchant to identify the order
Allowed chars: alphabetic, numeric, special chars
Max length: 64
order.line_items.namestringOptionalName 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.pricenumberOptionalPrice 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.quantitynumberOptionalQuantity of the product item, privacy concern so optional, but if send will help our risk engine
Allowed chars: numeric
order.amountnumberMandatoryIn IDR Currency and without decimal, and converted total amount.
Allowed chars: numeric
Max length: 12
order.session_idstringOptionalTransaction session id
Allowed chars: Alphabetic,numeric, special chars
Max length: 50
payment.token_idstringMandatoryThe token that will be use for this transaction
Max length: 128
payment.otp_expiration_timestampnumberOptionalOTP expiration time in minute
Default: 10 minutes

API Response#

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

TypeValue
HTTP Status201
ResultCREATED

Here is the sample response header:

Client-Id: MCH-0001-10791114622547Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22eResponse-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
Response Header Explanation
ParameterDescription
Client-IdSame as the request
Request-IdSame as the request
Response-TimestampTimestamp Response on UTC with format ISO8601 UTC+0 from Jokul
SignatureSignature generated by Jokul 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
ParameterTypeMandatoryDescription
customer.idstringMandatorySame as the request
customer.namestringOptionalSame as the request
customer.emailstringOptionalSame as the request
customer.phonestringOptionalSame as the request
customer.addressstringOptionalSame as the request
customer.countrystringOptionalSame as the request
customer.id_cardstringOptionalSame as the request
customer.date_of_birthstringOptionalSame as the request
order.amountnumberMandatorySame as the request
order.session_idstringOptionalTransaction session id
Allowed chars: Alphabetic,numeric, special chars
Max length: 50
order.invoice_numberstringMandatorySame as the request
order.line_items.namestringOptionalSame as the request
order.line_items.pricenumberOptionalSame as the request
order.line_items.quantitynumberOptionalSame as the request
payment.tokenstringMandatoryPayment token generated by Jokul specific for the transaction
payment.statusstringMandatoryPENDING 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#

TypeValue
HTTP MethodPOST
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-10791114622547Request-Id: bce963fc-bb93-4ef2-948a-7838044b537eRequest-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
Request Header Explanation
ParameterDescription
Client-IdClient ID retrieved from Jokul Back Office
Request-IdUnique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-TimestampTimestamp 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
SignatureSecurity 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
ParameterTypeMandatoryDescription
payment.tokenstringMandatoryThe token that generated by Jokul for the transaction
Max length: 256
payment.otpstringMandatoryThe 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, Jokul will give the response.

TypeValue
HTTP Status200
ResultSUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547Request-Id: bce963fc-bb93-4ef2-948a-7838044b537eResponse-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
Response Header Explanation
ParameterDescription
Client-IdSame as the request
Request-IdSame as the request
Response-TimestampTimestamp Response on UTC with format ISO8601 UTC+0 from Jokul
SignatureSignature generated by Jokul 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
ParameterTypeMandatoryDescription
customer.idstringMandatorySame as the request
customer.namestringOptionalSame as the request
customer.emailstringOptionalSame as the request
customer.phonestringOptionalSame as the request
customer.addressstringOptionalSame as the request
customer.countrystringOptionalSame as the request
customer.id_cardstringOptionalSame as the request
customer.date_of_birthstringOptionalSame as the request
customer.additional_infostringOptionalSame as the request
order.amountnumberMandatorySame as the request
order.invoice_numberstringMandatorySame as the request
order.line_items.namestringOptionalSame as the request
order.line_items.pricenumberOptionalSame as the request
order.line_items.quantitynumberOptionalSame as the request
payment.payment_idstringMandatoryPayment ID from the Bank
payment.tokenstringMandatorySame as the request
payment.statusstringMandatoryPayment status. In this state, it should be SUCCESS or FAILED

4. Acknowledge payment result#

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


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#

TypeValue
HTTP MethodPOST
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-10791114622547Request-Id: ea41603d-8f77-43ba-9dc3-def0766fe69bRequest-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
Request Header Explanation
ParameterDescription
Client-IdClient ID retrieved from Jokul Back Office
Request-IdUnique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-TimestampTimestamp 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
SignatureSecurity 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
ParameterTypeMandatoryDescription
payment.tokenstringMandatoryPayment token generated by Jokul specific for the transaction. The token valid for 2.5 minutes

API Response#

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

TypeValue
HTTP Status200
ResultSUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547Request-Id: ea41603d-8f77-43ba-9dc3-def0766fe69bResponse-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
Response Header Explanation
ParameterDescription
Client-IdSame as the request
Request-IdSame as the request
Response-TimestampTimestamp Response on UTC with format ISO8601 UTC+0 from Jokul
SignatureSignature generated by Jokul based on the response body

Here is the sample of response body:

{    "payment": {        "token":"?UiUVuLzrkuHzIZmKMkAMRU5yPI4x19utIF93ekkz0"    }}
Response Body Explanation
ParameterTypeMandatoryDescription
payment.tokenstringMandatorySame 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#

TypeValue
HTTP MethodPOST
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-10791114622547Request-Id: c8154b5b-25fa-430d-9e5f-5a8a34d6d371Request-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
Request Header Explanation
ParameterDescription
Client-IdClient ID retrieved from Jokul Back Office
Request-IdUnique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-TimestampTimestamp 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
SignatureSecurity 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
ParameterTypeMandatoryDescription
customer.idstringMandatoryThe customer ID that has been registered to Jokul
Allowed chars: alphabetic, numeric, special chars
Max Length: 50
customer.namestringOptionalThe customer name that has been registered to Jokul
Allowed chars: alphabetic
Max Length: 70
debit_card.token_idstringMandatoryToken generated by Jokul for the Debit card to use when do payment
Max length: 128

API Response#

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

TypeValue
HTTP Status200
ResultSUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547Request-Id: c8154b5b-25fa-430d-9e5f-5a8a34d6d371Response-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
Response Header Explanation
ParameterDescription
Client-IdSame as the request
Request-IdSame as the request
Response-TimestampTimestamp Response on UTC with format ISO8601 UTC+0 from Jokul
SignatureSignature generated by Jokul 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
ParameterTypeMandatoryDescription
customer.idstringMandatorySame as the request
customer.namestringOptionalSame as the request
debit_card.token_idstringMandatorySame as the request
debit_card.statusstringMandatoryThe unbinding card status
Possible value: SUCCESS, FAILED
debit_card.messagestringMandatoryThe 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#

TypeValue
HTTP MethodPOST
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-10791114622547Request-Id: 6cc9f8b1-d83d-4c24-b853-a3223f43a744Request-Timestamp: 2020-08-12T09:45:42ZSignature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
Request Header Explanation
ParameterDescription
Client-IdClient ID retrieved from Jokul Back Office
Request-IdUnique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-TimestampTimestamp 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
SignatureSecurity 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
ParameterTypeMandatoryDescription
order.invoice_numberstringMandatoryInvoice number of the transaction that being refunded
payment.original_request_idstringMandatoryOriginal Payment Request Id that want to refunded
refund.amountnumberMandatoryTransaction amount that wants to be refunded
refund.reasonstringOptionalGet from payment notification response

API Response#

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

TypeValue
HTTP Status201
ResultSUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547Request-Id: 6cc9f8b1-d83d-4c24-b853-a3223f43a744Response-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
Response Header Explanation
ParameterDescription
Client-IdSame as the request
Request-IdSame as the request
Response-TimestampTimestamp Response on UTC with format ISO8601 UTC+0 from Jokul
SignatureSignature generated by Jokul 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
ParameterTypeMandatoryDescription
order.invoice_numberstringMandatorySame as the request
payment.original_request_idstringSame as the request
refund.amountnumberMandatorySame as the request
refund.reasonstringOptionalSame as the request
refund.statusstringOptionalRefund status
Possible Value : SUCCESS or FAILED
refund.messagestringOptionalReason if failed refund

Jokul Token#

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


Jokul Fin - 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.