Settlements

Settlement is the process in which the money received from your customers is settled to your bank account. Settlements are made to the bank account, the details of which you submitted to us as a part of KYC verification.

Settlements for all payments will be done in INR (Indian Rupees), irrespective of the currency in which the payment was made. Once Razorpay receives the amount, it is settled to your bank account, after fees deduction.

Settlement APIs#

By default, the complete process takes a time of T+2 business days for domestic transactions and T+7 days for international transactions, T being the date of capture of payment.

This is called the settlement cycle. The settlement cycle is subject to bank approval and can vary based on your business vertical, risk factors and so on.

Postman Collection#

We have a Postman collection to make the integration quicker and easier. Click the Download Postman Collection button below to get started.

Instructions to use the Postman Collection#

All Razorpay APIs are authorized using Basic Authorization.
- Generate API Keys from the Dashboard.
- Add your API Keys to the API. Authorization → Type = Basic Auth → Username = <Your_Key_ID>; Password = <Your_Key_secret>.
Some APIs in the collection require data specific to your account such as setl_id (Settlement ID) as a path parameter.
- For example, the Fetch Settlement by ID API requires you to add the setl_id as a path parameter.
- Such parameters are enclosed in {} in the collection. For example, {setl_id}.
- The API throws an error if these values are incorrect or do not exist in your system.

Settlement Entity#

 Example Entity
Copy  {
    "id": "setl_7IZKKI4Pnt2kEe",
    "entity": "settlement",
    "amount": 50000,
    "status" : "processed",
    "fees": 123,
    "tax": 12,
    "utr": "1597813219e1pq6w",
    "created_at": 1509622307
  }

id

string Unique identifier of the settlement transaction, for example, setl_7IZKKI4Pnt2kEe

entity

string The name of the entity.

amount

integer The settlement amount in paise. For example, 50000 means ₹500. Settlements are always made in INR.

status

string The status of the settlement. Possible values are:

created
processed
failed

fees

integer This is the total fees charged to process all payments received from customers that are being settled to you in this settlement transaction.

tax

integer The total tax, in paise, charged on the fees collected to process all payments received from customers that are being settled to you in this settlement transaction.

utr

string Unique Transaction Reference number available across banks, which can be used to track a particular settlement in your bank account. For example, 1597813219e1pq6w.

created_at

integer Timestamp (in Unix format) when the settlement transaction was created.

Fetch all Settlements#

/settlements

 Request Response
Copycurl -u <YOUR_KEY>:<YOUR_SECRET>\
- X GET \
https://api.razorpay.com/v1/settlements/
Copy{
  "entity": "collection",
  "count": 2,
  "items": [
    {
      "id": "setl_DGlQ1Rj8os78Ec",
      "entity": "settlement",
      "amount": 9973635,
      "status": "processed",
      "fees": 471699,
      "tax": 42070,
      "utr": "1568176960vxp0rj",
      "created_at": 1568176960
    },
    {
      "id": "setl_4xbSwsPABDJ8oK",
      "entity": "settlement",
      "amount": 50000,
      "status": "processed",
      "fees": 123,
      "tax": 12,
      "utr": "RZRP173069230702",
      "created_at": 1509622306
    }
  ]
}

Query Parameters#

from optional: integer Unix timestamp (in seconds) from when settlements are to be fetched.
to optional: integer Unix timestamp (in seconds) till when settlements are to be fetched.
count optional: integer Number of settlement records to be fetched. Default value is 10. Maximum value is 100. This can be used for pagination, in combination with skip.
skip optional: integer Number of settlement records to be skipped. Default value is 0. This can be used for pagination, in combination with count.

Fetch Settlement using ID#

/settlements/:id

 Request Response
Copycurl -u <YOUR_KEY>:<YOUR_SECRET>\
- X GET \
https://api.razorpay.com/v1/settlements/setl_DGlQ1Rj8os78Ec
Copy{
    "id": "setl_DGlQ1Rj8os78Ec",
    "entity": "settlement",
    "amount": 9973635,
    "status": "processed",
    "fees": 471699,
    "tax": 42070,
    "utr": "1568176960vxp0rj",
    "created_at": 1568176960
}

Path Parameter#

id mandatory: string Unique identifier of the settlement to be retrieved.

Settlement Recon#

The settlement recon API returns a list of all transactions such as payments, refunds, transfers and adjustment that have been settled to you for a particular day or month.

/settlements/recon/combined?year=yyyy&month=mm

In the example request and response, we are fetching the settlement report for 11/09/2019.

 Request Response
