> ## 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 Test Your Integration

> Test settlement creation, processing and reconciliation for your S2S integration in Test Mode, including low-balance termination.

Available in
🇮🇳 India

Settlements move the money you collect into your bank account. In test mode you test the full journey with no real money moving: a settlement is created automatically from your test balance, reaches `processed` in about two minutes, and can be reconciled with the Recon API. The bank payout and customer notifications are stubbed, but webhooks still fire.

## 1. Test mode coverage

| Area | What you can test | Available on test mode |
| - | - | - |
| Settlement creation and processing | A settlement is created automatically on your schedule and moves `created` → `processed` in about 2 minutes, the same as in live. Your test balance decrements by the settled amount, and the UTR is a random mock value, not a real bank UTR. | (Available) |
| Recon API | Reconcile a `processed` test settlement’s transactions; same response shape as live. | (Coming soon) |
| Fetch settlements | Query settlements with `GET /v1/settlements` and `GET /v1/settlements/:id`. | (Coming soon) |
| Instant (on-demand) settlements | Create and fetch on-demand settlements with the `/v1/settlements/ondemand` APIs; a fee applies. | (Coming soon) |
| Webhooks | `settlement.processed` fires to your test webhook. | (Coming soon) |
| Low-balance termination | A settlement terminates at creation when the test balance is lower than the settlement amount. | (Available) |
| Settlement failure (bank reject) | Bank-side rejections such as a closed or invalid bank account. | (Live only) |
| Customer notifications | Email, SMS and WhatsApp to the merchant. | (Live only) |
| Real money movement | Actual payout to your bank account. | (Live only) |

## 2. Test kit

* Switch the Dashboard to **Test Mode** with the toggle at the top. Generate test keys: **Account & Settings → API Keys → Generate Test Key**. Test keys start with `rzp_test_`.
* You need a settleable **test balance**, so create and capture test payments first. Settlements are created **automatically on your settlement schedule**, not by a merchant API call.
* In your **test mode** Dashboard, add a webhook for the `settlement.processed` event pointing to your server, so Razorpay notifies you when a test settlement completes.

| Use it to test | Set up | Notes |
| - | - | - |
| A settlement that processes | A test balance that is **at least** the settlement amount. | The settlement reaches `processed` in \~2 min. |
| A terminated settlement | A test balance **lower than** the settlement amount. | Terminated at creation (“Balance is going negative”); never reaches `processed`. |
| The Recon API | At least one `processed` test settlement in the day you query. | Use your test key and query by the settlement’s date (year, month, day). |
| Fetch settlements (Coming soon) | Any settlement in test mode. | `GET /v1/settlements` or `GET /v1/settlements/:id` with your test key. |
| Instant (on-demand) settlements (Coming soon) | A settleable test balance. | `POST /v1/settlements/ondemand` to create, then `GET /v1/settlements/ondemand` or `GET /v1/settlements/ondemand/:id` to fetch. A fee applies. |

## 3. Scenarios to test your integration

Grouped into the must-have settlement flows, other common flows, and error scenarios. Click a Scenario ID for its details.

### 3.1 Must-have settlement scenarios

<table>
  <colgroup>
    <col width="10%" />

    <col width="24%" />

    <col width="24%" />

    <col width="42%" />
  </colgroup>

  <thead><tr><th>Scenario ID</th><th>Scenario</th><th>Trigger creds</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>SETL-01</td><td>A settlement is created and processed</td><td>A settleable test balance on your settlement schedule</td><td><ol><li>Create and capture test payments so your test balance covers the settlement.</li><li>Wait for your scheduled settlement to run.</li><li>Observe the settlement move `created` → `processed` (about 2 minutes), the test balance decrement, and `settlement.processed` fire.</li></ol></td></tr>
    <tr><td>SETL-02</td><td>Create an instant (on-demand) settlement (Coming soon)</td><td>A settleable test balance; a test key</td><td><ol><li>Call `POST /v1/settlements/ondemand` with an amount, or settle the full balance. A fee applies.</li><li>Confirm the response: `status`, amount settled, `fees` and `tax`.</li></ol></td></tr>
  </tbody>
</table>

### 3.2 Other common settlement scenarios

