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.Documentation Index
Fetch the complete documentation index at: https://developers.kotanipay.com/llms.txt
Use this file to discover all available pages before exploring further.
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. OnlyPENDING 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 inPENDING.
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 withsavedBeneficiaryId.
GET /api/v3/integrator/settlement-config/beneficiaries
See List Beneficiaries.POST /api/v3/integrator/settlement-config/beneficiaries
See Create Beneficiary.PATCH /api/v3/integrator/settlement-config/beneficiaries/:id
See Update Beneficiary.DELETE /api/v3/integrator/settlement-config/beneficiaries/:id
See Delete Beneficiary.Related
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