On-demand settlements let you transfer your available Razorpay balance to your bank account immediately, outside the normal settlement cycle. Fees apply. Requires Instant Settlements to be enabled on your account.
openapi: 3.0.0
info:
title: Razorpay Bills Instant Settlements API
version: 1.0.0
description: Razorpay payment gateway APIs for accepting payments, managing orders, processing refunds, payouts, and subscriptions. All amounts are in the smallest currency sub-unit (e.g. paise for INR). Supports 180+ payment methods including UPI, cards, netbanking, wallets, and EMI.
termsOfService: https://razorpay.com/terms/
contact:
name: Razorpay Support
url: https://razorpay.com/support/
email: support@razorpay.com
license:
name: Proprietary
url: https://razorpay.com/terms/
x-logo:
url: https://razorpay.com/favicon.png
x-auth-environments:
test:
keyPrefix: rzp_test_
description: Test mode — keys prefixed rzp_test_. Same API endpoint (https://api.razorpay.com/v1). No real money movement. Use test card numbers from https://razorpay.com/docs/payments/payments/test-card-details/.
live:
keyPrefix: rzp_live_
description: Live mode — keys prefixed rzp_live_. Real money movement. Requires KYC and business activation on the Razorpay Dashboard.
servers:
- url: https://api.razorpay.com/v1
description: Production
security:
- basicAuth: []
- oauth2:
- read_only
tags:
- name: Instant Settlements
description: On-demand settlements let you transfer your available Razorpay balance to your bank account immediately, outside the normal settlement cycle. Fees apply. Requires Instant Settlements to be enabled on your account.
paths:
/settlements/ondemand:
post:
operationId: createInstantSettlement
summary: Create an instant settlement
description: Request an on-demand (instant) settlement of your available Razorpay balance to your bank account. Fees apply. Use settle_full_balance=true to settle everything available, or specify an amount.
tags:
- Instant Settlements
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- amount
properties:
amount:
type: integer
description: Settlement amount in paise.
settle_full_balance:
type: boolean
description: Set true to settle the full available balance. Overrides amount.
default: false
description:
type: string
description: Custom reference note. Max 30 alphanumeric characters.
notes:
$ref: '#/components/schemas/Notes'
responses:
'200':
description: Instant settlement initiated.
content:
application/json:
schema:
$ref: '#/components/schemas/InstantSettlement'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
get:
operationId: fetchAllInstantSettlements
summary: Fetch all instant settlements
description: Retrieve a list of all on-demand instant settlements. Use expand[]=ondemand_payouts to include individual payout records inline.
tags:
- Instant Settlements
parameters:
- $ref: '#/components/parameters/from'
- $ref: '#/components/parameters/to'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/skip'
- name: expand[]
in: query
description: Set to ondemand_payouts to include payout details.
schema:
type: string
enum:
- ondemand_payouts
responses:
'200':
description: Collection of instant settlements.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Collection'
- properties:
items:
type: array
items:
$ref: '#/components/schemas/InstantSettlement'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
/settlements/ondemand/{id}:
get:
operationId: fetchInstantSettlement
summary: Fetch instant settlement by ID
description: Retrieve details of a specific on-demand instant settlement. Use expand[]=ondemand_payouts to include payout records.
tags:
- Instant Settlements
parameters:
- name: id
in: path
required: true
description: Instant settlement ID (setlod_*).
schema:
type: string
- name: expand[]
in: query
description: Set to ondemand_payouts to include payout details.
schema:
type: string
enum:
- ondemand_payouts
responses:
'200':
description: Instant settlement details.
content:
application/json:
schema:
$ref: '#/components/schemas/InstantSettlement'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
components:
schemas:
InstantSettlement:
type: object
properties:
id:
type: string
description: 'Unique instant settlement identifier. Prefix: setlod_'
entity:
type: string
enum:
- settlement.ondemand
amount_requested:
type: integer
description: Settlement amount requested (paise).
amount_settled:
type: integer
description: Total amount transferred minus fees and tax (paise).
amount_pending:
type: integer
description: Portion of requested amount yet to be settled (paise).
amount_reversed:
type: integer
description: Amount returned to PG balance (paise).
fees:
type: integer
description: Combined fees and tax deducted (paise).
tax:
type: integer
description: Tax on fee component (paise).
currency:
type: string
settle_full_balance:
type: boolean
description: If true, settles maximum available balance.
status:
type: string
enum:
- created
- initiated
- partially_processed
- processed
- reversed
description:
type: string
description: Custom reference note. Max 30 alphanumeric characters.
notes:
$ref: '#/components/schemas/Notes'
created_at:
type: integer
ondemand_payouts:
type: object
description: Collection of individual payout records for this instant settlement.
properties:
entity:
type: string
enum:
- collection
count:
type: integer
items:
type: array
items:
$ref: '#/components/schemas/InstantSettlementPayout'
Notes:
type: object
description: Key-value pairs for storing custom metadata. Maximum 15 pairs. Each key and value must not exceed 256 characters.
additionalProperties:
type: string
maxProperties: 15
InstantSettlementPayout:
type: object
properties:
id:
type: string
entity:
type: string
enum:
- settlement.ondemand_payout
initiated_at:
type: integer
processed_at:
type: integer
reversed_at:
type: integer
amount:
type: integer
amount_settled:
type: integer
fees:
type: integer
tax:
type: integer
utr:
type: string
status:
type: string
enum:
- created
- initiated
- processed
- reversed
created_at:
type: integer
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: 'Error code. Examples: BAD_REQUEST_ERROR, GATEWAY_ERROR, SERVER_ERROR.'
description:
type: string
source:
type: string
description: Where the error originated (e.g. business, gateway).
step:
type: string
reason:
type: string
description: 'Machine-readable reason. Examples: insufficient_funds, invalid_expiry_date, declined_by_bank.'
metadata:
type: object
field:
type: string
Collection:
type: object
properties:
entity:
type: string
enum:
- collection
count:
type: integer
description: Number of items in the current page.
items:
type: array
items: {}
parameters:
from:
name: from
in: query
description: Unix timestamp (seconds). Fetch records created on or after this time.
schema:
type: integer
to:
name: to
in: query
description: Unix timestamp (seconds). Fetch records created on or before this time.
schema:
type: integer
skip:
name: skip
in: query
description: Number of records to skip. Use with count for pagination. Default 0.
schema:
type: integer
minimum: 0
default: 0
count:
name: count
in: query
description: Number of records to return per call. Maximum 100. Default 10.
schema:
type: integer
minimum: 1
maximum: 100
default: 10
responses:
'404':
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Bad request. Invalid parameters or missing required fields.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authentication failed. Invalid or missing API key credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded. Implement exponential backoff with jitter before retrying.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic authentication using your Razorpay API key pair. Use key_id as the username and key_secret as the password. Encode as Base64(key_id:key_secret). Keys are environment-scoped (Test vs Live). Obtain keys at https://dashboard.razorpay.com/app/keys. Keys are case-sensitive.
oauth2:
type: oauth2
description: OAuth 2.0 via the Razorpay MCP server (mcp.razorpay.com). Supports Authorization Code with PKCE (S256) for user-delegated access and Client Credentials for server-to-server access. Tokens expire in 3600 seconds. Dynamic Client Registration available at the registration endpoint. For integration setup see https://razorpay.com/docs/build/llm-docs/mcp-server/oauth.md.
flows:
authorizationCode:
authorizationUrl: https://mcp.razorpay.com/authorize
tokenUrl: https://mcp.razorpay.com/token
refreshUrl: https://mcp.razorpay.com/token
scopes:
read_only: Read-only access to Razorpay account data (payments, orders, refunds, payouts, subscriptions, invoices)
clientCredentials:
tokenUrl: https://mcp.razorpay.com/token
scopes:
read_only: Read-only access to Razorpay account data (payments, orders, refunds, payouts, subscriptions, invoices)
externalDocs:
description: Razorpay API Documentation
url: https://razorpay.com/docs/api/
x-tagGroups:
- name: Core Payments
tags:
- Orders
- Payments
- Refunds
- Payment Downtimes
- name: Payment Collection
tags:
- Payment Links
- QR Codes
- name: Billing & Subscriptions
tags:
- Items
- Invoices
- Plans
- Subscriptions
- name: Customer Management
tags:
- Customers
- Documents
- name: Finance & Reconciliation
tags:
- Settlements
- Instant Settlements
- Disputes
- name: Route & Marketplace
tags:
- Linked Accounts
- Transfers
- name: Smart Collect
tags:
- Virtual Accounts
- name: Partners & Onboarding
tags:
- Partner Accounts
- Partner Products
- Partner Stakeholders
- Partner Documents
- Partner Webhooks
- name: Bills
tags:
- Bills
- name: RazorpayX
tags:
- X Contacts
- X Fund Accounts
- X Account Validation
- X Banking Balances
- X Payouts
- X Payout Links
- X Transactions
x-rateLimit:
description: Razorpay does not publish specific rate limits. If you receive HTTP 429, implement exponential backoff with jitter and retry. Add randomisation to avoid thundering-herd effects.
throttleStatus: 429
strategy: exponential backoff with jitter
x-pagination:
description: All list endpoints return at most 100 records per call (1000 for settlement recon). Use count and skip together to paginate. Date range filters (from/to) use Unix timestamps in seconds.
example: GET /payments?from=1700000000&to=1700086400&count=100&skip=100
x-amountEncoding:
description: 'All monetary amounts are in the smallest currency sub-unit. For INR: 1 rupee = 100 paise, so ₹500 = 50000. Minimum for INR is 100 paise (₹1). Three-decimal currencies (KWD, BHD, OMR): drop last decimal digit. Zero-decimal currencies (JPY): pass value as-is.'