Skip to main content

Integration Guide

Learn more about how Jokul Sub Account can help you Power up your online payments here.

Integration steps#

Here is the overview of how to integrate with Jokul Sub Account:

  1. Create Account
  2. Accept Payment
  3. Send Payout
  4. Transfer Intra Sub Account

1. Create Account#

To create the account, you will need to hit this API through your Backend:

API Request#

TypeValue
HTTP MethodPOST
API endpoint (Sandbox)https://api-sandbox.doku.com/sac-merchant/v1/accounts
API endpoint (Production)https://api.doku.com/sac-merchant/v1/accounts

Here is the sample of request header to create the payment:

Client-Id: MCH-0001-10791114622547Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22eRequest-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
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 create the account:

{    "account": {        "email": "test2@doku.com",        "type": "STANDARD",        "name": "nama2"    }}
Request Body Explanation
ParameterTypeMandatoryDescription
account.emailstringMandatoryEmail identifier for your partner account
Allowed chars: alphabetic, numeric, special chars
Max Length: 40
account.typestringMandatoryType of account. Available Values: Default, Standard
Allowed chars: alphabetic
Max Length: 20
account.namestringMandatoryYour partner name
Allowed chars: alphabetic
Max Length: 100

API Response#

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

TypeValue
HTTP Status201
ResultCREATED

Here is the sample response header:

Client-Id: MCH-0001-10791114622547Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22eResponse-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:

{    "account": {        "created_date": "2021-08-04T18:19:00.046085+07:00",        "updated_date": "2021-08-04T18:19:00.046085+07:00",        "name": "nama2",        "email": "test2@doku.com",        "type": "STANDARD",        "status": "PENDING",        "id": "SAC-9914-1628075940045"    }}
Response Body Explanation
ParameterTypeMandatoryDescription
account.created_datestringMandatoryTimestamp when the account was created
account.updated_datestringMandatoryTimestamp when the account was updated
account.namestringMandatorySame as the request
account.emailstringMandatorySame as the request
account.typestringMandatorySame as the request
account.statusstringMandatorySub Account status. In this state, it should be PENDING
account.idstringMandatoryID of your Sub Account, use this id to create transactions on behalf of your Partner

2. Accept Payment#

To accept payment add this additional_info.account object into your payment request.

..."additional_info": {    "account": {      "id": “SAC-11111111    }  }...
Request Header Explanation
ParameterTypeMandatoryDescription
additional_info.accountstringMandatoryInclude this object for routing the payment
additional_info.account.idstringMandatoryID of your Account, use this to create transactions on behalf of your Account
Allowed chars: alphabetic, numeric, special chars
Max Length: 40

Sample Usage#

Let's assume you are using the Jokul Direct integration. You can simply add these parameters into your API Initiate Payment:

{    "order": {        "invoice_number": "INV-20210124-0001",        "amount": 150000    },    "virtual_account_info": {        "expired_time": 60,        "reusable_status": false,        "info1": "Merchant Demo Store",        "info2": "Thank you for shopping",        "info3": "on our store"    },    "customer": {        "name": "Anton Budiman",        "email": "anton@example.com"    },    "additional_info": {        "account": {           "id": “SAC-11111111    }  }}

3. Send Payout#

You can request to send money from your accounts balance account for any disbursement purpose e.g: withdrawal, refund, paying vendor/supplier, etc

API Request#

TypeValue
HTTP MethodPOST
API endpoint (Sandbox)https://api-sandbox.doku.com/sac-merchant/v1/payouts
API endpoint (Production)https://api.doku.com/sac-merchant/v1/payouts

Here is the sample of request header to create the payment:

Client-Id: MCH-0001-10791114622547Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22eRequest-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
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 for payouts:

{    "account":    {        "id":"SAC-0000-0000000000001"    },    "payout":    {        "amount": 20000,        "invoice_number":"INV/123/45"    },    "beneficiary":    {        "bank_code":"BNINIDJA",        "bank_account_number":"712739123020001",        "bank_account_name":"Ria Florensi"    }}
Request Body Explanation
ParameterTypeMandatoryDescription
account.idstringMandatoryThe source of the payout
Allowed chars: alphabetic, numeric, special chars
Max Length: 40
payout.amountstringMandatoryPayout amount
Allowed chars: numeric
Max Length: 12
payout.invoice_numberstringMandatoryA unique reference for this Payout. Use this to reconcile your payout.
Allowed chars: alphabetic, numeric, special chars
Max Length: 100
beneficiary.bank_codestringMandatorySWIFT CODE Bank Destination
Allowed chars: alphabetic
Max Length: 12
beneficiary.bank_account_numberstringMandatoryBeneficiary Bank Account Number
Allowed chars: numeric
Max Length: 40
beneficiary.bank_account_namestringMandatoryBeneficiary Bank Account Name
Allowed chars: alphabetic
Max Length: 40

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: b6a465ea-bb65-48b2-a22b-3e8fb51cf22eResponse-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:

{    "account": {        "id": "SAC-123-111111"    },    "payout":{        "amount": 20000,        "invoice_number": “INV/123/11,        "status": “SUCCESS”,        "created":2021-08-06 15:18:06.820153+07:00    },    "beneficiary:{        "bank_code": “BNINIDJA”,        "bank_account_number": 1234567,        "bank_account_name": “Ria Florensi”    }}
Response Body Explanation
ParameterTypeMandatoryDescription
account.idstringMandatorySame as request
payout.amountstringMandatorySame as request
payout.invoice_numberstringMandatorySame as request
payout.statusstringMandatoryPayout status
payout.createdstringMandatoryTimestamp when Payout was created
beneficiary.bank_codestringMandatorySame as request
beneficiary.bank_account_numberMandatorystringSame as request
beneficiary.bank_account_nameMandatorystringSame as request

4. Transfer Intra Sub Account#

The Transfers API allows you to transfer balances between your accounts.

API Request#

TypeValue
HTTP MethodPOST
API endpoint (Sandbox)https://api-sandbox.doku.com/sac-merchant/v1/transfers
API endpoint (Production)https://api.doku.com/sac-merchant/v1/transfers

Here is the sample of request header to create the payment:

Client-Id: MCH-0001-10791114622547Request-Id: b6a465ea-bb65-48b2-a22b-3e8fb51cf22eRequest-Timestamp: 2020-08-11T08:45:42ZSignature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
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 for payouts:

{    "transfer":    {        "origin" : "SAC-0000-0000000000001",        "destination" : "SAC-8014-1628130619289",        "amount" : 10000,        "invoice_number" : "INV/7274812"    }}
Request Body Explanation
ParameterTypeMandatoryDescription
transfer.originstringMandatoryThe source of the Transfer
Allowed chars: alphabetic, numeric, special chars
Max Length: 40
transfer.destinationstringMandatoryThe destination of the Transfer
Allowed chars: alphabetic, numeric, special chars
Max Length: 40
transfer.amountstringMandatoryTransfer amount
Allowed chars: numeric
Max Length: 12
transfer.invoice_numberstringMandatoryA unique reference for this Payout. Use this to reconcile your payout.
Allowed chars: alphabetic, numeric, special chars
Max Length: 100

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: b6a465ea-bb65-48b2-a22b-3e8fb51cf22eResponse-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:

{    "transfer": {        "invoice_number": "INV/7274812",        "origin": "SAC-0000-0000000000001",        "destination": "SAC-8014-1628130619289",        "amount": 10000,        "status": "SUCCESS",        "created": "2021-08-06 15:18:06.820153+07:00"    }}
Response Body Explanation
ParameterTypeMandatoryDescription
transfer.invoice_numberstringMandatorySame as request
transfer.originstringMandatorySame as request
transfer.destinationstringMandatorySame as request
transfer.amountstringMandatorySame as request
transfer.createdstringMandatoryTimestamp when Payout was created