<table>
  <colgroup>
    <col width="10%" />

    <col width="24%" />

    <col width="24%" />

    <col width="42%" />
  </colgroup>

  <thead><tr><th>Scenario ID</th><th>Scenario</th><th>Trigger creds</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>SETL-03</td><td>Low balance terminates the settlement</td><td>A test balance lower than the settlement amount</td><td><ol><li>Keep your test balance below the settlement amount.</li><li>Let the scheduled settlement run.</li><li>Confirm the settlement is terminated at creation (“Balance is going negative”), does not reach `processed`, and does not appear in the Recon report.</li></ol></td></tr>
    <tr><td>SETL-04</td><td>Reconcile a settlement (Recon API) (Coming soon)</td><td>A `processed` test settlement; a test key</td><td><ol><li>Call `GET /v1/settlements/recon/combined?year=&month=&day=` with your test key for the settlement’s date.</li><li>Confirm the response is a collection with one row per transaction, each carrying the `settlement_id` and a (mock) UTR.</li><li>Reconcile each row (payment, refund, adjustment, card and order details) against your records.</li></ol></td></tr>
    <tr><td>SETL-05</td><td>Fetch settlements (Coming soon)</td><td>A settlement in test mode; a test key</td><td><ol><li>Call `GET /v1/settlements` to list all settlements, or `GET /v1/settlements/:id` for one.</li><li>Confirm each settlement's `id` (`setl_...`), `amount`, `status`, `fees`, `tax` and `utr`.</li><li>Use fetch to detect settlements that did not reach `processed` (a failed settlement fires no webhook).</li></ol></td></tr>
    <tr><td>SETL-06</td><td>Fetch instant (on-demand) settlements (Coming soon)</td><td>An instant settlement in test mode; a test key</td><td><ol><li>Call `GET /v1/settlements/ondemand` to list all instant settlements, or `GET /v1/settlements/ondemand/:id` for one.</li><li>Confirm each instant settlement's `status`, amount settled, `fees` and `tax`.</li></ol></td></tr>
  </tbody>
</table>

Settlements are created automatically at your scheduled settlement time, so there is no create-request error for the scheduled flow. The Recon, Fetch and on-demand APIs return the same request errors as live. Trigger the Recon errors below with a bad request and read the response to handle it.

| Scenario | Trigger | Expected |
| - | - | - |
| Invalid or missing date parameters on Recon | Call `GET /v1/settlements/recon/combined?year=&month=&day=` with a missing or malformed `year` / `month` / `day`. | HTTP `400` validation error, identical to live. |
| Querying a day with no settlements | Call Recon for a date with no `processed` test settlement. | An empty collection (no rows), not an error. |

## 4. Scenario details

SETL-01  A settlement is created and processed

<table>
  <tbody>
    <tr><th>Before you start</th><td>A settleable test balance (create and capture test payments first) and a configured test webhook.</td></tr>
    <tr><th>How to test</th><td>A settlement is created automatically at your scheduled settlement time; there is no create API to call. Let your scheduled settlement run, or wait for the schedule to fire.</td></tr>
    <tr><th>Expected result</th><td>Built the same way as in live, it moves `created` → `processed` within about 2 minutes, and your test balance decrements. The UTR is a random mock value, not a real bank UTR.</td></tr>
    <tr><th>Webhooks</th><td>`settlement.processed` fires. There is no `settlement.failed` in test mode.</td></tr>
    <tr><th>Your integration should</th><td>Treat `settlement.processed` as “Razorpay processed it,” reconcile on the webhook, and not depend on real bank-UTR formats.</td></tr>
  </tbody>
</table>

SETL-02  Create an instant (on-demand) settlement

<table>
  <tbody>
    <tr><th>Before you start</th><td>A settleable test balance and your test key.</td></tr>
    <tr><th>How to test</th><td>`POST /v1/settlements/ondemand` with an amount, or settle the full balance.</td></tr>
    <tr><th>Expected result</th><td>An instant settlement is created and settled on demand; the response carries `status`, amount settled, `fees` and `tax`. A fee applies.</td></tr>
    <tr><th>Webhooks</th><td>None confirmed for instant settlements in test; use the fetch APIs for status.</td></tr>
    <tr><th>Your integration should</th><td>Account for the instant-settlement fee and confirm the outcome with the fetch APIs.</td></tr>
  </tbody>
</table>

SETL-03  Low balance terminates the settlement

<table>
  <tbody>
    <tr><th>Before you start</th><td>A test balance lower than the settlement amount.</td></tr>
    <tr><th>How to test</th><td>Let the scheduled settlement run against a low balance.</td></tr>
    <tr><th>Expected result</th><td>The settlement is terminated at creation (“Balance is going negative”). It never reaches `processed` and never appears in the Recon report.</td></tr>
    <tr><th>Webhooks</th><td>None.</td></tr>
    <tr><th>Your integration should</th><td>Not assume every created settlement completes; handle the case where a settlement does not process.</td></tr>
  </tbody>
