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 | 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.
|
3.2 Other common settlement scenarios
| Scenario ID | Scenario | Trigger creds | Steps to follow |
|---|
| SETL-03 | Reconcile a settlement (Recon API) | 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.
|
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.
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.
6. Common Integration Gaps to Avoid
Last modified on November 17, 2026