DOKU DocsChangelogDOKU Github

Host-To-Host Integration Guide

Host to Host Integration Guide

If you are PCI DSS compliance, you can use this type of integration to receive card payments.

Payment types​

There are 5 payment types available depends on your needs:

  1. SALE

  2. MOTO

  3. AUTHORIZE CAPTURE

  4. INSTALLMENT

  5. RECURRING

(SALE) Integration steps​

Here is the overview of how to integrate SALE payment:

  1. Prepare credit card form input / Get token list

  2. Get 3DS authentication ID and 3DS URL

  3. Hit API Charge

  4. Acknowledge payment result

DOKU Direct - Credit Card H2H SALE Sequence Diagram

1. Prepare credit card form input / Get token list​

You can create credit card form input on your end, so that your customer can input their credit card number, expiry date, and CVV.

If you save the card token from DOKU side, you can use Tokenization to show the saved card of your customers.

2. Get 3DS authentication ID and 3DS URL​

To get 3DS authentication, you will need to hit this API through your backend:

API Request​

TypeValue

HTTP Method

POST

API endpoint (Sandbox)

https://api-sandbox.doku.com/credit-card/check-three-d-secure

API endpoint (Production)

https://api.doku.com/credit-card/check-three-d-secure

Here is the sample of request header to get 3DS authentication:

Client-Id: MCH-0001-10791114622547
Request-Id: 6d0bffbd-9246-455e-a1f1-44c1f76ad589
Request-Timestamp: 2021-08-24T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=

Request Header Explanation

ParameterDescription

Client-Id

Client ID retrieved from DOKU Back Office

Request-Id

Unique random string (max 128 characters) generated from merchant side to protect duplicate request

Request-Timestamp

Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z

Signature

Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample request body to get 3DS authentication:

{
    "order": {
        "amount": 90000,  
        "invoice_number": "test_invoice"
    },
    "card": {
        "token": "243591d7e49f45109961581718c3ef82",
        "number": "5573381011111101",
        "expiry": "1225"
    },
    "three_dsecure": {
        "callback_url_success": "https://www.merchant.com/success",
        "callback_url_failed": "https://www.merchant.com/failed"
    },
    "invoice_number": {
        "callback_url_success": "https://www.merchant.com/success",
        "callback_url_failed": "https://www.merchant.com/failed"
    },
}

Request Body Explanation

ParameterTypeMandatoryDescription

order.amount

number

Mandatory

In IDR Currency and without decimal Allowed chars: numeric Max length: 12

order.invoice_number

string

Optional

Invoice number of the transaction, if brought use consistent invoice number during charge as well Recommended to bring

card.token

string

Optional

Card token generated by DOKU, can be used if you already activate tokenization

card.number

string

Mandatory

Card number, can be optional if you sent card.token

card.expiry

string

Mandatory

Card expiry date, can be optional if you sent card.token Format: MMYY

three_dsecure.callback_url_success

string

Mandatory

After 3DS process success, customer will be redirected to this page

three_dsecure.callback_url_failed

string

Mandatory

After 3DS process success, customer will be redirected to this page

API Response​

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

TypeValue

HTTP Status

200

Result

SUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

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": {
        "amount": 90000
    },
    "three_dsecure": {
        "enrollment_status": true,
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e",
        "authentication_url": "https://doku.3ds.com?authenticationId=eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    }
}

Response Body Explanation

ParameterTypeMandatoryDescription

order.amount

number

Mandatory

Same as the request

three_dsecure.enrollment_status

boolean

Mandatory

Card 3D Secure enrollment status Possible value: true, false

three_dsecure.authentication_id

string

Mandatory

3DS process ID to use on API Charge

three_dsecure.authentication_url

string

Optional

3DS page if the three_dsecure.enrollment_status is true

3. Hit API Charge​

After the customer is redirected to the 3DS success page, then your backend must trigger the API Charge to DOKU:

API Request​

TypeValue

HTTP Method

POST

API endpoint (Sandbox)

