Integration Guide

Preparation

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


Integration steps

  1. Obtain payment.url on Backend
  2. Show Jokul Checkout Payment Page on Frontend
  3. Create test payment
  4. Acknowledge payment result
Jokul Checkout Sequence DiagramJokul 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 Jokul 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:

{
"order": {
"amount": 20000,
"invoice_number": "INV-20210231-0001",
"currency": "IDR",
"callback_url": "https://merchant.com/return-url",
"line_items": [
{
"name": "DOKU T-Shirt",
"price": 20000,
"quantity" : 1
}
]
},
"payment": {
"payment_due_date": 60,
"payment_method_types": [
"VIRTUAL_ACCOUNT_BCA",
"VIRTUAL_ACCOUNT_BANK_MANDIRI",
"VIRTUAL_ACCOUNT_BANK_SYARIAH_MANDIRI",
"VIRTUAL_ACCOUNT_DOKU",
"ONLINE_TO_OFFLINE_ALFA",
"CREDIT_CARD",
"DIRECT_DEBIT_BRI"
]
},
"customer": {
"id": "123123123",
"name": "Taufik Ismail",
"email": "taufik@example.com",
"phone": "6285694566147",
"address": "Plaza Asia Office Park Unit 3",
"country": "ID"
}
}
Request Body Explanation
ParameterTypeMandatoryDescription
order.amountnumberMandatoryIn IDR Currency and without decimal
Allowed chars: numeric
Max length: 14
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
order.currencystringOptional3 alphabetic currency code ISO 4217
Allowed chars: alphabetic
Min-max Length: 3
Default value: IDR
order.callback_urlstringOptionalMerchant URL that will redirected to after the order completed
Allowed chars: alphabetic, numeric, special chars
order.line_items.namestringOptionalName of the product item
Allowed chars: alphabetic, numeric, special chars
Max Length: 255
order.line_items.pricenumberOptionalPrice of the product item. Total price and quantity must match with the order.amount
Allowed chars: numeric
Max Length: 12
order.line_items.quantitynumberOptionalQuantity of the product item
Allowed chars: numeric
Max Length: 4
payment.payment_method_typesarrayOptionalPayment method that will shown to users in Checkout Page. Payment method list available in the section below
Default: All channels that active on your account
payment.payment_due_datenumberMandatoryIn minutes
Allowed chars: numeric
Max Length: 8
customer.idstringConditionalUnique customer identifier generated by merchant. Merchant must send this parameter to enable Tokenized payments (Direct Debit, Credit Card tokenization).
Allowed chars: alphabetic, numeric, special chars
Max Length: 50
customer.namestringOptionalCustomer name
Allowed chars: alphabetic
Max Length: 255
customer.emailstringOptionalCustomer email
Allowed chars: alphabetic, numeric, special chars
Max Length: 128
customer.phonestringOptionalCustomer phone number. Format: {calling_code}{phone_number}. Example: 6281122334455
Allowed chars: numeric
Max Length: 16
customer.addressstringOptionalCustomer address
Allowed chars: alphabetic, numeric, special chars
Max Length: 400
customer.countrystringOptional2 alphabetic country code ISO 3166-1
Allowed chars: alphabetic
Min-max Length: 2
Pro Tips

You can define the payment method that will be shown in the payment page through the Jokul 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
DOKU VAVIRTUAL_ACCOUNT_DOKU
Credit CardCREDIT_CARD
Alfa Group (Alfamart, Alfamidi, Dan+Dan)ONLINE_TO_OFFLINE_ALFA
Direct Debit BRIDIRECT_DEBIT_BRI

API Response

After hitting the above API request, Jokul 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 Jokul
SignatureSignature generated by Jokul based on the response body

Here is the sample of response body:

{
"message": [
"SUCCESS"
],
"response": {
"headers": {
"requestId": "8quQyK39l4aM5cCml0Yy",
"signature": "HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=",
"date": "2020-08-11T08:45:42Z",
"clientId": "MCH-0001-10791114622547"
},
"order": {
"amount": 20000,
"invoice_number": "INV-20210231-0001",
"currency": "IDR",
"session_id": "SU5WFDferd561dfasfasdfae123c",
"callback_url": "http://merchant.com/return-url",
"line_items": [
{
"name": "DOKU T-Shirt",
"price": 20000,
"quantity" : 1
}
]
},
"payment": {
"payment_method_types": [
"VIRTUAL_ACCOUNT_BCA",
"VIRTUAL_ACCOUNT_BANK_MANDIRI",
"VIRTUAL_ACCOUNT_BANK_SYARIAH_MANDIRI",
"VIRTUAL_ACCOUNT_DOKU",
"ONLINE_TO_OFFLINE_ALFA",
"CREDIT_CARD",
"DIRECT_DEBIT_BRI"
],
"payment_due_date": 60,
"token_id": "SU5WFDferd561dfasfasdfae123c20200510090550775",
"url": "https://jokul.doku.com/checkout/link/SU5WFDferd561dfasfasdfae123c20200510090550775",
"expired_date": "20210127100246"
},
"customer": {
"id": "123123123",
"name": "Taufik Ismail",
"email": "taufik@example.com",
"phone": "6285694566147",
"address": "Menara Mulia Lantai 8",
"country": "ID"
},
"uuid": 2225201118095946218107192228078002056789
}
}
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.headers.requestIdstringOptionalSame as the request
response.headers.signaturestringOptionalSame as the request
response.headers.datestringOptionalSame as the request
response.headers.clientIdstringOptionalSame as the request
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 Jokul
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.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 Jokul 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 your 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.countrystringOptionalSame as the request
response.uuidstringOptionalUnique number generated by Jokul

2. Show Jokul Checkout Payment Page on Frontend

Once you have the payment.url, you can now show the payment page by embedding the Jokul 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(payment.url); // Replace it with the 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 Jokul Checkout as follows:

Jokul Checkout Demo

Or you can try the demo here:

Try Jokul Checkout Demo

3. Creating Test Payment

Create a test payment to make sure that the Jokul 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, Jokul will send HTTP Notification to your defined Notification URL. Learn how to handle the notification from Jokul:

Jokul Checkout Implementation

Jokul Checkout User Experience is designed to increase your payment success rate, meaning that it allows your customers to change payment method if one is failed. Therefore, if you are integrating with Jokul Checkout, you must ignore the transaction.status FAILED.


Advanced features

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

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