Skip to main content

Integration Guide

Requirements#

  1. Make sure you have integrated with either Credit Card or Direct Debit
  2. Make sure that you sent customer.id parameter on the request to Jokul in order to activate the tokenization feature

Integration steps#

  1. Get token list
  2. Show token list to the customer
  3. Use the token for future payment

1. Get token list#

To get token list, you will need to hit this API through your backend:

API Request#

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

Here is the sample of request header to generate payment URL:

Client-Id: MCH-0001-10791114622547Request-Id: 9716a8cb-5ec1-4f8f-b72c-cd25975bafffRequest-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
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 request body to get token list:

{    "customer": {        "id": "CUST-0001"    },    "token_data": {        "type": "DIRECT_DEBIT"    }}
Request Body Explanation
ParameterTypeMandatoryDescription
customer.idstringMandatoryUnique customer identifier generated by merchant.
Allowed chars: alphabetic, numeric, special chars
Max Length: 50
token_data.typestringOptionalToken type, if not specified then return all type of tokens
Possible value: DIRECT_DEBIT, CREDIT_CARD

API Response#

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

TypeValue
HTTP Status200
ResultSUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547Request-Id: 9716a8cb-5ec1-4f8f-b72c-cd25975bafffResponse-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
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:

[    {        "token_data": {            "type": "DIRECT_DEBIT"        },        "customer": {            "id": "CUST-0001",            "name": "Anton Budiman"        },        "debit_card": {            "issuer": "BRI",            "token_id": "243591d7e49f45109961581718c3ef82",            "masked_card": "*********8982",        }    },    {        "token_data": {            "type": "DIRECT_DEBIT"        },        "customer": {            "id": "CUST-0001",            "name": "Anton Budiman"        },        "debit_card": {            "issuer": "BRI",            "token_id": "05fc9236261381647e24a14a691e1590",            "masked_card": "*********8981",        }    },    {        "token_data": {            "type": "CREDIT_CARD"        },        "customer": {            "id": "CUST-0001",            "name": "Anton Budiman"        },        "credit_card": {            "issuer": "BCA",            "token_id": "4bc187a24c60fc88977604d170eea4a5",            "masked_card": "4096****5464",            "brand": "visa"        }    }]
Response Body Explanation
ParameterTypeMandatoryDescription
token_data.typestringMandatoryToken type: DIRECT_DEBIT, CREDIT_CARD
customer.idstringMandatorySame as the request
customer.namestringOptionalCustomer name saved on Jokul
debit_card.issuerstringMandatoryIssuer of the debit card
debit_card.token_idstringMandatoryToken generated by Jokul. Use this value when hit request to Jokul for payment request
Possible value: alphabetic, numeric, special characters
Max length: 256
debit_card.masked_cardstringMandatoryDebit card number masked
credit_card.issuerstringMandatoryIssuer of the credit card
credit_card.token_idstringMandatoryToken generated by Jokul. Use this value when hit request to Jokul for payment request
Possible value: alphabetic, numeric, special characters
Max length: 256
credit_card.masked_cardstringMandatoryCredit card number masked
credit_card.brandstringOptionalPrincipal of the credit card

2. Show Token List to your customer#

You can save the debit_card.token_id and credit_card.token_id to your system along with the customer.id, so that the customer will be associated with their respective tokens.


3. Use token for future payment#

You can send then the token_id along with the payment request. Learn more for each payment channel: