Available in🇮🇳 India
You can create, fetch, query or cancel plans, subscriptions and addons using the Subscriptions API. These operations can also be performed on the Dashboard.
Plans
A plan is a foundation on which a Subscription is built. It acts as a reusable template and contains details of the goods or services offered, the amount to be charged and the frequency at which the customer should be charged (billing cycle). Depending upon your business, you can create multiple plans with different billing cycles and pricing. You should create a plan using the Checkout or Subscription link before creating a Subscription.Create a Plan
Use the below endpoint to create a plan.POST /plans
Request Parameters
This, combined with
interval, defines the frequency of the plan. Possible values:dailyweeklymonthlyquarterlyyearly
Handy TipsYou can create custom frequencies while creating a plan. For example, once in 3 weeks.
- For UPI, all undefined frequencies except
daily,weekly,monthly,quarterlyandyearlyare consideredas-presented. - For domestic cards, all undefined frequencies except
weekly,monthlyandyearlyare consideredas-presentedwhile registering the mandate with banks. - For Emandate, all defined and undefined frequencies are considered
as-presentedwhile registering the mandate with banks.
This, combined with
period, defines the frequency of the plan. If the billing cycle is 2 months, the value should be 2. For daily plans, the minimum value should be 7.Amount for the plan that is to be charged to the subscription in the next billing cycle. For example,
69900 translates to ₹699.Currency for the payment. For example,
INR. You can accept payment in any of the supported currencies.Notes you can enter of the contact for future reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example,
"note_key": "Monthly gym membership".Response Parameters
The unique identifier linked to a plan. For example,
plan_00000000000001. This ID is used when creating a subscription for a customer.Used together with
interval to define how often the customer should be charged. Possible values:dailyweeklymonthlyyearly
Amount for the plan. When you use this plan to create a subscription, the customer will be charged this amount periodically.
Currency for the payment. You can accept payment in any of the supported currencies.
Notes you can enter of the contact for future reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example,
"note_key": "Monthly Gym".Fetch all Plans
Use the below endpoint to fetch details of all plans.GET /plans
Query Parameters
The number of plans to be fetched. Default value is 10. Maximum value is 100. This can be used for pagination in combination with
skip.The number of plans to be skipped. Default value is 0. This can be used for pagination in combination with
count.Fetch a Plan by ID
Use the below endpoint to fetch details of a plan by its unique identifier.GET /plans/:id
Path Parameter
Subscriptions
You can use Subscriptions to charge a customer periodically. A Subscription ties a customer to a particular plan you have created. It contains details like the plan, the start date, total number of billing cycles, free trial period (if any) and upfront amount to be collected.Create a Subscription
Handy Tips
- In order to process subscription, customer card details will need to be secured/tokenised in accordance with the applicable laws. The merchant will be solely responsible for obtaining informed consent from customers for the processing of e-mandates and such consent shall be explicit and not by way of a forced/default/automatic selection of check box, radio button etc.
- When the merchant is sharing
plan_id : unique identifier, it is for tokenising the card as per applicable rules for subscription mandate creation. If such consent is not shared during the payment flow, then Razorpay will not tokenise the card or process the e-mandate/ subscription transaction.
Request Parameters
The unique identifier of a plan that should be linked to the Subscription. For example,
plan_00000000000001.The number of billing cycles for which the customer should be charged. For example, if a customer is buying a 1-year subscription billed on a bi-monthly basis, this value should be
6.The number of times the customer should be charged the plan amount per invoice. For example, a customer subscribes to use software. The charges are ₹100 /month/license. The customer wants 5 licenses. You should pass
5 as the quantity. The customer is charged ₹500 (5 x ₹100) monthly. By default, this value is set to 1.Unix timestamp that indicates from when the Subscription should start. If not passed, the Subscription starts immediately after the authorisation payment. For example,
1581013800. For Subscriptions with a future start_date, frequency is considered as_presented.Unix timestamp that indicates till when the customer can make the authorisation payment. For example,
1581013800. The default value is 30 years. Do not pass any value if you do not want to set an expiry date.Indicates whether the communication to the customer would be handled by businesses or Razorpay. Possible values:
true(default): Communication handled by Razorpay.false: Communication handled by businesses.
Array that contains details of any upfront amount you want to collect as part of the authorisation transaction.
The upfront amount in the currency subunit you want to charge the customer. For example ,
30000.The currency in which you want to charge the customer. This has to match the plan currency. For example,
INR.The unique identifier of the offer that is linked to the Subscription. You can obtain this from the Dashboard. For example,
offer_JHD834hjbxzhd38d.Notes you can enter for the contact for future reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example,
"note_key": "Beam me up Scotty”.Response Parameters
The unique identifier for a plan that is linked to the created subscription. For example,
plan_00000000000001.The unique identifier of the customer linked to the subscription. This is populated automatically once the customer completes the authorisation transaction. For example,
cust_00000000000001.Status of the subscription. Refer to the life cycle section for more details. Possible values:
createdauthenticatedactivependinghaltedcancelledcompletedexpired
Unix timestamp. The start time of the current billing cycle of the subscription. For example,
1581013800.Unix timestamp. The end time of the current billing cycle of the subscription. For example,
1581013800.The timestamp, in Unix format, when the subscription was completed or was cancelled. For example,
1581013800.The number of times the plan should be linked to the subscription. For example, if the plan is ₹100/user/month and the customer has 5 users, you should pass 5 as the quantity to have the customer charged ₹500 (5 x ₹100) monthly. By default, this value is set to 1.
Notes you can enter for the contact for future reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example,
"note_key": "Beam me up Scotty”.Unix timestamp. This indicates when the next charge on the subscription should be made. For example,
1581013800.The unique identifier of the offer that should be linked to the subscription. For example,
offer_JHD834hjbxzhd38d.The timestamp, in Unix format, when the subscription should start. If not passed, the subscription starts immediately after the authorisation payment. For example,
1581013800.The number of times that the charge for the current billing cycle has been attempted on the card. For example,
2.The number of billing cycles for which the customer should be charged. For example,
2. We support subscriptions for a maximum duration of 100 years. The number of billing cycles depends if the subscription is daily, weekly, monthly or yearly.This indicates the number of billing cycles for which the customer has already been charged. For example,
2.Indicates whether the communication to the customer would be handled by businesses or Razorpay.
true: Communication handled by Razorpay. Defaults totrue.false: Communication handled by businesses.
The timestamp, in Unix format, till when the customer can make the authorisation payment. For example,
1581013800.URL that can be used to make the authorisation payment. For example,
https://rzp.io/i/PWtAiEo.Indicates if the subscription has any scheduled changes. Possible values:
true: Subscription has scheduled changes.false: Subscription does not have scheduled changes.
Represents when the subscription should be updated. Possible values:
now(default): Updates the subscription immediately.cycle_end: Updates the subscription at the end of the current billing cycle.
Create a Subscription Link
Handy Tips
- In order to process subscription, customer card details will need to be secured/tokenised in accordance with the applicable laws. The merchant will be solely responsible for obtaining informed consent from customers for the processing of e-mandates and such consent shall be explicit and not by way of a forced/default/automatic selection of check box, radio button etc.
- When the merchant is sharing
plan_id : unique identifier, it is for tokenising the card as per applicable rules for subscription mandate creation. If such consent is not shared during the payment flow, then Razorpay will not tokenise the card or process the e-mandate/ subscription transaction.
Request Parameters
The unique identifier of a plan that should be linked to the Subscription. For example,
plan_00000000000001.The number of billing cycles for which the customer should be charged. For example, if a customer is buying a 1-year subscription billed on a bi-monthly basis, this value should be
6.The number of times the customer should be charged the plan amount per invoice. For example, a customer subscribes to use software. The charges are ₹100 /month/license. The customer wants 5 licenses. You should pass
5 as the quantity. The customer is charged ₹500 (5 x ₹100) monthly. By default, this value is set to 1.Unix timestamp that indicates from when the Subscription should start. If not passed, the Subscription starts immediately after the authorisation payment. For example,
1581013800. For Subscriptions with a future start_date, frequency is considered as_presented.Unix timestamp that indicates till when the customer can make the authorisation payment. For example,
1581013800. The default value is 30 years. Do not pass any value if you do not want to set an expiry date.Indicates whether the communication to the customer would be handled by businesses or Razorpay. Possible values:
true(default): Communication handled by Razorpay.false: Communication handled by businesses.
Array that contains details of any upfront amount you want to collect as part of the authorisation transaction.
The upfront amount in the currency subunit you want to charge the customer. For example ,
30000.The currency in which you want to charge the customer. This has to match the plan currency. For example,
INR.The unique identifier of the offer that is linked to the Subscription. You can obtain this from the Dashboard. For example,
offer_JHD834hjbxzhd38d.Notes you can enter for the contact for future reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example,
"note_key": "Beam me up Scotty”.The customer’s email and phone number to which notifications are to be sent. Use this array only if you have set the
customer_notify parameter to true. That is, Razorpay sends notifications to the customer. The customer details entered in the API request are only to notify the customer about the Subscription. The same will not be prefilled in the checkout as per the government guidelines.Response Parameters
The unique identifier for a plan that is linked to the created subscription. For example,
plan_00000000000001.The unique identifier of the customer linked to the subscription. This is populated automatically once the customer completes the authorisation transaction. For example,
cust_00000000000001.Status of the subscription. Refer to the life cycle section for more details. Possible values:
createdauthenticatedactivependinghaltedcancelledcompletedexpired
Unix timestamp. The start time of the current billing cycle of the subscription. For example,
1581013800.Unix timestamp. The end time of the current billing cycle of the subscription. For example,
1581013800.The timestamp, in Unix format, when the subscription was completed or was cancelled. For example,
1581013800.The number of times the plan should be linked to the subscription. For example, if the plan is ₹100/user/month and the customer has 5 users, you should pass 5 as the quantity to have the customer charged ₹500 (5 x ₹100) monthly. By default, this value is set to 1.
Notes you can enter for the contact for future reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example,
"note_key": "Beam me up Scotty”.Unix timestamp. This indicates when the next charge on the subscription should be made. For example,
1581013800.The unique identifier of the offer that should be linked to the subscription. For example,
offer_JHD834hjbxzhd38d.The timestamp, in Unix format, when the subscription should start. If not passed, the subscription starts immediately after the authorisation payment. For example,
1581013800.The number of times that the charge for the current billing cycle has been attempted on the card. For example,
2.The number of billing cycles for which the customer should be charged. For example,
2. We support subscriptions for a maximum duration of 100 years. The number of billing cycles depends if the subscription is daily, weekly, monthly or yearly.This indicates the number of billing cycles for which the customer has already been charged. For example,
2.Indicates whether the communication to the customer would be handled by businesses or Razorpay.
true: Communication handled by Razorpay. Defaults totrue.false: Communication handled by businesses.
The timestamp, in Unix format, till when the customer can make the authorisation payment. For example,
1581013800.URL that can be used to make the authorisation payment. For example,
https://rzp.io/i/PWtAiEo.Indicates if the subscription has any scheduled changes. Possible values:
true: Subscription has scheduled changes.false: Subscription does not have scheduled changes.
Represents when the subscription should be updated. Possible values:
now(default): Updates the subscription immediately.cycle_end: Updates the subscription at the end of the current billing cycle.
Fetch All Subscriptions
Query Parameters
The number of Subscriptions to be fetched. Default value is
10. Maximum value is 100. This can be used for pagination, in combination with skip.The number of Subscriptions to be skipped. Default value is
0. This can be used for pagination, in combination with count.Fetch Subscription by ID
Path Parameters
Cancel a Subscription
Path Parameters
Request Parameter
Use this parameter to cancel a Subscription at the end of a billing cycle. Possible values:
true: Cancel the subscription at the end of the current billing cycle.false(default): Cancel the subscription immediately.
Update a Subscription
Path Parameters
Request Parameters
The unique identifier of the new plan that should be linked to the Subscription. For example,
plan_00000000000001.The unique identifier of the offer that should be linked to the Subscription. You can obtain this from the Dashboard. For example,
offer_JHD834hjbxzhd38d.The number of times the plan should be linked to the Subscription. For example, if the plan is ₹100/user/month and the customer has 5 users, you should pass
5 as the quantity to have the customer charged ₹500 (5 x ₹100) monthly. By default, this value is set to 1.This parameter is used to update the
total_count for a Subscription. For example, let us consider a monthly Subscription with 12 billing cycles. The Subscription has been charged successfully 4 times and 3 more invoices have been issued, but have not been charged. The remaining count in such cases is 5. However, you can overwrite this value using this parameter.Represents when the Subscription should be updated.
now(default): Updates the Subscription immediately.cycle_end: Updates the Subscription at the end of the current billing cycle.
Represents who sends notifications to the customer. Possible values:
true(default): Notifications sent by Razorpay.false: Notifications sent by you.
Fetch Details of a Pending Update
Path Parameters
Cancel an Update
Path Parameters
Pause a Subscription
Path Parameters
Request Parameters
Resume a Subscription
Path Parameters
Request Parameters
Fetch All Invoices for a Subscription
Query Parameter
Response Parameters
The customer’s name. Know more Customers API.
Details of the line item that is billed in the invoice. Number of arrays = number of line items billed in the invoice. For example, if the Subscription starts immediately and has an upfront fee attached to it, the number of line items = 2. One for the Subscription charge and one for the upfront fee.
The unique identifier linked to the item billed in the invoice. For example,
li_00000000000001.Unique identifier of the payment made by the customer using this invoice. For example,
pay_00000000000001.The status of the invoice. Possible values:
draftissuedpartially_paidpaidexpiredcancelleddeleted
The Unix timestamp, indicates at which the invoice was issued to the customer. For example,
1593411209The Unix timestamp, indicates at which the invoice was canceled by you. For example,
1593411209Indicates whether the SMS notification for the invoice was sent to the customer. Possible values:
pendingsent
Indicates whether the email notification for the invoice was sent to the customer. Possible values:
pendingsent
Indicates whether the customer can make a partial payment on the invoice.
true: Customer can make partial payments.false: Customer cannot make partial payments.
Amount to be paid using the invoice. This should be in the smallest unit of the currency. For example,
29995.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”.The short URL that is generated. This is the link that can be shared with customers to accept payments. Once canceled, no payments can be accepted using the link. For example,
https://rzp.io/i/gb5827Hh.Used when the link description is lengthy and you want to make the text collapsible. The text can be expanded by the customer using the Show More link.
true(default): Link description appears collapsed, with a Show More link.false: Link description appears expanded.
The Unix timestamp, that indicates when this invoice entity was created. For example,
1593411943.Delete an Offer Linked to a Subscription
Path Parameters
The unique identifier of the Subscription from which you want to remove the offer. For example,
sub_00000000000001.The unique identifier of the offer you want remove from the Subscription. For example,
offer_JHD834hjbxzhd38d.Authentication Transaction
Create Authentication Transaction
After you create a plan and a subscription, you have to create an authentication transaction. This authenticates the customer’s payment method and authorizes you to collect recurring payments via the authenticated payment method. Use the below endpoint to create an authentication transaction with methodcard.
POST /payments/create/json
Request Parameters
Unformatted card number. This field is required if value of
method is card. Use one of our test cards to try out the payment flow.The expiry month of the card in
MM format. For example, 01 for January and 12 for December.CVV printed on the back of the card.
Handy Tips
- CVV is not required by default for tokenised cards across all networks.
- CVV is optional for tokenised card payments. Do not pass dummy CVV values.
- To implement this change, skip passing the
cvvparameter entirely, or pass anullor empty value in the CVV field. - We recommend removing the CVV field from your checkout UI/UX for tokenised cards.
- If CVV is still collected for tokenised cards and the customer enters a CVV, pass the entered CVV value to Razorpay.
Response Parameters
If the payment request is valid, the response contains the following fields. Refer to the S2S Json V2 integration document for more details.A list of action objects available to you to continue the payment process. Present when the payment requires further processing.
An indication of the next step available to you to continue the payment process. Possible values:
otp_generate- Use this URL to allow the customer to generate OTP and complete the payment on your webpage.redirect- Use this URL to redirect the customer to submit the OTP on the bank page.
Verify Payment
This is a mandatory step that allows you to confirm the authenticity of the card details returned to the Checkout form for successful payments.Handy TipsYou should consider the payment as successful and Subscription as authorised only after the signature has been successfully verified.
razorpay_signature returned to you by the Checkout form:
-
Create a signature in your server using the following attributes:
subscription_id: Retrieve thesubscription_idfrom your server. Do not use therazorpay_subscription_idreturned by Checkout.razorpay_payment_id: Returned by Checkout.key_secret: Available in your server.
Thekey_secretthat was generated from the Dashboard.
-
Use the SHA256 algorithm, the
razorpay_payment_idand thesubscription_idto construct a HMAC hex digest as shown below:
- If the signature you generate on your server matches the
razorpay_signaturereturned to you by the Checkout form, the payment received is from an authentic source.
Add-ons
You can create add-ons to charge the customer an extra amount for a particular billing cycle. Once you create an add-on for a Subscription, it is added to the next invoice that is generated. On the next scheduled charge, the customer is charged the add-on amount in addition to their regular Subscription amount.Create an Add-on
Path Parameter
Request Parameters
The amount you want to charge the customer for the add-on, in the currency subunit. For example,
30000.The currency in which the customer should be charged for the add-on. For example,
INR.This specifies the number of units of the add-on to be charged to the customer. For example,
2. Defaults to 1. The total amount is calculated as amount * quantity.Response Parameters
Amount of the add-on that is to be charged to the subscription in the next billing cycle. For example,
30000.The currency in which the customer should be charged for the add-on. For example,
INR. Know more about the currencies we support.This specifies the number of units of the add-on to be charged to the customer. For example,
2. The total amount is calculated as amount * quantity.The unique identifier of the subscription to which the add-on is being added. For example,
sub_00000000000001.The add-on is added to the next invoice that is generated after the add-on is created. This field is populated only after the invoice is generated. Until then, it is
null. Once the add-on is linked to an invoice, it cannot be deleted.Fetch all Add-ons
Query Parameters
The number of add-ons to be fetched. Default value is
10. Maximum value is 100. This can be used for pagination, in combination with skip.The number of add-ons to be skipped. Default value is
0. This can be used for pagination, in combination with count.