> ## 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.

# Settlement Requests

> Settlement lifecycle, batch and merge flows, webhook events, and schedule rules

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.

***

<Note>
  You need [an API key](/v3/getting-started/api-keys) and a reachable `callbackUrl` — see the [Quickstart](/v3/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](/v3/api-reference/settlements/settlement-config/beneficiaries).
</Note>

## 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](#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. |

<Note>
  Stop polling once a settlement reaches a terminal state. Use the `callbackUrl` or configure [notification preferences](/v3/api-reference/settlements/notification-preferences) to receive status-change events instead.
</Note>

***

## 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](#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](/v3/api-reference/settlements/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](/v3/api-reference/settlements/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](/v3/api-reference/settlements/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](/v3/api-reference/settlements/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](/v3/api-reference/settlements/batch/create) with an optional `batchReference` for your own tracking.

**3. Track the batch** — call [Get Settlement Batch](/v3/api-reference/settlements/batch/get) for the overall status. Each child can also be fetched individually via [Get Settlement](/v3/api-reference/settlements/get-settlement).

**4. Cancelling** — call [Cancel Settlement Batch](/v3/api-reference/settlements/batch/cancel). 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](/v3/api-reference/settlements/merge) 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.

<Warning>
  You cannot un-merge settlements once grouped into a batch. To cancel, use [Cancel Settlement Batch](/v3/api-reference/settlements/batch/cancel).
</Warning>

***

## Webhook Events

Settlement events are delivered via the signed webhook system — see [Webhook Notifications](/v3/essentials/webhooks) 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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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.

1. Create — [Create Settlement Beneficiary](/v3/api-reference/settlements/settlement-config/create-beneficiary)
2. Use `savedBeneficiaryId` in your settlement or batch request
3. Update — [Update Settlement Beneficiary](/v3/api-reference/settlements/settlement-config/get-beneficiary)
4. Delete — [Delete Settlement Beneficiary](/v3/api-reference/settlements/settlement-config/delete-beneficiary)

***

## Notification Preferences

Configure email and Slack notifications via [Update Notification Preferences](/v3/api-reference/settlements/notification-preferences). These supplement signed webhook delivery and are intended for human awareness rather than programmatic integration.

***

## Related

<CardGroup cols={2}>
  <Card title="Dashboard Settlements API" icon="code" href="/v3/api-reference/settlements/dashboard-settlements">
    Full parameter reference for all settlement endpoints
  </Card>

  <Card title="Webhook Notifications" icon="bell" href="/v3/essentials/webhooks">
    Signed webhooks, verification, and retry behaviour
  </Card>

  <Card title="Balances & Settlement" icon="wallet" href="/v3/essentials/balances-and-settlement">
    Deposit vs payout balances
  </Card>

  <Card title="Transaction Statuses" icon="circle-dot" href="/v3/essentials/transaction-statuses">
    All status codes across the API
  </Card>
</CardGroup>