Deploy on Vexlo Cloud in 60s (₹149/mo UPI) — India's First & Only Developer PaaS. Instant INR UPI & 17 global currencies ($5/mo).
Deploy Now
Bucket 2: Indian Payment Gateways & UPI Webhooks7 min readVerified

Handling UPI AutoPay Recurring Mandate Declines & Pre-Debit Notifications in India

Complete engineering reference for NPCI UPI AutoPay recurring mandate execution failures. Handle 24-hour Pre-Debit Notifications (PDN), Purpose Code 14 rules, ₹15,000 AFA thresholds, and retry cooling windows.

TL;DR — Immediate Production Fix

Executing recurring SaaS subscription debits in India via NPCI UPI AutoPay requires strict adherence to a two-phase state machine: (1) sending a Pre-Debit Notification (PDN) at least 24 hours (and no more than 48–72 hours) prior to the actual debit execution, and (2) triggering the recurring debit execution only after the 24-hour cooling window elapses on an `ACTIVE` mandate (`Purpose Code=14`, `Revocable=Y`). Attempting to execute a debit earlier than 24 hours after PDN delivery, exceeding the registered maximum mandate amount, or exceeding the RBI ₹15,000 silent auto-debit threshold without user MPIN approval results in immediate NPCI mandate execution declines.

Verified Root Causes in Production Environments

  • Violating the Mandatory 24-Hour Pre-Debit Notification (PDN) Window: Calling the gateway's Execute Recurring Debit API less than 24 hours after the `mandate.pdn_sent` timestamp causes the issuer bank switch to reject the debit.
  • Mandate Paused or Revoked Inside Customer's UPI App (`MANDATE_PAUSED` / `MANDATE_REVOKED`): Under RBI & NPCI rules (`Revocable=Y`), users can pause or cancel any SaaS mandate directly inside Google Pay, PhonePe, or Paytm at any time.
  • Insufficient Balance at Execution Time (`Z9`) & Uncoordinated Retries: Executing auto-debits at 3:00 AM during bank CBS maintenance windows or exhausting NPCI's maximum retry attempts within the validity window.

1. The Mandatory T-24h Pre-Debit Notification (PDN) State Machine

Unlike US Stripe card subscriptions where a cron job simply charges a saved payment method on the billing anniversary date, RBI and NPCI regulations mandate that every Indian recurring UPI AutoPay debit be preceded by a Pre-Debit Notification (PDN) sent to the customer's UPI app at least 24 hours before the debit is executed.

When you use Razorpay Subscriptions, Cashfree Subscriptions, or Setu/Decentro UPI AutoPay APIs, your billing scheduler must trigger the PDN at `T - 26 hours`, listen for the gateway webhook confirming PDN acknowledgment by the issuing bank, and schedule the actual debit execution at `T + 0 hours` (strictly `>= 24 hours` after PDN acknowledgment).

upi-autopay-scheduler.ts
typescript
export interface UpiMandateSubscription {
  subscriptionId: string;
  umn: string; // Unique Mandate Number assigned by NPCI (e.g., 7890123456@ybl)
  amountPaise: number; // e.g., 14900 for ₹149.00 Vexlo Cloud Pro
  nextBillingAt: Date;
  pdnAcknowledgedAt: Date | null;
  mandateStatus: 'ACTIVE' | 'PAUSED' | 'REVOKED' | 'EXPIRED';
}

export function evaluateMandateAction(sub: UpiMandateSubscription, now = new Date()) {
  if (sub.mandateStatus !== 'ACTIVE') {
    return { action: 'SKIP_INACTIVE_MANDATE', reason: `Mandate is ${sub.mandateStatus}` };
  }

  const hoursUntilBilling = (sub.nextBillingAt.getTime() - now.getTime()) / (1000 * 60 * 60);

  // Step 1: Send Pre-Debit Notification 26 to 48 hours before billing date
  if (!sub.pdnAcknowledgedAt && hoursUntilBilling <= 36 && hoursUntilBilling >= 25) {
    return { action: 'SEND_PRE_DEBIT_NOTIFICATION', umn: sub.umn, amountPaise: sub.amountPaise };
  }

  // Step 2: Execute recurring debit ONLY after >= 24.5 hours have elapsed since PDN acknowledgment
  if (sub.pdnAcknowledgedAt) {
    const hoursSincePdn = (now.getTime() - sub.pdnAcknowledgedAt.getTime()) / (1000 * 60 * 60);
    if (hoursSincePdn >= 24.5 && hoursSincePdn <= 72) {
      return { action: 'EXECUTE_RECURRING_DEBIT', umn: sub.umn, amountPaise: sub.amountPaise };
    }
  }

  return { action: 'WAIT', reason: 'Waiting for T-24h PDN window' };
}

2. NPCI UPI AutoPay Mandate Error Codes & Recovery Matrix

