Handy Tips
This section has information on APIs used as part of Razorpay Capital.

With Instant Settlements (earlier known as On-demand Settlement APIs), you get access to your funds as and when you want.

Normally, you would receive settlements according to your settlement cycle. Razorpay Instant Settlements helps to reduce your settlement period from T+2 days (default settlement cycle) to a few minutes (from the time of the transaction), thus enabling your business to avoid cash-flow challenges and prepare better for working capital requirements.

Feature Request
This is an on-demand feature. Please raise a request with our Support team to get this feature activated on your Razorpay account.

You can try out our APIs on the Razorpay Postman Public Workspace.

Instant Settlement Entity🔗

The Instant Settlement entity has the following fields:

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 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.

entity

string Indicates the type of ondemand_payouts entity. Here it is collection.

count

integer The number of items in the array. For example, 1.

items

array List of payouts created for the instant settlement.

id

string The unique identifier for the payout. For example, setlodp_FNj7g2cbvw8ueO.

entity

string Indicates the type of items entity. Here it is settlement.ondemand_payout.

initiated_at

integer Unix timestamp at which the payout was initiated. For example, 1596771430.

processed_at

integer Unix timestamp at which the payout was processed. For example, 1596778752.

reversed_at

integer Unix timestamp at which the payout was reversed. For example, 1596778752.

amount

integer The amount, in paise, settled through this payout. For example, 200000.

amount_settled

integer Amount (minus fees and tax), in paise, settled through this payout. For example, 199410.

fees

integer Amount (fees+tax), in paise, deducted for this payout. For example, 590.

tax

integer Tax charged, in paise, for the fee component. For example, 90.

utr

string The unique transaction number linked to a payout.

status

string Status of the payout. Possible values:

created: The payout has been created.
initiated: The payout has been initiated.
processed: The payout has been processed. The amount has been transferred to your bank account.
reversed: The payout has been reversed. The amount has been transferred back to your PG balance.

created_at

integer Unix timestamp at which the payout was created.

You can manage Instant Settlements using APIs or from the Razorpay Dashboard.

 Sample Entity
Copy{
  "id": "setlod_FNj7g2YS5J67Rz",
  "entity": "settlement.ondemand",
  "amount_requested": 200000,
  "amount_settled": 0,
  "amount_pending": 199410,
  "amount_reversed": 0,
  "fees": 590,
  "tax": 90,
  "currency": "INR",
  "settle_full_balance": false,
  "status": "initiated",
  "description": "Need this to make vendor payments.",
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey… decaf."
  },
  "created_at": 1596771429,
  "ondemand_payouts": {
    "entity": "collection",
    "count": 1,
    "items": [
      {
        "id": "setlodp_FNj7g2cbvw8ueO",
        "entity": "settlement.ondemand_payout",
        "initiated_at": null,
        "processed_at": null,
        "reversed_at": null,
        "amount": 200000,
        "amount_settled": null,
        "fees": 590,
        "tax": 90,
        "utr": null,
        "status": "created",
        "created_at": 1596771429
      }
    ]
  }
}

Create an Instant Settlement🔗

The following endpoint creates an Instant Settlement.

/settlements/ondemand

 Curl Java Python Go PHP Ruby Node.JS Response
Copycurl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/settlements/ondemand \
-H "content-type: application/json" \
-d '{
  "amount": 200000,
  "settle_full_balance": false,
  "description": "Need this to make vendor payments.",
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey… decaf."
  }
}'

CopyRazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

JSONObject settlementRequest = new JSONObject();
settlementRequest.put("amount", 200000);
settlementRequest.put("settle_full_balance", false);
settlementRequest.put("description", "Need this to make vendor payments.");
JSONObject notes = new JSONObject();
notes.put("notes_key_1","Tea, Earl Grey, Hot");
notes.put("notes_key_2","Tea, Earl Grey… decaf.");
settlementRequest.put("notes", notes);       
        
Settlement settlement = razorpay.settlement.create(settlementRequest);

Copyimport razorpay
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.settlement.create_ondemand_settlement({
  "amount": 200000,
  "settle_full_balance": 0,
  "description": "Need this to make vendor payments.",
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey… decaf."
  }
})

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

data:= map[string]interface{}{
  "amount": 200000,
  "settle_full_balance": false,
  "description": "Need this to make vendor payments.",
  "notes": map[string]interface{}{
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey… decaf.",
  },
}
body, err := client.Settlement.CreateOnDemandSettlement(data, nil)

Copy$api = new Api($key_id, $secret);

$api->settlement->createOndemandSettlement(array("amount"=> 200000, "settle_full_balance"=> false, "description"=>"Need this to make vendor payments.","notes" => array("notes_key_1"=> "Tea, Earl Grey, Hot","notes_key_2"=> "Tea, Earl Grey… decaf.")));

Copyrequire "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

param_attr = {
  "amount": 200000,
  "settle_full_balance": false,
  "description": "Need this to make vendor payments.",
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey… decaf."
  }
}
Razorpay::Settlement.create(param_attr)

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.settlements.createOndemandSettlement({
  "amount": 200000,
  "settle_full_balance": false,
  "description": "Need this to make vendor payments.",
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey… decaf."
  }
})

