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

1curl -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 get settled instantly.

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 value): 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

Minimum amount that can be settled is ₹ 1.

Error Status: 400

The amount entered is less than ₹1.

Solution

Payout amount including fees should be greater than Re 1.

Error Status: 400

The amount entered is ₹1.

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 get settled instantly.

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 value): 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

Minimum amount that can be settled is ₹ 1.

Error Status: 400

The amount entered is less than ₹1.

Solution

Payout amount including fees should be greater than Re 1.

Error Status: 400

The amount entered is ₹1.

Solution

Curl

change language

1curl -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}