BRI Direct Debit Guide

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


Requirements

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

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

Jokul Direct - BRI Direct Debit Credential RequestJokul Direct BRI Direct Debit Credential Request Step 1Jokul Direct BRI Direct Debit Credential Request Step 2
  1. Login to Jokul Back Office
  2. Go to Configuration > Direct Debit
  3. Select BRI Direct Debit and click Activate button
  4. Select No
  5. Click Request button
  6. Our team will contact you within 5 working days with the credentials

After received the credentials from our team, you can set the Consumer Key and Consumer Secret to the Configuration page.

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

Congratulations! You are now ready for the integration.


Integration steps

Here is the overview how you integrate 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 register card
  2. Resend OTP for payment
  3. Delete token

Advanced Features:

  1. Create a recurring payment

1. Register Debit card (tokenization)

Here is the flow for registering card:

Jokul Direct - BRI Direct Debit Register Card Sequence DiagramJokul Direct BRI 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/direct-debit/v1/token
API endpoint (Production)https://api.doku.com/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
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:

{
"acquirer": {
"id":"BRI"
},
"customer": {
"id": "00000000016",
"name": "Taufik Ismail",
"email": "taufik@example.com",
"phone": "628621278167",
"id_card": "182918299187776",
"address": "Menara Mulia Lantai 8",
"country": "ID",
"date_of_birth": "15-12-1996"
},
"debit_card": {
"account_email": "anton@budiman.com",
"account_mobile_phone": "6286241451232",
"card_expiry": "0525",
"card_last_four": "8224"
}
}
Request Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatoryThe acquiring that will process the transaction. In this case the value is BRI
customer.idstringMandatoryUnique customer identifier generated by merchant. Required to generate payment token.
Allowed chars: alphabetic, numeric, special chars
Max Length: 50
customer.namestringOptionalCustomer name
Allowed chars: alphabetic
Max Length: 255
customer.emailstringOptionalCustomer email
Allowed chars: alphabetic, numeric, special chars
Max Length: 128
customer.phonestringOptionalCustomer phone number. Format: {calling_code}{phone_number}. Example: 6281122334455
Allowed chars: numeric
Max Length: 16
customer.id_cardstringOptionalCustomer Identity Card number (KTP) for our risk engine assessment
Allowed chars: alphabetic, numeric, special chars
Max length: 64
customer.addressstringOptionalCustomer address
Allowed chars: alphabetic, numeric, special chars
Max Length: 400
customer.countrystringOptional2 alphabetic country code ISO 3166-1
Allowed chars: alphabetic
Min-max Length: 2
customer.date_of_birthstringOptionalCustomer date of birth for our risk engine assesment
Format: dd-MM-yyyy
debit_card.account_emailstringOptionalRegistered email on the BRI
debit_card.account_mobile_phonestringMandatoryRegistered phone number on the BRI. Format: {calling_code}{phone_number}. Example: 6281122334455
debit_card.card_expirystringMandatoryDebit card expired date. Format: MMyy. Example the expiry date is February 2025, then the value is 0225
debit_card.card_last_fourstringMandatoryLast 4 digit of the Debit Card number

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-10791114622547
Request-Id: 672118bb-9963-43ce-93b2-26d4fd0732a3
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: 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:

{
"acquirer": {
"id":"BRI"
},
"customer": {
"id": "00000000016",
"name": "Taufik Ismail",
"email": "taufik@example.com",
"phone": "628621278167",
"id_card": "182918299187776",
"address": "Menara Mulia Lantai 8",
"country": "ID",
"date_of_birth": "15-12-1996"
},
"debit_card": {
"token_id": "TOK_MKZTIFPRLLDPIBH5BJNZWFUV4WE2ZO56::062116:56:56.355",
"status": "INACTIVE",
"message": "Waiting for validate OTP"
}
}
Response Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatorySame as the request
customer.idstringMandatorySame as the request
customer.namestringOptionalSame as the request
customer.emailstringOptionalSame as the request
customer.phonestringOptionalSame as the request
customer.id_cardstringOptionalSame as the request
customer.addressstringOptionalSame as the request
customer.countrystringOptionalSame as the request
customer.date_of_birthstringOptionalSame as the request
debit_card.token_idstringMandatoryToken generated by Jokul for the Debit card to use when do payment
Max length: 256
debit_card.statusstringMandatoryToken status. In this state, it should be INACTIVE
debit_card.messagestringMandatoryThe registration message

