> For the complete documentation index, see [llms.txt](https://developers.doku.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.doku.com/accept-payments/finance-and-settlement/split-settlement.md).

# Split Settlement

Split Settlement is a feature that enables to define your settlement rule for a payment. This is a good solution for a merchant that need customized settlement rule such as, marketplace, platforms, franchise, business with various branches, and many more. Split Settlement will help you to manage your complex payment flows.

## Activation <a href="#preparation" id="preparation"></a>

1. This feature only works for Aggregator Merchant, meaning that your funds are settled from acquiring to DOKU, then DOKU will forward the funds to your account.
2. You have activated the split settlement service when onboarding to DOKU. If not activated, we will settle all settlement amounts to your default bank account. You can activate split settlement service through menu **Setting > Service.**

![](/files/eaJcb5h8SaCphwnID3xG)

a. Click the “+ Add Service” button and select Financial Service > Others > Split Settlement. If this section is disabled, please contact your sales.

![](/files/6WE09vwQrr0SI96yDvzv)

b. Once Split Settlement is activated, you can see Split Settlement on your service list.

![](/files/OfvkibYNSXUZ7PFE3xpf)

c. Your split transaction will have a split Icon on the right of Invoice Number.

![](/files/tBka7gAsCpuHhcd8IS3E)

3. Create new bank account on DOKU Back Office from menu **Setting  > Bank Account** and click the **Add** button, then fill the form and click Submit button.

<figure><img src="/files/aiCFRuHTdQxgaou5JACz" alt=""><figcaption></figcaption></figure>

4. We will verify your data and after the status is `Verified` then you can retrieve the `settlement_bank_account_id` from Bank Settlement ID column to put into your Split Settlement Rule
5. Split settlement currently only works for integration with:
   * Checkout
   * Direct API

Then you are good to go!

## Request Split Settlement on Accept Payment <a href="#implementation" id="implementation"></a>

Request split settlement can be done during payment success.To do split settlement, please add this `additional_info.settlement` object into your payment request:

```json
{
...
    "additional_info": {
        "settlement": [
            {
                "bank_account_settlement_id": "SBA-0001-123123123",
                "value": 10,
                "type": "PERCENTAGE"
            },
            {
                "bank_account_settlement_id": "SBS-0002-321321321",
                "value": 90,
                "type": "PERCENTAGE"
            }
        ]
    }
...
}
```

<table><thead><tr><th>Parameter</th><th width="119">Type</th><th width="118">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>additional.info.settlement</code></td><td><code>array</code></td><td>Mandatory</td><td>Include this object to do split settlement for the transaction</td></tr><tr><td><code>additional_info.settlement[].</code><br><code>bank_account_settlement_id</code></td><td><code>string</code></td><td>Mandatory</td><td>The <code>bank_account_settlement_id</code> that you retrieved from the DOKU Back Office</td></tr><tr><td><code>additional_info.settlement[].value</code></td><td><code>string</code></td><td>Mandatory</td><td>The value of the settlement can be in IDR or percentage based on the <code>type</code> defined. If you are using <code>FIX</code> type then the value should be the exact amount. If you are using <code>PERCENTAGE</code> type then the value should be the percentage</td></tr><tr><td><code>additional_info.settlement[].type</code></td><td><code>string</code></td><td>Mandatory</td><td>The type of the splitting funds<br>Possible value: <code>FIX</code>, <code>PERCENTAGE</code></td></tr></tbody></table>

{% hint style="info" %}
Please be aware that the object names in this system are **case sensitive**. This means that "ObjectName" and "objectname" would be treated as two distinct objects. Be sure to use the exact case as specified to avoid any errors or issues in your implementation
{% endhint %}

#### Sample Usage <a href="#sample-usage" id="sample-usage"></a>

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

```json
{
    "order": {
        "invoice_number": "INV-20210231-0001",
        "amount": 90000,
        "line_items": [
            {
                "name": "T-Shirt Red",
                "price": 30000,
                "quantity": 2
            },
            {
                "name": "Polo Navy",
                "price": 30000,
                "quantity": 1
            }
        ],
        "currency": "IDR",
        "callback_url": "https://merchant.com/return-url"
    },
    "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": "CUST-0001",
        "name": "Anton Budiman",
        "email": "anton@example.com",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID"
    },
    "additional_info": {
        "settlement": [
            {
                "bank_account_settlement_id": "SBA-0001-123123123",
                "value": 15,
                "type": "PERCENTAGE"
            },
            {
                "bank_account_settlement_id": "SBS-0002-321321321",
                "value": 85,
                "type": "PERCENTAGE"
            }
        ]
    }
}
```

***

## Update Split Settlement via Post Payment

The Update Split Settlement on Post Payment feature allows you to modify fund distributions for transactions that have pending settlement. You can easily update the split settlement through the dashboard or API.

### **Update Via Host-to-Host**

1. **Check Status Split Settlement (API)**\
   Check Status Split Settlement (POST v1/split-settlement/check-status): Show the value for a split settlement transaction such as settlement bank account information, split value, and split type.

## POST /v1/split-settlement/check-status

> Check Status of Split Settlement

```json
{"openapi":"3.0.0","info":{"title":"FC H2H API - Bank Register & Split Settlement (Actual Implementation)","version":"2.0.0"},"tags":[{"name":"Split Settlement","description":"Split Settlement feature by API"}],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{sandbox/production.doku.com}.com/fc-h2h-api"}],"paths":{"/v1/split-settlement/check-status":{"post":{"tags":["Split Settlement"],"summary":"Check Status of Split Settlement","operationId":"checkStatusSplitSettlement","parameters":[{"$ref":"#/components/parameters/ClientId"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/RequestTimestamp"},{"$ref":"#/components/parameters/Signature"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestQuerySplitSettlement"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCheckStatusSplitSettlement"}}}},"404":{"description":"Account, transaction, or settlement bank account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Split settlement is not allowed for this country, or the split_settlement account flag is not true\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"ClientId":{"in":"header","name":"Client-Id","schema":{"type":"string"},"required":true,"description":"Client ID retrieved from DOKU Back Office"},"RequestId":{"in":"header","name":"Request-Id","schema":{"type":"string"},"required":true,"description":"Unique random string (max 128 characters), validated globally by the security filter (not at the controller level)\n"},"RequestTimestamp":{"in":"header","name":"Request-Timestamp","schema":{"type":"string"},"required":true,"description":"Timestamp request UTC ISO8601, validated globally (out-of-range check)"},"Signature":{"in":"header","name":"Signature","schema":{"type":"string"},"required":true,"description":"HMAC signature, validated globally by RequestHeaderFilter"}},"schemas":{"RequestQuerySplitSettlement":{"description":"Used by /check-status and /cancel. Only contains fields that are actually read by SplitSettlementService... split_transaction_bank_account is INTENTIONALLY omitted here: for /check-status this field is absolutely not used at all (dead field), and for /cancel this field is only passed raw (pass-through) to financial-core, not used by this service itself. See docs/api/compare-api.md for details.\n","type":"object","required":["invoice_number","transaction_date","amount"],"properties":{"invoice_number":{"type":"string","description":"transaction invoice number"},"transaction_date":{"type":"string","format":"date-time","description":"transaction date in ISO-8601 format"},"amount":{"type":"number","format":"double"}}},"ResponseCheckStatusSplitSettlement":{"type":"array","items":{"$ref":"#/components/schemas/SplitSettlementCheckStatusItem"}},"SplitSettlementCheckStatusItem":{"description":"Fields that are actually set by getSplitSettlementResponseDto() (SplitSettlementService.java:219-229) for the /check-status endpoint.\n","type":"object","properties":{"bank_account_settlement_id":{"type":"string"},"bank_name":{"type":"string"},"bank_account_number":{"type":"string"},"bank_account_name":{"type":"string"},"value":{"type":"number","format":"double"},"type":{"type":"string"}}},"ErrorResponse":{"type":"object","description":"General error format (ResponseBodyDTO from com.doku.au.security). The actual code value for ErrorType.DATA_NOT_FOUND is 'data not found' (with spaces), not 'data_not_found'.\n","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"type":{"type":"string"}}}}}}}}
```

1. **Edit Split Settlement (API)**\
   Edit Split Settlement (POST /v1/split-settlement/edit): Updates destination bank accounts and split allocation rules (percentages or fixed amounts) for an unbatched transaction in pending status.

## POST /v1/split-settlement/edit

> Edit Split Settlement of Transaction

```json
{"openapi":"3.0.0","info":{"title":"FC H2H API - Bank Register & Split Settlement (Actual Implementation)","version":"2.0.0"},"tags":[{"name":"Split Settlement","description":"Split Settlement feature by API"}],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{sandbox/production.doku.com}.com/fc-h2h-api"}],"paths":{"/v1/split-settlement/edit":{"post":{"tags":["Split Settlement"],"summary":"Edit Split Settlement of Transaction","operationId":"editSplitSettlement","parameters":[{"$ref":"#/components/parameters/ClientId"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/RequestTimestamp"},{"$ref":"#/components/parameters/Signature"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestEditSplitSettlement"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEditSplitSettlement"}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Split transaction is empty, transaction not found, journey code is not eligible, split settlement configuration is inactive, settlement schedule has passed, split type is different, split value <= 0, or split amount is insufficient\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"ClientId":{"in":"header","name":"Client-Id","schema":{"type":"string"},"required":true,"description":"Client ID retrieved from DOKU Back Office"},"RequestId":{"in":"header","name":"Request-Id","schema":{"type":"string"},"required":true,"description":"Unique random string (max 128 characters), validated globally by the security filter (not at the controller level)\n"},"RequestTimestamp":{"in":"header","name":"Request-Timestamp","schema":{"type":"string"},"required":true,"description":"Timestamp request UTC ISO8601, validated globally (out-of-range check)"},"Signature":{"in":"header","name":"Signature","schema":{"type":"string"},"required":true,"description":"HMAC signature, validated globally by RequestHeaderFilter"}},"schemas":{"RequestEditSplitSettlement":{"type":"object","required":["invoice_number","transaction_date","amount","split_transaction_bank_account"],"properties":{"invoice_number":{"type":"string"},"transaction_date":{"type":"string","format":"date-time"},"amount":{"type":"number","format":"double"},"split_transaction_bank_account":{"type":"array","minItems":1,"description":"Must contain at least 1 item; if empty, the service throws 500 'Split Transaction cannot be empty'","items":{"$ref":"#/components/schemas/SplitTransactionBankAccount"}}}},"SplitTransactionBankAccount":{"type":"object","required":["bank_account_settlement_id","value","type"],"properties":{"bank_account_settlement_id":{"type":"string"},"value":{"type":"string","description":"Sent as a string then manually parsed using Long.parseLong by the service (not a native JSON number)\n"},"type":{"type":"string","description":"Not validated as an enum by the service; values other than FIX or PERCENTAGE will cause the split amount to be calculated as 0 without an error\n"}}},"ResponseEditSplitSettlement":{"type":"array","items":{"$ref":"#/components/schemas/SplitSettlementEditItem"}},"SplitSettlementEditItem":{"description":"Fields that are actually set by validateSplitTransaction() (SplitSettlementService.java:121-147) for endpoint /edit. bank_name, bank_account_number, bank_account_name are INTENTIONALLY omitted: the service never sets these fields, so they do not appear in the JSON response (DTO uses @JsonInclude NON_NULL).\n","type":"object","properties":{"bank_account_settlement_id":{"type":"string"},"value":{"type":"number","format":"double"},"type":{"type":"string"}}},"ErrorResponse":{"type":"object","description":"General error format (ResponseBodyDTO from com.doku.au.security). The actual code value for ErrorType.DATA_NOT_FOUND is 'data not found' (with spaces), not 'data_not_found'.\n","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"type":{"type":"string"}}}}}}}}
```

1. **Cancel Split Settlement (API)**\
   Cancel Split Settlement (POST /v1/split-settlement/cancel): Cancels the custom split settlement configuration for an unbatched transaction, restoring 100% fund settlement to the merchant's default bank account.

## POST /v1/split-settlement/cancel

> Cancel Split Settlement of Transaction

```json
{"openapi":"3.0.0","info":{"title":"FC H2H API - Bank Register & Split Settlement (Actual Implementation)","version":"2.0.0"},"tags":[{"name":"Split Settlement","description":"Split Settlement feature by API"}],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{sandbox/production.doku.com}.com/fc-h2h-api"}],"paths":{"/v1/split-settlement/cancel":{"post":{"tags":["Split Settlement"],"summary":"Cancel Split Settlement of Transaction","operationId":"cancelSplitSettlement","parameters":[{"$ref":"#/components/parameters/ClientId"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/RequestTimestamp"},{"$ref":"#/components/parameters/Signature"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestQuerySplitSettlement"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCancelSplitSettlement"}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Split settlement is not allowed for this country, transaction not found, or financial-core returned a failure response\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"ClientId":{"in":"header","name":"Client-Id","schema":{"type":"string"},"required":true,"description":"Client ID retrieved from DOKU Back Office"},"RequestId":{"in":"header","name":"Request-Id","schema":{"type":"string"},"required":true,"description":"Unique random string (max 128 characters), validated globally by the security filter (not at the controller level)\n"},"RequestTimestamp":{"in":"header","name":"Request-Timestamp","schema":{"type":"string"},"required":true,"description":"Timestamp request UTC ISO8601, validated globally (out-of-range check)"},"Signature":{"in":"header","name":"Signature","schema":{"type":"string"},"required":true,"description":"HMAC signature, validated globally by RequestHeaderFilter"}},"schemas":{"RequestQuerySplitSettlement":{"description":"Used by /check-status and /cancel. Only contains fields that are actually read by SplitSettlementService... split_transaction_bank_account is INTENTIONALLY omitted here: for /check-status this field is absolutely not used at all (dead field), and for /cancel this field is only passed raw (pass-through) to financial-core, not used by this service itself. See docs/api/compare-api.md for details.\n","type":"object","required":["invoice_number","transaction_date","amount"],"properties":{"invoice_number":{"type":"string","description":"transaction invoice number"},"transaction_date":{"type":"string","format":"date-time","description":"transaction date in ISO-8601 format"},"amount":{"type":"number","format":"double"}}},"ResponseCancelSplitSettlement":{"description":"For the /cancel endpoint, data is taken from deserializing the financial-core response (BaseResponse.data pada cancel(), SplitSettlementService.java:255-277), then transaction_date is reformatted to yyyy-MM-dd by formatDate() (SplitSettlementService.java:280-287). invoice_number and amount are explicitly used/processed by this code; bank_* fields are NOT explicitly set by the service for this endpoint.\n","type":"object","properties":{"invoice_number":{"type":"string"},"transaction_date":{"type":"string","description":"Reformatted to yyyy-MM-dd by formatDate()"},"amount":{"type":"number","format":"double"}}},"ErrorResponse":{"type":"object","description":"General error format (ResponseBodyDTO from com.doku.au.security). The actual code value for ErrorType.DATA_NOT_FOUND is 'data not found' (with spaces), not 'data_not_found'.\n","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"type":{"type":"string"}}}}}}}}
```

### Update via Dashboard Setting <a href="#faqs" id="faqs"></a>

1. **Cancel Split Settlement (Dashboard)**

Cancel Split Settlement: Navigate to **Reports > Reconciled Transactions**, click the three-dot menu (⋮) on an unbatched pending transaction, select Cancel Split Settlement, click the red Cancel Split Settlement button, and select Yes on the confirmation prompt.

<img src="/files/iQUZ4njbKG8YIdefOB0D" alt="" height="305" width="624">

2. **Edit Split Settlement (Dashboard)**

   Edit Split Settlement: Navigate to **Reports > Reconciled Transactions**, click the three-dot menu (⋮) in the Actions column, select Settlement Configuration, adjust your bank account allocations or split values, and click Save Configuration.

<figure><img src="/files/oZoOUE2VeauHOuGMmIOH" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/tOeVtPDEhEGdKhA63l5l" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/MbxyHHNOCaqv5fExXTam" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/mYpxpKM3exW5N7OEb03o" alt=""><figcaption></figcaption></figure>

***

## Rules and Limitation

{% hint style="success" %}
**NOTES**

The split settlement is calculated based on the Net Settlement amount, not the order amount. This means you must deduct the Total Fee from the order amount to determine the Net Settlement value.
{% endhint %}

**Here is the illustration:**

Let's assume that the `order.amount` is `Rp104,500` and the Total Fee that being charged by DOKU for this transaction is `Rp4,500` and you want to split the amount into two bank accounts with percentage of `15%` into the first bank account (`SBA-0001-123123123`) and `85%` into the second bank account (`SBA-0002-321321321`).

| Name                             | Percentage | Amount      |
| -------------------------------- | ---------- | ----------- |
| `order.amount`                   | -          | 104,500     |
| Total Fee by DOKU                | -          | 4,500       |
| **Amount that will be splitted** | **100%**   | **100,000** |
| SBA-0001-123123123               | 15%        | 15,000      |
| SBA-0002-321321321               | 85%        | 85,000      |

Therefore, the first bank account will receive `Rp15,000` and second bank account will receive `Rp85,000`.

***

## FAQs <a href="#faqs" id="faqs"></a>

#### What if the settlement amount defined incorrectly? <a href="#what-if-the-settlement-amount-defined-incorrectly" id="what-if-the-settlement-amount-defined-incorrectly"></a>

The transaction will still be processed, but the split settlement mechanism will not be executed. The funds will settled to the primary bank account that you set in the settlement configuration.

#### Can I use this feature with [hold & release settlement](https://developers.doku.com/accept-payments/finance-and-settlement/hold-and-release-settlement#hold-settlement) or custom settlement report? <a href="#can-i-use-this-feature-with-hold--release-settlement-or-custom-settlement-report" id="can-i-use-this-feature-with-hold--release-settlement-or-custom-settlement-report"></a>

Of course, you can!