https://api-sandbox.doku.com/credit-card/charge

API endpoint (Production)

https://api.doku.com/credit-card/charge

Here is the sample of request header to charge the transaction:

Client-Id: MCH-0001-10791114622547
Request-Id: b154c582-4501-436a-8012-0346f2a46b47
Request-Timestamp: 2021-08-24T08:46:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=

Request Header Explanation

ParameterDescription

Client-Id

Client ID retrieved from DOKU Back Office

Request-Id

Unique random string (max 128 characters) generated from merchant side to protect duplicate request

Request-Timestamp

Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z

Signature

Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample request body to charge the transaction:

{
    "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
            }
        ]
    },
    "customer": {
        "id": "CUST-0001",
        "name": "Anton Budiman",
        "email": "anton@example.com",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID"
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    },
    "payment": {
        "type": "SALE",
        "tenor": "12",
        "plan_id": "1232131"
    },
    "card": {
        "token": "243591d7e49f45109961581718c3ef82",
        "number": "5573381011111101",
        "expiry": "1225",
        "cvv": "123",
        "save": true
    }
}

Request Body Explanation

ParameterTypeMandatoryDescription

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: 30 (27 If you have Mandiri Acquirer)

order.line_items.name

string

Optional

Name of the product item Allowed chars: alphabetic, numeric, special chars Max Length: 255

order.line_items.price

number

Optional

Price of the product item. Total price and quantity must match with the order.amount Allowed chars: numeric Max Length: 12

order.line_items.quantity

number

Optional

Quantity of the product item Allowed chars: numeric Max Length: 4

customer.id

string

Conditional

Unique customer identifier generated by merchant. Mandatory if merchant wants to use tokenization feature. Allowed chars: alphabetic, numeric, special chars Max Length: 50

customer.name

string

Recommended

Customer name Allowed chars: alphabetic Max Length: 255

customer.email

string

Conditional

Customer email Allowed chars: alphabetic, numeric, special chars Bringing the proper email will improve Credit Card Approval Rate bringing atleast one of customer.email or customer.phone is mandatory

Max Length: 128

customer.phone

string

Conditional

Customer phone number. Format: {calling_code}{phone_number}. Example: 6281122334455 Allowed chars: numeric Max Length: 16

customer.address

string

Optional

Customer address Allowed chars: alphabetic, numeric, special chars Max Length: 400

customer.country

string

Optional

2 alphabetic country code ISO 3166-1 Allowed chars: alphabetic Min-max Length: 2

three_dsecure.authentication_id

string

Mandatory

After 3DS process success, customer will be redirected to this page

payment.type

string

Mandatory

Payment type Possible value: SALE, MOTO, AUTHORIZE

payment.tenor

string

Optional

Tenor for issuer that have installment feature with DOKU - For MOTO and SALE only

payment.plan_id

string

Optional

Promotion ID from the bank for merchant

card.token

string

Conditional

Card token generated by DOKU, for 3ds transaction please bring three_dsecure.authentication_id only

card.number

string

Conditional

Card number, can be optional if you sent card.token

card.expiry

string

Conditional

Card expiry date, can be optional if you sent card.token Format: MMYY

card.cvv

string

Mandatory

Card CVV, Optional if payment.type is MOTO

card.save

boolean

Optional

Set true if you are using card.number andwant to tokenize the card for the next payment Possible value: true, false Default value: false

API Response​

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

TypeValue

HTTP Status

200

Result

SUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

ParameterDescription

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
    },
    "customer": {
        "id": "CUST-0001"
    },
    "payment": {
        "type": "SALE",
        "identifier": [
           {
              "name": "Acquirer",
              "value": "Mandiri"
           },
           {
              "name": "MID",
              "value": "71003372992"
           },
           {
              "name": "TID",
              "value": "73120903"
           }
        ],
        "request_id": "20201026193843836",
        "authorize_id": "",
        "response_code": "01",
        "response_message": "sukses transaksi",
        "eci": "",
        "status": "SUCCESS",
        "approval_code": "123123"
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    },
    "card": {
        "masked": "557338*******101",
        "type": "CREDIT",
        "issuer": "Bank Mandiri",
        "brand": "MASTER",
        "token": "243591d7e49f45109961581718c3ef82"
    }
}