1.1. Validate register Debit Card OTP

Maximum Retry OTP is 5 times

The customer only have 5 times maximum for retrying the OTP if the OTP they input is invalid. After that, the card will temporary blocked by the BRI for 10-15 minutes.

Now the token is generated but the status is INACTIVE. BRI 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/direct-debit/v1/token/validate
API endpoint (Production)https://api.doku.com/direct-debit/v1/token/validate

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

Client-Id: MCH-0001-10791114622547
Request-Id: 4127892a-8b23-49d8-8277-c3b4fd1c786c
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: 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:

{
"acquirer": {
"id":"BRI"
},
"debit_card": {
"token_id" : "TOK_MKZTIFPRLLDPIBH5BJNZWFUV4WE2ZO56::062116:56:56.355",
"otp" : "999999"
}
}
Request Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatoryThe acquiring that will process the transaction. In this case the value is BRI
debit_card.token_idstringMandatoryToken generated by Jokul for the Debit card to use when do payment
Max length: 256
debit_card.otpstringMandatoryThe Register Card OTP that sent by the BRI to the customer

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-10791114622547
Request-Id: 4127892a-8b23-49d8-8277-c3b4fd1c786c
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: 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:

{
"acquirer":{
"id": "BRI"
},
"debit_card": {
"token_id": "TOK_MKZTIFPRLLDPIBH5BJNZWFUV4WE2ZO56::062116:56:56.355",
"status": "SUCCESS",
"message": "Success Register Card"
}
}
Response Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatorySame as the request
debit_card.token_idstringMandatorySame as the request
debit_card.statusstringMandatoryToken status. In this state, it should be SUCCESS
debit_card.messagestringMandatoryThe message to indicates the card has been registered (binded)

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/direct-debit/v1/tokens
API endpoint (Production)https://api.doku.com/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
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":"00000000016",
"name": "Anton Budiman"
}
}
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: 255

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-10791114622547
Request-Id: 415f8064-ce1c-4c94-84b8-167201fd47cb
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: 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:

[
{
"acquirer": {
"id": "BRI"
},
"customer": {
"id":"00000000016",
"name": "Anton Budiman"
},
"debit_card": {
"token_id": "TOK_MKZTIFPRLLDPIBH5BJNZWFUV4WE2ZO56::062116:56:56.355",
"card_last_four": "8224"
}
}
]
Response Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatoryThe acquiring that process the transaction
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: 256
debit_card.card_last_fourstringMandatoryLast 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 - BRI Direct Debit Payment Sequence DiagramJokul Direct BRI 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/direct-debit/v1/payment
API endpoint (Production)https://api.doku.com/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
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:

{
"acquirer": {
"id": "BRI"
},
"customer": {
"id": "00000000016",
"name": "Taufik Ismail",
"email": "taufik@example.com",
"phone": "628621278167",
"id_card": "182918299187776",
"address": "Menara Mulia Lantai 8",
"country": "ID",
"date_of_birth": "15-12-1996"
},
"order": {
"amount": 90000,
"invoice_number": "INV-20210118-0001",
"line_items": [
{
"name": "DOKU T-Shirt Red",
"price": 30000,
"quantity": 2
},
{
"name": "DOKU T-Shirt Black",
"price": 30000,
"quantity": 1
}
]
},
"payment": {
"token_id": "TOK_MKZTIFPRLLDPIBH5BJNZWFUV4WE2ZO56::062116:56:56.355"
}
}
Request Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatoryThe acquirer that will process the transaction. Please put BRI as the value
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: 255
customer.namestringOptionalCustomer name
Allowed chars: alphabetic
Max Length: 255
customer.emailstringOptionalCustomer email
Allowed chars: alphabetic, numeric, special chars
Max Length: 128
customer.phonestringOptionalCustomer phone number. Format: {calling_code}{phone_number}. Example: 6281122334455
Allowed chars: numeric
Max Length: 16
customer.id_cardstringOptionalCustomer Identity Card number (KTP) for our risk engine assessment
Allowed chars: alphabetic, numeric, special chars
Max length: 64
customer.addressstringOptionalCustomer address
Allowed chars: alphabetic, numeric, special chars
Max Length: 400
customer.countrystringOptional2 alphabetic country code ISO 3166-1
Allowed chars: alphabetic
Min-max Length: 2
customer.date_of_birthstringOptionalCustomer date of birth for our risk engine assesment
Format: dd-MM-yyyy
order.amountnumberMandatoryIn IDR Currency and without decimal
Allowed chars: numeric
Max length: 14
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
Allowed chars: alphabetic, numeric, special chars
Max Length: 255
order.line_items.pricenumberOptionalPrice of the product item. Total price and quantity must match with the order.amount
Allowed chars: numeric
Max Length: 12
order.line_items.quantitynumberOptionalQuantity of the product item
Allowed chars: numeric
Max Length: 4
payment.token_idstringMandatoryThe token that will be use for this transaction

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-10791114622547
Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22e
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: 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:

{
"acquirer": {
"id": "BRI"
},
"customer": {
"id": "00000000016",
"name": "Taufik Ismail",
"email": "taufik@example.com",
"phone": "628621278167",
"id_card": "182918299187776",
"address": "Menara Mulia Lantai 8",
"country": "ID",
"date_of_birth": "15-12-1996"
},
"order": {
"amount": 90000,
"invoice_number": "INV-20210118-0001",
"line_items": [
{
"name": "DOKU T-Shirt Red",
"price": 30000,
"quantity": 2
},
{
"name": "DOKU T-Shirt Black",
"price": 30000,
"quantity": 1
}
]
},
"payment": {
"token": "kSooS93xUk6kJu9VuH33ec5QjlYxoNDEc+AfnoZYaB0=",
"status": "PENDING"
}
}
Response Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatorySame as the request
customer.idstringMandatorySame as the request
customer.namestringOptionalSame as the request
customer.emailstringOptionalSame as the request
customer.phonestringOptionalSame as the request
customer.id_cardstringOptionalSame as the request
customer.addressstringOptionalSame as the request
customer.countrystringOptionalSame 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.tokenstringMandatoryPayment token generated by Jokul specific for the transaction
payment.statusstringMandatoryPayment status. In this state, it should be PENDING

3.1. Validate payment OTP

Maximum Retry OTP is 5 times

The customer only have 5 times maximum for retrying the OTP if the OTP they input is invalid. After that, the card will temporary blocked by the BRI for 10-15 minutes.

Now the payment is created but the status is PENDING. BRI 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/direct-debit/v1/payment/validate
API endpoint (Production)https://api.doku.com/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
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:

{
"acquirer":{
"id": "BRI"
},
"payment":{
"token": "kSooS93xUk6kJu9VuH33ec5QjlYxoNDEc+AfnoZYaB0=",
"otp": "999999"
}
}
Request Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatoryThe acquirer that will process the transaction. Please put BRI as the value
debit_card.tokenstringMandatoryThe token that generated by Jokul for the transaction
Max length: 256
debit_card.otpstringMandatoryThe Payment OTP that sent by the BRI to the customer

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-10791114622547
Request-Id: bce963fc-bb93-4ef2-948a-7838044b537e
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: 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": "00000000016",
"name": "Taufik Ismail",
"email": "taufik@example.com",
"phone": "628621278167",
"id_card": "182918299187776",
"address": "Menara Mulia Lantai 8",
"country": "ID",
"date_of_birth": "15-12-1996"
},
"order": {
"amount": 90000,
"invoice_number": "INV-20210118-0001",
"line_items": [
{
"name": "DOKU T-Shirt Red",
"price": 30000,
"quantity": 2
},
{
"name": "DOKU T-Shirt Black",
"price": 30000,
"quantity": 1
}
]
},
"payment": {
"token": "kSooS93xUk6kJu9VuH33ec5QjlYxoNDEc+AfnoZYaB0=",
"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.id_cardstringOptionalSame as the request
customer.addressstringOptionalSame as the request
customer.countrystringOptionalSame 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.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:


Optional 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 register card

If for some reasons, your customers didn't receive the OTP when registering their card. You can use this API to resend new OTP.

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

API Request

TypeValue
HTTP MethodPOST
API endpoint (Sandbox)https://api-sandbox.doku.com/direct-debit/v1/token-otp
API endpoint (Production)https://api.doku.com/direct-debit/v1/token-otp

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

Client-Id: MCH-0001-10791114622547
Request-Id: 8b6758ee-167b-4253-916a-4ad06cbc898f
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: 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 register card:

{
"acquirer": {
"id":"BRI"
},
"debit_card": {
"token_id":"TOK_MKZTIFPRLLDPIBH5BJNZWFUV4WE2ZO56::062116:56:56.355"
}
}
Request Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatoryThe acquirer that will process the transaction. Please put BRI as the value
debit_card.token_idstringMandatoryThe token that generated by Jokul for the transaction
Max length: 256

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-10791114622547
Request-Id: 8b6758ee-167b-4253-916a-4ad06cbc898f
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: 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:

{
"acquirer": {
"id":"BRI"
},
"debit_card": {
"token_id":"TOK_MKZTIFPRLLDPIBH5BJNZWFUV4WE2ZO56::062116:56:56.355"
}
}
Response Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatorySame as the request
debit_card.token_idstringMandatorySame as the request

2. 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/direct-debit/v1/token-otp
API endpoint (Production)https://api.doku.com/direct-debit/v1/token-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
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:

{
"acquirer": {
"id":"BRI"
},
"payment": {
"token":"kSooS93xUk6kJu9VuH33ec5QjlYxoNDEc+AfnoZYaB0="
}
}
Request Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatoryThe acquirer that will process the transaction. Please put BRI as the value
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-10791114622547
Request-Id: ea41603d-8f77-43ba-9dc3-def0766fe69b
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: 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:

{
"acquirer": {
"id":"BRI"
},
"payment": {
"token":"kSooS93xUk6kJu9VuH33ec5QjlYxoNDEc+AfnoZYaB0="
}
}
Response Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatorySame as the request
payment.tokenstringMandatorySame as the request

3. 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/direct-debit/v1/token-otp
API endpoint (Production)https://api.doku.com/direct-debit/v1/token-otp

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

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

{
"acquirer": {
"id": "BRI"
},
"customer": {
"id": "00000000016",
"name": "Anton Budiman"
},
"debit_card": {
"token_id": "TOK_MKZTIFPRLLDPIBH5BJNZWFUV4WE2ZO56::062116:56:56.355"
}
}
Request Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatoryThe acquiring that will process the transaction. In this case the value is BRI
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: 255
debit_card.token_idstringMandatoryToken generated by Jokul for the Debit card to use when do payment
Max length: 256

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-10791114622547
Request-Id: c8154b5b-25fa-430d-9e5f-5a8a34d6d371
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: 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:

{
"acquirer": {
"id": "BRI"
},
"customer": {
"id": "00000000016",
"name": "Anton Budiman"
},
"debit_card": {
"token_id": "TOK_MKZTIFPRLLDPIBH5BJNZWFUV4WE2ZO56::062116:56:56.355",
"status": "SUCCESS",
"message": "Succes Unbinding Card"
}
}
Response Body Explanation
ParameterTypeMandatoryDescription
acquirer.idstringMandatorySame as the request
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

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