BRI Direct Debit Guide

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

Direct API - BRI Direct Debit Activation

Direct API - BRI Direct Debit Credential Request Step 1

Direct API - BRI Direct Debit Credential Request Step 2

Login to DOKU Back Office
Go to Configuration > Direct Debit
Select BRI Direct Debit and click Activate button
Input Consumer Key
Input Consumer 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 register card
Resend OTP for payment
Delete token

Advanced Features:

Create a recurring payment

1. Register Debit card (tokenization)

Here is the flow for registering card:

Direct API - BRI Direct Debit Register Card Sequence Diagram

= Direct API - BRI 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/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

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": "CUST-0001",
        "name": "Anton Budiman",
        "email": "anton@example.com",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID",
        "id_card": "182918299187776",
        "date_of_birth": "15-12-1996"
    },
    "debit_card": {
        "account_email": "anton@example.com",
        "account_mobile_phone": "6286241451232",
        "card_expiry": "0525",
        "card_last_four": "8224",
        "card_number": "12344567890"
    }
}

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: `50`
`customer.name`	`string`	Optional	Customer name Allowed chars: `alphabetic` Max Length: `70`
`customer.email`	`string`	Optional	Customer email Allowed chars: `alphabetic, numeric, special chars` Max Length: `255`
`customer.phone`	`string`	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`
`debit_card.account_email`	`string`	Conditional	Registered email on bank account (Mandatory and must be valid if use multiple account feature)
`debit_card.account_mobile_phone`	`string`	Mandatory	Registered phone number on the BRI. Format: `{calling_code}{phone_number}`.Example: 6281122334455 Max Length: `20`
`debit_card.card_expiry`	`string`	Mandatory	Debit card expired date. Format: `MMyy`. Example the expiry date is February 2025, then the value is `0225`
`debit_card.card_last_four`	`string`	Mandatory	Last 4 digit of the Debit Card number Max Length: `4`
`debit_card.card_number`	`string`	Conditional	Card number, Mandatory if not send `card_last_four` Max Length: `16`

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": {
        "id": "CUST-0001",
        "name": "Anton Budiman",
        "email": "anton@example.com",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID",
        "id_card": "182918299187776",
        "date_of_birth": "15-12-1996"
    },
    "debit_card": {
        "token_id": "243591d7e49f45109961581718c3ef82",
        "status": "INACTIVE",
        "message": "Waiting for validate OTP"
    }
}

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
`debit_card.token_id`	`string`	Mandatory	Token generated by DOKU for the Debit card to use when do payment Max length: `128`
`debit_card.status`	`string`	Mandatory	Token status. In this state, it should be `INACTIVE`
`debit_card.message`	`string`	Mandatory	The 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 24 hours.

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

Type	Value
HTTP Method	POST
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

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:

{
    "debit_card": {
        "token_id"  : "243591d7e49f45109961581718c3ef82",
        "otp"       : "999999"
    }
}

Request Body Explanation

Parameter	Type	Mandatory	Description
`debit_card.token_id`	`string`	Mandatory	Token generated by DOKU for the Debit card to use when do payment Max length: `128`
`debit_card.otp`	`string`	Mandatory	The Register Card OTP that sent by the BRI to the customer Max length: `6`

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: 4127892a-8b23-49d8-8277-c3b4fd1c786c
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:

{
    "debit_card": {
        "token_id": "243591d7e49f45109961581718c3ef82",
        "status": "SUCCESS",
        "message": "Success Register Card"
    }
}

Response Body Explanation

Parameter	Type	Mandatory	Description
`debit_card.token_id`	`string`	Mandatory	Same as the request
`debit_card.status`	`string`	Mandatory	Token status. In this state, it should be `SUCCESS`
`debit_card.message`	`string`	Mandatory	The 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

Type	Value
HTTP Method	POST
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

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":"CUST-0001",
        "name": "Anton Budiman"
    }
}

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": "CUST-0001",
            "name": "Anton Budiman",
        },
        "debit_card": {
            "token_id": "243591d7e49f45109961581718c3ef82",
            "card_last_four": "8224"
        }
    }
]

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.card_last_four`	`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 - BRI Direct Debit Payment Sequence Diagram

Direct API - BRI 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/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

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:

{
    "order": {
        "amount": 90000,
        "invoice_number": "INV-20210118-0001",
        "line_items": [
            {
                "name": "T-Shirt Red",
                "price": 30000,
                "quantity": 2
            },
            {
                "name": "Polo Navy",
                "price": 30000,
                "quantity": 1
            }
        ]
    },
    "payment": {
        "token_id": "243591d7e49f45109961581718c3ef82",
        "otp_expiration_timestamp": 360010
    },
    "customer": {
        "id": "CUST-0001",
        "name": "Anton Budiman",
        "email": "anton@example.com",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID",
        "id_card": "182918299187776",
        "date_of_birth": "15-12-1996"
    }
}

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`	`string`	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`
`order.amount`	`number`	Mandatory	In IDR Currency and without decimal Allowed chars: `numeric` Max length: `12`
`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 Allowed chars: `alphabetic, numeric, special chars`
`order.line_items.price`	`number`	Optional	Price of the product item. Total price and quantity must match with the `order.amount` Allowed chars: `numeric`
`order.line_items.quantity`	`number`	Optional	Quantity of the product item Allowed chars: `numeric`
`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:

{
    "order": {
        "invoice_number": "INV-20210118-0001",
        "amount": 90000,
        "line_items": [
            {
                "name": "T-Shirt Red",
                "price": 30000,
                "quantity": 2
            },
            {
                "name": "Polo Navy",
                "price": 30000,
                "quantity": 1
            }
        ]
    },
    "payment": {
        "token": "kSooS93xUk6kJu9VuH33ec5QjlYxoNDEc+AfnoZYaB0=",
        "status": "PENDING"
    },
    "customer": {
        "id": "CUST-0001",
        "name": "Anton Budiman",
        "email": "anton@example.com",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID",
        "id_card": "182918299187776",
        "date_of_birth": "15-12-1996"
    }
}

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.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	Payment 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 24 hours.

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

Type	Value
HTTP Method	POST
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

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": "kSooS93xUk6kJu9VuH33ec5QjlYxoNDEc+AfnoZYaB0=",
        "otp": "999999"
    }
}

Request Body Explanation

Parameter	Type	Mandatory	Description
`debit_card.token`	`string`	Mandatory	The token that generated by DOKU for the transaction Max length: `128`
`debit_card.otp`	`string`	Mandatory	The Payment OTP that sent by the BRI to the customer Max length: `6`

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:

{
    "order": {
        "invoice_number": "INV-20210118-0001",
        "amount": 90000,
        "line_items": [
            {
                "name": "T-Shirt Red",
                "price": 30000,
                "quantity": 2
            },
            {
                "name": "Polo Navy",
                "price": 30000,
                "quantity": 1
            }
        ]
    },
    "payment": {
        "token": "kSooS93xUk6kJu9VuH33ec5QjlYxoNDEc+AfnoZYaB0=",
        "status": "SUCCESS"
    },
    "customer": {
        "id": "CUST-0001",
        "name": "Anton Budiman",
        "email": "anton@example.com",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID",
        "id_card": "182918299187776",
        "date_of_birth": "15-12-1996"
    }
}

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

Type	Value
HTTP Method	POST
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

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

{
    "debit_card": {
        "token_id": "243591d7e49f45109961581718c3ef82"
    }
}

Request Body Explanation

Parameter	Type	Mandatory	Description
`debit_card.token_id`	`string`	Mandatory	The token that generated by DOKU for the transaction 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: 8b6758ee-167b-4253-916a-4ad06cbc898f
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:

{
    "debit_card": {
        "token_id": "243591d7e49f45109961581718c3ef82"
    }
}

Response Body Explanation

Parameter	Type	Mandatory	Description
`debit_card.token_id`	`string`	Mandatory	Same 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

Type	Value
HTTP Method	POST
API endpoint (Sandbox)	`https://api-sandbox.doku.com/direct-debit/v1/payment-otp`
API endpoint (Production)	`https://api.doku.com/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": "kSooS93xUk6kJu9VuH33ec5QjlYxoNDEc+AfnoZYaB0="
    }
}

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": "kSooS93xUk6kJu9VuH33ec5QjlYxoNDEc+AfnoZYaB0="
    }
}

Response Body Explanation

Parameter	Type	Mandatory	Description
`payment.token`	`string`	Mandatory	Same 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

Type	Value
HTTP Method	POST
API endpoint (Sandbox)	`https://api-sandbox.doku.com/direct-debit/v1/token-delete`
API endpoint (Production)	`https://api.doku.com/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": "CUST-0001",
        "name": "Anton Budiman"
    },
    "debit_card": {
        "token_id": "243591d7e49f45109961581718c3ef82"
    }
}

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": "CUST-0001",
        "name": "Anton Budiman"
    },
    "debit_card": {
        "token_id": "243591d7e49f45109961581718c3ef82",
        "status": "SUCCESS",
        "message": "Succes 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

4. Recurring Payment

To create the recurring 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/direct-debit/v1/payment-recurring`
API endpoint (Production)	`https://api.doku.com/direct-debit/v1/payment-recurring`

