Skip to main content
Cashfree Subscriptions lets you set up and manage recurring payments for your customers.
  • INITIALIZED – Subscription created, authorisation pending.
  • BANK APPROVAL PENDING – Authorisation successful, pending bank approval.
  • ACTIVE – Subscription registered across NPCI and destination bank.
  • ON HOLD – A charge has failed for the subscription.
  • PAUSED – Subscription is paused by the merchant.
  • COMPLETED – Subscription completed its scheduled duration.
  • CUSTOMER CANCELLED – Subscription cancelled by the customer.
  • CUSTOMER PAUSED – Subscription paused by the customer.
  • EXPIRED – In seamless subscriptions, authorisation wasn’t attempted before expiry.
  • LINK EXPIRED – In non-seamless subscriptions, authorisation wasn’t attempted before expiry.
Yes. You can retry the last failed charge via the Merchant Dashboard or API.
Refer to the retry subscription charge API for details.
No. You can’t extend the expiry date of a subscription. You can cancel the subscription and create a new one.
Yes. You can test any subscription model in the test environment before going live.
You can use webhooks to receive notifications for all transactions.
Follow these steps to configure webhooks.
Subscription webhook events use a separate configuration from the main Payment Gateway webhooks. Log in to the Merchant Dashboard, go to Payment Gateway > Developers > Webhooks, and select the Subscriptions tab. Add your endpoint there and select the subscription events you want to receive. An endpoint configured only under the main webhooks section does not receive subscription-specific events.
No. Cashfree does not currently support replaying or resending subscription webhooks, such as SUBSCRIPTION_PAYMENT_SUCCESS, after they trigger. To check the current status of a subscription payment instead, call the Fetch Single Charge API to poll the latest transaction state. As a fallback, configure webhook retry handling on your own server.
This happens when each environment uses a different webhook version. Select the same webhook version, 2026-01-01 (the current version), in both your sandbox and production subscription webhook settings. Older versions (2022-09-01, 2023-08-01, 2025-01-01) return a different payload structure, so mismatched versions across environments produce mismatched payloads for the same event.
Yes. You can update the recurring amount of an active subscription using the Update Recurring Amount API.
Yes. Use On-Demand Subscriptions. The customer authorises a maximum mandate amount once, at setup. You can then charge any amount up to that maximum for each billing cycle by calling POST /pg/subscriptions/pay with payment_type: CHARGE, without requiring re-authorisation. This approach suits usage-based or milestone billing, where the charge amount varies each cycle.
The customer is authenticated by their bank using either net banking or debit card credentials. Debit card credentials are used only for authentication. Therefore, the mandate remains valid even if the debit card expires.
Mandate creation and transactions may fail due to operational or customer-related issues. View the common failure reasons.
Only savings accounts and individual (proprietor) current accounts are supported. Most destination banks do not support mandates for proprietor current accounts. For unsupported cases, consider using Physical NACH.
Yes. Customers can pause or cancel a mandate from their UPI app (Mandates > Active Mandates > Pause/Cancel > Submit).
No. Only the customer can resume a paused mandate from their UPI app.
The expiry period for an eNACH mandate can be set up to a maximum of 30 years.
If the card expires, the subscription is marked as card_expired.
Yes. The subscription_card_expiry_reminder webhook is triggered 6 days before the card expiry.
Once the card expires, the subscription moves to card_expired status. Further charges cannot be processed.
The merchant must create a new mandate using the updated card details. The customer must then authorise the new mandate.
Cashfree offers four different payment methods, each with specific limits on the allowed subscription amounts, as outlined below.
  • UPI AutoPay
  • Cards
  • eNach
  • Physical Mandate
Learn more about these payment modes.
Yes, it is fully compliant with the new Digital Lending Guidelines by RBI. NBFCs and Fintechs can use Cashfree to collect repayments, disburse credit, and co-lend without a hassle.
Cashfree Subscriptions caters to various industries with diverse use cases. Some of the top ones include:
  • NBFCs and digital lending apps
  • OTT platforms
  • Ed-tech platforms
  • E-commerce companies
  • Investment firms
  • Insurance providers
  1. Go to Subscription Dashboard > All subscriptions > Create Subscriptions
  2. Enter details – Add customer info, subscription ID, recurring amount, due date, and max debits.