Copycurl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \
-X GET \
https://api.razorpay.com/v1/settlements/recon/combined?year=2019&month=09&day=11 \
Copy{
  "entity": "collection",
  "count": 4,
  "items": [
    {
      "entity_id": "pay_DEXrnipqTmWVGE",
      "type": "payment",
      "debit": 0,
      "credit": 97100,
      "amount": 100000,
      "currency": "INR",
      "fee": 2900,
      "tax": 0,
      "on_hold": false,
      "settled": true,
      "created_at": 1567692556,
      "settled_at": 1568176960,
      "settlement_id": "setl_DGlQ1Rj8os78Ec",
      "posted_at": null,
      "credit_type": "default",
      "description": "Recurring Payment via Subscription",
      "notes": "{}",
      "payment_id": null,
      "settlement_utr": "1568176960vxp0rj",
      "order_id": "order_DEXrnRiR3SNDHA",
      "order_receipt": null,
      "method": "card",
      "card_network": "MasterCard",
      "card_issuer": "KARB",
      "card_type": "credit",
      "dispute_id": null
    },
    {
      "entity_id": "rfnd_DGRcGzZSLyEdg1",
      "type": "refund",
      "debit": 242500,
      "credit": 0,
      "amount": 242500,
      "currency": "INR",
      "fee": 0,
      "tax": 0,
      "on_hold": false,
      "settled": true,
      "created_at": 1568107224,
      "settled_at": 1568176960,
      "settlement_id": "setl_DGlQ1Rj8os78Ec",
      "posted_at": null,
      "credit_type": "default",
      "description": null,
      "notes": "{}",
      "payment_id": "pay_DEXq1pACSqFxtS",
      "settlement_utr": "1568176960vxp0rj",
      "order_id": "order_DEXpmZgffXNvuI",
      "order_receipt": null,
      "method": "card",
      "card_network": "MasterCard",
      "card_issuer": "KARB",
      "card_type": "credit",
      "dispute_id": null
    },
    {
      "entity_id": "trf_DEUoCEtdsJgvl7",
      "type": "transfer",
      "debit": 100296,
      "credit": 0,
      "amount": 100000,
      "currency": "INR",
      "fee": 296,
      "tax": 46,
      "on_hold": false,
      "settled": true,
      "created_at": 1567681786,
      "settled_at": 1568176960,
      "settlement_id": "setl_DGlQ1Rj8os78Ec",
      "posted_at": null,
      "credit_type": "default",
      "description": null,
      "notes": null,
      "payment_id": "pay_DEApNNTR6xmqJy",
      "settlement_utr": "1568176960vxp0rj",
      "order_id": null,
      "order_receipt": null,
      "method": null,
      "card_network": null,
      "card_issuer": null,
      "card_type": null,
      "dispute_id": null
    },
    {
      "entity_id": "adj_EhcHONhX4ChgNC",
      "type": "adjustment",
      "debit": 0,
      "credit": 1012,
      "amount": 1012,
      "currency": "INR",
      "fee": 0,
      "tax": 0,
      "on_hold": false,
      "settled": true,
      "created_at": 1567681786,
      "settled_at": 1568176960,
      "settlement_id": "setl_DGlQ1Rj8os78Ec",
      "posted_at": null,
      "description": "test reason",
      "notes": null,
      "payment_id": null,
      "settlement_utr": null,
      "order_id": null,
      "order_receipt": null,
      "method": null,
      "card_network": null,
      "card_issuer": null,
      "card_type": null,
      "dispute_id": null
    }
  ]
}

Query Parameters#

year mandatory: integer The year the settlement was received in the YYYY format. For example, 2020.
month mandatory: integer The month the settlement was received in the MM format. For example, 09.
day optional: integer The date on which the settlement was received in the DD format. For example, 03.
count optional: integer Specifies the number of available settlements to be fetched. Maximum count can be 1000.
skip optional: integer Specifies the number of available settlements to be skipped when fetching a count.

Response Parameters#

entity_id

string Unique identifier of the transaction that has been settled.

type

string Indicates the type of transaction. Possible values:

payment
refund
transfer
adjustment

debit

integer The amount, in paise, that has been debited from your account.

credit

integer The amount, in paise, that has been credited to your account.

amount

integer The total amount, in paise, debited or credited from your account.

currency

string The 3-letter ISO currency code for the transaction.

fee

integer The fees, in paise, charged to processing the transaction.

tax

integer The tax on the fee, in paise, charged to processing the transaction.

on_hold

boolean Indicates whether the account settlement for transfer is on hold. Possible values:

true
false

settled

boolean Indicates whether the transaction has been settled or not. Possible values:

true
false

created_at

integer Timestamp (in Unix) at which the transaction was created.

settled_at

integer Timestamp (in Unix) when the transaction was settled.

settlement_id

string Unique identifier of the settlement transaction.

description

string Brief description about the transaction. For example, Invoice #inv_DEWHZlfIcdVIXL".

notes

