Entities

Razorpay provides a number of payment entities that are in JSON format.

API Endpoint: https://api.razorpay.com/v1

Our response contain entities that are shared across origins. Every entity will the following common attributes along with the other attributes.

In an entity, the attributes can be utilized for making an entity-specific API calls. For example, in a paid invoice response, you found a payment entity. You can use the payment id and make refund API call, for initiating a refund for the paid amount.

Order Entity#

The order entity consists of the following fields:

id string
The order id of this particular order.
amount integer
The amount (in paisa) that this order was created for.
currency string
The currency associated with this order's amount.
attempts integer
The number of payment attempts that have been made against this order.
status string
This order's status in the Order lifecycle.
receipt string
Your receipt id corresponding to this order. Maximum length 40 chars.
payment_capture boolean
Flag for auto capturing the payment.
created_at timestamp
The timestamp corresponding to this order's creation time.
notes object
Object consisting of notes passed while creating an order Entity.

Payment Entity#

The payment entity returned by Razorpay is as shown on the right. It will be returned in JSON form by the API (or in the object form if using language SDKs).

The various parameters are explained below:

id string
Unique ID that identifies your payment on the gateway.
entity string
Indicates type of entity.
Wallet Yolo
Mobikwik, PayUMoney, JioMoney
UPI Hot
Universal Payments Interface Can be spread in multiple lines

Plan Entity#

You can create plans via the API and also fetch them as required. The plan entity has the following attributes:

Attribute

Mandatory/Optional (in request)

Type

Description

id

NA

string

Plan ID which will be used to create subscriptions for the customers.

item.name

Mandatory

string

Name of the plan.

item.description

Optional

string

Description of the plan.

item.amount

Mandatory

integer

Amount of the plan, that will be charged to all the customers subscribed to this plan, on a recurring basis.

item.currency

Mandatory

string

Currently, only INR is supported.

interval

Mandatory

integer

This, combined with period, defines the frequency. If the billing cycle is of 2 months, the value for this attribute would be 2.

period

Mandatory

string

This, combined with interval, defines the frequency. If the billing cycle is of 2 months, the value for this attribute would be monthly. The values supported for this attribute currently are: weekly and monthly.

notes

Optional

JSON object

Object consisting of key value pairs as notes. Refer here for more details.

Subscription Entity#

Subscriptions allow you to charge a customer's card on a recurring basis. A subscription ties a customer to a particular plan you've created. The following are the attributes of a subscription entity:

Attribute

Mandatory/Optional (in request)

Type

Description

id

NA

string

Subscription ID

plan_id

Mandatory

string

ID of the plan to which the customer is subscribing to.

customer_id

NA

string

ID of the customer who is subscribing to a plan. This will be populated automatically once the customer completes the first transaction via our checkout.

total_count

Mandatory

integer

The number of billing cycles that the customer needs to be charged for. If the customer is buying a 1 year subscription, billed bi-monthly, this value should be 6.

customer_notify

Mandatory

integer

This indicates whether the communication to the customer would be handled by you or by us. If it's set to 0, the communication to the customer would be handled by the merchant. If it's set to 1, we would take care of communicating any failures or charges to the customer.

start_at

Optional

integer (timestamp)

This would be the start of the first billing cycle. If the start_at is not passed, the billing cycle for the customer starts immediately during the auth transaction. Otherwise, the billing cycle would start at the specified time.

quantity

Optional

integer

The quantity of the plan to which the customer should be subscribed. For example, if the plan is Rs100/user/month, and the customer has 5 users, you should pass 5 as the quantity to have the customer charged Rs500 (5 x Rs100) monthly. By default, this value is set to 1, if nothing is passed.

notes

Optional

object

Object consisting of key value pairs as notes. Read more here

addons

Optional

Array of objects

This can be used to charge the customer a one time fees before the start of the subscription. This can include something like one-time delivery charges or a security deposit. More details about this can be found at upfront section

status

NA

string

Status of the subscription. Possible values: created, authenticated, active, pending, halted, cancelled, completed, expired. The explanations for these is provided in the Lifecycle section.

paid_count

NA

