Skip to main content
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 IDScenarioTrigger credsSteps to follow
SETL-01A settlement is created and processedA settleable test balance on your settlement schedule
  1. Create and capture test payments so your test balance covers the settlement.
  2. Wait for your scheduled settlement to run.
  3. Observe the settlement move created → processed (about 2 minutes), the test balance decrement, and settlement.processed fire.
SETL-02Create an instant (on-demand) settlement (Coming soon)A settleable test balance; a test key
  1. Call POST /v1/settlements/ondemand with an amount, or settle the full balance. A fee applies.
  2. Confirm the response: status, amount settled, fees and tax.

3.2 Other common settlement scenarios

Scenario IDScenarioTrigger credsSteps to follow
SETL-03Low balance terminates the settlementA test balance lower than the settlement amount
  1. Keep your test balance below the settlement amount.
  2. Let the scheduled settlement run.
  3. Confirm the settlement is terminated at creation (“Balance is going negative”), does not reach processed, and does not appear in the Recon report.
SETL-04Reconcile a settlement (Recon API) (Coming soon)A processed test settlement; a test key
  1. Call GET /v1/settlements/recon/combined?year=&month=&day= with your test key for the settlement’s date.
  2. Confirm the response is a collection with one row per transaction, each carrying the settlement_id and a (mock) UTR.
  3. Reconcile each row (payment, refund, adjustment, card and order details) against your records.
SETL-05Fetch settlements (Coming soon)A settlement in test mode; a test key
  1. Call GET /v1/settlements to list all settlements, or GET /v1/settlements/:id for one.
  2. Confirm each settlement’s id (setl_…), amount, status, fees, tax and utr.
  3. Use fetch to detect settlements that did not reach processed (a failed settlement fires no webhook).
SETL-06Fetch instant (on-demand) settlements (Coming soon)An instant settlement in test mode; a test key
  1. Call GET /v1/settlements/ondemand to list all instant settlements, or GET /v1/settlements/ondemand/:id for one.
  2. 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 startA settleable test balance (create and capture test payments first) and a configured test webhook.
How to testA 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 resultBuilt 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.
Webhookssettlement.processed fires. There is no settlement.failed in test mode.
Your integration shouldTreat 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 startA settleable test balance and your test key.
How to testPOST /v1/settlements/ondemand with an amount, or settle the full balance.
Expected resultAn instant settlement is created and settled on demand; the response carries status, amount settled, fees and tax. A fee applies.
WebhooksNone confirmed for instant settlements in test; use the fetch APIs for status.
Your integration shouldAccount for the instant-settlement fee and confirm the outcome with the fetch APIs.
SETL-03  Low balance terminates the settlement
Before you startA test balance lower than the settlement amount.
How to testLet the scheduled settlement run against a low balance.
Expected resultThe settlement is terminated at creation (“Balance is going negative”). It never reaches processed and never appears in the Recon report.
WebhooksNone.
Your integration shouldNot assume every created settlement completes; handle the case where a settlement does not process.
SETL-04  Reconcile a settlement (Recon API)
Before you startAt least one processed test settlement in the day you query.
How to testCall GET /v1/settlements/recon/combined?year=&month=&day= with your test key.
Expected resultSame 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.
WebhooksNone (synchronous API).
Your integration shouldReconcile by settlement_id and date, and not hardcode the UTR format (it is a mock ID in test).
SETL-05  Fetch settlements
Before you startAt least one settlement in test mode and your test key.
How to testGET /v1/settlements and GET /v1/settlements/:id.
Expected resultSettlement-level data: id, amount, status, fees, tax, utr and created_at, same shape as live.
WebhooksNone (synchronous API).
Your integration shouldFetch to detect settlements that did not reach processed, since a failed settlement fires no webhook.
SETL-06  Fetch instant (on-demand) settlements
Before you startAt least one instant settlement in test mode and your test key.
How to testGET /v1/settlements/ondemand and GET /v1/settlements/ondemand/:id.
Expected resultInstant settlement-level data: status, amount settled, fees and tax, same shape as live.
WebhooksNone (synchronous API).
Your integration shouldUse 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

Last modified on November 18, 2026