Skip to main content

Integration Guide

Preparation

Make sure you already have Client ID & Secret Key to continue this section. Please refer to this section.


Integration steps

Here is the overview of how to integrate with Checkout:

  1. Obtain payment.url on Backend
  2. Display DOKU Checkout Payment Page on Frontend
  3. Create test payment
  4. Acknowledge payment result
Checkout Sequence Diagram
Checkout Flow

1. Obtain payment.url on Backend

To obtain the payment.url, you will need to hit this API through your Backend:

API Request

TypeValue
HTTP MethodPOST
API endpoint (Sandbox)https://api-sandbox.doku.com/checkout/v1/payment
API endpoint (Production)https://api.doku.com/checkout/v1/payment

Here is the sample of request header to obtain payment.url:

Client-Id: MCH-0001-10791114622547
Request-Id: fdb69f47-96da-499d-acec-7cdc318ab2fe
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
Request Header Explanation
ParameterDescription
Client-IdClient ID retrieved from DOKU Back Office
Request-IdUnique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-TimestampTimestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z
SignatureSecurity parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample of request body to obtain payment.url, you can send a simple request for a basic payment page and you can send the parameter according to your needs:

{
"order": {
"amount": 20000,
"invoice_number": "INV-20210231-0001"
},
"payment": {
"payment_due_date": 60
}
}
Request Body Explanation
ParameterTypeMandatoryDescription
order.amountnumberMandatoryIn IDR Currency and without decimal
Allowed chars: numeric
Max length: 12
order.invoice_numberstringMandatoryGenerated by merchant to identify the order
Allowed chars: alphabetic, numeric, special chars
Max length: 64
Notes: If you have Credit Card channel activated, the maximum length is 30 chars due to the acquirer's requirements
payment.payment_due_datenumberMandatoryIn minutes
Allowed chars: numeric
Max Length: 8
Pro Tips

You can define the payment method that will be shown in the payment page through the DOKU Back Office or by inputing the array list of payment method in the payment.payment_method_types. If you send only one payment method, then your customer will redirected directly to defined payment method.

Payment Method List

Here is the payment method list available:

NameValue
BCA VAVIRTUAL_ACCOUNT_BCA
Bank Mandiri VAVIRTUAL_ACCOUNT_BANK_MANDIRI
Bank Syariah Indonesia VAVIRTUAL_ACCOUNT_BANK_SYARIAH_MANDIRI
BRI VAVIRTUAL_ACCOUNT_BRI
BNI VAVIRTUAL_ACCOUNT_BNI
DOKU VAVIRTUAL_ACCOUNT_DOKU
PERMATA VAVIRTUAL_ACCOUNT_PERMATA
CIMB VAVIRTUAL_ACCOUNT_CIMB
Danamon VAVIRTUAL_ACCOUNT_DANAMON

API Response

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

Here is the sample of response header:

TypeValue
HTTP Status200
ResultSUCCESS
Client-Id: MCH-0001-10791114622547
Request-Id: fdb69f47-96da-499d-acec-7cdc318ab2fe
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
Response Header Explanation
ParameterDescription
Client-IdSame as the request
Request-IdSame as the request
Response-TimestampTimestamp Response on UTC with format ISO8601 UTC+0 from DOKU
SignatureSignature generated by DOKU based on the response body

Here is the sample of response body:

{
"message": [
"SUCCESS"
],
"response": {
"order": {
"amount": "80000",
"invoice_number": "INV-20220909-001",
"currency": "IDR",
"session_id": "5f02558578234084a15a82e3bcfc22da",
"callback_url": "http://doku.com/",
"line_items": [
{
"name": "HP ninu",
"quantity": 1,
"price": "80000",
"sku": "1002",
"category": "Shirt",
"url": "http://doku.com/"
}
],
"language": "EN",
"disable_retry_payment": true,
"auto_redirect": true
},
"payment": {
"payment_method_types": [
"VIRTUAL_ACCOUNT_DOKU",
"VIRTUAL_ACCOUNT_BANK_MANDIRI"
],
"payment_due_date": 60,
"token_id": "5f02558578234084a15a82e3bcfc22da20221511191550566",
"url": "https://jokul.doku.com/checkout/link/5f02558578234084a15a82e3bcfc22da20221511191550566",
"expired_date": "20220911201550"
},
"customer": {
"id": "JC-01",
"state": "Jakarta",
"city": "Jakarta Selatan",
"postcode": "12960",
"email": "zolanda@example.com",
"phone": "081234234123",
"name": "Zolanda",
"address": "taman setiabudi",
"country": "ID"
},
"uuid": 2225220911191550551107112514617000142673,
"headers": {
"request_id": "8e33b9b6-2a79-4d92-98c3-488493eb4392",
"signature": "HMACSHA256=gtOaokjcMCkGY+wQ6+m0YFBjXsIdscxSLf/Rp+8SFRk=",
"date": "2022-09-11T12:15:50Z",
"client_id": "MCH-0008-1296507211683"
},
"shipping_address": {
"address": "Jalan Teknologi Indonesia No. 25",
"city": "Jakarta",
"phone": "081234234123",
"first_name": "Zolanda",
"postal_code": "12960",
"country_code": "IDN"
}
}
}