Response Body Explanation

ParameterTypeMandatoryDescription

order.invoice_number

string

Mandatory

Same as the request

order.amount

number

Mandatory

Same as the request

customer.id

string

Optional

Same as the request

payment.type

string

Mandatory

Same as the request

payment.identifier.name

string

Mandatory

Additional payment info name

payment.identifier.value

string

Mandatory

Additional payment info value

payment.request_id

string

Mandatory

Request ID sent on merchant's request header

payment.authorize_id

string

Optional

Authorize ID for authorize transaction. Mandatory if payment.type is AUTHORIZE

payment.response_code

string

Mandatory

Reponse code generated by DOKU / Acquirer

payment.response_message

string

Mandatory

Response message generated by DOKU / Acquirer

payment.status

string

Mandatory

Payment status Possible value: SUCCESS, FAILED, PENDING

payment.eci

string

Mandatory

ECI for this transaction

payment.approval_code

string

Optional

Approval code for success transaction generated by acquirer

three_dsecure.authentication_id

string

Mandatory

Same as the request

card.masked

string

Optional

Card masked number

card.type

string

Mandatory

Card type Possible value: CREDIT, DEBIT

card.issuer

string

Mandatory

Card issuer

card.brand

string

Mandatory

Principal brand VISA, MASTER, JCB, AMEX

card.token

string

Optional

Card token generated by DOKU if card.save is true

INFO

You can check the list of possible response code and how to handle them here

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:

(MOTO) Integration steps​

Here is the overview of how to integrate MOTO payment:

  1. Prepare credit card form input / Get token list

  2. Hit API Charge

  3. Acknowledge payment result

Jokul Direct - Credit Card H2H MOTO Sequence Diagram

1. Prepare credit card form input / Get token list​

You can create credit card form input on your end, so that your customer can input their credit card number, expiry date, and CVV.

If you save the card token from DOKU side, you can use Tokenization to show the saved card of your customers.

2. Hit API Charge​

After the customer input the credit card, then your backend must trigger the API Charge to DOKU:

API Request​

TypeValue

HTTP Method

POST

API endpoint (Sandbox)

https://api-sandbox.doku.com/credit-card/charge

API endpoint (Production)

https://api.doku.com/credit-card/charge

Here is the sample of request header to charge the transaction:

Client-Id: MCH-0001-10791114622547
Request-Id: b154c582-4501-436a-8012-0346f2a46b47
Request-Timestamp: 2021-08-24T08:46:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=

Request Header Explanation

ParameterDescription

Client-Id

Client ID retrieved from DOKU Back Office

Request-Id

Unique random string (max 128 characters) generated from merchant side to protect duplicate request

Request-Timestamp

Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z

Signature

Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample request body to charge the transaction:

{
    "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
            }
        ]
    },
    "customer": {
        "id": "CUST-0001",
        "name": "Anton Budiman",
        "email": "anton@example.com",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID"
    },
    "payment": {
        "type": "MOTO"
    },
    "card": {
        "token": "243591d7e49f45109961581718c3ef82",
        "number": "5573381011111101",
        "expiry": "1225",
        "save": true
    }
}

Request Body Explanation

ParameterTypeMandatoryDescription

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 Max Length: 255

order.line_items.price

number

Optional

Price of the product item. Total price and quantity must match with the order.amount Allowed chars: numeric Max Length: 12

order.line_items.quantity

number

Optional

Quantity of the product item Allowed chars: numeric Max Length: 4

customer.id

string

Conditional

Unique customer identifier generated by merchant. Mandatory if merchant wants to use tokenization feature. Allowed chars: alphabetic, numeric, special chars Max Length: 50

customer.name

string

Optional

Customer name Allowed chars: alphabetic Max Length: 255

customer.email

string

