> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay-881012b3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
Available in
🇮🇳 India
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.
## Understanding Mandates
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.
### What is Inside a Mandate
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.
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.
The amount debited during mandate registration to activate the mandate. The minimum amount is ₹1 for UPI and Cards, and ₹0 for eMandate. Without a successful first payment, the mandate is not confirmed.
How often the customer can be debited: daily, weekly, monthly, quarterly, yearly or as\_presented. For UPI, NPCI enforces this strictly. Only one debit per frequency cycle is allowed.
When the mandate 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.
**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.
## Setting Up a Mandate
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.
## Performing Recurring Debits
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 [AFA Limits](#afa-limits) below).
### Pre-Debit Notification Timeline
| Timeline | Event |
| ---------------- | --------------------------------------------------------- |
| T + 0 | You call Create Order + Create Payment. |
| T + 0 to T + 24h | PDN sent to NPCI. Bank notifies the customer. |
| T + 25h | Debit executed (1-hour buffer after notification window). |
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.
## Payment and Token States
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.
| Payment State | Token State | What is Happening |
| --------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `created` | `initiated` | The `token_id` has been created and is awaiting successful first payment authorisation. The customer has not yet approved the mandate in their UPI app, card form or netbanking portal. |
| `authenticated` | `initiated` | The customer has approved the mandate in their UPI app or completed bank authentication. NPCI or the card network has received the registration request and is processing it. The token is not yet confirmed. UPI and eMandate only. |
| `authorized` | `active (pending)` | The mandate has been registered with NPCI. The first debit (₹1 for UPI and Cards) is being processed through the payment network. The token is active but awaiting capture confirmation before moving to confirmed. |
| `captured` | `confirmed` | The first payment is successfully authorised and captured. The mandate is fully active. The `token.confirmed` webhook fires. You can now schedule recurring debits against this `token_id`. |
| `failed` | `rejected` | The first payment failed due to wrong MPIN, insufficient balance, bank decline or customer cancellation. The token could not be confirmed and the mandate is not registered. The customer must go through the entire registration flow again. |
| `captured` | `cancellation_initiated` | The mandate was registered successfully but the customer has since initiated a cancellation from their UPI app or banking portal. The cancellation is in progress. Avoid scheduling new debits. |
| `captured` | `cancelled` | The mandate was registered successfully but the customer later cancelled it. The mandate is permanently closed. Stop all scheduled debits for this token. A new mandate registration is required to resume charging. |
| `captured` | `paused` | The mandate was registered successfully but is now temporarily paused, either by you via the Tokens API or by the customer from their UPI app. Debits cannot be executed until the mandate is resumed. |
| Payment State | Token State | What is Happening |
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `created` | `confirmed` | A debit has been triggered for a confirmed mandate. The payment is queued. For UPI, Razorpay is sending the Pre-Debit Notification and the actual debit will execute after the 24-hour window. For Cards and eMandate, the debit is being processed directly. |
| `captured` | `confirmed` | The recurring debit was successful. The customer's account has been debited. Update your billing records and confirm continued access or service delivery accordingly. |
| `failed` | `confirmed` | The debit failed due to insufficient funds, bank downtime or a missed debit window. The mandate itself is still active. Check `error.reason` in the webhook payload and retry or notify the customer as appropriate. |
| `failed` | `cancelled` | The debit failed because the mandate has been cancelled, either by the customer or by you via the Tokens API. Stop all scheduled debits for this token. A new mandate is required. |
| `failed` | `rejected` | A debit was attempted against a token that was never successfully confirmed. This happens if mandate registration did not complete but a debit was triggered anyway. Always check the token state before every debit. |
| `failed` | `paused` | The debit failed because the mandate is paused. Resume the mandate via the Tokens API before attempting another debit. |
| `failed` | `cancellation_initiated` | The customer has initiated a cancellation and the payment cannot be executed. Wait for the cancellation to complete, then stop further debit attempts for this token. |
## AFA Limits
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.
For insurance, financial services, security brokers, grocery and a few other notified categories, debits up to **₹1,00,000** are processed silently per RBI directive and NPCI circular OC-151A (December 2023). See the MCC table below for the full list.
### Limits by MCC
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.
| MCC | Category | Max Mandate (Freq: as\_presented) | Max Mandate (Other Frequencies) | AFA-Free Limit (per debit) |
| -------------- | ------------------------------------------------------ | --------------------------------- | ------------------------------- | -------------------------- |
| 4722 | Travel Agencies and Tour Operators | ₹25,000 | ₹5,00,000 | ₹15,000 |
| 5413 | Grocery Stores and Supermarkets | ₹1,00,000 | ₹5,00,000 | ₹1,00,000 |
| 5944 | Clock, Jewellery, Watch and Silverware Shops | ₹25,000 | ₹2,00,000 | ₹15,000 |
| 5960 | Direct Marketing: Insurance Services | ₹1,00,000 | ₹5,00,000 | ₹1,00,000 |
| 6012 | Financial Institutions: Merchandise and Services | ₹1,00,000 | ₹5,00,000 | ₹1,00,000 |
| 6211 | Security Brokers and Dealers | ₹1,00,000 | ₹5,00,000 | ₹1,00,000 |
| 6300 | Insurance Sales, Underwriting and Premiums | ₹1,00,000 | ₹5,00,000 | ₹1,00,000 |
| 6381 | Insurance Premiums | ₹1,00,000 | ₹1,00,000 | ₹1,00,000 |
| 6399 | Insurance | ₹1,00,000 | ₹1,00,000 | ₹1,00,000 |
| 6529 | Remote Stored Value Load: Member Financial Institution | ₹1,00,000 | ₹5,00,000 | ₹1,00,000 |
| 7322 | Debt Collection Agencies | ₹25,000 | ₹5,00,000 | ₹15,000 |
| 7409 | Equipment Rental and Leasing Services | ₹25,000 | ₹2,00,000 | ₹15,000 |
| 7410 | Buying and Shopping Services and Clubs | ₹25,000 | ₹5,00,000 | ₹15,000 |
| 9311 | Tax Payments: Government Agencies | ₹25,000 | ₹5,00,000 | ₹15,000 |
| 9400 | Government Services | ₹25,000 | ₹2,00,000 | ₹15,000 |
| All other MCCs | — | ₹25,000 | ₹1,00,000 | ₹15,000 |
**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.
## Integration Matrix
Use the table below to navigate directly to the integration guide for your payment method and checkout type.
| Payment Method | Standard Checkout | Custom Checkout | S2S |
| -------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| UPI Autopay | [UPI Standard](/docs/api/payments/recurring-payments/upi/create-authorization-transaction) | [UPI Custom](/docs/api/payments/recurring-payments/custom/upi/create-authorization-transaction) | [UPI S2S](/docs/payments/payment-gateway/s2s-integration/recurring-payments/upi/authorization-transaction) |
| UPI Autopay with TPV | [UPI with TPV Standard](/docs/api/payments/recurring-payments/upi-tpv/create-authorization-transaction) | [UPI with TPV Custom](/docs/api/payments/recurring-payments/custom/upi-tpv/create-authorization-transaction) | [UPI with TPV S2S](/docs/payments/payment-gateway/s2s-integration/recurring-payments/upi-tpv/authorization-transaction) |
| UPI One Time Mandate | [UPI One Time Mandate Standard](/docs/api/payments/recurring-payments/upi-otm/authorization-transaction) | [UPI One Time Mandate Custom](/docs/api/payments/recurring-payments/custom/upi-otm/create-authorization-transaction) | [UPI One Time Mandate S2S](/docs/payments/payment-gateway/s2s-integration/recurring-payments/upi-otm/authorization-transaction) |
| UPI ReservePay | [UPI ReservePay Standard](/docs/api/payments/recurring-payments/upi-reserve-pay/authorization-transaction) | [UPI ReservePay Custom](/docs/api/payments/recurring-payments/custom/upi-reserve-pay/create-authorization-transaction) | [UPI ReservePay S2S](/docs/payments/payment-gateway/s2s-integration/recurring-payments/upi-reserve-pay/integration-steps) |
| Cards | [Cards Standard](/docs/api/payments/recurring-payments/cards/create-authorization-transaction) | [Cards Custom](/docs/api/payments/recurring-payments/custom/cards/create-authorization-transaction) | [Cards S2S](/docs/payments/payment-gateway/s2s-integration/recurring-payments/cards/authorization-transaction) |
| eMandate | [eMandate Standard](/docs/api/payments/recurring-payments/emandate/create-authorization-transaction) | [eMandate Custom](/docs/api/payments/recurring-payments/custom/emandate/create-authorization-transaction) | [eMandate S2S](/docs/payments/payment-gateway/s2s-integration/recurring-payments/emandate/authorization-transaction) |
| Paper NACH | [Paper NACH Standard](/docs/api/payments/recurring-payments/paper-nach/create-authorization-transaction) | [Paper NACH Custom](/docs/api/payments/recurring-payments/custom/paper-nach/create-authorization-transaction) | [Paper NACH S2S](/docs/payments/payment-gateway/s2s-integration/recurring-payments/paper-nach/authorization-transaction) |
## Pre-Launch Checklist
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 [test credentials page](/docs/payments/payments/test-card-details) for the methods and values that can be tested before going live.