Response Body Explanation
ParameterTypeMandatoryDescription
messagearrayMandatoryMessage will display the result of the request. If there are some errors on your request, they will be diplayed in this parameter.
response.order.amountnumberMandatorySame as the request
response.order.invoice_numberstringMandatorySame as the request
response.order.currencystringOptionalSame as the request
response.order.session_idstringOptionalUnique session ID generated by DOKU
response.order.callback_urlstringOptionalSame as the request
response.order.line_items.namestringOptionalSame as the request
response.order.line_items.quantitynumberOptionalSame as the request
response.order.line_items.pricenumberOptionalSame as the request
response.order.line_items.skustringOptionalSame as the request
response.order.line_items.categorystringOptionalSame as the request
response.order.line_items.urlnumberOptionalSame as the request
response.order.languagestringOptionalSame as the request
response.order.disable_retry_paymentbooleanOptionalSame as the request
response.order.auto_redirectbooleanOptionalSame as the request
response.payment.payment_method_typesarrayOptionalPayment method that will be displayed on the Checkout Page
response.payment.payment_due_datenumberMandatorySame as the request
response.payment.token_idstringMandatoryToken generated by DOKU for the Checkout Page
response.payment.urlstringMandatoryCheckout page URL to display for the customer
response.payment.expired_datestringMandatoryDate time of payment page will be expired with the format of yyyyMMddHHmmss. The expired date uses UTC+7 time. Use this to set the expiry order on merchant side
response.customer.idstringOptionalSame as the request
response.customer.namestringOptionalSame as the request
response.customer.emailstringOptionalSame as the request
response.customer.phonestringOptionalSame as the request
response.customer.addressstringOptionalSame as the request
response.customer.statestringOptionalSame as the request
response.customer.citystringOptionalSame as the request
response.customer.postcodestringOptionalSame as the request
response.customer.countrystringOptionalSame as the request
response.uuidstringOptionalUnique number generated by DOKU
response.headers.requestIdstringOptionalSame as the request
response.headers.signaturestringOptionalSame as the request
response.headers.datestringOptionalSame as the request
response.headers.clientIdstringOptionalSame as the request
response.shipping_address.addressstringOptionalSame as the request
response.shipping_address.citystringOptionalSame as the request
response.shipping_address.phonestringOptionalSame as the request
response.shipping_address.first_namestringOptionalSame as the request
response.shipping_address.postal_codestringOptionalSame as the request
response.shipping_address.country_codestringOptionalSame as the request

2. Display DOKU Checkout Payment Page on Frontend

Once you have the payment.url, you can now display the payment page by embedding the DOKU Checkout JS on your HTML file.

Simply import the jokul-checkout-1.0.0.js and then call the loadJokulCheckout() with the payment.url:

TypeValue
JS Sandboxhttps://sandbox.doku.com/jokul-checkout-js/v1/jokul-checkout-1.0.0.js
JS Productionhttps://jokul.doku.com/jokul-checkout-js/v1/jokul-checkout-1.0.0.js
Alternative Implementation

If you want your customers redirected to the payment page instead the payment page is popped up on your website, you can simply use the payment.url value without importing the JS file.

<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://sandbox.doku.com/jokul-checkout-js/v1/jokul-checkout-1.0.0.js"></script>
</head>
<body>
<button id="checkout-button">Checkout Now</button>

<script type="text/javascript">
var checkoutButton = document.getElementById('checkout-button');
// Example: the payment page will show when the button is clicked
checkoutButton.addEventListener('click', function () {
loadJokulCheckout('https://jokul.doku.com/checkout/link/SU5WFDferd561dfasfasdfae123c20200510090550775'); // Replace it with the response.payment.url you retrieved from the response
});
</script>
</body>
</html>
Viewport

The viewport on the <head> tag is important to ensure that the payment page is load correctly.

