Available in🇮🇳 India
Settlements move your captured payments into your bank account automatically, on your settlement cycle (T+2 working days by default). You do not trigger a settlement. Instead, you integrate by fetching settlements, reconciling the transactions inside each one, and reacting to the settlement.processed webhook. This guide covers the live integration; validate it first with Settlements: Test your integration.
How settlements work
Razorpay automatically settles your captured payments on your settlement cycle. There is no “create settlement” call, so your integration has three jobs:- Fetch your settlements.
- Reconcile the transactions in each settlement.
- React to the
settlement.processedwebhook.
created → processed. It can also move to failed; failed is not final, so a failed settlement may be retried and still reach processed.
NoteInstant Settlements are the on-demand exception. Unlike automatic settlements, you trigger them yourself through the Instant Settlements API when you want faster access to your funds.
Before you begin
- Generate your live API keys (
rzp_live_). - Your account must be KYC approved, activated, and have a valid bank account added. Settlements are credited to this account.
- Configure a webhook URL subscribed to
settlement.processed.
How to integrate
Fetch settlements
GET /v1/settlements/lists your settlements.GET /v1/settlements/:idreturns a single settlement.
id (setl_...), amount (in paise), status, fees, tax, utr and created_at.
A failed settlement does not fire a webhook, so GET /v1/settlements/ is how you detect settlements that did not reach processed. Fetch periodically to catch them.
Reconcile settlements
Use the recon API to see every transaction that made up a settlement.day is optional; omit it to reconcile the whole month. The response is paginated, so page through it with count and skip to avoid missing rows when there are many transactions.
The response returns one row per transaction (payments, refunds, adjustments and transfers), each carrying the settlement_id and the settlement UTR. Rows appear as soon as the settlement is created, so the UTR can be empty until it is processed. Reconcile by settlement_id and date against your records, and do not hardcode the UTR format.
Instant Settlements (on-demand)
Instant Settlements let you settle on demand instead of waiting for the cycle. A fee applies.POST /v1/settlements/ondemandcreates an instant settlement (set an amount or settle the full balance).GET /v1/settlements/ondemandlists your instant settlements.GET /v1/settlements/ondemand/:idreturns a single instant settlement.
Handle the webhook
Only successful settlements fire a webhook. A
failed settlement sends no event, so detect those with GET /v1/settlements/.
Verify the webhook signature on every event before acting on it.
Best practices
- Listen to
settlement.processedfor successful settlements, and fetchGET /v1/settlements/to catch settlements that did not process (there is no failure webhook). - Verify the webhook signature on every event.
- Reconcile each settlement through the recon API, by
settlement_idand date. - Treat
settlement.processedas “Razorpay processed it,” not money in the bank; the bank credit can still lag. - Do not hardcode the UTR format, and remember amounts are in the smallest currency unit (paise).
- If you use on-demand (instant) settlements, account for the per-settlement fee and confirm the outcome with the fetch APIs.
Common mistakes to avoid
Test your integration
Before going live, run the full flow in test mode: a settlement that is created and processed, low-balance termination, and recon. See Settlements: Test your integration.Go-live checklist
- Confirm a valid, active bank account is on file.
- Verify webhook signatures.
- Reconcile each settlement through the recon API.
- Handle settlements that do not reach
processed.