Integrate with Recurring Payment APIs
Understand how Razorpay's Recurring Payment APIs work, from mandate setup to ongoing debits, before writing a single line of code.
This page explains how Razorpay's Recurring Payment APIs work, from mandate setup to ongoing debits and gives you everything you need to reason through the integration before writing a single line of code.
At the heart of every Recurring Payment is a mandate, a standing permission that a customer gives you to debit their payment method on a schedule. Think of it as a signed agreement stored electronically against the customer's UPI id, card or bank account.
Setting up a mandate always requires the customer to actively authorise it. This is a regulatory requirement, the customer must enter their UPI MPIN, card OTP or Aadhaar OTP before the mandate is registered. No mandate can be created without explicit customer consent.
Once the mandate is confirmed, all future debits happen backend, automatically, on your schedule, without the customer doing anything. Unless the debit amount crosses RBI's AFA threshold, the customer is not involved at all.
Every mandate has four key parameters that you define at setup time. These are locked once the mandate is registered. You cannot change them later without creating a fresh mandate.
Handy Tips
Every registered mandate is uniquely identified by a token_id issued by Razorpay. This is the key you use for all future debit calls. Before attempting any debit, always check the token's current state: debiting against a paused or cancelled token will fail. Store the token_id securely against the customer record in your system.
Mandate registration is a four-step process. Steps 1 to 3 happen as part of the customer's checkout journey. Step 4 is confirmed asynchronously after NPCI or the card network processes the registration.
Razorpay links every mandate to a customer object. Create one with the customer's name, email and contact number. You get back a customer_id. Store this against the user in your system. If the customer already exists, pass fail_existing: "0" to retrieve the existing record instead of throwing an error. POST /v1/customers
Create a Razorpay order that carries the mandate parameters (max_amount, frequency and expire_at) inside a token object. This is the order the customer will authorise. The amount field is the first payment charge: ₹1 (100 paise) for UPI and Cards, ₹0 for eMandate. POST /v1/orders
Present the payment UI to the customer. For UPI, this means redirecting them to their UPI app via an intent deep-link to approve the mandate with their MPIN. For Cards, the customer enters card details and completes an OTP. For eMandate, the customer logs into netbanking or authenticates via Aadhaar. This is the only time the customer actively participates. POST /v1/payments/create/upi or POST /v1/payments/create/json or via the SDK.
After the customer authorises, Razorpay processes the registration with NPCI or the card network. Once the first payment is successfully captured, the mandate becomes active and Razorpay sends you a token.confirmed webhook. The token_id is now ready for recurring debits. Do not attempt any debits before this event fires. Webhook: token.confirmed
Watch Out!
A failed first payment means a failed mandate. The mandate is only confirmed once the first payment is successfully captured. If the first payment fails due to wrong MPIN, insufficient balance or bank decline, the token moves to rejected state and the mandate is not registered. The customer must go through the authorisation flow again from the beginning.
Once the mandate is confirmed, all future debits are backend operations. You initiate them from your server with no customer interaction needed.
When you trigger a debit, Razorpay first sends a Pre-Debit Notification (PDN) to the customer through the issuing bank. This is an RBI-mandated notification that informs the customer of the upcoming debit, including the merchant name, amount and scheduled date. For UPI, this must be sent at least 24 hours before the actual debit. Razorpay handles this automatically.
After the PDN window, the actual debit happens backend. The customer's account is debited directly with no MPIN or OTP required, unless the amount exceeds the AFA limits set by RBI (see
below).Create a new order for every debit. The amount must not exceed the max_amount set at mandate registration. Set payment_capture: true for automatic capture. POST /v1/orders
Call the Recurring Payment endpoint with the order_id, customer_id and token_id. This is fully server-side. There is no UI and the customer is not redirected anywhere. Razorpay queues the debit, sends the PDN and executes the debit after the notification window. POST /v1/payments/create/recurring
Razorpay sends a payment.captured webhook when the debit succeeds. For UPI, this typically arrives 24 to 36 hours after you trigger the payment due to the PDN window. For Cards and eMandate, it is typically faster. Avoid creating another debit for the same token until you have received a terminal status (payment.captured or payment.failed) via webhook.
Watch Out!
Avoid creating a debit on the last day of the mandate's frequency cycle. Creating a subsequent payment on the last day of the cycle (for example, last day of the month for a monthly mandate) will fail because the pre-debit notification takes 24 hours and the actual debit attempt falls into the next billing cycle. Always allow at least one business day of buffer before the cycle resets.
Every mandate is tracked through two parallel objects: a payment (the individual transaction) and a token (the mandate itself). The combination of payment state and token state tells you exactly what is happening at any point in the lifecycle.
Handy Tips
Always check the token state before attempting a debit. A payment against a paused, cancelled or rejected token will fail. Use GET /v1/customers/:customer_id/tokens/:token_id to fetch the current state at any time.
AFA (Additional Factor of Authentication) is an extra layer of approval required for high-value recurring debits. When AFA is triggered, the customer receives a notification from their bank and must enter their UPI MPIN or card OTP before the debit is processed. This is an RBI mandate, not a Razorpay policy, and applies across all Recurring Payment methods.
For UPI Autopay, NPCI enforces both the maximum mandate amount you can register and the per-debit silent threshold below which AFA is not required. Two parameters drive the applicable limits:
- Your Merchant Category Code (MCC): Assigned to your business by Razorpay during onboarding. The MCC determines both the maximum mandate amount you can register and the AFA-free per-debit threshold.
- The mandate frequency: Variable-amount mandates (
frequency: as_presented) have lower maximum mandate ceilings than fixed-schedule mandates (daily,weekly,monthly,quarterly,yearly).
For most merchant categories, debits up to ₹15,000 are processed silently with no customer action needed. For debits above ₹15,000, the customer must approve via UPI MPIN before the debit executes.
The table below lists the limits enforced by NPCI per merchant category for UPI Autopay. The two Max Mandate Amount columns map to your mandate's frequency value at registration. The AFA-Free Limit is the per-debit amount below which silent debits are processed. If your MCC is not listed, the All other MCCs row applies.
Handy Tips
If you are not sure which MCC has been assigned to your account, check with your Razorpay account manager. Attempting to create a mandate with a max_amount that exceeds the limit shown above for your MCC and frequency will cause the order creation request to fail.
Use the table below to navigate directly to the integration guide for your payment method and checkout type.
Before flipping the switch to live mode, walk through this checklist. Each item below maps to a configuration or handler that, if missed, results in failed mandates, dropped webhooks or rejected debits in production. Most go-live issues come from missing one of these.
Handy Tips
This checklist applies regardless of which checkout type you have integrated. The items that vary between Standard, Custom and S2S are called out inline.
Confirm with your Razorpay account manager that the payment methods you plan to support, UPI Autopay, Cards, eMandate or Paper NACH, are enabled on your account. Recurring is enabled per method, not as a single switch. Test mode and live mode are activated separately.
Verify that every authorisation order you create carries the correct mandate parameters inside the token object. Confirm auth_type, max_amount, frequency, expire_at, recurring_type and recurring_value are set to match your business model. For UPI Autopay with TPV, include the bank account details in the order. For eMandate and Paper NACH, decide between Register and Charge or Register Only, since this affects how the first debit is processed. For Custom and S2S UPI integrations, pass the TPAP name in the notes object so Razorpay can route correctly and report mandate quality analytics.
For Standard and Custom Checkout, implement both the success handler function and the dismiss or cancel callback function so that closed-without-paying scenarios are handled cleanly. For S2S, implement deep-link handling for UPI intent flows so that the customer is correctly returned to your app after approving the mandate in their UPI app. Always pass recurring: true (or recurring: 1, or recurring: "preferred" for some flows) and the customer_id in the order or payment request. A missing recurring flag silently degrades the payment to a one-time transaction, with no mandate created.
For Standard and Custom Checkout, verify the razorpay_signature returned in the success callback against the payment_id and order_id. Never trust the callback payload without verification, since this is the only way to confirm the response is genuinely from Razorpay. After verification, fetch the payment status using the payment_id to double check the final state before granting access or service to the customer. The code sample for signature verification is included in each checkout integration guide.
Build handlers that consume the error_code and error_reason returned for failed payments. Different error codes call for different actions, retry, notify the customer or stop scheduled debits entirely. Refer to the Error Codes reference for the full list and the recommended action for each. Failing to differentiate between transient bank errors and permanent mandate failures is a common source of unnecessary retries and customer churn.
Implement the four Token APIs you will need post-launch: Fetch Token by Payment id, Fetch Tokens by Customer id, Cancel Token (UPI only) and Delete Token. Always check the token state before triggering a debit, since debiting against a paused, cancelled or rejected token will fail. Store the token_id against the customer record in your system and treat it as the source of truth for whether you can charge.
Auto-capture windows default to 2 days for UPI and 3 days for other methods. Configure these to match your business policy. Beyond the auto-capture window, payments can still arrive in a late_authorized state, typically due to bank-side delays. Build your reconciliation logic to consume the payment state at capture time rather than at initiation, so late authorisations are not silently dropped from your records.
Subscribe to the events you depend on, at minimum token.confirmed, token.cancelled, payment.captured and payment.failed. Implement signature verification on every webhook payload using your webhook secret. Webhooks are at-least-once, so deduplicate on payment_id or event_id before acting. Implement the Fetch Payment and Fetch Token APIs as a fallback path, since webhooks can be delayed or missed during outages. Treat the API response as the source of truth when webhooks and your records disagree.
For auth payments (the ₹1 or ₹0 first payment), set payment_capture to manual if you want to avoid auto-refunding. Otherwise, the auth amount is auto-refunded back to the customer after the auto-capture window. For regular debits, integrate the Refunds API so your support team can refund failed-service or disputed transactions without engineering intervention. Test the refund flow end-to-end in test mode before launch.
Document the platform (web, Android, iOS, React Native, Flutter), checkout type (Standard, Custom, S2S) and server-side SDK or language version your integration uses. Razorpay periodically updates SDKs for security and NPCI compliance, especially for UPI. Track the version you launched with so you can upgrade cleanly when needed.
Watch Out! Test mode does not enforce the 24-hour Pre-Debit Notification window for UPI. Debits queue and execute much faster in test mode than they will in production. Do not benchmark your end-to-end debit timing using test mode, plan for the full PDN window when calculating SLAs and reconciliation windows for live traffic. UPI Autopay end-to-end testing requires a live merchant account, since UPI test values are not available in test mode. Refer to the
for the methods and values that can be tested before going live.Was this page helpful?