Settlement Requests

A settlement moves your Kotani Pay balance to an external account — a bank account, mobile money wallet, or crypto address. This guide covers the full lifecycle from submission to completion, including batch and merge patterns, the PAUSED state, and the webhook events fired at each transition.

You need an API key and a reachable callbackUrl — see the Quickstart if you haven’t set those up. For this flow you also need a fiat wallet with a balance to settle from, and a destination — either inline beneficiary details or a saved beneficiary.

Settlement Lifecycle

PENDING → UNDER_REVIEW → APPROVED → PROCESSED

Active States

State	Description
`PENDING`	Request submitted and awaiting review. The only state in which you can cancel.
`UNDER_REVIEW`	A Kotani Pay agent has picked up the request for manual review.
`APPROVED`	Review passed. Funds are being disbursed to the destination account.
`PAUSED`	An admin has paused the settlement pending additional information or due to a compliance hold — see PAUSED State.

Terminal States

State	Description
`PROCESSED`	Funds have been delivered. The settlement is complete.
`REJECTED`	Review failed. Not approved. The reason is recorded on the settlement record.
`CANCELLED`	Cancelled by the integrator before review began. Only possible from `PENDING`.
`FAILED`	An error occurred during disbursement after approval. Contact support with the settlement ID.
`REVERSED`	Disbursement was sent but subsequently reversed. Contact support to confirm balance treatment.

Stop polling once a settlement reaches a terminal state. Use the callbackUrl or configure notification preferences to receive status-change events instead.

PAUSED State

An admin can pause a settlement at any point before PROCESSED. When paused:

pauseReason on the settlement record explains why it was paused
pausedUntil indicates when the system will automatically resume the settlement (if set)
A settlement.paused webhook fires immediately — see Webhook Events

The settlement resumes automatically on pausedUntil if set. Otherwise it resumes when the admin lifts the hold. Check your registered notification email or Slack channel for context from the Kotani Pay team.

Checking the Schedule

Call Settlement Schedule before submitting to confirm settlements are open and your amount is within limits. Key fields:

enabled — if false, requests will be rejected
allowedDays — requests on unlisted days are queued to the next allowed day
cutoffEnabled / cutoffTime / timezone — requests after the cutoff are queued to the next allowed day
minAmount / maxAmount — both in USD; your local-currency amount is converted before this check

Previewing Fees

Call Settlement Fee Preview with ?amount=&walletId= before submitting. The response shows the fee, net amount, and USD-equivalent values used for limit checking.

Single Settlement Flow

1. Check the schedule — confirm settlements are enabled and your amount is within minAmount/maxAmount. 2. Preview the fee — confirm the net amount is acceptable. 3. Submit — call Request Settlement. The response includes the settlement ID and initial status PENDING. 4. Wait for review — status moves to UNDER_REVIEW then APPROVED. 5. Funds disbursed — status moves to PROCESSED once funds reach your destination. 6. You are notified — via callbackUrl or notification preferences at each status transition.

Batch Settlement Flow

Batch settlements submit multiple wallet requests in one call. Each child settlement is processed independently. The batch status reflects the aggregate of its children. 1. Prepare your requests array — each item follows the same schema as a single settlement request: walletId, amount, balanceSource, plus beneficiaryDetails or savedBeneficiaryId. 2. Submit the batch — call Create Batch Settlement with an optional batchReference for your own tracking. 3. Track the batch — call Get Settlement Batch for the overall status. Each child can also be fetched individually via Get Settlement. 4. Cancelling — call Cancel Settlement Batch. Children still in PENDING are cancelled; children in UNDER_REVIEW or later are not affected.

Batch Status at Completion

Condition	Webhook fired
All children `PROCESSED`	`settlement.batch.processed`
All children `REJECTED`	`settlement.batch.rejected`
Mix of `PROCESSED` and `REJECTED`/`FAILED`	`settlement.batch.partial`
Batch cancelled	`settlement.batch.cancelled`
Batch approved by admin	`settlement.batch.approved`

