Introduction

API Reference Guide

API Changelog

Understand Razorpay APIs

Authentication

Sandbox Setup

Install CLI

Best Practices

Glossary

Payments

Orders

Payments

Downtime

Settlements

Instant Settlements

Refunds

Disputes

Documents

Customers

Payment Links

QR Codes

Invoices

Subscriptions

Route

Smart Collect

Bills

About Bills

Bills Entity

Create a Bill

Update a Bill

Delete a Bill

Partners

Account

Product Configuration

Stakeholder

Documents

Webhooks

Payout APIs

Get Started

Account Validation

Fetch Balance

Composite Account Validation

Contacts

Fund Accounts

Payouts

Payouts to Cards

Payout Composite

Payouts Approval

Payout Idempotency

Payout Links

Payout Wallet - Amazon

Transactions

Api

Settlements

Instant

Create

API Test Keys

Create an Instant Settlement

POST
/v1/settlements/ondemand

Click to copy

Use this endpoint to create an Instant Settlement.

Is this page helpful?

Curl

change language

change language

1
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
2
-X POST https://api.razorpay.com/v1/settlements/ondemand \
3
-H "content-type: application/json" \
4
-d '{
5
  "amount": 200000,
6
  "settle_full_balance": false,
7
  "description": "Need this to make vendor payments.",
8
  "notes": {
9
    "notes_key_1": "Tea, Earl Grey, Hot",
10
    "notes_key_2": "Tea, Earl Grey… decaf."
11
  }
12
}'

Success

Failure

1
{
2
  "id": "setlod_FNj7g2YS5J67Rz",
3
  "entity": "settlement.ondemand",
4
  "amount_requested": 200000,
5
  "amount_settled": 0,
6
  "amount_pending": 199410,
7
  "amount_reversed": 0,
8
  "fees": 590,
9
  "tax": 90,
10
  "currency": "INR",
11
  "settle_full_balance": false,
12
  "status": "initiated",
13
  "description": "Need this to make vendor payments.",
14
  "notes": {
15
    "notes_key_1": "Tea, Earl Grey, Hot",
16
    "notes_key_2": "Tea, Earl Grey… decaf."
17
  },
18
  "created_at": 1596771429,
19
  "ondemand_payouts": {
20
    "entity": "collection",
21
    "count": 1,
22
    "items": [
23
      {
24
        "id": "setlodp_FNj7g2cbvw8ueO",
25
        "entity": "settlement.ondemand_payout",
26
        "initiated_at": null,
27
        "processed_at": null,
28
        "reversed_at": null,
29
        "amount": 200000,
30
        "amount_settled": null,
31
        "fees": 590,
32
        "tax": 90,
33
        "utr": null,
34
        "status": "created",
35
        "created_at": 1596771429
36
      }
37
    ]
38
  }
39
}
Request Parameters
amount

*

integer

The amount, in paise, you want to instantly settle.

What's New

Settlement amounts of ₹1 or lower are now supported.

settle_full_balance
boolean

Indicates whether full balance is settled. Possible values:

  • true: Razorpay will settle the maximum amount possible. Values passed in the amount parameter are ignored.
  • false (default): Razorpay will settle the amount requested in the amount parameter.

description
string

This is a custom note you can pass for the instant settlement for your reference. For example, Need this to make vendor payments..

  • Maximum length: 30 characters.
  • Allowed characters: a-z, A-Z, 0-9 and space.

notes
object

Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, Beam me up Scotty.

Response Parameters
id
string

The unique identifier of the instant settlement transaction. For example, setlod_FNj7g2YS5J67Rz.

entity
string

Indicates the type of entity. Here it is settlement.ondemand.

amount_requested
integer

The settlement amount, in paise, requested by you. For example, 200000.

amount_settled
integer

Total amount (minus fees and tax), in paise, settled to the bank account. For example, 199410.

amount_pending
integer

Portion of the requested amount, in paise, yet to be settled to you.

amount_reversed
integer

Portion of the requested amount, in paise, that was not settled to you. This amount is reversed to your PG current balance.

fees
integer

Total amount (fees+tax), in paise, deducted for the instant settlement. For example, 590.

tax
integer

Total tax, in paise, charged for the fee component. For example, 90.

currency
string

The 3-letter ISO currency code for the settlement. Here it is INR.

settle_full_balance
boolean

Indicates whether full balance is settled. Possible values:

  • true: Razorpay will settle the maximum amount possible. Values passed in the amount parameter are ignored.
  • false (default): Razorpay will settle the amount requested in the amount parameter.

status
string

Indicates the state of the instant settlement. Possible values:

  • created: The instant settlement request has been created.
  • initiated: The instant settlement process has been initiated.
  • partially_processed: The instant settlement is being processed.
  • processed: The instant settlement has been processed and the amount has been transferred to your bank account.
  • reversed: The instant settlement could not be processed for some reason and the amount has been transferred back to your PG balance.

description
string

This is a custom note you can pass for the instant settlement for your reference. For example, Need this to make vendor payments..

notes
object

Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.

created_at
integer

Unix timestamp at which the instant settlement was created. For example, 1596771429.

ondemand_payouts
object

List of payouts created for the instant settlement.

Show child parameters (3)

Errors

The API {key/secret} provided is invalid.

Error Status: 4xx

The API credentials passed in the API call differ from the ones generated on the Dashboard.

Solution

The requested URL was not found on the server.

Error Status: 400

Instant Settlement is not enabled on the merchant account, so the endpoint is not routable.

Solution

Minimum amount that can be settled is ₹ 1.

Error Status: 400

The amount requested is below the minimum allowed for an Instant Settlement.

Solution

Minimum amount that can be settled is ₹ 2000.

Error Status: 400

Returned for merchants who do not have Instant Settlements set to "automatic" mode — for such accounts, the minimum per-request amount is higher than the default.

Solution

Amount requested is more than the max limit for ondemand settlement.

Error Status: 400

The amount exceeds the per-request hard cap for Instant Settlements (₹ 5 Cr). The API may also return this as Maximum amount that can be settled is ₹ 5 Cr.

Solution

Amount requested for the ondemand settlement exceeds the settlement balance.

Error Status: 400

The requested amount is greater than the unsettled balance available for Instant Settlement. The API may also return this as Amount exceeds the available balance or Insufficient balance.

Solution

Your Instant Settlements is disabled for using Money Saver.

Error Status: 400

The merchant has the Money Saver / B2B Export product enabled, which is incompatible with Instant Settlements.

Solution

Please provide an amount less than 2 Lacs to get a settlement at this point of time.

Error Status: 400

Instant Settlement is being requested outside banking hours, when only IMPS-based payouts are available. IMPS has a per-transaction cap of ₹ 2 lakh.

Solution

Currency is not supported.

Error Status: 400

The currency field is set to a value other than the supported settlement currency.

Solution

Another payout operation for merchant is in progress. Please try again later.

Error Status: 400

A merchant-scoped payout is currently being processed, blocking new Instant Settlement requests.

Solution

Payout amount including fees should be greater than Re 1.

Error Status: 400

The amount requested, once fees are deducted, would result in a payout below ₹ 1. The net amount sent to your bank account must exceed ₹ 1.

Solution

Duplicate ondemand settlement request.

Error Status: 400

An Instant Settlement request with the same characteristics (amount, idempotency key, or other request signature) was already submitted recently.

Solution

Amount that can be settled for the day is exhausted, please try again on the next working day.

Error Status: 400

The merchant's daily Instant Settlement limit has been fully consumed.

Solution

Minimum amount that can be settled via smart settlement is below the threshold.

Error Status: 400

For Smart Settlements, the requested amount is below the minimum threshold configured for the merchant. The API may return either Minimum amount that can be settled via smart settlement is ₹ 5,00,000. or Minimum amount that can be settled using Smart Settlements is ₹ 2 L, depending on the merchant configuration.

Solution

Maximum amount that can be settled using Smart Settlements is ₹ 50 Cr.

Error Status: 400

For Smart Settlements, the requested amount is above the per-request maximum of ₹ 50 Cr.

Solution

Smart settlements not enabled.

Error Status: 400

The merchant account does not have the Smart Settlements feature enabled.

Solution

The value provided for settle_full_balance field is invalid.

Error Status: 400

The settle_full_balance field contains a value that is not a valid boolean.

Solution

The amount should be between 100 and {max} paise.

Error Status: 400

The amount value is outside the allowed range when settle_full_balance is false.

Solution

The description may not be greater than 30 characters.

Error Status: 400

The description field exceeds the maximum allowed length of 30 characters.

Solution

The value should be a valid type.

Error Status: 400

The type field contains an invalid value.

Solution

The value should be a valid product type.

Error Status: 400

The product_type field contains an invalid value.

Solution

Your Instant Settlements has been disabled.

Error Status: 400

Instant Settlements has been disabled for the merchant due to delayed LOC, Loan, or Card repayments.

Solution

Instant Settlements has been blocked for a while.

Error Status: 400

A global on-demand settlement block is currently active for the merchant.

Solution

Requested amount is greater than available limit.

Error Status: 400

The requested amount exceeds the daily merchant or global Instant Settlement limit.

Solution

No more attempts left for today.

Error Status: 400

The merchant has exhausted the maximum number of Instant Settlement attempts allowed for the day.

Solution

Smart Settlement timing is 2:00 AM to 9:00 PM. Holidays are Jan 26, Aug 15 and Apr 1.

Error Status: 400

The Smart Settlement request was made outside of banking hours or on a holiday when RTGS is unavailable.

Solution

You are not enabled for Linked Instant Settlements.

Error Status: 400

The merchant account does not have the Linked Instant Settlements feature enabled.

Solution

Create an Instant Settlement

POST
/v1/settlements/ondemand

Click to copy

Use this endpoint to create an Instant Settlement.

Is this page helpful?

Request Parameters
amount

*

integer

The amount, in paise, you want to instantly settle.

What's New

Settlement amounts of ₹1 or lower are now supported.

settle_full_balance
boolean

Indicates whether full balance is settled. Possible values:

  • true: Razorpay will settle the maximum amount possible. Values passed in the amount parameter are ignored.
  • false (default): Razorpay will settle the amount requested in the amount parameter.

description
string

This is a custom note you can pass for the instant settlement for your reference. For example, Need this to make vendor payments..

  • Maximum length: 30 characters.
  • Allowed characters: a-z, A-Z, 0-9 and space.

notes
object

Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, Beam me up Scotty.

Response Parameters
id
string

The unique identifier of the instant settlement transaction. For example, setlod_FNj7g2YS5J67Rz.

entity
string

Indicates the type of entity. Here it is settlement.ondemand.

amount_requested
integer

The settlement amount, in paise, requested by you. For example, 200000.

amount_settled
integer

Total amount (minus fees and tax), in paise, settled to the bank account. For example, 199410.

amount_pending
integer

Portion of the requested amount, in paise, yet to be settled to you.

amount_reversed
integer

Portion of the requested amount, in paise, that was not settled to you. This amount is reversed to your PG current balance.

fees
integer

Total amount (fees+tax), in paise, deducted for the instant settlement. For example, 590.

tax
integer

Total tax, in paise, charged for the fee component. For example, 90.

currency
string

The 3-letter ISO currency code for the settlement. Here it is INR.

settle_full_balance
boolean

Indicates whether full balance is settled. Possible values:

  • true: Razorpay will settle the maximum amount possible. Values passed in the amount parameter are ignored.
  • false (default): Razorpay will settle the amount requested in the amount parameter.

status
string

Indicates the state of the instant settlement. Possible values:

  • created: The instant settlement request has been created.
  • initiated: The instant settlement process has been initiated.
  • partially_processed: The instant settlement is being processed.
  • processed: The instant settlement has been processed and the amount has been transferred to your bank account.
  • reversed: The instant settlement could not be processed for some reason and the amount has been transferred back to your PG balance.

description
string

This is a custom note you can pass for the instant settlement for your reference. For example, Need this to make vendor payments..

notes
object

Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.

created_at
integer

Unix timestamp at which the instant settlement was created. For example, 1596771429.

ondemand_payouts
object

List of payouts created for the instant settlement.

Show child parameters (3)

Errors

The API {key/secret} provided is invalid.

Error Status: 4xx

The API credentials passed in the API call differ from the ones generated on the Dashboard.

Solution

The requested URL was not found on the server.

Error Status: 400

Instant Settlement is not enabled on the merchant account, so the endpoint is not routable.

Solution

Minimum amount that can be settled is ₹ 1.

Error Status: 400

The amount requested is below the minimum allowed for an Instant Settlement.

Solution

Minimum amount that can be settled is ₹ 2000.

Error Status: 400

Returned for merchants who do not have Instant Settlements set to "automatic" mode — for such accounts, the minimum per-request amount is higher than the default.

Solution

Amount requested is more than the max limit for ondemand settlement.

Error Status: 400

The amount exceeds the per-request hard cap for Instant Settlements (₹ 5 Cr). The API may also return this as Maximum amount that can be settled is ₹ 5 Cr.

Solution

Amount requested for the ondemand settlement exceeds the settlement balance.

Error Status: 400

The requested amount is greater than the unsettled balance available for Instant Settlement. The API may also return this as Amount exceeds the available balance or Insufficient balance.

Solution

Your Instant Settlements is disabled for using Money Saver.

Error Status: 400

The merchant has the Money Saver / B2B Export product enabled, which is incompatible with Instant Settlements.

Solution

Please provide an amount less than 2 Lacs to get a settlement at this point of time.

Error Status: 400

Instant Settlement is being requested outside banking hours, when only IMPS-based payouts are available. IMPS has a per-transaction cap of ₹ 2 lakh.

Solution

Currency is not supported.

Error Status: 400

The currency field is set to a value other than the supported settlement currency.

Solution