After implementing the steps above, you can see the Checkout as follows:

Checkout Demo

Or you can try the demo here:

Try Checkout Demo

3. Creating Test Payment

Create a test payment to make sure that the DOKU Checkout has been successfully integrated. Simply initiate the payment from your page and then make the payment from our Simulator.

After the payment is completed, your customers will be redirected to callback_url that defined in the request.


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:

Checkout Implementation

Checkout User Experience is designed to increase merchant's payment success rate, meaning that it allows merchant's customers to change payment method if one is failed. Therefore, merchant must ignore the transaction.status FAILED. Instead, merchant are required to set the expiry time on merchant side based on the payment.expired_date in the API response, so that if there is no SUCCESS transaction in between the time period, then merchant must flag the transaction status as cancelled on their side.


Additional features

We provide various additional features to suited your needs. Learn more here.

Custom Checkout Page Color

You can change the Checkout page color according to your brand color to make a good harmony with your brand. Follow the given steps:

Checkout Custom Color
Checkout Custom Color
  1. Login to DOKU Back Office
  2. Go to Configuration > Checkout Page
  3. Scroll to Interface Settings
  4. Fill the color with the HEX color code you wish for each element of the checkout page. For example: #FFFFFF
  5. Click Save Interface Configuration button

Track Checkout Page with Google analytics

If you wish to track the usage of the checkout page through your Google Analytics, please follow given steps below:

Checkout Google Analytics
Checkout Google Analytics
  1. Login to DOKU Back Office
  2. Go to Configuration > Checkout Page
  3. Scroll to System Settings section
  4. Input your Google Analytics tracking ID
  5. Click Save button

QRIS on Checkout

Activation

If you are interested to activate QRIS on Checkout, you can contact our team to get sandbox credential and production credential.

After you have the credential, you can setup the QRIS credential according to the environment (sandbox / production). Here is the steps:

Checkout QRIS Activation
Checkout QRIS Activation
  1. Login to DOKU Back Office
  2. Go to Configuration > Checkout Page
  3. Scroll to QRIS credential
  4. Input the credential given
  5. Click Submit button
  6. Your customer can now see the QRIS at the Checkout Payment Page

Integration

After you activated the QRIS on the Checkout Configuration, you should now see QRIS as one of the payment method available for your customers.

Checkout QRIS Payment Interface
Checkout QRIS Payment interface

Testing Payment

You can simulate the payment through our simulator.

Payment Notification

To receive payment notification, please inform the notification URL that you wish to receive the notification to our integration team. After our integration team configured it for you, then you will receive the notification.

The notification format will not be the same with other DOKU channel, here is the notification format for QRIS:

TypeValue
HTTP MethodPOST

Request Parameters

NameDescription
TXNDATETransaction Date time
Format: yyyyMMddHHmmss
TXNSTATUSTransaction status
Possible value: S for Success, F for Failed
ACQUIRERAcquirer name
Allowed chars: alphabetic, numeric, special characters
MERCHANTPANMerchant DOKU QRIS PAN
Allowed chars: alphabetic, numeric, special characters
ISSUERNAMEIssuer name
Allowed chars: alphabetic, numeric, special characters
ISSUERIDIssuer ID
Allowed chars: numeric
CONVENIENCEFEEConvenience Fee
Allowed chars: numeric
Format: XXXX
INVOICEPurchase payment Invoice number
Allowed chars: alphabetic, numeric, special characters
AMOUNTPurchase amount
Allowed chars: numeric
Format: XXXX
TRANSACTIONIDTransaction ID generated by DOKU
Allowed chars: alphabetic, numeric
WORDSSecurity parameter from DOKU. Hashed SHA1 from element: (ISSUERID + TXNDATE + MERCHANTPAN + INVOICE + sharedKey)
CUSTOMERPANCustomer QRIS PAN
Allowed chars: alphabetic, numeric, special characters
TERMINALIDTerminal ID from QR
Allowed chars: alphabetic, numeric, special characters
ORIGINTransaction origin
Possible value: ONUS, INBOUND
REFERENCEIDReference number from issuer
Allowed chars: alphabetic, numeric, special characters
Validate WORDS

You must validate the WORDS to ensure the authenticity of the notification is coming from DOKU.


Split Settlement

If you are a platform or a marketplace, you can use this feature to settle the funds to your sellers or partners programmatically, save many operational efforts.


What's next?

Congratulations! Now you are ready for going live. Make sure you have registered to our Production environment and the business has been approved by our team.