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 3 payment types available depends on your needs:

SALE
MOTO
AUTHORIZE CAPTURE

(SALE) Integration steps

Here is the overview of how to integrate SALE payment:

Prepare credit card form input / Get token list
Get 3DS authentication ID and 3DS URL
Hit API Charge
Acknowledge payment result

DOKU Direct - Credit Card H2H SALE Sequence Diagram

DOKU Direct Credit Card H2H SALE Merchant Flow

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

Type	Value
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

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

Here is the sample request body to 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

Parameter	Type	Mandatory	Description
`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.

Type	Value
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

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

Response Body Explanation

Parameter	Type	Mandatory	Description
`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

Type	Value
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

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

Here is the sample request body to 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

Parameter	Type	Mandatory	Description
`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.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`	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.

Type	Value
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

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
    },
    "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

Parameter	Type	Mandatory	Description
`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`

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

(MOTO) Integration steps

Here is the overview of how to integrate MOTO payment:

Prepare credit card form input / Get token list
Hit API Charge
Acknowledge payment result

Jokul Direct - Credit Card H2H MOTO Sequence Diagram

Jokul Direct Credit Card H2H MOTO Merchant Flow

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

Type	Value
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

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

Here is the sample request body to 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",
        "tenor": "12",
        "plan_id": "1232131"
    },
    "card": {
        "token": "243591d7e49f45109961581718c3ef82",
        "number": "5573381011111101",
        "expiry": "1225",
        "save": true
    }
}

Request Body Explanation

Parameter	Type	Mandatory	Description
`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.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`	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.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.

Type	Value
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

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
    },
    "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

Parameter	Type	Mandatory	Description
`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:

Handling DOKU HTTP Notification

(AUTHORIZE CAPTURE) Integration steps

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

Prepare credit card form input / Get token list
Get 3DS authentication ID and 3DS URL
Hit API Charge
Hit API Capture
Acknowledge payment result

Jokul Direct - Credit Card H2H AUTH CAP Sequence Diagram

Jokul Direct Credit Card H2H AUTH CAP Merchant Flow

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

Type	Value
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

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

Here is the sample request body to 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

Parameter	Type	Mandatory	Description
`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.

Type	Value
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

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

Response Body Explanation

Parameter	Type	Mandatory	Description
`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

Type	Value
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

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

Here is the sample request body to 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

Parameter	Type	Mandatory	Description
`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.

Type	Value
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

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
    },
    "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

Parameter	Type	Mandatory	Description
`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

Type	Value
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

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

Here is the sample request body to capture the transaction:

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

Request Body Explanation

Parameter	Type	Mandatory	Description
`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.

Type	Value
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

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
    },
    "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

Parameter	Type	Mandatory	Description
`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:

Handling DOKU HTTP Notification

List of Error Code

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

API	Error message	Error Code	HTTP Status Code	Explanation
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

Explore the New API Documentation!

Payment types​

(SALE) Integration steps​

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

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

API Request​

API Response​

3. Hit API Charge​

API Request​

API Response​

4. Acknowledge payment result​

(MOTO) Integration steps​

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

2. Hit API Charge​

API Request​

API Response​

3. Acknowledge payment result​

(AUTHORIZE CAPTURE) Integration steps​

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

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

API Request​

API Response​

3. Hit API Charge​

API Request​

API Response​

4. Hit API Capture​

API Request​

API Response​

5. Acknowledge payment result​

List of Error Code​

Payment types

(SALE) Integration steps

1. Prepare credit card form input / Get token list

2. Get 3DS authentication ID and 3DS URL

API Request

API Response

3. Hit API Charge

API Request

API Response

4. Acknowledge payment result

(MOTO) Integration steps

1. Prepare credit card form input / Get token list

2. Hit API Charge

API Request

API Response

3. Acknowledge payment result

(AUTHORIZE CAPTURE) Integration steps

1. Prepare credit card form input / Get token list

2. Get 3DS authentication ID and 3DS URL

API Request

API Response

3. Hit API Charge

API Request

API Response

4. Hit API Capture

API Request

API Response

5. Acknowledge payment result

List of Error Code