To create a new subscription from the Merchant Dashboard, go to Subscriptions Dashboard > All Subscriptions > Create Subscription.You can also create multiple subscriptions at once using the Merchant Dashboard. Go to Subscriptions Dashboard > Batch Subscriptions > Upload File to upload a file that contains all the information required for multiple subscriptions.Learn more
Cashfree does not offer UPI AutoPay activation as a self-serve feature. Contact your Cashfree account manager, or fill out the Support Form, to request activation on your production and sandbox accounts. Charges depend on your pricing plan, so confirm the applicable rate with your account manager.
For On-Demand subscriptions, when you want to initiate a large number of payments for multiple subscriptions, you can use the Bulk Payments feature.
Cashfree supports importing mandate information for a subscription. You can move any historical mandate data to Cashfree and continue processing transactions in Cashfree. Cashfree ensures a smooth mandate porting experience.To initiate the porting process:
  1. Contact Cashfree support: Initiate the porting process by nominating Cashfree as your payment processing partner for your Utility Code or mandates.
  2. Partner bank coordination: Share the mandate list with your partner bank to update their systems. Our team will guide you through the process.
  3. Import mandates: Upload the updated mandate list into Cashfree’s system.
  4. Start processing payments: Once imported, you can begin processing payments seamlessly through Cashfree. Learn more about importing mandates.
Once the eMandate is successfully created, the corresponding transactions can get declined due to the reasons listed below:
Multiple auths will appear if the customer attempts the transaction more than once.
The API returns this error when the requested payment mode is not valid for the action you are performing. Common causes include:
  • UPI AutoPay is not activated on your merchant account.
  • An AUTH action is being attempted on a subscription that is already authorised. Only one AUTH is allowed per mandate.
  • The plan or subscription type does not support the requested action. See subscription payment modes for supported actions per mode.
Use the Fetch Subscription API to check the subscription’s current status first. If UPI AutoPay activation is the cause, contact your account manager or fill out the Support Form. This requires commercial approval.
Yes, subscription may move to SUCCESS state or it may move to FAILED state based on bank’s confirmation. But the subscription state will move to terminal state.
No, the subscription will move to SUCCESS.
No. A PERIODIC subscription payment moves from INITIALIZED to PENDING only when its scheduled billing date arrives, and the sandbox environment does not support forcing this transition early. For ON_DEMAND subscriptions, trigger an immediate charge by calling POST /pg/subscriptions/pay with subscription_id and payment_type: CHARGE in the request body. Use this as the sandbox-friendly way to test a charge without waiting for a billing cycle.
Offers are not currently supported with Subscriptions.
Yes. The Subscriptions API requires both customer_email and the customer’s mobile number to create a UPI AutoPay mandate, and neither field is optional. The API rejects the subscription creation request if either field is missing. If collecting an email address upfront is difficult, capture a valid address during customer onboarding, before you initiate mandate creation.
The customer’s phone number is primarily used for sending payment links to customers and sending subscription mandate notifications for recurring payments. It may also be used for transaction-related communication where applicable. This applies to both domestic and international transactions wherever relevant.
It is not mandatory for the merchant to perform OTP validation at their end. However, since the customer’s phone number is used to send payment links and important mandate notifications, we expect the number to be accurate. If an incorrect number is provided, the customer may not receive the communication.
Yes, Cashfree performs a basic validation check to ensure the phone number is in the correct format. For Indian transactions, this includes verifying that it is a valid 10-digit mobile number. This is only a format-level validation and does not include OTP-based verification.
If a subscription remains in the INITIALIZED state and the configured expiry time is reached, and there is no successful authorisation or payment against the subscription (or the authorisation attempt fails), the subscription will continue to remain in the INITIALIZED state. Once the subscription crosses its expiry time, it will be moved to the EXPIRED state.
No. The debit amount cannot change after the PDN is initiated. If the executed debit amount differs from the amount notified in the PDN, the transaction is declined by the issuing bank due to the amount-match logic enforced at the issuing bank.
Once the authorisation payment is successfully completed and the subscription moves to the ACTIVE state, the behaviour is different. Even if the merchant has not specified the number of cycles (max_cycles), when the subscription reaches its configured expiry time (expires_on), the subscription will be moved to the COMPLETED state and not the EXPIRED state.
For an On-Demand Subscription, the charge date must be less than 14 days from the request date. If the charge date is outside this 14-day window, the request fails with a CHARGE_FAILED error for an invalid schedule date. For periodic subscriptions, the first charge date must also be within this 14-day window. See First charge date (FCD) for a subscription.
This discrepancy can occur when Cashfree first marks a transaction as Successful and the transaction then fails internal checks. In that case, the transaction can appear as Successful at the transaction level and in reconciliation reports, while Cashfree marks the payment as Failed. Cashfree then initiates a refund for the affected transactions.
The Maximum Amount is the upper limit you can charge under a mandate, set through the plan_max_amount parameter in the Create Plan API or the Create Subscription API. The customer sees this limit during the authorisation process. If a future charge exceeds this authorised limit, you need a new authorisation or mandate from the customer.
If Cards are enabled at the account level but the Card payment option is not displayed during the subscription flow, check the following:
  1. Plan Maximum Amount: In both Sandbox and Production, if the plan_max_amount configured for the subscription is greater than ₹15,000, Card and UPI payment modes may not be displayed by default due to the applicable mandate limits. Ensure that the plan_max_amount is within the supported limit. If you need to support amounts above ₹15,000, the AFA (Additional Factor Authentication) configuration must be enabled. Once AFA is enabled, customers must authenticate each recurring charge using UPI PIN for UPI Autopay, or OTP/2FA for Cards.
  2. Customer Phone Number: If the plan_max_amount is less than ₹15,000 and Cards are still not visible, ensure that a valid customer phone number is passed while creating the subscription. Dummy phone numbers are blacklisted for Card payment mode and may result in Cards not being displayed.