Optional

Customer email Allowed chars: alphabetic, numeric, special chars Max Length: 128

customer.phone

string

Optional

Customer phone number. Format: {calling_code}{phone_number}. Example: 6281122334455 Allowed chars: numeric Max Length: 16

customer.address

string

Optional

Customer address Allowed chars: alphabetic, numeric, special chars Max Length: 400

customer.country

string

Optional

2 alphabetic country code ISO 3166-1 Allowed chars: alphabetic Min-max Length: 2

payment.type

string

Mandatory

Payment type Possible value: SALE, MOTO, RECURRING, AUTHORIZE

card.token

string

Conditional

Token generated by DOKU Either card.token or card.number is mandatory (only 1 needed)

card.number

string

Conditional

Card number (PAN) Either card.token or card.number is mandatory (only 1 needed)

card.expiry

string

Conditional

Card expiry date, not needed if you sent card.token Format: MMYY

card.save

boolean

Optional

Set true if you are using card.number andwant to tokenize the card for the next payment Possible value: true, false Default value: false

API Response​

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

TypeValue

HTTP Status

200

Result

SUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

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
    },
    "customer": {
        "id": "CUST-0001"
    },
    "payment": {
        "type": "MOTO",
        "identifier": [
           {
              "name": "Acquirer",
              "value": "Mandiri"
           },
           {
              "name": "MID",
              "value": "71003372992"
           },
           {
              "name": "TID",
              "value": "73120903"
           }
        ],
        "request_id": "20201026193843836",
        "authorize_id": "",
        "response_code": "01",
        "response_message": "sukses transaksi",
        "eci": "",
        "status": "SUCCESS",
        "approval_code": "123123"
    },
    "card": {
        "masked": "557338*******101",
        "type": "CREDIT",
        "issuer": "Bank Mandiri",
        "brand": "MASTER",
        "token": "243591d7e49f45109961581718c3ef82"
    }
}

Response Body Explanation

ParameterTypeMandatoryDescription

order.invoice_number

string

Mandatory

Same as the request

order.amount

number

Mandatory

Same as the request

customer.id

string

Optional

Same as the request

payment.type

string

Mandatory

Same as the request

payment.identifier.name

string

Mandatory

Additional payment info name

payment.identifier.value

string

Mandatory

Additional payment info value

payment.request_id

string

Mandatory

Request ID sent on merchant's request header

payment.authorize_id

string

Optional

Authorize ID for authorize transaction. Mandatory if payment.type is AUTHORIZE

payment.response_code

string

Mandatory

Reponse code generated by DOKU / Acquirer

payment.response_message

string

Mandatory

Response message generated by DOKU / Acquirer

payment.status

string

Mandatory

Payment status Possible value: SUCCESS, FAILED, PENDING

payment.eci

string

Mandatory

ECI for this transaction

payment.approval_code

string

Optional

Approval code for success transaction generated by acquirer

card.masked

string

Optional

Card masked number

card.type

string

Mandatory

Card type Possible value: CREDIT, DEBIT

card.issuer

string

Mandatory

Card issuer

card.brand

string

Mandatory

Principal brand VISA, MASTER, JCB, AMEX

card.token

string

Optional

Card token generated by DOKU if card.save is true

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

(AUTHORIZE CAPTURE) Integration steps​

Here is the overview of how to integrate AUTHORIZE CAPTURE payment:

  1. Prepare credit card form input / Get token list

  2. Get 3DS authentication ID and 3DS URL

  3. Hit API Charge

  4. Hit API Capture

  5. Acknowledge payment result

Jokul Direct - Credit Card H2H AUTH CAP Sequence Diagram

1. Prepare credit card form input / Get token list​

You can create credit card form input on your end, so that your customer can input their credit card number, expiry date, and CVV.

If you save the card token from DOKU side, you can use Tokenization to show the saved card of your customers.

2. Get 3DS authentication ID and 3DS URL​

To get 3DS authentication, you will need to hit this API through your backend:

API Request​

TypeValue