Here is the sample of request header to create the recurring 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 recurring payment:

{
    "customer": {
        "id":"1232131321",
        "name":"Jessica Tessalonika",
        "email":"jessica@gmail.com",
        "phone":"081287458232",
        "id_card":"",
        "country":"ID",
        "address":"Jakarta, Menara Mulia Lt 8",
        "date_of_birth":"08-09-1998",
        "additional_info":""
    },
    "additional_info":{},
    "order": {
        "invoice_number":"MINV20201231468",
        "line_items": [
            {
            "name": "bola",
            "price": 10000,
            "quantity": 1
            },
            {
            "name": "ubi",
            "price": 5000,
            "quantity": 1
            }
        ],
        "amount": 15000,
        "session_id":"session"
    },
    "payment": {
        "token_id":"bcdbcdbcdbcbdbcdb-bcdbcd-bcdbcdb"
    }
}

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`	`string`	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`
`customer.additional_info`	`string`	Optional	Customer additional info
`additional_info`	`string`	Optional	additional info
`order.amount`	`number`	Mandatory	In IDR Currency and without decimal Allowed chars: `numeric` Max length: `12`
`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 Allowed chars: `alphabetic, numeric, special chars`
`order.line_items.price`	`number`	Optional	Price of the product item. Total price and quantity must match with the `order.amount` Allowed chars: `numeric`
`order.line_items.quantity`	`number`	Optional	Quantity of the product item Allowed chars: `numeric`
`order.session_id`	`string`	Optional	Transaction session id
`payment.card_token`	`string`	Mandatory	Token created from debit card data that linked to customer id (token id)

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:

{
    "acquirer": {
        "id":"BRI"
    },
    "customer": {
        "id":"1232131321",
        "name":"Jessica Tessalonika",
        "email":"jessica@gmail.com",
        "phone":"081287458232",
        "id_card":"",
        "country":"ID",
        "address":"Jakarta, Menara Mulia Lt 8",
        "date_of_birth":"",
        "additional_info":""
    },
    "additional_info":{},
    "order": {
        "invoice_number":"MINV20201231468",
        "line_items": [
            {
            "name": "bola",
            "price": 10000,
            "quantity": 1
            },
            {
            "name": "ubi",
            "price": 5000,
            "quantity": 1
            }
        ],
        "amount": 15000,
        "session_id":"session"
    },
    "payment": {
        "payment_id":"123212313",  
        "token":"qweqweqwewqeqwdasdassad",
        "status":"SUCCESS"
    }
}

Response Body Explanation

Parameter	Type	Mandatory	Description
`acquirer.id`	`string`	Mandatory	Bank Acquirer
`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
`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
`order.session_id`	`string`	Optional	Transaction session id
`payment.payment_id`	`string`	Mandatory	Payment ID generated by Acquirer
`payment.token`	`string`	Mandatory	Payment token generated by DOKU specific for the transaction
`payment.status`	`string`	Mandatory	Payment status. In this state, it should be `PENDING`

Tokenization

Want to make your checkout experience faster? You can combine this integration with the DOKU Token, 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​

1.1. Validate register Debit Card OTP​

Maximum Retry OTP is 5 times

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​

Maximum Retry OTP is 5 times

API Request​

API Response​

4. Acknowledge payment result​

Additional Features​

1. Resend OTP for register card​

API Request​

API Response​

2. Resend OTP for payment​

API Request​

API Response​

3. Delete the token​

API Request​

API Response​

4. Recurring Payment​

API Request​

API Response​

Tokenization​

Split Settlement​

Requirements

Integration steps

1. Register Debit card (tokenization)

API Request

API Response

1.1. Validate register Debit Card OTP

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

API Request

API Response

2. Resend OTP for payment

API Request

API Response

3. Delete the token

API Request

API Response

4. Recurring Payment

API Request

API Response

Tokenization

Split Settlement