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

# Test Settlements

> 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 way as in live. | Available |
| Settled balance | Your test balance decrements by the settled amount, exactly as in live. | Available |
| Reference / UTR | The settlement's UTR is a random mock value, not a real bank UTR. | Available (mock) |
| Recon API | Reconcile a `processed` test settlement's transactions; same response shape as live. | Available |
| Webhooks | `settlement.processed` fires to your test webhook. | Available |
| 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). |

## 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>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>
  </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>Reconcile a settlement (Recon API)</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>
  </tbody>
</table>

### 3.3 Settlement error scenarios

Settlements are created automatically, so request errors come only from the Recon API. Trigger each 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**

*Before you start:* a settleable test balance (create and capture test payments first) and a configured test webhook.

*How to test:* let your scheduled settlement run, or wait for the schedule to fire.

*Expected result:* 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.

*Webhooks:* `settlement.processed` fires. There is no `settlement.failed` in test mode.

*Your integration should:* treat `settlement.processed` as "Razorpay processed it," reconcile on the webhook, and not depend on real bank-UTR formats.

**SETL-02: Low balance terminates the settlement**

*Before you start:* a test balance lower than the settlement amount.

*How to test:* let the scheduled settlement run against a low balance.

*Expected result:* the settlement is terminated at creation ("Balance is going negative"). It never reaches `processed` and never appears in the Recon report.

*Webhooks:* none.

*Your integration should:* not assume every created settlement completes; handle the case where a settlement does not process.

**SETL-03: Reconcile a settlement (Recon API)**

*Before you start:* at least one `processed` test settlement in the day you query.

*How to test:* call `GET /v1/settlements/recon/combined?year=&month=&day=` with your test key.

*Expected result:* 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.

*Webhooks:* none (synchronous API).

*Your integration should:* reconcile by `settlement_id` and date, and not hardcode the UTR format (it is a mock ID in test).

## 5. Webhooks: What Fires, and What It Lets You Decide

Settlement creation is the only scenario that delivers a webhook. Recon is 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 | 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-03 | Reconcile a settlement (Recon API) | None (synchronous API) | Recon is request/response. Read the response directly; do not wait for an event. |

## 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-03 |
| Assuming every settlement completes | A low-balance or held settlement is treated as done. | Handle settlements that do not reach `processed`. | SETL-02 |
| 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-02 / SETL-03 |

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