Copy{
  "id": "setlod_FNj7g2YS5J67Rz",
  "entity": "settlement.ondemand",
  "amount_requested": 200000,
  "amount_settled": 0,
  "amount_pending": 199410,
  "amount_reversed": 0,
  "fees": 590,
  "tax": 90,
  "currency": "INR",
  "settle_full_balance": false,
  "status": "initiated",
  "description": "Need this to make vendor payments.",
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey… decaf."
  },
  "created_at": 1596771429,
  "ondemand_payouts": {
    "entity": "collection",
    "count": 1,
    "items": [
      {
        "id": "setlodp_FNj7g2cbvw8ueO",
        "entity": "settlement.ondemand_payout",
        "initiated_at": null,
        "processed_at": null,
        "reversed_at": null,
        "amount": 200000,
        "amount_settled": null,
        "fees": 590,
        "tax": 90,
        "utr": null,
        "status": "created",
        "created_at": 1596771429
      }
    ]
  }
}

Request Parameters🔗

amount mandatory

integer The amount, in paise, you want settled to your account.

settle_full_balance optional

boolean 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 optional

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 optional

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🔗

Descriptions for the response parameters are present in the Instant Settlements Entity parameters table.

Fetch All Instant Settlements🔗

The following endpoint retrieves the details of all Instant Settlements. Use the expand[]=ondemand_payouts query parameter to fetch payout details as part of the response.

/settlements/ondemand

 Request: Normal Java Python Ruby Go PHP Node.JS Response: Normal
Copycurl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]\
- X GET \
https://api.razorpay.com/v1/settlements/ondemand

CopyRazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

List<Settlement> settlement = razorpay.settlement.fetchAllDemand(options)

Copyimport razorpay
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.settlement.fetch_all_ondemand_settlement(options)

Copyrequire "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

para_attr = {"count":1}

Razorpay::Settlement.fetch_all_ondemand_settlement(para_attr)

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

body, err := client.Settlement.FetchAllOnDemandSettlement(options, nil)

Copy$api = new Api($key_id, $secret);

$api->settlement->fetchAllOndemandSettlement($options);

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.settlements.fetchAllOndemandSettlement(options)

Copy{
  "entity": "collection",
  "count": 2,
  "items": [
    {
      "id": "setlod_FNj7g2YS5J67Rz",
      "entity": "settlement.ondemand",
      "amount_requested": 200000,
      "amount_settled": 199410,
      "amount_pending": 0,
      "amount_reversed": 0,
      "fees": 590,
      "tax": 90,
      "currency": "INR",
      "settle_full_balance": false,
      "status": "processed",
      "description": "Need this to make vendor payments.",
      "notes": {
        "notes_key_1": "Tea, Earl Grey, Hot",
        "notes_key_2": "Tea, Earl Grey, decaf."
      },
      "created_at": 1596771429
    },
    {
      "id": "setlod_FJOp0jOWlalIvt",
      "entity": "settlement.ondemand",
      "amount_requested": 300000,
      "amount_settled": 299114,
      "amount_pending": 0,
      "amount_reversed": 0,
      "fees": 886,
      "tax": 136,
      "currency": "INR",
      "settle_full_balance": false,
      "status": "processed",
      "description": "Need this to buy stock.",
      "notes": {
        "notes_key_1": "Tea, Earl Grey, Hot",
        "notes_key_2": "Tea, Earl Grey, decaf."
      },
      "created_at": 1595826576
    }
  ]
}

 Request: With payout details Response: With payout details
Copycurl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]\
- X GET \
https://api.razorpay.com/v1/settlements/ondemand?expand[]=ondemand_payouts

Copy{
  "entity": "collection",
  "count": 2,
  "items": [
    {
      "id": "setlod_FNj7g2YS5J67Rz",
      "entity": "settlement.ondemand",
      "amount_requested": 200000,
      "amount_settled": 199410,
      "amount_pending": 0,
      "amount_reversed": 0,
      "fees": 590,
      "tax": 90,
      "currency": "INR",
      "settle_full_balance": false,
      "status": "processed",
      "description": "Need this to make vendor payments.",
      "notes": {
        "notes_key_1": "Tea, Earl Grey, Hot",
        "notes_key_2": "Tea, Earl Grey, decaf."
      },
      "created_at": 1596771429,
      "ondemand_payouts": {
        "entity": "collection",
        "count": 1,
        "items": [
          {
            "id": "setlodp_FNj7g2cbvw8ueO",
            "entity": "settlement.ondemand_payout",
            "initiated_at": 1596771430,
            "processed_at": 1596778752,
            "reversed_at": null,
            "amount": 200000,
            "amount_settled": 199410,
            "fees": 590,
            "tax": 90,
            "utr": "022011173948",
            "status": "processed",
            "created_at": 1596771429
          }
        ]
      }
    },
    {
      "id": "setlod_FJOp0jOWlalIvt",
      "entity": "settlement.ondemand",
      "amount_requested": 300000,
      "amount_settled": 299114,
      "amount_pending": 0,
      "amount_reversed": 0,
      "fees": 886,
      "tax": 136,
      "currency": "INR",
      "settle_full_balance": false,
      "status": "processed",
      "description": "Need this to buy stock.",
      "notes": {
        "notes_key_1": "Tea, Earl Grey, Hot",
        "notes_key_2": "Tea, Earl Grey, decaf."
      },
      "created_at": 1595826576,
      "ondemand_payouts": {
        "entity": "collection",
        "count": 1,
        "items": [
          {
            "id": "setlodp_FJOp0jTqoZdGen",
            "entity": "settlement.ondemand_payout",
            "initiated_at": 1595826577,
            "processed_at": 1595826588,
            "reversed_at": null,
            "amount": 300000,
            "amount_settled": 299114,
            "fees": 886,
            "tax": 136,
            "utr": "020910199316",
            "status": "processed",
            "created_at": 1595826576
          }
        ]
      }
    }
  ]
}