HTTP Method

POST

API endpoint (Sandbox)

https://api-sandbox.doku.com/credit-card/check-three-d-secure

API endpoint (Production)

https://api.doku.com/credit-card/check-three-d-secure

Here is the sample of request header to get 3DS authentication:

Client-Id: MCH-0001-10791114622547
Request-Id: 6d0bffbd-9246-455e-a1f1-44c1f76ad589
Request-Timestamp: 2021-08-24T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=

Request Header Explanation

ParameterDescription

Client-Id

Client ID retrieved from DOKU Back Office

Request-Id

Unique random string (max 128 characters) generated from merchant side to protect duplicate request

Request-Timestamp

Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z

Signature

Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample request body to get 3DS authentication:

{
    "order": {
        "amount": 90000
    },
    "card": {
        "token": "243591d7e49f45109961581718c3ef82",
        "number": "5573381011111101",
        "expiry": "1225"
    },
    "three_dsecure": {
        "callback_url_success": "https://www.merchant.com/success",
        "callback_url_failed": "https://www.merchant.com/failed"
    }
}

Request Body Explanation

ParameterTypeMandatoryDescription

order.amount

number

Mandatory

In IDR Currency and without decimal Allowed chars: numeric Max length: 12

card.token

string

Optional

Card token generated by DOKU, can be used if you already activate tokenization

card.number

string

Mandatory

Card number, can be optional if you sent card.token

card.expiry

string

Mandatory

Card expiry date, can be optional if you sent card.token Format: MMYY

three_dsecure.callback_url_success

string

Mandatory

After 3DS process success, customer will be redirected to this page

three_dsecure.callback_url_failed

string

Mandatory

After 3DS process success, customer will be redirected to this page

API Response​

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

TypeValue

HTTP Status

200

Result

SUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

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": {
        "amount": 90000
    },
    "three_dsecure": {
        "enrollment_status": true,
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e",
        "authentication_url": "https://doku.3ds.com?authenticationId=eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    }
}

Response Body

ParameterTypeMandatoryDescription

order.amount

number

Mandatory

Same as the request

three_dsecure.enrollment_status

boolean

Mandatory

Card 3D Secure enrollment status Possible value: true, false

three_dsecure.authentication_id

string

Mandatory

3DS process ID to use on API Charge

three_dsecure.authentication_url

string

Optional

3DS page if the three_dsecure.enrollment_status is true

3. Hit API Charge​

After the customer is redirected to the 3DS success page, then your backend must trigger the API Charge to DOKU:

API Request​

TypeValue

HTTP Method

POST

API endpoint (Sandbox)

https://api-sandbox.doku.com/credit-card/charge

API endpoint (Production)

https://api.doku.com/credit-card/charge

Here is the sample of request header to charge the transaction:

Client-Id: MCH-0001-10791114622547
Request-Id: b154c582-4501-436a-8012-0346f2a46b47
Request-Timestamp: 2021-08-24T08:46:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=

Request Header Explanation

ParameterDescription

Client-Id

Client ID retrieved from DOKU Back Office

Request-Id

Unique random string (max 128 characters) generated from merchant side to protect duplicate request

Request-Timestamp

Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z

Signature

Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample request body to charge the transaction:

{
    "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
            }
        ]
    },
    "customer": {
        "id": "CUST-0001",
        "name": "Anton Budiman",
        "email": "anton@example.com",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID"
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    },
    "payment": {
        "type": "AUTHORIZE",
        "plan_id": "1232131"
    },
    "card": {
        "token": "243591d7e49f45109961581718c3ef82",
        "number": "5573381011111101",
        "expiry": "1225",
        "cvv": "123",
        "save": true
    }
}

Request Body Explanation

ParameterTypeMandatoryDescription

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 Max Length: 255

order.line_items.price

number

Optional

Price of the product item. Total price and quantity must match with the order.amount Allowed chars: numeric Max Length: 12

order.line_items.quantity

number

Optional

Quantity of the product item Allowed chars: numeric Max Length: 4

