Available in🇮🇳 India
This page explains how Razorpay’s Recurring Payment APIs work, from token setup to ongoing debits and gives you everything you need to reason through the integration before writing a single line of code.
Understanding Tokens
At the heart of every Recurring Payment is a token, 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.Mandate and tokenYou will see both words in this guide, and they are two views of the same thing. Mandate is what the customer sees and approves in their UPI app, and it is the word NPCI uses. Token is the object you work with in the Razorpay APIs: every approved mandate has exactly one
token_id, and that is what you pass on every subsequent debit. Where this guide describes something the customer does, it says mandate; where it describes something your code does, it says token.token_id issued by Razorpay. This is the key you use for all future debit calls.
What is Inside a Token
Every Autopay token has four key parameters that you define, and are reviewed by the user during setup time. These are locked once the token is registered. You cannot change them later without creating a fresh token.Max Amount (token.max_amount)
The maximum amount that can be debited in a single charge. The customer sees this at approval time. Individual debits must not exceed this value.
First Debit (order.amount)
The amount debited during token registration to activate the token. The minimum amount is ₹1 for UPI. Without a successful first payment, the token is not confirmed.
Frequency (token.frequency)
How often the customer can be debited: daily, weekly, monthly, quarterly, yearly or as_presented. Only one debit per frequency cycle is allowed.
Expiry (token.expire_at)
When the token expires, as a Unix timestamp. After this date, no further debits can be collected. Defaults to 10 years if not set. Maximum 30 years for UPI.
Setting Up a Token
Token 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.Step 1: Create a Customer
Step 1: Create a Customer
Razorpay links every token to a customer object. Create one with the customer’s name, email and contact number. These values are optional, however, we recommend that you pass this to maintain clean customer mapping. 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 customer-id to create a new token. POST /v1/customersStep 2: Create an Order with token details
Step 2: Create an Order with token details
Create a Razorpay order that carries the token 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 debit, or the setup charge the customer pays for token registration. POST /v1/ordersStep 4: Token is confirmed
Step 4: Token is confirmed
After the customer authenticates, Razorpay authorises the registration amount with NPCI or the card network. Once the first payment is successfully captured, the token 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.confirmedPerforming Recurring Debits
Once the token 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 and schedules the debit after 25 hours. The additional 1 hour is added to accommodate any notification delays. 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 Additional Approval Criteria below). Check the presentment time in the FAQs before you start sending recurring payments, so your debit schedule lines up with when the issuing bank presents them.Step 1: Create an Order
Step 1: Create an Order
Create a new order for every debit. The amount must not exceed the
max_amount set at token registration. And ensure that you create orders only on confirmed tokens. Set payment_capture: true for automatic capture. POST /v1/ordersStep 2: Create the Recurring Payment
Step 2: Create the Recurring Payment
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/recurringStep 3: Payment is confirmed
Step 3: Payment is confirmed
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 via webhook. That is payment.captured when the order was created with payment_capture set to true, payment.authorized when it was not, or payment.failed.Payment and Token States
Every token is tracked through two parallel objects: a payment (the individual transaction) and a token (the token itself). The combination of payment state and token state tells you exactly what is happening at any point in the lifecycle.Handy TipsAlways 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.- During Token Registration
- During Recurring Debits
There is no failed order stateAn order never moves to a
failed state and there is no order failed webhook. A failed payment leaves its order in the attempted state, so track failure through the payment (payment.failed) rather than waiting on the order.Additional Approval Criteria
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 requirement, not a Razorpay policy, and applies across all Recurring Payment methods. For UPI Autopay, NPCI enforces both the maximum token 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 token amount you can register and the AFA-free per-debit threshold.
- The token frequency: Variable-amount tokens (
frequency: as_presented) have lower maximum token ceilings than fixed-schedule tokens (daily,weekly,monthly,quarterly,yearly).
- Standard Limit (Most MCCs)
- Enhanced Limit (Select MCCs)
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.
Limits by MCC
The table below lists the limits enforced by NPCI per merchant category for UPI Autopay. The twoMax Token columns map to your token’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 TipsIf you are not sure which MCC has been assigned to your account, check with your Razorpay account manager. Attempting to create a token with a
max_amount that exceeds the limit shown above for your MCC and frequency will cause the order creation request to fail.Integration Steps
To integrate UPI Autopay using the S2S (server-to-server) flow, follow these steps:- Initiate Mandate Registration - Create a customer, create an order with mandate details and create an authorisation payment.
- Fetch and Manage Tokens - Retrieve the
token_idby fetching it or waiting for thetoken.confirmedwebhook, check token states, and cancel or delete tokens as needed. - Create Subsequent Payments - Create orders and charge the customer on a recurring basis using the
token_id. - Webhooks - Set up webhook listeners to receive real-time notifications for mandate and payment events. Integrating with webhooks is strongly recommended as it is the most efficient method for tracking payment and token status changes.