</table>

SETL-04  Reconcile a settlement (Recon API)

<table>
  <tbody>
    <tr><th>Before you start</th><td>At least one `processed` test settlement in the day you query.</td></tr>
    <tr><th>How to test</th><td>Call `GET /v1/settlements/recon/combined?year=&month=&day=` with your test key.</td></tr>
    <tr><th>Expected result</th><td>Same response shape as live: a collection with one row per transaction, the `settlement_id` and a mock UTR on each row, with payment, refund, adjustment, card and order details.</td></tr>
    <tr><th>Webhooks</th><td>None (synchronous API).</td></tr>
    <tr><th>Your integration should</th><td>Reconcile by `settlement_id` and date, and not hardcode the UTR format (it is a mock ID in test).</td></tr>
  </tbody>
</table>

SETL-05  Fetch settlements

<table>
  <tbody>
    <tr><th>Before you start</th><td>At least one settlement in test mode and your test key.</td></tr>
    <tr><th>How to test</th><td>`GET /v1/settlements` and `GET /v1/settlements/:id`.</td></tr>
    <tr><th>Expected result</th><td>Settlement-level data: `id`, `amount`, `status`, `fees`, `tax`, `utr` and `created_at`, same shape as live.</td></tr>
    <tr><th>Webhooks</th><td>None (synchronous API).</td></tr>
    <tr><th>Your integration should</th><td>Fetch to detect settlements that did not reach `processed`, since a failed settlement fires no webhook.</td></tr>
  </tbody>
</table>

SETL-06  Fetch instant (on-demand) settlements

<table>
  <tbody>
    <tr><th>Before you start</th><td>At least one instant settlement in test mode and your test key.</td></tr>
    <tr><th>How to test</th><td>`GET /v1/settlements/ondemand` and `GET /v1/settlements/ondemand/:id`.</td></tr>
    <tr><th>Expected result</th><td>Instant settlement-level data: `status`, amount settled, `fees` and `tax`, same shape as live.</td></tr>
    <tr><th>Webhooks</th><td>None (synchronous API).</td></tr>
    <tr><th>Your integration should</th><td>Use the fetch APIs to confirm instant settlements and reconcile them.</td></tr>
  </tbody>
</table>

## 5. Webhooks: what fires, and what it lets you decide

Only a settlement that reaches `processed` delivers a webhook (`settlement.processed`). Fetch, recon and on-demand settlements are request/response, and a terminated settlement fires nothing, so your integration must not wait for an event in those cases.

| Scenario | What it is | Events, in order | What it lets you decide |
| - | - | - | - |
| **SETL-01** | A settlement is created and processed | `settlement.processed` | `settlement.processed`: Razorpay has processed the settlement and the payout has left Razorpay. In live the bank credit can still lag, so treat this as processed, not money in the bank. Reconcile on this event. |
| **SETL-02** | Create an instant (on-demand) settlement | None confirmed | Confirm the instant settlement with the fetch APIs; do not rely on a webhook in test. |
| **SETL-03** | Low balance terminates the settlement | None | A terminated settlement fires no webhook. Do not assume every scheduled settlement emits `settlement.processed`; handle the settlement that never arrives. |
| **SETL-04** | Reconcile a settlement (Recon API) | None (synchronous API) | Recon is request/response. Read the response directly; do not wait for an event. |
| **SETL-05** | Fetch settlements | None (synchronous API) | Fetch is request/response. Read the response directly; use it to detect settlements that did not process. |
| **SETL-06** | Fetch instant (on-demand) settlements | None (synchronous API) | Fetch is request/response. Read the response directly. |

## 6. Common integration gaps to avoid

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| 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. In test it is instant and mocked. | SETL-01 |
| Hardcoding the UTR format | Reconciliation breaks because the test UTR is a random mock ID. | Reconcile by `settlement_id` and date, not by UTR shape. | SETL-04 |
| Assuming every settlement completes | A failed settlement fires no webhook, so a settlement that did not process can look like nothing happened. | Fetch `GET /v1/settlements` to detect settlements that did not reach `processed`. | SETL-05 |
| Reconciling before settlements exist | An empty Recon response is read as an error. | Recon only returns settlements created in the day’s window; create test payments and let a settlement process first. | SETL-03 / SETL-04 |

### Related Information

* [Test Your S2S Integration](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s.md)
* [Orders](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md)
* [About Settlements](https://razorpay.com/docs/payments/settlements)
