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
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.
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
| Scenario ID | Scenario | Trigger creds | Steps to follow |
|---|
| SETL-01 | A settlement is created and processed | A settleable test balance on your settlement schedule | - Create and capture test payments so your test balance covers the settlement.
- Wait for your scheduled settlement to run.
- Observe the settlement move
created → processed (about 2 minutes), the test balance decrement, and settlement.processed fire.
|
| SETL-02 | Create an instant (on-demand) settlement (Coming soon) | A settleable test balance; a test key | - Call
POST /v1/settlements/ondemand with an amount, or settle the full balance. A fee applies. - Confirm the response:
status, amount settled, fees and tax.
|
3.2 Other common settlement scenarios
| Scenario ID | Scenario | Trigger creds | Steps to follow |
|---|
| SETL-03 | Low balance terminates the settlement | A test balance lower than the settlement amount | - Keep your test balance below the settlement amount.
- Let the scheduled settlement run.
- Confirm the settlement is terminated at creation (“Balance is going negative”), does not reach
processed, and does not appear in the Recon report.
|
| SETL-04 | Reconcile a settlement (Recon API) (Coming soon) | A processed test settlement; a test key | - Call
GET /v1/settlements/recon/combined?year=&month=&day= with your test key for the settlement’s date. - Confirm the response is a collection with one row per transaction, each carrying the
settlement_id and a (mock) UTR. - Reconcile each row (payment, refund, adjustment, card and order details) against your records.
|
| SETL-05 | Fetch settlements (Coming soon) | A settlement in test mode; a test key | - Call
GET /v1/settlements to list all settlements, or GET /v1/settlements/:id for one. - Confirm each settlement’s
id (setl_…), amount, status, fees, tax and utr. - Use fetch to detect settlements that did not reach
processed (a failed settlement fires no webhook).
|
| SETL-06 | Fetch instant (on-demand) settlements (Coming soon) | An instant settlement in test mode; a test key | - Call
GET /v1/settlements/ondemand to list all instant settlements, or GET /v1/settlements/ondemand/:id for one. - Confirm each instant settlement’s
status, amount settled, fees and tax.
|
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.
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 | 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. |
|---|
| 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 Create an instant (on-demand) settlement
| Before you start | A settleable test balance and your test key. |
|---|
| How to test | POST /v1/settlements/ondemand with an amount, or settle the full balance. |
|---|
| Expected result | An instant settlement is created and settled on demand; the response carries status, amount settled, fees and tax. A fee applies. |
|---|
| Webhooks | None confirmed for instant settlements in test; use the fetch APIs for status. |
|---|
| Your integration should | Account for the instant-settlement fee and confirm the outcome with the fetch APIs. |
|---|
SETL-03 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-04 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). |
|---|
SETL-05 Fetch settlements
| Before you start | At least one settlement in test mode and your test key. |
|---|
| How to test | GET /v1/settlements and GET /v1/settlements/:id. |
|---|
| Expected result | Settlement-level data: id, amount, status, fees, tax, utr and created_at, same shape as live. |
|---|
| Webhooks | None (synchronous API). |
|---|
| Your integration should | Fetch to detect settlements that did not reach processed, since a failed settlement fires no webhook. |
|---|
SETL-06 Fetch instant (on-demand) settlements
| Before you start | At least one instant settlement in test mode and your test key. |
|---|
| How to test | GET /v1/settlements/ondemand and GET /v1/settlements/ondemand/:id. |
|---|
| Expected result | Instant settlement-level data: status, amount settled, fees and tax, same shape as live. |
|---|
| Webhooks | None (synchronous API). |
|---|
| Your integration should | Use the fetch APIs to confirm instant settlements and reconcile them. |
|---|
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.
6. Common integration gaps to avoid