Host-To-Host Integration Guide

Host to Host Integration Guide

If you are a PCI DSS-compliant merchant, you can use this type of integration to receive card payments to manages your own card, token, and UI.

---

​

DOKU Direct - Credit Card H2H Sequence Diagram

Here is the overview of how to integrate process transaction using H2H API:

1. Prepare credit card form input / Get token list (Optional)

2. Hit Check 3DS to Get 3DS authentication ID and 3DS URL (Conditional)

3. Hit API Charge

4. Acknowledge payment result

Get Token List is Optional, only needed if you utilize DOKU's tokenization feature where you can send token instead of cards number to avoid security risk by sending sensitive data

Check 3DS Process is Conditional, it is required for payment type SALE, AUTHORIZE, INSTALLMENT but not required for MOTO & RECURRING, you may skip this process and proceed to Charge API

Get Token List

If you've previously made payment and you or your customer choose to save the credit card info You may use this Get Token List API show the saved card of your customers. this API can be used to obtain token from other payment method such as OVO, BRI Direct Debit, Allobank, etc that also uses tokenization feature.

Get Token List

post

/tokenization/v2/get-token

Body

customerobjectrequired

channelobject

issuerobject

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/tokenization/v2/get-token' \
  --header 'Content-Type: application/json' \
  --data '{"customer":{"id":"WT_CC001"},"channel":{"id":"CREDIT_CARD"},"issuer":{"id":"BANK_MANDIRI"}}'

200

200

{
  "customer": {
    "id": "text"
  },
  "tokens": [
    {
      "id": "doku-gateway-creditcard",
      "masked_account": "********5464",
      "card": {
        "cardholder_name": "EGXXXXXXI",
        "expiry": "26/12",
        "brand": "VISA",
        "issuer": "BCA",
        "country": "ID",
        "bin": 123456,
        "hashed_card_number": "0H9NEF3TY840WC8GWC48CHMW90309C3C43",
        "payer_account_id": "0H9NEF3TY840WC8GWC48CHMW90309C3C43",
        "encrypted_expiry": "NZdUASLwMQWy2eaq4ADZIPV9PC5iFSku80BNz6Mu9+g=|DEV-AA|2|2|noFCnMnn5v7WoYyZfujcwg=="
      }
    }
  ]
}

Successful response - Token Found

Check 3D Secure

3D Secure (3DS) is an authentication protocol used in online credit card transactions to enhance security and reduce fraud. It requires the cardholder to complete an additional verification step with their issuing bank before the transaction is approved. This process helps confirm that the legitimate cardholder is making the purchase.

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

Parameter	Type	Mandatory	Description
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	Conditional	Card token generated by DOKU, can be used if you already activate tokenizationeither card.token or card.number must be sent
card.number	string	Conditional	Card numbe printed on card either card.token or card.number must be sent
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

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

​

Charge API

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,
        "descriptor": "NAMA_MERCHANT",
        "line_items": [
            {
                "name": "T-Shirt Red",
                "price": 30000,
                "quantity": 2
            },
            {
                "name": "Polo Navy",
                "price": 30000,
                "quantity": 1
            }
        ]
    },
    "customer": {
        "id": "CUST-0001",
        "name": "Alisa Mikhailovna",
        "email": "[e-mail]",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID"
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    },
    "payment": {
        "type": "INSTALLMENT",
        "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: 30 (27 If you have Mandiri Acquirer)
order.descriptor	string	Optional	Custom value to print on customer's billing statement, please contact our Integration Team first
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	obtained in the response during Check 3DS API
payment.type	string	Mandatory	Payment type Possible value: SALE, AUTHORIZE, INSTALLMENT, MOTO, RECURRING
payment.tenor	string	Conditional	Chosen Installment Tenor for this transaction Mandatory if payment.type ='INSTALLMENT' eg: 3, 6, 9, 12
payment.plan_id	string	Optional	Promotion ID from the bank for merchant if you have special collaboration with issuer
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 or RECURRING
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.

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",
        "descriptor": "NAMA_MERCHANT",
        "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": "00",
        "response_message": "Approved",
        "eci": "05",
        "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

---

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:

• Handling DOKU HTTP Notification

---

MOTO Payment Type example​

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 Get Token List 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,
        "descriptor":"NAMA_MERCHANT"
        "line_items": [
            {
                "name": "T-Shirt Red",
                "price": 30000,
                "quantity": 2
            },
            {
                "name": "Polo Navy",
                "price": 30000,
                "quantity": 1
            }
        ]
    },
    "customer": {
        "id": "CUST-0001",
        "name": "Togawa Sakiko",
        "email": "[e-mail]",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID"
    },
    "payment": {
        "type": "MOTO"
    },
    "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.descriptor	string	Optional	Custom value to print on customer's billing statement, please contact our Integration Team first
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.

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

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": "00",
        "response_message": "Approved",
        "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 Payment Type​​

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​

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

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

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,
        "descriptor": "NAMA_MERCHANT",
        "line_items": [
            {
                "name": "T-Shirt Red",
                "price": 30000,
                "quantity": 2
            },
            {
                "name": "Polo Navy",
                "price": 30000,
                "quantity": 1
            }
        ]
    },
    "customer": {
        "id": "LAB_MEMBER_004",
        "name": "Kurisu Makise",
        "email": "[e-mail]",
        "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.descriptor	string	Optional	Custom value to print on customer's billing statement, please contact our Integration Team first
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

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": "00",
        "response_message": "Approved",
        "eci": "02",
        "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

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": "Approved",
        "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