integer

This indicates the number of billing cycles that the customer has already been charged for.

current_start

NA

integer (timestamp)

This indicates the start time of the current billing cycle of the subscription.

current_end

NA

integer (timestamp)

This indicates the end time of the current billing cycle of the subscription.

ended_at

NA

integer (timestamp)

This will have the timestamp of the time when the subscription has completed its period or has been cancelled midway.

charge_at

NA

integer (timestamp)

This indicates the time when the next charge on the subscription will be made.

auth_attempts

NA

integer

The number of times that the charge for the current billing cycle has been attempted for, on the card.

Add-on Entity#

You can create add-ons to charge an extra amount for a particular billing cycle. Once you create an add-on, it gets attached to the next invoice that gets generated for the given subscription. Hence, it'll get applied to the next automated charge scheduled for the subscription.

The add-on entity has the following attributes:

Attribute

Mandatory/Optional (in request)

Type

Description

id

NA

string

Addon ID

item.name

Mandatory

string

Name of the add-on.

item.description

Optional

string

Description of the add-on.

item.amount

Mandatory

integer

Amount of the addon, that will be charged to the subscription for the next billing cycle.

item.currency

Mandatory

string

Currently, only INR is supported.

quantity

Optional

integer

This specifies the number of units of the item that you want to charge the customer for. By default, this is 1. The total amount is calculated as item.amount * quantity.

subscription_id

NA

string

The ID of the subscription to which the addon is being applied to.

invoice_id

NA

string

The ID of the invoice to which the addon has been applied to. This field gets populated only after the invoice is generated. Until then, it'll be null. The add-on will get added to the next invoice that gets generated after the addon has been created. Once the addon has been consumed by an invoice, it cannot be deleted.

Transfer Entity#

The attributes of the transfer entity are listed below:

id string
Transfer ID
source string
Entity ID of the transfer source
receipt string
Entity ID of the transfer destination.
amount integer
Transfer amount.
currency string
3 character ISO currency code.
amount_reversed integer
Amount reversed from this transfer for refunds.
on_hold Boolean
Boolean representing whether the account settlement for transfer is on hold.
on_hold_until integer
Timestamp. Until when should the settlement of the transfer be put on hold.
created_at timestamp
UNIX timestamp of record creation.

In the sample request given, transfers to multiple linked accounts are specified, each with a different amount. The payment transferred to these accounts will be settled to their bank accounts as per the settlement_period defined by you for each linked account.

Invoices Entity#

The below JSON is the representation for the invoice entity:

type String in: link/ecod/invoice
Mandatory. Must pass type=invoice
currency String
Mandatory. Only INR is supported currently
description String
Optional
customer_id String
Optional. You can pass the customer_id in this field, if you are using Customer API. If not, you can pass the customer object described in the below fields.
customer[name] String
Mandatory, without customer_id.
customer[email] string
Optional
customer[contact] string
Optional
customer[billing_address][line1] string
Mandatory, with customer[billing_address]
customer[billing_address][line2] string
Optional customer[billing_address][city] string
Mandatory, with customer[billing_address]
customer[billing_address][zipcode] string
Mandatory, with customer[billing_address]
customer[billing_address][state] string
Mandatory, with customer[billing_address]
customer[billing_address][country] string
Mandatory, with customer[billing_address]
line_items[][item_id] string
Optional. If you are using Items API, you may use existing item as a template for line items of invoice. You can still override other details such as name, description by passing these along with item_id. Item will not be updated.
line_items[][name] string
Mandatory. without item_id
line_items[][description] string
Optional
line_items[][amount] integer
Mandatory, without item_id
line_items[][currency] integer
Mandatory, without item_id. Only INR is accepted for now. Also, this needs to be same as currency attribute.
line_items[][quantity] integer
Optional. Defaults to 1
expire_by epoch/integer
Optional
sms_notify string in: 0/1
Optional. Defaults to 1
email_notify string in: 0/1
Optional. Defaults to 1
date epoch/integer
Optional
terms string
Optional
notes object
Optional
comment string
Optional
draft string in: 0/1
Optional, Defaults to 0