The Max. No. of Debits defines the maximum number of times you can charge a customer under a specific subscription or mandate, set via the plan_max_cycles parameter in the Create Plan API or the Create Subscription API. If you leave it blank, the subscription remains active until its configured expiry date or cancellation.
The On Hold status occurs for NACH and Card standing instructions when a recurring payment fails. To reactivate it, you can retry the failed charge (up to 3 retries per billing cycle) via the Merchant Dashboard or the Manage Payment API. Once the payment succeeds, the subscription resumes.
Yes. A Subscription Payment Form can have a single plan or multiple plans. Add more plans to the same form when you want customers to choose an option at checkout. Customers select one plan and complete mandate registration for that plan only. See Subscription Payment Form.
The default expiry value for the subscription session ID is 2 hours. If the session ID expires, the subscription remains in INITIALISED status. You must generate a new session ID using the Fetch Subscription API to open the checkout page again.
When searching for subscriptions in the Merchant Dashboard using date filters, you must use the original creation date of the subscription rather than the last updated date. If a subscription was created in the past but updated recently, set your Merchant Dashboard date range filter to include that original creation period to locate the record.
You can refer to the following API documentation for UPI AutoPay integration:
In the Merchant-Controlled flow, the payment_type field is not used. Instead, the merchant handles notification and execution separately using specific APIs (notify-mandate and execute-mandate). The payment_type field is only applicable to Cashfree-controlled flows, where a single API call triggers both the pre-debit notification and the charge.
A 25-hour window is required between a successful pre-debit notification and the execution of the charge. This logic and restriction apply to both the Sandbox and Production environments.
No separate enablement process or lead time is required. You can start using the merchant-controlled APIs directly in Production and migrate subscriptions gradually.
If you are using Juspay as a payment orchestrator for Cashfree subscriptions, you should not call Cashfree’s Cancel Subscription API directly. Instead, use Juspay’s Revoke Mandate API. Juspay internally maps their mandateId to Cashfree’s subscription_id and handles the underlying cancellation with Cashfree and the NPCI.
The customer_id parameter is not supported in the Subscription APIs. It belongs to Payment Gateway order APIs, including the Create Order API. If you pass customer_id in a Create Subscription API request, Cashfree does not capture, store, or display the value in the Merchant Dashboard.
UPI AutoPay mandate limits follow the payment method caps for subscriptions: ₹15,000 without Additional Factor Authentication (AFA), and ₹1,00,000 with AFA. This cap is set by the payment ecosystem, not by Cashfree, so it cannot be changed at the gateway level. If a charge exceeds the authorised mandate limit, request a new authorisation from the customer. See plan_max_amount on the Create Plan API and the Create Subscription API.To enable AFA for charges of ₹15,000 and above, raise a request through the Support Form. For the full payment-method limits, see Supported Payment Methods.
To include a customer reference ID or other custom identifiers in the Subscription report, pass the value in subscription_tags when you create the subscription. The value then appears in the Subscription report in the Merchant Dashboard. See subscription_tags on the Create Subscription API.
A subscription plan is the template that defines how you debit a customer after they authorise a mandate. You set the plan type with plan_type on the Create Plan API or the Create Subscription API. Cashfree supports two types: PERIODIC for a fixed amount on a fixed schedule, and ON_DEMAND for a variable amount that you trigger when you need it. Monthly billing is one PERIODIC interval (MONTH), not a third plan type.The two types differ as follows:
  • PERIODIC: Cashfree automatically debits a fixed recurring amount (plan_amount) on the schedule you set with plan_interval_type (DAY, WEEK, MONTH, or YEAR) and plan_intervals. Use this for memberships, retainers, or any charge that repeats on a known cycle.
  • ON_DEMAND: You trigger each charge yourself, for a variable amount up to plan_max_amount, at the time you choose. Cashfree does not run a billing schedule, and next_schedule_date is null. Use this for utility bills or usage-based billing. Raise charges from the Merchant Dashboard or the Charge Subscription API.