Query Parameters🔗

expand[]=ondemand_payouts optional

string Pass this if you want to fetch payout details as part of the response.

from optional

integer Unix timestamp (in seconds) from when instant settlements are to be retrieved.

to optional

integer Unix timestamp (in seconds) till when instant settlements are to be retrieved.

count optional

integer Number of instant settlement records to be retrieved.

Default value: 10
Maximum value: 100
This can be used for pagination, in combination with skip.

skip optional

integer Number of instant settlement records to be skipped.

Default value: 0
This can be used for pagination, in combination with count.

Response Parameters🔗

Descriptions for the response parameters are present in the Instant Settlements Entity parameters table.

Fetch Instant Settlement by ID🔗

The following endpoint retrieves the details of a particular Instant Settlement. Use the expand[]=ondemand_payouts query parameter to fetch payout details as part of the response.

/settlements/ondemand/:setlod_id

 Request: Normal Java Python Ruby Go PHP Node.JS Response: Normal
Copycurl -u <YOUR_KEY>:<YOUR_SECRET>\
- X GET \
https://api.razorpay.com/v1/settlements/ondemand/setlod_FNj7g2YS5J67Rz

CopyRazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

String settlementId = "setlod_FNj7g2YS5J67Rz";

Settlement settlement = razorpay.settlement.fetchDemandSettlement(settlementId);

Copyimport razorpay
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.settlement.fetch_ondemand_settlement_id(settlementId)

Copyrequire "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

settlementId = "setlod_FNj7g2YS5J67Rz"

para_attr = {
  "expand[]": "ondemand_payouts"
}

Razorpay::Settlement.fetch_ondemand_settlement_by_id(settlementId, para_attr);

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

body, err := client.Settlement.FetchOnDemandSettlementById("<settlementId>", nil, nil)

Copy$api = new Api($key_id, $secret);

$api->settlement->fetch($settlementId)->fetchOndemandSettlementById();

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.settlements.fetchOndemandSettlementById(settlementId);

Copy{
  "id": "setlod_FNj7g2YS5J67Rz",
  "entity": "settlement.ondemand",
  "amount_requested": 200000,
  "amount_settled": 199410,
  "amount_pending": 0,
  "amount_reversed": 0,
  "fees": 590,
  "tax": 90,
  "currency": "INR",
  "settle_full_balance": false,
  "status": "processed",
  "description": "Need this to make vendor payments.",
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey, decaf."
  },
  "created_at": 1596771429
}

 Request: With payout details Response: With payout details
Copycurl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]\
- X GET \
https://api.razorpay.com/v1/settlements/ondemand/setlod_FNj7g2YS5J67Rz?expand[]=ondemand_payouts
Copy{
  "id": "setlod_FNj7g2YS5J67Rz",
  "entity": "settlement.ondemand",
  "amount_requested": 200000,
  "amount_settled": 199410,
  "amount_pending": 0,
  "amount_reversed": 0,
  "fees": 590,
  "tax": 90,
  "currency": "INR",
  "settle_full_balance": false,
  "status": "processed",
  "description": "Need this to buy stock.",
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey, decaf."
  },
  "created_at": 1596771429,
  "ondemand_payouts": {
    "entity": "collection",
    "count": 1,
    "items": [
      {
        "id": "setlodp_FNj7g2cbvw8ueO",
        "entity": "settlement.ondemand_payout",
        "initiated_at": 1596771430,
        "processed_at": 1596778752,
        "reversed_at": null,
        "amount": 200000,
        "amount_settled": 199410,
        "fees": 590,
        "tax": 90,
        "utr": "022011173948",
        "status": "processed",
        "created_at": 1596771429
      }
    ]
  }
}

Path Parameter🔗

setlod_id: string The unique identifier for the instant settlement transaction. For example, setlod_FNj7g2YS5J67Rz.

Query Parameters🔗

expand[]=ondemand_payouts optional: string Pass this if you want to fetch payout details as part of the response.

Response Parameters🔗

Descriptions for the response parameters are present in the Instant Settlements Entity parameters table.