object Notes for the transaction. For example. {\"comment\":\"Partial\"}.

payment_id

string Unique identifier of the payment linked to refund or transfer that has been settled. For example, pay_DEApNNTR6xmqJy. It is null for payments.

settlement_utr

string Unique reference number linked to the settlement. For example, KKBKH14156891582.

order_id

string Order ID linked to the payment made by the customer that has been settled. For example, order_DEXrnRiR3SNDHA.

order_receipt

string Receipt number entered while creating the Order.

method

string The payment method used to complete the payment. Possible values:

card
netbanking
wallet
emi
upi

card_network

string The card network used to process the payment. Possible values are:

American Express
Diners Club
Maestro
MasterCard
RuPay
Visa
unknown

card_issuer

string The card issuer. 4-character code denoting the issuing bank. For example, KARB.

This attribute will not be set for international cards, that is, for cards issued by foreign banks.

card_type

string The card type used to process the payment. Possible values:

credit
debit

dispute_id

string Unique identifier of any dispute that might have arisen for this transaction.

On-demand Settlement APIs#

With On-demand Settlements, you get access to your funds as and when you want. Normally, you would receive settlements according to your settlement cycle. Razorpay On-demand Settlements helps you 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.

Benefits of On-demand Settlements:

Easy and early access to your money.
Reduction in daily cash crunch and increased cash flows.
Better management of inventory and stock.
Payments to creditors and vendors without any delays.

Feature Request:
This feature is only available on request. It is not available by default. Raise a request on our Support Portal to enable this feature for your account.

Postman Collection#

We have a Postman collection to make the integration quicker and easier. Click the Download Postman Collection button below to get started.

Instructions to use the Postman Collection#

All Razorpay APIs are authorized using Basic Authorization.
- Generate API Keys from the Dashboard.
- Add your API Keys to the API. Authorization → Type = Basic Auth → Username = <Your_Key_ID>; Password = <Your_Key_secret>.
Some APIs in the collection require data specific to your account such as sod_id (On-demand Settlement ID) as a path parameter.
- For example, the Fetch On-Demand Settlement by ID API requires you to add the sod_id as a path parameter.
- Such parameters are enclosed in {} in the collection. For example, {setl_id}.
- The API throws an error if these values are incorrect or do not exist in your system.

Create an On-demand Settlement#

/settlements/ondemand

 Request Response
Copycurl -u <YOUR_KEY_ID>:<YOUR_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."
  }
}'
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 will be ignored.
false (default) - Razorpay will settle the amount requested in the amount parameter.

description optional

string Maximum length 30 characters. Allowed characters: a-z, A-Z, 0-9 and space. This is a custom note you can pass for the on-demand settlement for your reference. For example, Need this to make vendor payments.

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, "note_key": "Beam me up Scotty”.

Response Parameters#

id

string Unique identifier for the on-demand settlement. For example, setlod_FNj7g2YS5J67Rz.

entity

string 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 on-demand 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 will be ignored.
false (default) - Razorpay will settle the amount requested in the amount parameter.

status

string Status of the on-demand settlement. Possible values:

created - The on-demand settlement request has been created.
initiated - The on-demand settlement process has been initiated.
partially_processed - The on-demand settlement is being processed.
processed - The on-demand settlement has been processed and the amount has been transferred to your bank account.
reversed - The on-demand 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 on-demand 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 The Unix timestamp at which the on-demand settlement was created. For example, 1596771429.

ondemand_payouts

object List of payouts created for the on-demand settlement.

entity

string Here it is collection.

count

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

items

array List of payouts created for the on-demand settlement.

id

string Unique identifier for the payout. For example, setlodp_FNj7g2cbvw8ueO.

entity

string Here it is settlement.ondemand_payout.

initiated_at

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

processed_at

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

reversed_at

integer The 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 is 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 The Unix timestamp at which the payout was created.

Fetch All On-demand Settlements#

Use the below endpoint to fetch details of all On-demand Settlements. Use the expand[]=ondemand_payouts query parameter to fetch payout details as part of the response.

/settlements/ondemand

 Request: Normal Response: Normal Request: With payout details Response: With payout details
Copycurl -u <YOUR_KEY>:<YOUR_SECRET>\
- X GET \
https://api.razorpay.com/v1/settlements/ondemand
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
    }
  ]
}
Copycurl -u <YOUR_KEY>:<YOUR_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 on-demand settlements are to be fetched.
to optional: integer Unix timestamp (in seconds) till when on-demand settlements are to be fetched.
count optional: integer Number of on-demand settlement records to be fetched. Default value is 10. Maximum value is 100. This can be used for pagination, in combination with skip.
skip optional: integer Number of on-demand settlement records to be skipped. Default value is 0. This can be used for pagination, in combination with count.

Fetch by On-demand Settlements by ID#

Use the below endpoint to fetch details of a particular On-demand Settlements. Use the expand[]=ondemand_payouts query parameter to fetch payout details as part of the response.

/settlements/ondemand/:setlod_id

 Request: Normal Response: Normal Request: With payout details Response: With payout details
Copycurl -u <YOUR_KEY>:<YOUR_SECRET>\
- X GET \
https://api.razorpay.com/v1/settlements/ondemand/setlod_FNj7g2YS5J67Rz
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
}
Copycurl -u <YOUR_KEY>:<YOUR_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 Unique identifier for the on-demand settlement. 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.