customer.id

string

Conditional

Unique customer identifier generated by merchant. Mandatory if merchant wants to use tokenization feature. Allowed chars: alphabetic, numeric, special chars Max Length: 50

customer.name

string

Optional

Customer name Allowed chars: alphabetic Max Length: 255

customer.email

string

Optional

Customer email Allowed chars: alphabetic, numeric, special chars Max Length: 128

customer.phone

string

Optional

Customer phone number. Format: {calling_code}{phone_number}. Example: 6281122334455 Allowed chars: numeric Max Length: 16

customer.address

string

Optional

Customer address Allowed chars: alphabetic, numeric, special chars Max Length: 400

customer.country

string

Optional

2 alphabetic country code ISO 3166-1 Allowed chars: alphabetic Min-max Length: 2

three_dsecure.authentication_id

string

Mandatory

After 3DS process success, customer will be redirected to this page

payment.type

string

Mandatory

Payment type Possible value: SALE, MOTO, AUTHORIZE

payment.plan_id

string

Optional

Promotion ID from the bank for merchant

card.token

string

Optional

Card token generated by DOKU, for 3ds transaction please bring three_dsecure.authentication_id only

card.number

string

Mandatory

Card number, can be optional if you sent card.token

card.expiry

string

Mandatory

Card expiry date, can be optional if you sent card.token Format: MMYY

card.cvv

string

Mandatory

Card CVV, Optional if payment.type is MOTO

card.save

boolean

Optional

Set true if you want to force customer to save the card token for the next payment Possible value: true, false Default value: false

API Response​

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

TypeValue

HTTP Status

200

Result

SUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

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
    },
    "customer": {
        "id": "CUST-0001"
    },
    "payment": {
        "type": "AUTHORIZE",
        "identifier": [
           {
              "name": "Acquirer",
              "value": "Mandiri"
           },
           {
              "name": "MID",
              "value": "71003372992"
           },
           {
              "name": "TID",
              "value": "73120903"
           }
        ],
        "request_id": "20201026193843836",
        "authorize_id": "12312391719112",
        "response_code": "01",
        "response_message": "sukses transaksi",
        "eci": "",
        "status": "SUCCESS",
        "approval_code": "123123"
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    },
    "card": {
        "masked": "557338*******101",
        "type": "CREDIT",
        "issuer": "Bank Mandiri",
        "brand": "MASTER",
        "token": "243591d7e49f45109961581718c3ef82"
    }
}

Response Body Explanation

ParameterTypeMandatoryDescription

order.invoice_number

string

Mandatory

Same as the request

order.amount

number

Mandatory

Same as the request

customer.id

string

Optional

Same as the request

payment.type

string

Mandatory

Same as the request

payment.identifier.name

string

Mandatory

Additional payment info name

payment.identifier.value

string

Mandatory

Additional payment info value

payment.request_id

string

Mandatory

Request ID sent on merchant's request header

payment.authorize_id

string

Mandatory

Authorize ID for authorize transaction. Mandatory if payment.type is AUTHORIZE

payment.response_code

string

Mandatory

Reponse code generated by DOKU / Acquirer

payment.response_message

string

Mandatory

Response message generated by DOKU / Acquirer

payment.status

string

Mandatory

Payment status Possible value: SUCCESS, FAILED, PENDING

payment.eci

string

Mandatory

ECI for this transaction

payment.approval_code

string

Optional

Approval code for success transaction generated by acquirer

three_dsecure.authentication_id

string

Mandatory

Same as the request

card.masked

string

Optional

Card masked number

card.type

string

Mandatory

Card type Possible value: CREDIT, DEBIT

card.issuer

string

Mandatory

Card issuer

card.brand

string

Mandatory

Principal brand VISA, MASTER, JCB, AMEX

card.token

string

Optional

Card token generated by DOKU if card.save is true

DOKU will also send the HTTP Notification with the payment.authorize_id to your defined Notification URL.

4. Hit API Capture​

