> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Settlements: How to Integrate

> Integrate Settlements on your server: fetch settlements, reconcile transactions and handle the settlement webhook.

Available in
🇮🇳 India

Settlements move your captured payments into your bank account automatically, on your settlement cycle (T+2 working days by default). You do not trigger a settlement. Instead, you integrate by fetching settlements, reconciling the transactions inside each one, and reacting to the `settlement.processed` webhook. This guide covers the live integration; validate it first with [Settlements: Test your integration](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/settlements.md).

## How settlements work

Razorpay automatically settles your captured payments on your settlement cycle. There is no "create settlement" call, so your integration has three jobs:

* **Fetch** your settlements.
* **Reconcile** the transactions in each settlement.
* **React** to the `settlement.processed` webhook.

Each settlement is the net amount:

**Amount settled = Payment ± Adjustment - Refunds - Fee - Tax - Transfer**

A settlement moves `created` → `processed`. It can also move to `failed`; `failed` is not final, so a failed settlement may be retried and still reach `processed`.

> [!NOTE]
>
> **Note**
>
> Instant Settlements are the on-demand exception. Unlike automatic settlements, you trigger them yourself through the Instant Settlements API when you want faster access to your funds.

## Before you begin

* Generate your **live** API keys (`rzp_live_`).
* Your account must be KYC approved, activated, and have a valid bank account added. Settlements are credited to this account.
* Configure a webhook URL subscribed to `settlement.processed`.

## How to integrate

### Fetch settlements

* `GET /v1/settlements/` lists your settlements.
* `GET /v1/settlements/:id` returns a single settlement.

The settlement entity carries `id` (`setl_...`), `amount` (in paise), `status`, `fees`, `tax`, `utr` and `created_at`.

A `failed` settlement does not fire a webhook, so `GET /v1/settlements/` is how you detect settlements that did not reach `processed`. Fetch periodically to catch them.

### Reconcile settlements

Use the recon API to see every transaction that made up a settlement.

```
GET /v1/settlements/recon/combined?year=&month=&day=
```

`day` is optional; omit it to reconcile the whole month. The response is paginated, so page through it with `count` and `skip` to avoid missing rows when there are many transactions.

The response returns one row per transaction (payments, refunds, adjustments and transfers), each carrying the `settlement_id` and the settlement UTR. Rows appear as soon as the settlement is `created`, so the UTR can be empty until it is `processed`. Reconcile by `settlement_id` and date against your records, and do not hardcode the UTR format.

### Instant Settlements (on-demand)

Instant Settlements let you settle on demand instead of waiting for the cycle. A fee applies.

* `POST /v1/settlements/ondemand` creates an instant settlement (set an amount or settle the full balance).
* `GET /v1/settlements/ondemand` lists your instant settlements.
* `GET /v1/settlements/ondemand/:id` returns a single instant settlement.

### Handle the webhook

| Event | What it means | What to do |
| - | - | - |
| `settlement.processed` | Razorpay has processed the settlement and the payout has left Razorpay for your bank account. | Treat it as "Razorpay processed it," not "money in the bank". The bank credit can still lag on the NEFT, RTGS or IMPS timeline. Reconcile on this event. |

Only successful settlements fire a webhook. A `failed` settlement sends no event, so detect those with `GET /v1/settlements/`.

Verify the webhook signature on every event before acting on it.

## Best practices

* Listen to `settlement.processed` for successful settlements, and fetch `GET /v1/settlements/` to catch settlements that did not process (there is no failure webhook).
* Verify the webhook signature on every event.
* Reconcile each settlement through the recon API, by `settlement_id` and date.
* Treat `settlement.processed` as "Razorpay processed it," not money in the bank; the bank credit can still lag.
* Do not hardcode the UTR format, and remember amounts are in the smallest currency unit (paise).
* If you use on-demand (instant) settlements, account for the per-settlement fee and confirm the outcome with the fetch APIs.

## Common mistakes to avoid

| Mistake | What goes wrong | What to do |
| - | - | - |
| Treating `settlement.processed` as money-in-bank | You tell a vendor they are paid before the bank credit lands. | Treat `processed` as "Razorpay processed it"; the bank credit can lag in live. |
| Hardcoding the UTR format | Reconciliation breaks when the UTR format differs from what you expect. | Reconcile by `settlement_id` and date, not by UTR shape. |
| Relying only on the webhook to know the outcome | A `failed` settlement fires no event, so a settlement that did not process looks like nothing happened. | Fetch `GET /v1/settlements/` to detect settlements that did not reach `processed`; `failed` is not final and can be retried. |
| Reading an empty UTR as a failure | Recon rows appear as soon as a settlement is `created`, before it is `processed`, so the UTR can be empty. | Reconcile once the settlement is `processed` to get the UTR, and page through the response with `count` and `skip`. |

## Test your integration

Before going live, run the full flow in test mode: a settlement that is created and processed, low-balance termination, and recon. See [Settlements: Test your integration](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/settlements.md).

## Go-live checklist

* Confirm a valid, active bank account is on file.
* Verify webhook signatures.
* Reconcile each settlement through the recon API.
* Handle settlements that do not reach `processed`.

## Related information

* [About Settlements](https://razorpay.com/docs/payments/settlements)
* [Settlement APIs](https://razorpay.com/docs/payments/settlements/apis.md)
* [Settlement API reference](https://razorpay.com/docs/api/settlements.md)
* [Settlements: Test your integration](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/settlements.md)