Merge Flow

The merge endpoint converts two or more existing individual settlements into a batch after the fact. 1. Identify settlements to merge — all must be PENDING or UNDER_REVIEW and not already in a batch. 2. Submit the merge — call Merge Settlements into Batch with the settlementIds array (minimum 2). 3. A new batch is created — the response contains the new batch ID. The source settlements become children of that batch.

You cannot un-merge settlements once grouped into a batch. To cancel, use Cancel Settlement Batch.

Webhook Events

Settlement events are delivered via the signed webhook system — see Webhook Notifications for verification and retry details.

Event	When it fires
`settlement.approved`	Settlement moves to `APPROVED`
`settlement.rejected`	Settlement is `REJECTED` after review
`settlement.processed`	Settlement reaches `PROCESSED` — funds delivered
`settlement.cancelled`	Settlement cancelled by integrator
`settlement.paused`	Admin pauses the settlement
`settlement.batch.approved`	Batch approved by admin
`settlement.batch.rejected`	All children in a batch are `REJECTED`
`settlement.batch.processed`	All children in a batch reach `PROCESSED`
`settlement.batch.partial`	Some children `PROCESSED`, others `REJECTED` or `FAILED`
`settlement.batch.cancelled`	Batch cancelled by integrator

Example: `settlement.paused`

{
  "event": "settlement.paused",
  "data": {
    "settlementId": "stl_abc123",
    "status": "PAUSED",
    "pauseReason": "Additional KYC documentation required for this destination",
    "pausedUntil": "2025-05-10T00:00:00.000Z",
    "currency": "KES",
    "amount": 50000
  },
  "signature": "sha256=a1b2c3..."
}

Example: `settlement.batch.partial`

{
  "event": "settlement.batch.partial",
  "data": {
    "batchId": "bat_def789",
    "processedCount": 3,
    "rejectedCount": 1,
    "failedCount": 0,
    "totalCount": 4
  },
  "signature": "sha256=b2c3d4..."
}

Saved Beneficiaries

Store destination details once and reference by ID on any settlement or batch request.

Create — Create Settlement Beneficiary
Use savedBeneficiaryId in your settlement or batch request
Update — Update Settlement Beneficiary
Delete — Delete Settlement Beneficiary

Notification Preferences

Configure email and Slack notifications via Update Notification Preferences. These supplement signed webhook delivery and are intended for human awareness rather than programmatic integration.

Dashboard Settlements API

Full parameter reference for all settlement endpoints

Webhook Notifications

Signed webhooks, verification, and retry behaviour

Balances & Settlement

Deposit vs payout balances

Transaction Statuses

All status codes across the API

Getting Started

Testing & Launch

Core Concepts

Connecting Your System

Products

Settlement Lifecycle

Active States

Terminal States

PAUSED State

Checking the Schedule

Previewing Fees

Single Settlement Flow

Batch Settlement Flow

Batch Status at Completion

Merge Flow

Webhook Events

Example: `settlement.paused`

Example: `settlement.batch.partial`

Saved Beneficiaries

Notification Preferences

Dashboard Settlements API

Webhook Notifications

Balances & Settlement

Transaction Statuses

​Settlement Lifecycle

​Active States

​Terminal States

​PAUSED State

​Checking the Schedule

​Previewing Fees

​Single Settlement Flow

​Batch Settlement Flow

​Batch Status at Completion

​Merge Flow

​Webhook Events

​Example: settlement.paused

​Example: settlement.batch.partial

​Saved Beneficiaries

​Notification Preferences

​Related

Dashboard Settlements API

Webhook Notifications

Balances & Settlement

Transaction Statuses

Settlement Lifecycle

Active States

Terminal States

PAUSED State

Checking the Schedule

Previewing Fees

Single Settlement Flow

Batch Settlement Flow

Batch Status at Completion

Merge Flow

Webhook Events

Example: `settlement.paused`

Example: `settlement.batch.partial`

Saved Beneficiaries

Notification Preferences

Related