After you get the payment.authorize_id, then your backend must trigger the API Charge to DOKU:

API Request​

TypeValue

HTTP Method

POST

API endpoint (Sandbox)

https://api-sandbox.doku.com/credit-card/capture

API endpoint (Production)

https://api.doku.com/credit-card/capture

Here is the sample of request header to capture the transaction:

Client-Id: MCH-0001-10791114622547
Request-Id: 071a6a32-6785-4011-833d-d2c2049cf744
Request-Timestamp: 2021-08-24T08:46:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=

Request Header Explanation

ParameterDescription

Client-Id

Client ID retrieved from DOKU Back Office

Request-Id

Unique random string (max 128 characters) generated from merchant side to protect duplicate request

Request-Timestamp

Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z

Signature

Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample request body to capture the transaction:

{
    "payment": {
        "authorize_id": "12312391719112",
        "capture_amount": 90000
    }
}

Request Body Explanation

ParameterTypeMandatoryDescription

payment.authorize_id

string

Mandatory

Authorize ID from the Charge API Response / HTTP Notification

payment.capture_amount

string

Optional

The value of transactions which will be paid by the customer. If undefined, capture full transaction.

API Response​

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

TypeValue

HTTP Status

200

Result

SUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

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
    },
    "customer": {
        "id": "CUST-0001"
    },
    "payment": {
        "type": "CAPTURE",
        "identifier": [
           {
              "name": "Acquirer",
              "value": "Mandiri"
           },
           {
              "name": "MID",
              "value": "71003372992"
           },
           {
              "name": "TID",
              "value": "73120903"
           }
        ],
        "request_id": "20201026193843836",
        "authorize_id": "12312391719112",
        "response_code": "01",
        "response_message": "sukses transaksi",
        "eci": "",
        "status": "SUCCESS",
        "approval_code": "123123"
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    },
    "card": {
        "masked": "557338*******101",
        "type": "CREDIT",
        "issuer": "Bank Mandiri",
        "brand": "MASTER",
        "token": "243591d7e49f45109961581718c3ef82"
    }
}

Response Body Explanation

ParameterTypeMandatoryDescription

order.invoice_number

string

Mandatory

Same as the request

order.amount

number

Mandatory

Same as the request

customer.id

string

Optional

Same as the request

payment.type

string

Mandatory

Same as the request

payment.identifier.name

string

Mandatory

Additional payment info name

payment.identifier.value

string

Mandatory

Additional payment info value

payment.request_id

string

Mandatory

Request ID sent on merchant's request header

payment.authorize_id

string

Mandatory

Authorize ID for authorize transaction. Mandatory if payment.type is AUTHORIZE

payment.response_code

string

Mandatory

Reponse code generated by DOKU / Acquirer

payment.response_message

string

Mandatory

Response message generated by DOKU / Acquirer

payment.status

string

Mandatory

Payment status Possible value: SUCCESS, FAILED, PENDING

payment.eci

string

Mandatory

ECI for this transaction

payment.approval_code

string

Optional

Approval code for success transaction generated by acquirer

three_dsecure.authentication_id

string

Mandatory

Same as the request

card.masked

string

Optional

Card masked number

card.type

string

Mandatory

Card type Possible value: CREDIT, DEBIT

card.issuer

string

Mandatory

Card issuer

card.brand

string

Mandatory

Principal brand VISA, MASTER, JCB, AMEX

card.token

string

Optional

Card token generated by DOKU if card.save is true

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

List of Error Code​

If something happens, you can see the following error code to find out what error is happening :

APIError messageError CodeHTTP Status CodeExplanation

Check-three-d-secure

Invalid Client-Id

invalid_client_id

400

Invalid Client ID

Check-three-d-secure

Header Client-Id is required

invalid_header_request

400

empty client id

Check-three-d-secure

Invalid Header Signature

invalid_signature

400

Payment charge with invalid signature

Check-three-d-secure

Invalid CC Number LENGTH

INVALID_PARAMETER

400

Invalid CC Number LENGTH

Check-three-d-secure