CHANGE_PLAN and PAUSE are not supported for On-Demand subscriptions. See Subscriptions Overview.
To refund a subscription payment, including the initial authorisation payment or a later charge, use the Create Subscription Refund API. The request requires the following parameters:
  • subscription_id
  • payment_id
  • refund_id
  • refund_amount
Pass a partial amount in refund_amount to issue a partial refund.
The Create Subscription API returns customer bank account details such as account number and IFSC only when the subscription Third Party Validation (TPV) flag is enabled for your merchant ID. This flag is separate from Payment Gateway TPV. If subscription TPV is enabled, pass customer_bank_account_number and at least one of customer_bank_ifsc or customer_bank_code in the request.
To call Subscription APIs on behalf of a merchant, use the Subscriptions API with partner authentication headers instead of x-client-id and x-client-secret. Include the following headers:
  • x-partner-apikey: your partner API key
  • x-partner-merchantid: the merchant ID
  • x-api-version: a current Payments API version, such as 2025-01-01 or 2026-01-01
See API authentication.
The SUBSCRIPTION_PAYMENT_SUCCESS webhook does not include the bank UTR or RRN (bank_reference). Use the cf_payment_id from the webhook to find the transaction in the Merchant Dashboard and read the UTR from the transaction details. See Subscription Webhooks.
The Merchant Dashboard displays only subscription plans created within the past two years. Plans older than two years cannot be accessed in the Merchant Dashboard dropdown.Older plans are not deleted and remain active. You can still use them through the Cashfree APIs without needing to recreate them.To view older plans or subscriptions, use the Custom Date filter and specify a date range that includes the period when the plan or subscription was originally created. You can then use the search and filter functions to find specific plan IDs.
No. For UPI and Card payment methods, the authorisation amount cannot be set to ₹0. A ₹0 authorisation amount is supported only for eNACH (Netbanking). If you set it to ₹0 for UPI, Cashfree deducts a ₹1 authorisation amount from the customer’s account.
The Split creation failed error typically occurs if Easy Split is not enabled for your account or if the vendors are not correctly configured. Ensure that:
  • Easy Split is enabled at the account level. Contact your account manager, or fill out the Support Form, to enable this for your sandbox and production accounts.
  • The vendor_id used in the request already exists in your account.
  • The vendor is in an ACTIVE state before using it in a subscription request.
To set up a subscription with a trial period (for example, 3 days) and an initial authorisation fee, follow these steps:
  1. Create a Plan: Use the Create Plan API with plan_type: PERIODIC, plan_interval_type: MONTH, and the recurring amount in plan_recurring_amount.
  2. Create the Subscription: Use the Create Subscription API with the following parameters:
    • authorization_details.authorization_amount: Set to 1 to charge ₹1 instantly for mandate setup.
    • authorization_details.authorization_amount_refund: Set to false to keep the ₹1 as a trial fee, or true to refund it after authorisation.
    • subscription_first_charge_time: Set this to the date when the trial ends (for example, 3 days from the authorisation date). The first recurring charge will trigger on this date.
When you create a subscription in the Merchant Dashboard, select Email and SMS to enable notifications.
For subscription authorisation transactions, the authorization_amount_refund parameter that you set during subscription creation determines the refund behaviour. If you initiate a refund through the Merchant Dashboard, Cashfree triggers the REFUND_STATUS webhook event. If this event is not enabled in your webhook configuration, Cashfree does not send a notification. Make sure that you enable REFUND_STATUS in your Payment Gateway webhook settings.
After a subscription authorisation payment is completed, Cashfree sends a POST request to the return_url. If your return_url points to a frontend page that only handles GET requests, it returns a 405 error.To resolve this, use one of the following options:
  • Use a backend endpoint as the return_url that accepts POST requests.
  • Configure your frontend route to accept both GET and POST methods.
  • Use the SUBSCRIPTION_PAYMENT_STATUS webhook to handle payment status updates, and use the return_url only for customer redirection.
