Hold and Release Settlement
Last updated
Was this helpful?
Last updated
Was this helpful?
Hold & Release Settlement is a feature that enables you to hold the settlement for a payment. This is a good solution for a merchant that needs to hold and release the settlement when needed. It is suitable for merchants who have a marketplace or ecommerce business.
"Pasar Kelontong" is an online marketplace where sellers and buyers meet. They need to hold the settlement to their sellers and will only settle it after the buyers confirmed they have received the goods.
Therefore, they implement Hold and Release Settlement feature which makes the settlement hold until they trigger the release settlement API.
To do hold settlement, please add this additional_info.hold_settlement object into your payment request:
You can validate whether the settlement is hold by checking to and go to Report > Reconciled Transactions. You should see the transaction will have Settlement Schedule with HOLD.
Let's assume you are using the Checkout integration. You can simply add these parameters into your API Initiate Payment:
To release the settlement, you will need to hit this API through your backend:
API Request
HTTP Method
POST
API endpoint (Sandbox)
https://api-sandbox.doku.com/finance/v1/release
API endpoint (Production)
https://api.doku.com/finance/v1/release
Here is the sample of request header to release transaction into settlement:
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
Here is the sample of request body:
order.invoice_number
string
Mandatory
Same as the request that merchant sent on the payment initiation
order.amount
number
Mandatory
Same as the request that merchant sent on the payment initiation
order.currency
string
Mandatory
Same as the currency of original payment
Default value: IDR
transaction.original_request_id
string
Mandatory
The request ID that sent when initiate the payment
override_settlement.bank_account_settlement_id
string
Optional
The bank_account_settlement_id that you retrieved from the DOKU Back Office
override_settlement.value
numeric
Optional
The value of the settlement can be in IDR or percentage based on the type defined. If you are using FIX type then the value should be the exact amount. If you are using PERCENTAGE type then the value should be the percentage
override_settlement.type
string
Optional
The type of the splitting funds.
Possible value: FIX, PERCENTAGE
API Response
After hitting the above API request, DOKU will give the response.
HTTP Status
200
Result
SUCCESS
Client-Id
Same as the request
Request-Id
Same as the request
Response-Timestamp
Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU
Signature
Signature generated by DOKU based on the response body
Here is the sample response body:
order.invoice_number
string
Mandatory
Same as the request
order.amount
number
Mandatory
Same as the request
order.currency
string
Mandatory
Same as the request
transaction.original_request_id
string
Mandatory
Same as the request
transaction.settlement_date
string
Mandatory
Settlement date of this transaction (H+1)
Format: yyyy-mm-dd
transaction.settlement_amount
number
Mandatory
The settlement amount after deducted with fee
The funds will be settled to the defined bank account within one business day (H+1)
You will receive your funds H+1 after you hit the release API
We support IDR, SGD, and USD settlement. Please make sure that your defined bank account is on respective currency.
Of course, you can!
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 to generate the signature