Another payout operation for merchant is in progress. Please try again later.

Error Status: 400

A merchant-scoped payout is currently being processed, blocking new Instant Settlement requests.

Solution

Payout amount including fees should be greater than Re 1.

Error Status: 400

The amount requested, once fees are deducted, would result in a payout below ₹ 1. The net amount sent to your bank account must exceed ₹ 1.

Solution

Duplicate ondemand settlement request.

Error Status: 400

An Instant Settlement request with the same characteristics (amount, idempotency key, or other request signature) was already submitted recently.

Solution

Amount that can be settled for the day is exhausted, please try again on the next working day.

Error Status: 400

The merchant's daily Instant Settlement limit has been fully consumed.

Solution

Minimum amount that can be settled via smart settlement is below the threshold.

Error Status: 400

For Smart Settlements, the requested amount is below the minimum threshold configured for the merchant. The API may return either Minimum amount that can be settled via smart settlement is ₹ 5,00,000. or Minimum amount that can be settled using Smart Settlements is ₹ 2 L, depending on the merchant configuration.

Solution

Maximum amount that can be settled using Smart Settlements is ₹ 50 Cr.

Error Status: 400

For Smart Settlements, the requested amount is above the per-request maximum of ₹ 50 Cr.

Solution

Smart settlements not enabled.

Error Status: 400

The merchant account does not have the Smart Settlements feature enabled.

Solution

The value provided for settle_full_balance field is invalid.

Error Status: 400

The settle_full_balance field contains a value that is not a valid boolean.

Solution

The amount should be between 100 and {max} paise.

Error Status: 400

The amount value is outside the allowed range when settle_full_balance is false.

Solution

The description may not be greater than 30 characters.

Error Status: 400

The description field exceeds the maximum allowed length of 30 characters.

Solution

The value should be a valid type.

Error Status: 400

The type field contains an invalid value.

Solution

The value should be a valid product type.

Error Status: 400

The product_type field contains an invalid value.

Solution

Your Instant Settlements has been disabled.

Error Status: 400

Instant Settlements has been disabled for the merchant due to delayed LOC, Loan, or Card repayments.

Solution

Instant Settlements has been blocked for a while.

Error Status: 400

A global on-demand settlement block is currently active for the merchant.

Solution

Requested amount is greater than available limit.

Error Status: 400

The requested amount exceeds the daily merchant or global Instant Settlement limit.

Solution

No more attempts left for today.

Error Status: 400

The merchant has exhausted the maximum number of Instant Settlement attempts allowed for the day.

Solution

Smart Settlement timing is 2:00 AM to 9:00 PM. Holidays are Jan 26, Aug 15 and Apr 1.

Error Status: 400

The Smart Settlement request was made outside of banking hours or on a holiday when RTGS is unavailable.

Solution

You are not enabled for Linked Instant Settlements.

Error Status: 400

The merchant account does not have the Linked Instant Settlements feature enabled.

Solution

Curl

change language

change language

1
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
2
-X POST https://api.razorpay.com/v1/settlements/ondemand \
3
-H "content-type: application/json" \
4
-d '{
5
  "amount": 200000,
6
  "settle_full_balance": false,
7
  "description": "Need this to make vendor payments.",
8
  "notes": {
9
    "notes_key_1": "Tea, Earl Grey, Hot",
10
    "notes_key_2": "Tea, Earl Grey… decaf."
11
  }
12
}'

Success

Failure

1
{
2
  "id": "setlod_FNj7g2YS5J67Rz",
3
  "entity": "settlement.ondemand",
4
  "amount_requested": 200000,
5
  "amount_settled": 0,
6
  "amount_pending": 199410,
7
  "amount_reversed": 0,
8
  "fees": 590,
9
  "tax": 90,
10
  "currency": "INR",
11
  "settle_full_balance": false,
12
  "status": "initiated",
13
  "description": "Need this to make vendor payments.",
14
  "notes": {
15
    "notes_key_1": "Tea, Earl Grey, Hot",
16
    "notes_key_2": "Tea, Earl Grey… decaf."
17
  },
18
  "created_at": 1596771429,
19
  "ondemand_payouts": {
20
    "entity": "collection",
21
    "count": 1,
22
    "items": [
23
      {
24
        "id": "setlodp_FNj7g2cbvw8ueO",
25
        "entity": "settlement.ondemand_payout",
26
        "initiated_at": null,
27
        "processed_at": null,
28
        "reversed_at": null,
29
        "amount": 200000,
30
        "amount_settled": null,
31
        "fees": 590,
32
        "tax": 90,
33
        "utr": null,
34
        "status": "created",
35
        "created_at": 1596771429
36
      }
37
    ]
38
  }
39
}