Percentage values in subscription_payment_splits follow Easy Split rules. Keep the following in mind:
  • Each vendor percentage must be greater than 0.
  • The total of all vendor percentages cannot exceed 100.
  • Any remaining percentage stays with you as the merchant.
You can pass decimal values, for example, 12.05.
For domestic payments (both one-time and subscription payments), no additional charges apply for processing normal refunds, whether they are partial or full refunds. Normal refunds take 5–10 working days to process.
Platform fees, transaction discount rate (TDR) charges, and flat subscription fees that Cashfree collects at the time of the transaction are not reversed when you initiate a refund. Cashfree retains these fees.
To refund a subscription payment, use the dedicated Subscription Refund API. You don’t need to create a separate payment gateway order.Endpoint (Production): POST https://api.cashfree.com/pg/subscriptions/{subscription_id}/refundsCashfree supports partial refunds. You can specify a refund_amount lower than the original payment amount. The request body must include the subscription_id, payment_id (or cf_payment_id), a unique refund_id, and the refund_amount.
Cashfree supports initiating a refund for a subscription payment only up to 6 months (approximately 180 days) from the transaction success time. After this period, refund initiation is not allowed.
No. The CHANGE_PLAN action does not support charging an amount that exceeds the plan_max_amount defined in the original plan. The plan_max_amount is the maximum mandate amount captured during the initial authorisation. If the new plan’s charges exceed the original plan_max_amount, you can’t use CHANGE_PLAN for the upgrade.To move a customer to a plan where charges exceed their current mandate limit, follow these steps:
  1. Create a new plan with the higher plan_max_amount or recurring amount.
  2. Create a new subscription (mandate) authorisation for the customer against this higher maximum so they re-authorise the higher cap.
  3. Start charging on the new subscription and cancel or expire the old one, depending on your business flow.
To prevent this scenario in the future, you can set the plan_max_amount to the highest amount you might ever need to charge across tiers during initial setup, while keeping plan_recurring_amount at the current tier’s price.
You can’t move a subscription from PAUSED to ACTIVE if any of the following conditions apply:
  • Subscription expiry: If the subscription_expiry_time has passed while the subscription was paused, it moves to EXPIRED status and you can’t reactivate it. You must create a new subscription.
  • Max cycles reached: If the subscription has already completed the maximum number of cycles defined by the plan’s plan_max_cycles, you can’t reactivate it.
  • Mandate revocation: If the customer revoked their UPI AutoPay mandate from their bank or UPI app while the subscription was paused, the underlying mandate is no longer valid.
To check the current status and expiry, use the Fetch Subscription API.
To resume a paused subscription, use the Manage Subscription API with the ACTIVATE action. Include the x-api-version header in the request. The ACTIVATE action requires action_details.next_scheduled_time. Cashfree uses only the date component of this value.If the customer paused the mandate from their UPI app, only the customer can resume it. See Can I resume a mandate if my customer has paused it?
Common reasons the Subscription Charge API (POST /pg/subscriptions/pay) fails include the following:
  • Subscription status: You can raise charges only on subscriptions in ACTIVE status. If the mandate is pending or in ACTION_REQUIRED, Cashfree rejects the charge.
  • Payment amount: The charge amount must not exceed the plan_max_amount configured for the subscription.
  • Payment ID reuse: Each charge attempt must use a unique payment_id. Reusing an ID from a prior attempt results in a duplicate rejection.
  • Timing: The charge can fail if you raise it before the subscription_first_charge_time.
  • Mandate validity: The charge fails if the mandate has expired or the customer has revoked it (CANCELLED).
Yes. If the customer’s mobile number is unavailable, you may provide a default number in the Create Order API. You must inform your Account Manager of the specific number you are using as the default. This prevents transactions from being blocked or flagged by risk and velocity checks.
To show only UPI Autopay and hide other payment methods such as Bank Account or Credit/Debit Card, pass the specific payment method in the authorization_details object during subscription creation. If no payment method filters are passed, all available modes are displayed by default. Refer to the payment_methods parameter documentation for details.