Dashboard Settlements

The settlements API lets you request, track, and manage the movement of your Kotani Pay balance to an external account. You can submit individual requests, group them into batches, merge existing requests, and configure saved beneficiaries for faster reuse. All endpoints require a valid API key — see API Keys.

Schedule & Limits

Before submitting a settlement, check the active schedule to understand allowed days, cutoff times, and amount limits.

GET /api/v3/integrator/settlements/schedule

See Settlement Schedule.

Field	Type	Description
`enabled`	boolean	Whether settlements are currently open for requests
`allowedDays`	number[]	Days of the week accepted (0 = Sunday … 6 = Saturday)
`cutoffEnabled`	boolean	Whether a daily cutoff time is enforced
`cutoffTime`	string	Cutoff in `HH:MM` format — requests after this are queued to the next allowed day
`timezone`	string	IANA timezone for cutoff evaluation (e.g. `"Africa/Nairobi"`)
`minAmount`	number	Minimum settlement amount in USD
`maxAmount`	number	Maximum settlement amount in USD

Fee Preview

Preview the fee before submitting.

GET /api/v3/integrator/settlements/fee-preview

See Settlement Fee Preview. Query parameters: amount (required), walletId (required).

Field	Type	Description
`amount`	number	The queried amount in local currency
`fee`	number	Fee amount in local currency
`feePercentage`	number	Fee as a percentage of `amount`
`netAmount`	number	Amount received after fee (`amount - fee`)
`currency`	string	Local currency code
`usdRate`	number	Exchange rate used to convert to USD
`usdAmount`	number	`amount` in USD
`usdNetAmount`	number	`netAmount` in USD

Single Settlement Requests

POST /api/v3/integrator/settlements

See Request Settlement.

Field	Type	Required	Description
`walletId`	string	Yes	Fiat wallet to settle from
`amount`	number	Yes	Amount in the wallet’s local currency
`balanceSource`	string	Yes	`PAYOUT` or `DEPOSIT`
`beneficiaryDetails`	object	Conditional	Inline beneficiary — required if `savedBeneficiaryId` is omitted
`savedBeneficiaryId`	string	Conditional	Saved beneficiary ID — required if `beneficiaryDetails` is omitted
`integratorNote`	string	No	Internal memo
`callbackUrl`	string	No	URL to receive webhook on status change

GET /api/v3/integrator/settlements

See List Settlements. Query: limit, offset, status, from, to.

GET /api/v3/integrator/settlements/:id

See Get Settlement.

DELETE /api/v3/integrator/settlements/:id

See Cancel Settlement. Only PENDING settlements can be cancelled.

Batch Settlements

Group multiple wallet settlements into one operation under a single admin approval.

POST /api/v3/integrator/settlements/batch

See Create Batch Settlement.

Field	Type	Required	Description
`requests`	object[]	Yes	Array of settlement sub-requests. Each accepts `walletId`, `amount`, `balanceSource`, and optionally `beneficiaryDetails` or `savedBeneficiaryId`
`batchReference`	string	No	Your own idempotency reference for the batch
`integratorNote`	string	No	Internal memo for the batch

GET /api/v3/integrator/settlements/batch

See List Settlement Batches.

GET /api/v3/integrator/settlements/batch/:batchId

See Get Settlement Batch.

DELETE /api/v3/integrator/settlements/batch/:batchId

See Cancel Settlement Batch. Cancels all children still in PENDING.

Merge Into Batch

Convert two or more existing settlements into a batch after the fact.

POST /api/v3/integrator/settlements/merge

See Merge Settlements into Batch.

Field	Type	Required	Description
`settlementIds`	string[]	Yes	IDs to merge. Minimum 2. All must be `PENDING` or `UNDER_REVIEW` and not already in a batch
`integratorNote`	string	No	Internal memo for the resulting batch

Notification Preferences

PATCH /api/v3/integrator/settlements/notification-preferences

See Update Notification Preferences.

Field	Type	Description
`settlementNotificationEmail`	string	Email address for settlement notifications
`settlementNotificationsEnabled`	boolean	Toggle email notifications
`settlementSlackWebhookUrl`	string	Slack incoming webhook URL
`settlementSlackEnabled`	boolean	Toggle Slack notifications

Saved Beneficiaries

Store destination account details once and reuse with savedBeneficiaryId.

Settlement Flow

Lifecycle states, batch flow, webhooks, and schedule rules

Balances & Settlement

How deposit and payout balances work

Webhook Notifications

How to verify and handle signed webhook events

Transaction Statuses

All status codes used across the API

Get Supported Chains & Tokens Request Settlement

​Schedule & Limits

​GET /api/v3/integrator/settlements/schedule

​Fee Preview

​GET /api/v3/integrator/settlements/fee-preview

​Single Settlement Requests

​POST /api/v3/integrator/settlements

​GET /api/v3/integrator/settlements

​GET /api/v3/integrator/settlements/:id

​DELETE /api/v3/integrator/settlements/:id

​Batch Settlements

​POST /api/v3/integrator/settlements/batch

​GET /api/v3/integrator/settlements/batch

​GET /api/v3/integrator/settlements/batch/:batchId

​DELETE /api/v3/integrator/settlements/batch/:batchId

​Merge Into Batch

​POST /api/v3/integrator/settlements/merge

​Notification Preferences

​PATCH /api/v3/integrator/settlements/notification-preferences

​Saved Beneficiaries

​GET /api/v3/integrator/settlement-config/beneficiaries

​POST /api/v3/integrator/settlement-config/beneficiaries

​PATCH /api/v3/integrator/settlement-config/beneficiaries/:id

​DELETE /api/v3/integrator/settlement-config/beneficiaries/:id

​Related