According to NPCI's UPI Recurring Mandate specification (and Axis Bank / Digio H2H documentation), recurring mandates must always carry `Purpose Code=14` (Recurring Mandate / SI) and `Revocable=Y`. Furthermore, for recurring charges up to ₹15,000 (₹1,00,000 for mutual funds/insurance/credit card bills), execution occurs automatically without the user entering their UPI MPIN; above ₹15,000 for general SaaS merchants, the user must approve the collect request in their UPI app with their MPIN.

Below is the reference matrix for the top UPI AutoPay mandate registration and execution failure codes.

upi-autopay-error-codes.json
json
{
  "U66": {
    "stage": "Mandate Registration / Execution",
    "meaning": "Device fingerprint or mandate velocity limit exceeded on remitter bank",
    "recovery": "Ask user to register the mandate using an alternate bank account or VPA."
  },
  "V5 / V6": {
    "stage": "Mandate Creation",
    "meaning": "Purpose Code=14 or Revocable=Y tag invalid for SI/Recurring Mandate",
    "recovery": "Ensure gateway API call sets revocable: true and frequency: 'MONTHLY' or 'AS_PRESENTED'."
  },
  "Z9": {
    "stage": "Recurring Debit Execution",
    "meaning": "Insufficient funds in customer account at time of auto-debit",
    "recovery": "Schedule up to 2 smart retries spaced 24-48 hours apart (avoid 00:00-05:00 IST bank maintenance windows) and send WhatsApp/Email payment link fallback."
  },
  "U30": {
    "stage": "Recurring Debit Execution",
    "meaning": "Remitter Bank CBS technical debit failure",
    "recovery": "Retry execution with a new sequence number after 4 hours within the valid PDN window."
  },
  "MANDATE_REVOKED_BY_USER": {
    "stage": "Webhook Notification",
    "meaning": "User cancelled the AutoPay mandate inside GPay / PhonePe / Paytm",
    "recovery": "Mark subscription as cancel_at_period_end and offer 1-click UPI Intent renewal."
  }
}

3. Optimal IST Time-of-Day Scheduling for Indian Bank CBS Success Rates

Never trigger your UPI AutoPay debit execution cron job at `00:00 IST` (midnight) or between `01:00 IST` and `04:30 IST`. Most Indian public and private sector banks run nightly Core Banking System (CBS) batch reconciliation and EOD (End-of-Day) jobs during this window, causing `U30` and `BT` switch timeouts to spike by 3x. Schedule recurring UPI AutoPay executions between `10:00 AM IST` and `02:00 PM IST` on business days for the highest first-attempt authorization rate.

autopay-cron-schedule.yaml
yaml
# Recommended IST Cron Schedule for Indian SaaS UPI AutoPay Billing
schedules:
  send_pre_debit_notifications:
    cron: "30 4 * * *" # 10:00 AM IST (04:30 UTC) at T-1 Day
    task: "Dispatch T-24h PDN for tomorrow's renewals"

  execute_authorized_debits:
    cron: "0 5 * * *" # 10:30 AM IST (05:00 UTC) on Billing Day (>=24.5h after PDN)
    task: "Execute recurring UPI AutoPay debits during peak bank CBS uptime"

Pre-Deployment Verification Checklist

  • Dispatch Pre-Debit Notifications (PDN) at least 24.5 hours before executing the recurring debit.
  • Keep SaaS recurring plan amounts at or below ₹15,000 per debit so execution stays frictionless (no MPIN prompt required).
  • Execute recurring debits between 10:00 AM and 02:00 PM IST instead of midnight CBS maintenance windows.
  • Listen for `subscription.paused` and `subscription.cancelled` webhooks when users modify mandates inside GPay or PhonePe.
India's First & Only Developer PaaS

Deploy on Vexlo Cloud in 60s (₹149/mo UPI)

Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.

Frequently Asked Questions

Why did my UPI AutoPay recurring debit fail even though the customer has an active mandate?

The most common technical cause is calling the recurring debit execution endpoint before 24 full hours have elapsed since the Pre-Debit Notification (PDN) was acknowledged by the customer's bank, or attempting to charge an amount higher than the `max_amount` authorized in the mandate.

What is the RBI limit for automatic UPI AutoPay debits without entering a UPI PIN?

For general SaaS, OTT, and cloud hosting subscriptions, recurring debits up to ₹15,000 execute automatically without user intervention after the 24-hour PDN. Debits above ₹15,000 require the user to approve the debit with their UPI MPIN.

How many times can I retry a failed UPI AutoPay debit on the same Pre-Debit Notification?

Most gateways and NPCI guidelines allow up to 2–3 execution retries within the validity window of the PDN for technical (`U30`) or insufficient fund (`Z9`) declines, using a fresh unique transaction reference for each retry.

Primary Upstream References & Specifications

Keep Debugging

Related Guides

Browse all 30 guides →