Settlement

The Kashier Settlement API provides endpoints for retrieving settlement windows and exporting settlement batch data. These APIs enable merchants to track their settlement transactions.

Don't want to wait for the window?

If you'd rather not wait for a transaction's regular settlement window, see Instant Settlement — request an early payout of eligible transactions for a fee.

Get settlement windows

Retrieve a list of settlement windows with optional filtering and sorting.

Endpoint	Value
LIVE-URL	https://api.kashier.io/v3/payment/settlement/windows
Method	GET

Note

This API can only be performed on live data. In testing mode, there are no settlement windows or batches. The test-api.kashier.io examples below show the request shape only — against a test host they never return data. Call the live host with your live secret key.

Required permissions

Your key must carry the balance.all.view_balance permission. A key without it is rejected even when the secret key itself is valid.

Query parameters

Key	Value
page	current page number, default 1
limit	number of records per page, default 20
q	Search term. A value prefixed with `TX-` resolves the window containing that settlement transaction id.
sortType	1=>ASCENDING, -1=>DESCENDING
sortBy	sort field, default createdAt
dateFrom	The settlement window date to start search from
dateTo	The settlement window date to end search at
status	The settlement window status: `open`, `in_progress`, `closed`, or `failed`. Default `all` applies no status filter.
batchDateFrom	Batch start date
batchDateTo	Batch end date
action	Set to `export` to download the settlement windows list as an Excel file instead of JSON (requires `balance.all.export_balance` permission)

Window status values

Value	What it means for your payout
`open`	Window is still accumulating transactions. Nothing has been paid out yet.
`in_progress`	Settlement processing is running. The payout is being prepared but has not landed.
`closed`	Settled. The transactions in this window have been paid out.
`failed`	Settlement processing failed for this window. Nothing was paid out — contact support.

curl --location 'https://test-api.kashier.io/v3/payment/settlement/windows?sortBy=&sortType=-1&limit=20&page=1&q=&dateFrom='
      --header 'Authorization: YOUR_TEST_SECRET_KEY'

Headers

Key	Description
Authorization	The Authorization is the secret key that is used to identify the merchant. You can obtain it from Kashier dashboard. Learn more about Authorization.

Permissions

Permission	Use case
`balance.all.view_balance`	Required to read settlement windows via `GET /v3/payment/settlement/windows`
`balance.all.export_balance`	Required when using `action=export` to download the settlement windows list as an Excel file

Response structure

{
  "message": "success",
  "data": [
    {
      "accountId": "ACC-XXXXXXXX",
      "merchantId": "MID-XXXXX-XXX",
      "windowId": "STW-2123288831",
      "windowDate": "2025-07-21 00:00",
      "status": "closed",
      "totalSettlementAmount": 9450,
      "totalOriginalAmount": 10000,
      "transactionsCount": 12,
      "batchesCount": 2,
      "batchesIds": "BATCH-1,BATCH-2,"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "page": 1,
    "pages": 1
  }
}

Response fields

Field	Type	Description
`accountId`	String	Your settlement account ID at Kashier.
`merchantId`	String	Your merchant ID.
`windowId`	String	The Kashier ID for this settlement window.
`windowDate`	String	The date of the settlement window.
`status`	String	Window status — see Window status values. `closed` means the window is settled and its transactions have been paid out.
`totalSettlementAmount`	Number	The net amount to be settled for the window — what actually lands in your account, after fees and VAT.
`totalOriginalAmount`	Number	The gross transactions amount for the window, before fees and VAT. Reconcile the difference between this and `totalSettlementAmount` against the per-transaction fee columns in the batch export.
`transactionsCount`	Number	The number of transactions that will be settled in this window.
`batchesCount`	Number	Number of batches in the window. Each batch carries its own `channel`, `method`, ready-for-settlement date, and fee totals.
`batchesIds`	String	The IDs of the batches inside the window, comma-separated.

The window list gives you counts and IDs, not the batches themselves. For the per-transaction fee breakdown, call Export settlement batches with the windowId.

Export settlement batches

Export settlement batch details for a specific settlement window.

Endpoint	Value
LIVE-URL	https://api.kashier.io/v3/payment/settlement/windows/batches/export
Method	GET

Note

This API can only be performed on live data. In testing mode, there are no settlement windows or batches. The test-api.kashier.io example below shows the request shape only — against a test host there is nothing to export.

Required permissions

Export requires the balance.all.export_balance permission on your key, in addition to balance.all.view_balance for reading windows.

Query parameters

Key	Value
q	Search query. A value prefixed with `TX-` resolves the window containing that settlement transaction id.

curl --location 'https://test-api.kashier.io/v3/payment/settlement/windows/batches/export?q=STW-2123288831'
      --header 'Authorization: YOUR_TEST_SECRET_KEY'

Headers

Key	Description
Authorization	The Authorization is the secret key that is used to identify the merchant. You can obtain it from Kashier dashboard. Learn more about Authorization.

Permissions

Permission	Use case
`balance.all.export_balance`	Required to export settlement batch data via `GET /v3/payment/settlement/windows/batches/export`

Response structure

Status: 200 OK
Content-Type: application/vnd.ms-excel
Response: Excel file containing batch data will be downloaded.

Notes

Ensure that the Authorization header contains a valid secret key.
Use proper date formats (YYYY-MM-DD) when filtering results.
The export endpoint returns an Excel file containing batch details.

On this page