Luhn Validation

INVALID_PARAMETER

400

Card number not valid

Check-three-d-secure

Expiry Date Validation

INVALID_PARAMETER

400

Invalid expiry date 2525

Check-three-d-secure

This field is required.,This merchant does not have three d secure configuration

INVALID_PARAMETER

400

invalid configuration / haven't 3ds mid

Check-three-d-secure

This card is not support three d secure

THREE_D_SECURE_AUTHENTICATION_FAILED

400

card not support 3ds / cannot connect to mpi

Charge

Invalid Client-Id

invalid_client_id

400

Invalid Client ID

Charge

empty client id

invalid_header_request

400

empty client id

Charge

size must be between 1 and 128

invalid_header_request

400

Payment charge with client id length more than max

Charge

Invalid format Header Request-Timestamp

invalid_header_request

400

Payment charge with invalid format request timestamp

Charge

Header Request-Timestamp is not in +- 10 second of now

invalid_header_request

400

Payment charge with request timestamp < now

Charge

Header Request-Timestamp is not in +- 10 second of now

invalid_header_request

400

Payment charge with request timestamp > now

Charge

Invalid Header Signature

invalid_signature

400

Payment charge with invalid signature

Charge

Invalid Header Signature

invalid_signature

400

Payment charge using signature has been used

Charge

Invalid Format Email

INVALID_PARAMETER

400

Payment charge with invalid format email

Charge

Invalid amount

INVALID_PARAMETER

400

Payment charge with amount contain comma

Charge

Invalid amount

INVALID_PARAMETER

400

Payment charge with amount contain dot

Charge

Expiry Date Validation

INVALID_PARAMETER

400

Payment charge with format expiry is YYMM

Charge

Expiry Date Validation

INVALID_PARAMETER

400

Payment charge with expiry date is expired

Charge

Invalid AuthenticationId.

INVALID_PARAMETER

400

invalid authentication_id

Charge

Country Is Not Exists

INVALID_PARAMETER

400

Payment charge with invalid country

Charge

Invalid CC Number LENGTH

INVALID_PARAMETER

400

Invalid CC Number LENGTH

Charge

Luhn Validation

INVALID_PARAMETER

400

Card number not valid

Charge

REQUEST ID IS NOT VALID

INVALID_PARAMETER

400

Payment charge with request id has been used for transaction

Charge

Unauthorized Transaction

MID_TID_NOT_EXIST

400

Payment charge sale using card rejected

Charge

Invalid Authentication Id

INVALID_PARAMETER

400

Invalid Authentication Id

Charge

Invalid Authentication Id

INVALID_PARAMETER

400

Different amount check 3ds & charge

Charge

Invalid Authentication Id

INVALID_PARAMETER

400

Three D Secure Process Not Yet Done (Not yet send OTP)

Charge

Line item 1 quantity must be not empty

INVALID_PARAMETER

400

Invalid line item (quantity is null)

Charge

Your transaction is detected to be concurrent, please create another transaction

DOUBLE_REQUEST_DETECTED

400

Concurent Request

Charge

Conflict

INVALID_PARAMETER

409

duplicate request with same request body

Charge

Precondition failed

INVALID_PARAMETER

412

duplicate request with different request body

Capture

Invalid Client-Id

invalid_client_id

400

Invalid Client ID

Capture

Header Client-Id is required

invalid_header_request

400

empty client id

Capture

Invalid Header Signature

invalid_signature

400

Payment charge with invalid signature

Capture

Authorize Id Must Not Be Blank

INVALID_PARAMETER

400

authorize_id is null

Capture

Failed Get Transaction

TRANSACTION_NOT_FOUND

400

Invalid authorize_id

Capture

Conflict

INVALID_PARAMETER

409

duplicate request with same request body

Capture

Precondition failed

INVALID_PARAMETER

412

duplicate request with different request body

PreviousPayment Page Integration GuideNextMastercard Automatic Billing Updater (ABU) Integration Guide

Last updated

DOKU API

Legacy Documentation