Settlements

The following section will explain the settlement entity and the associated API.

Settlement Entity#

id: string The unique Id of the settlement. Example: "setl_7IZKKI4Pnt2kEe".
entity: string The name of the entity.
amount: integer The settlement amount in paise. For example, 50000.
status: string The status of the settlement. The values can be created and processed.
fees: integer The amount charged for processing the settlement transaction.
tax: integer The tax amount charged.
utr: string Unique Transaction Reference number. For example, RZRP173069230703.
created_at: integer The UNIX timestamp that indicates when the settlement transaction was created.

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

Fetch Settlements#

The following endpoint is used for retrieving all settlements.

/settlements

from optional: integer The UNIX timestamp in seconds after which the settlements were created.
to optional: integer The UNIX timestamp in seconds before which the settlements were created.
count optional: integer The number of settlements to fetch. Maximum is 100.
skip optional: integer The number of settlements to be skipped.

 Request Response
Copycurl -u <YOUR_KEY>:<YOUR_SECRET>\
- X GET \ 
https://api.razorpay.com/v1/settlements/?count=2&skip=1&from=1400826740
Copy{
  "entity": "collection",
  "count": 2,
  "items": [
    {
      "id": "setl_7IZKKI4Pnt2kEe",
      "entity": "settlement",
      "amount": 50000,
      "status" : "processed",
      "fees": 123,
      "tax": 12,
      "utr": "RZRP173069230703",
      "created_at": 1509622307
    },
    {
      "id": "setl_4xbSwsPABDJ8oK",
      "entity": "settlement",
      "amount": 50000,
      "status" : "processed",
      "fees": 123,
      "tax": 12,
      "utr": "RZRP173069230702",
      "created_at": 1509622306
    }
  ]
}

Fetch Settlement using ID#

The following endpoint is used to retrieve settlements made using the settlement id.

/settlements/:id

id mandatory: string The id of the settlement to be retrieved.

 Request Response
Copycurl -u <YOUR_KEY>:<YOUR_SECRET>\
- X GET \ 
https://api.razorpay.com/v1/settlements/setl_7IZKKI4Pnt2kEe 
Copy{
    "id": "setl_7IZKKI4Pnt2kEe",
    "entity": "settlement",
    "amount": 50000,
    "status": "processed",
    "fees": 123,
    "tax": 12,
    "utr": RZRP111111111111,
    "created_at": 1455696913
}

Settlement Recon#

The settlement recon API returns all settled transactions (credit and debit) on your account for a particular day or month.

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

An example request and response to fetch a settlement report for the date 02/11/2016 is shown in the sample code.

 Request Response
Copycurl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \
-X GET \
https://api.razorpay.com/v1/settlements/recon/combined?year=2016&month=11&day=2 \
Copy{
  "entity": "collection",
  "count": 2,
  "items": [
    {
      "entity_id": "pay_9rvIMJo4sJkwB7",
      "type": "payment",
      "debit": 0,
      "credit": 48750,
      "amount": 59900, 
      "currency": "INR",
      "fee": 1250,
      "tax": 0,
      "on_hold": false,
      "settled": true,
      "created_at": 1478067659, 
      "settled_at": 1478075346,
      "settlement_id": "setl_9uGt8OcMCeAEiR",
      "description": "Settlement based on the invoice no. #inv_9rvHBJrv2Oluwh",
      "notes": "{}",
      "payment_id": "pay_9rvIMJo4sJkwB7",
      "settlement_utr": "KKBKH14156891582",
      "order_id": "order_9rvHBMFeGlrEp4",
      "order_receipt": "BILL13375649",
      "method": "card",
      "card_network": "Visa",
      "card_issuer": "YESB",
      "card_type": "credit",
      "dispute_id": null
    },
    {
      "entity_id": "pay_9ruIfMiMmbZ6fx",
      "type": "payment",
      "debit": 0,
      "credit": 97,
      "amount": 19900, 
      "currency": "INR",
      "fee": 3, 
      "tax": 0,
      "on_hold": false,
      "settled": true,
      "created_at": 1478067659,
      "settled_at": 1478075346,
      "settlement_id": "setl_9uGt8OcMCeAEiR",
      "description": "Invoice #inv_9ruFmsK63rBrG7",
      "notes": "{}",
      "payment_id": "pay_9ruIfMiMmbZ6fx",
      "settlement_utr": "KKBKH14156891582",
      "order_id": "order_9ruGFg9yNKWjfS",
      "order_receipt": "BILL13375640",
      "method": "card",
      "card_network": "Visa",
      "card_issuer": "YESB",
      "card_type": "credit",
      "dispute_id": null
    }
  ]
}

Path Parameters#

year mandatory: integer The year the settlement was received, in YYYY format. For example, 2012.
month mandatory: integer The month the settlement was received, in MM format. For example, 09. It can accept value from the range 01-12. To fetch the monthly settlement report, you need to pass year and month query parameters in the request. For example, year=2012&month=11.
day mandatory: integer The date on which the settlement was received. It can accept value from the range 1-31 This parameter is mandatory if you want to retrieve the daily settlement report. To retrieve the daily settlement report, you need to pass the year, month and day path parameters in the request. If day is not provided, the monthly settlement report will be retrieved.
count optional: integer Specifies the number of available settlements to fetch. 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 Represents the payment ID of the transaction that has been settled.
type: string Indicates the type of transaction. Here it is payment.
debit: integer The amount that has been debited from your account, in paise.
credit: integer The amount that has been credited to your account, in paise.
amount: integer The total amount paid by the customer, in paise.
currency: string Settlements are always made in INR. Hence, currency value by default is INR.
fee: integer The amount charged for processing the settlement transaction, in paise.
tax: integer The tax amount charged, in paise.
on_hold: boolean Indicates whether the account settlement for transfer is on hold.
settled: boolean Indicates whether the transaction has been settled or not.
created_at: integer The UNIX timestamp that indicates when the settlement was created.
settled_at: integer The UNIX timestamp that indicates when the settlement was completed.
settlement_id: string The unique identifier of the settlement.
description: string Brief description on the settlement.
payment_id: string Unique identifier of the payment that has been settled.
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. Read Orders API to learn more.
order_receipt: string Receipt number entered while creating the Order.
method: string The payment method used for making the payment. Possible values are card, netbanking, wallet, emi and upi.
card_network: string The card network. Possible values are American Express, Diners Club, Maestro, MasterCard, RuPay and Visa.
card_issuer: string The card issuer. 4-character code denoting the issuing bank. This attribute will not be set for the card that has been issued by a foreign bank.
card_type: string Possible values include Credit and Debit.
dispute_id: string Unique identifier of any dispute that might have arisen for this transaction.