DOKU DocsChangelogDOKU Github

Backend Integration

Backend Integration to initiate payment​

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

Endpoint

TypeValue

HTTP Method

POST

API endpoint (sandbox)

https://api-sandbox.doku.com/checkout/v1/payment

API endpoint (production)

https://api.doku.com/checkout/v1/payment

Request

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-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 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
    }
}
Body ParameterTypeMandatoryDescription

order.amount

number

Mandatory

In IDR Currency and without decimal Max length: 12

order.invoice_number

string

Mandatory

Generated by merchant to identify the order. Max length: 64 Notes: If you have Credit Card channel activated, the maximum length is 30 chars due to the acquirer's requirements If you are using KKI, all the symbols are not allowed. Ensure you do not put any symbol on Invoice number value.

payment.payment_due_date

number

Optional

The payment due date of the checkout page in minutes. Default : 60 minutes. Max Length: 6

This basic request only could be implement for selected payment method, such as :

  1. Virtual Account

  2. Credit Card

  3. QRIS

  4. Convenience Store

  5. E-money (OVO and Linkaja)

Order object

{
"order": {
  "amount": 80000,
  "invoice_number": "INV-{{$timestamp}}",
  "currency": "IDR",
  "callback_url": "http://merchantcallbackurl.domain/",
  "callback_url_cancel": "https://merchantcallbackurl-cancel.domain",
  "callback_url_result": "https://merchantcallbackurl-cancel.domain",
  "language":"EN",
  "auto_redirect":true,
  "disable_retry_payment" :true,
  "line_items": [
    {
        "id":"001",
        "name":"Fresh flowers",
        "quantity":1,
        "price":40000,
        "sku": "FF01",
        "category": "gift-and-flowers",
        "url": "http://item-url.domain/",
        "image_url":"http://image-url.domain/",
        "type":"ABC"
    },
    {
        "id":"002",
        "name":"T-shirt",
        "quantity":1,
        "price":40000,
        "sku": "T01",
        "category": "clothing",
        "url": "http://item-url.domain/",
        "image_url":"http://image-url.domain/",
        "type":"ABC"
    }
  ]
}
Body ParameterType`MandatoryDescription

order.amount

number

Mandatory

Order amount in IDR currency and without decimal. Max length: 12

order.invoice_number

string

Mandatory

Unique identifier generated by merchant to identify the order.

Max length: 64, except credit card which 30 chars only If you are using KKI, all the symbols are not allowed. Ensure you do not put any symbol on Invoice number value.

order.currency

string

Optional

3 alphabetic currency code ISO 4217 Min-max Length: 3 Default value: IDR

order.callback_url

string

Conditional, Mandatory for Payment Methods : Jenius.

The "Back to Merchant" button is configured using the URL provided in callback_url. If only callback_url is set, it will apply to the "Back to Merchant" button on both the main page and the result page. However, if the merchant also sets callback_url_result, then callback_url will only affect the "Back to Merchant" button on the main page, while callback_url_result will specifically affect the button on the result page.

order.callback_url_cancel

string

Conditional, Currently only available for payment methods : Indodana

The URL specified for merchant redirection in the event of order cancellation.

order.callback_url_result

string

Optional

The URL designated for button "Back to merchant" in result page.

order.language

string

Optional

Default language shown when redirect to checkout page Max length: 2

order.auto_redirect

boolean

Mandatory

When set to true, the transaction result page redirects to the callback URL; otherwise, it redirects to the payment result page.

order.disable_retry_payment

boolean

Conditional, Only applied for payment methods : Credit Card, DOKU Wallet, Akulaku, OVO, ShopeePay

This condition is applicable only when the merchant sends this parameter with a "true" value. If the merchant does not include this parameter, sends a "false" value, or if the customer fails to complete the payment, the result page will be displayed in the Checkout. From there, the customer can retry payment or modify their payment options if multiple channels are available.

order.line_items.id

string

Conditional Mandatory for Payment Methods : Akulaku, Kredivo, Indodana

Item ID of the item in this transaction. Max Length: 64 Note : If you are using KKI, all the symbols are not allowed. Ensure you do not put any symbol on Invoice number value.

order.line_items.name

string

Conditional, Mandatory for Payment Methods : Jenius, Kredivo, Indodana, KKI.

Name of the product item. Max Length: 255 Note If you are using KKI, all the symbols are not allowed. Ensure you do not put any symbol.

order.line_items.price

number

Conditional, Mandatory for Payment Methods : Jenius, Kredivo, Akulaku, Indodana, KKI.

Price of the product item. Total price and quantity must match with the order.amount. Note If you are using KKI, all the symbols are not allowed. Ensure you do not put any symbol.

order.line_items.quantity

number

Conditional, Mandatory for Payment Methods : Jenius, Kredivo, Akulaku, Indodana, KKI.

Quantity of the product item. Note If you are using KKI, all the symbols are not allowed. Ensure you do not put any symbol.

order.line_items.sku

string

Conditional. Mandatory for Payment Methods : Akulaku, Kredivo, Indodana.

SKU of the product item.

order.line_items.category

string

Conditional, Mandatory for Payment Methods : Akulaku, Kredivo, Indodana.

Category of the product item. For Indodana, the category should be based on these list.

order.line_items.url

string

Conditional, Mandatory for Payment Methods : Kredivo and Indodana.

URL to the product item on merchant site.

order.line_items.image_url

string

Conditional, Mandatory for Payment Methods : Indodana.

URL the image of the product item on merchant site.

order.line_items.type

string

Conditional, Mandatory for Payment Methods : Indodana.

Type of the item in this transaction.

Payment Object

"payment": {
      "payment_due_date": 60,
      "type" : "SALE/INSTALLMENT/AUTHORIZE",
      "payment_method_types": [
          "VIRTUAL_ACCOUNT_BCA",
          "VIRTUAL_ACCOUNT_BANK_MANDIRI",
          "VIRTUAL_ACCOUNT_BANK_SYARIAH_MANDIRI",
          "VIRTUAL_ACCOUNT_DOKU",
          "VIRTUAL_ACCOUNT_BRI",
          "VIRTUAL_ACCOUNT_BNI",
          "VIRTUAL_ACCOUNT_BANK_PERMATA",
          "VIRTUAL_ACCOUNT_BANK_CIMB",
          "VIRTUAL_ACCOUNT_BANK_DANAMON",
          "ONLINE_TO_OFFLINE_ALFA",
          "CREDIT_CARD",
          "DIRECT_DEBIT_BRI",
          "EMONEY_SHOPEEPAY",
          "EMONEY_OVO",
          "QRIS",
          "PEER_TO_PEER_AKULAKU",
          "PEER_TO_PEER_KREDIVO",
          "PEER_TO_PEER_INDODANA"
      ]
  }
Body parameterTypeMandatoryDescription

payment.payment_method_types

array

optional

Payment method that will shown to users in Checkout Page. If you wish to showcase all available payment methods, simply omit sending this parameter, and all options will be visible. Alternatively, if you prefer to direct users to a specific payment method, include this parameter and specify the desired payment method by filling in its corresponding value. The value are listed here.

payment.type

string

Optional

Possible Value : "SALE", "INSTALLMENT", "AUTHORIZE" If you set the type as Authorize, the status will be stated as On Hold. The status will change, if the customer do payment. Only applicable in Credit Card.

payment.payment_due_date

number

optional

The payment due date of the checkout page in minutes. Default : 60 minutes. Max Length: 6

Customer Object

"customer":{
      "id":"JC-01",
      "name":"Zolanda",
      "last_name":"Anggraeni",
      "phone":"628121212121",
      "email": "zolanda@example.com",
      "address":"taman setiabudi",
      "postcode":"120129",
      "state":"Jakarta",
      "city":"Jakarta Selatan",
      "country":"ID"
}
Body parameterTypeMandatoryDescription

customer.id

string

Conditional, mandatory to enable tokenized payments (BRI Direct Debit, Allobank, Credit Card tokenization) and Akulaku Paylater.

Unique customer identifier generated by merchant. Allowed chars: alphabetic, numeric, special chars Max Length: 50

customer.name

string

Conditional, mandatory for payment methods Jenius, Akulaku, Indodana

Customer name. Allowed chars: alphabetic Max Length: 255

customer.last_name

string

Optional

Customer last name. Max Length: 16

customer.email

string

Conditional, mandatory for payment method Indodana

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

customer.phone

string

Conditional

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

customer.address

string

Conditional, mandatory for payment method Akulaku

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

customer.postcode

string

Conditional, mandatory for payment method Akulaku

Customer address' post code

customer.state

string

Conditional, mandatory for payment method Akulaku

Customer state or province.

customer.city

string

Conditional, mandatory for payment method Akulaku

Customer address' city

customer.country

string

Optional

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

Shipping Address Object

"shipping_address":{
  "first_name":"Joe",
  "last_name":"Doe",
  "address":"Jalan DOKU no 15",
  "city":"Jakarta",
  "postal_code":"11923",
  "phone":"081312345678",
  "country_code":"IDN"
}
Body ParameterTypeMandatoryDescription

shipping_address.first_name

string

Conditional, mandatory for payment method Kredivo and Indodana

Customer's first name used as shipping address

shipping_address.last_name

string

Optional

Customer's last name used as shipping address.

shipping_address.address

string

Conditional, mandatory for payment method Kredivo and Indodana

Customer's address used as shipping address.

shipping_address.city

string

Conditional, mandatory for payment method Kredivo and Indodana

City of customer's shipping address.

shipping_address.postal_code

string

Conditional, mandatory for payment method Kredivo and Indodana

Postal code of customer's shipping address.

shipping_address.phone

string

Conditional, mandatory for payment method Kredivo and Indodana

Customer's phone used as shipping address.

shipping_address.country_code

string

Conditional, mandatory for payment method Kredivo and Indodana

Country of customer's shipping address.

Billing Address Object

"billing_address":{
  "first_name":"Joe",
  "last_name":"Doe",
  "address":"Jalan DOKU no 15",
  "city":"Jakarta",
  "postal_code":"11923",
  "phone":"081312345678",
  "country_code":"IDN"
}
Body ParameterTypeMandatoryDescription

billing_address.first_name

string

Conditional, mandatory for payment method Indodana

Customer's first name used as billing address

billing_address.last_name

string

Conditional, mandatory for payment method Indodana

Customer's last name used as billing address.

billing_address.address

string

Conditional, mandatory for payment method Indodana

Customer's address used as billing address.

billing_address.city

string

Conditional, mandatory for payment method Indodana

City of customer's billing address.

billing_address.postal_code

string

Conditional, mandatory for payment method Indodana

Postal code of customer's billing address.

billing_address.phone

string

Conditional, mandatory for payment method Indodana

Customer's phone used as billing address.

billing_address.country_code

string

Conditional, mandatory for payment method Indodana

Country of customer's billing address.

Additional Info Object

"additional_info":{
  "allow_tenor" : [0,3,6,12],
  "doku_wallet_notify_url" : "https://dw-notification.merchantdomain",
  "override_notification_url": "https://another.example.com/payments/notifications"
}
Body parameterTypeMandatoryDescription

additional_info.allow_tenor

number

Optional

The transaction exclusively supports installment tenors as per its current configuration. The allowed values are 0,3,6,12. To hide the "no installment" option, refrain from inputting 0 (zero) in the parameter.

additional_info.doku_wallet_notify_url

string

Conditional, only for payment method DOKU Wallet

Notification url set in this parameter

additional_info.override_notification_url

string

Optional

This parameter is intended to override the configured Notification URL with another URL. Click here for more information.

Response

Success Response

TypeValue

HTTP Status

200

{
    "message": [
        "SUCCESS"
    ],
    "response": {
        "order": {
            "amount": "20000",
            "invoice_number": "INV-20210231-0001",
            "currency": "IDR",
            "session_id": "2ebffd22d23e436895ce5c38f7ddcf86"
        },
        "payment": {
            "payment_method_types": [
                "JENIUS_PAY",
                "ONLINE_TO_OFFLINE_ALFA",
                "OCTO_CLICKS",
                "PEER_TO_PEER_KREDIVO",
                "VIRTUAL_ACCOUNT_BCA",
                "CREDIT_CARD",
                "EMONEY_OVO",
                "ONLINE_TO_OFFLINE_INDOMARET",
                "EMONEY_DOKU",
                "VIRTUAL_ACCOUNT_BANK_MANDIRI",
                "EPAY_BRI",
                "PEER_TO_PEER_INDODANA",
                "VIRTUAL_ACCOUNT_BRI",
                "EMONEY_LINKAJA",
                "EMONEY_SHOPEE_PAY",
                "VIRTUAL_ACCOUNT_BNI",
                "VIRTUAL_ACCOUNT_BANK_PERMATA",
                "VIRTUAL_ACCOUNT_DOKU",
                "VIRTUAL_ACCOUNT_BANK_CIMB",
                "VIRTUAL_ACCOUNT_BANK_DANAMON",
                "VIRTUAL_ACCOUNT_BANK_SYARIAH_MANDIRI",
                "VIRTUAL_ACCOUNT_MAYBANK",
                "DIRECT_DEBIT_CIMB",
                "EMONEY_DANA",
                "DIRECT_DEBIT_BRI",
                "DIRECT_DEBIT_ALLO",
                "PEER_TO_PEER_BRI_CERIA",
                "VIRTUAL_ACCOUNT_BNC",
                "PERMATA_NET",
                "KLIKPAY_BCA",
                "VIRTUAL_ACCOUNT_BTN",
                "DANAMON_ONLINE_BANKING",
                "VIRTUAL_ACCOUNT_SINARMAS"
            ],
            "payment_due_date": 60,
            "token_id": "2ebffd22d23e436895ce5c38f7ddcf8620244712094712362",
            "url": "https://sandbox.doku.com/checkout-link-v2/2ebffd22d23e436895ce5c38f7ddcf8620244712094712362",
            "expired_date": "20240712104711"
        },
        "additional_info": {
            "origin": {
                "product": "CHECKOUT",
                "system": "mid-jokul-checkout-system",
                "apiFormat": "JOKUL",
                "source": "direct"
            }
        },
        "uuid": 2225240712094712339107164227041411929328,
        "headers": {
            "request_id": "ed06da30-bbbc-4e90-a3c7-390c24476cb9",
            "signature": "HMACSHA256=cyoua5cA6DR5mG/4vw3ice48KjCX+CGdLdSfMumJUuo=",
            "date": "2024-07-12T02:47:11Z",
            "client_id": "BRN-0214-1714016624673"
        }
    }
}

Response Body Explanation

Body ParameterTypeMandatoryDescription

message

array

Mandatory

Message will display the result of the request. If there are some errors on your request, they will be diplayed in this parameter.

response.order.amount

number

Mandatory

Same as the request

response.order.invoice_number

string

Mandatory

Same as the request

response.order.currency

string

Optional

Same as the request

response.order.session_id

string

Optional

Unique session ID generated by DOKU

response.order.callback_url

string

Optional

Same as the request

response.order.callback_url_cancel

string

Optional

Same as the request

response.order.line_items.name

string

Optional

Same as the request

response.order.line_items.quantity

number

Optional

Same as the request

response.order.line_items.price

number

Optional

Same as the request

response.order.line_items.sku

string

Optional

Same as the request

response.order.line_items.category

string

Optional

Same as the request

response.order.line_items.url

string

Optional

Same as the request

response.order.line_items.image_url

string

Optional

Same as the request

response.order.line_items.type

string

Optional

Same as the request

response.order.language

string

Optional

Same as the request

response.order.disable_retry_payment

boolean

Optional

Same as the request

response.order.auto_redirect

boolean

Optional

Same as the request

response.payment.payment_method_types

array

Optional

Payment method that will be displayed on the Checkout Page

response.payment.payment_due_date

number

Mandatory

Same as the request

response.payment.token_id

string

Mandatory

Token generated by DOKU for the Checkout Page

response.payment.url

string

Mandatory

Checkout page URL to display for the customer

response.payment.expired_date

string

Mandatory

Date 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.id

string

Optional

Same as the request

response.customer.state

string

Optional

Same as the request

response.customer.city

string

Optional

Same as the request

response.customer.postcode

string

Optional

Same as the request

response.customer.email

string

Optional

Same as the request

response.customer.phone

string

Optional

Same as the request

response.customer.name

string

Optional

Same as the request

response.customer.last_name

string

Optional

Same as the request

response.customer.address

string

Optional

Same as the request

response.customer.country

string

Optional

Same as the request

response.additional_info.allow_tenor

string

Optional

Same as the request

response.additional_info.close_redirect

string

Optional

Same as the request

response.additional_info.doku_wallet_notify_url

string

Optional

Same as the request

response.additional_info.override_notification_url

string

Optional

Same as the request

response.uuid

string

Optional

Unique number generated by DOKU

response.headers.requestId

string

Optional

Same as the request

response.headers.signature

string

Optional

Same as the request

response.headers.date

string

Optional

Same as the request

response.headers.clientId

string

Optional

Same as the request

response.shipping_address.address

string

Optional

Same as the request

response.shipping_address.city

string

Optional

Same as the request

response.shipping_address.phone

string

Optional

Same as the request

response.shipping_address.first_name

string

Optional

Same as the request

response.shipping_address.last_name

string

Optional

Same as the request

response.shipping_address.postal_code

string

Optional

Same as the request

response.shipping_address.country_code

string

Optional

Same as the request

response.billing_address.address

string

Optional

Same as the request

response.billing_address.city

string

Optional

Same as the request

response.billing_address.phone

string

Optional

Same as the request

response.billing_address.first_name

string

Optional

Same as the request

response.billing_address.first_name

string

Optional

Same as the request

response.billing_address.postal_code

string

Optional

Same as the request

response.billing_address.country_code

string

Optional

Same as the request

Failed Response

TypeValue

HTTP Status

400

{
    "error_messages": [
        "order.invoice_number must be filled",
        "order.amount must greater than 0"
    ]
}

List Category

List category can be used as reference. But this is part of payment channel Indodana with mandatory value need to set in order.line_items.category.

NoCategory

1

airlines

2

arts-crafts-and-collectibles

3

automotive

4

baby

5

beauty-and-fragrances

6

biller

7

books-and-magazines

8

business-to-business-including-mlm

9

charity-and-non-profit

10

clothing

11

community

12

digital-content

13

electronics-and-telecom

14

entertainment-and-media

15

fee

16

financial-services-and-products

17

financial-services-and-technology

18

food-and-beverage

19

food-retail-and-service

20

games-voucher

21

gifts-and-flowers

22

government

23

health-and-personal-care

24

home-and-garden

25

hotel-and-travel

26

insurance

27

marketplace

28

nonprofit

29

offline-store

30

others

31

over-the-air

32

overseas

33

pets-and-animals

34

property

35

public-services

36

religion-and-spirituality

37

retail

38

services

39

sports-and-outdoors

40

telco

41

ticketing

42

toys-and-hobbies

43

transportation

45

travel

46

vehicle-sales

47

vehicles-service-and-accessories

PreviousIntegration GuideNextFrontend Integration

Last updated

DOKU API

Legacy Documentation