NPCI UPI Error Codes Reference (U30, U16, U28, Z9, BT) & Webhook Handling
Complete developer reference for NPCI UPI error codes U30 (Debit Failed), U16 (Risk Threshold Exceeded), U28 (PSP Unavailable), and Z9 (Insufficient Funds) with Node.js webhook retry classification.
When integrating Indian UPI payment gateways (Razorpay, Cashfree, PhonePe PG, Paytm, or self-hosted UPI observers like YouPI PG), failed transactions return standardized NPCI (National Payments Corporation of India) alphanumeric response codes in the webhook payload. Code U30 means the remitter bank failed to debit the customer's account (technical CBS decline—safe for immediate retry with a new Transaction ID), U16 means the transaction tripped NPCI/bank velocity or 24-hour cooling-off risk limits (hard decline—do not auto-retry on the same VPA), U28/BT indicates PSP or issuer switch timeout, and Z9 indicates insufficient funds in the customer's bank account.
Verified Root Causes in Production Environments
- U30 (Debit Has Been Failed - Remitter CBS): The customer's issuing bank Core Banking System (CBS) failed to complete the debit leg due to high load or database lock timeouts.
- U16 (Risk Threshold Exceeded): Triggered when a user exceeds the ₹1,00,000 daily UPI limit, exceeds 10-20 daily P2P/P2M transactions, or hits the ₹5,000 limit within the first 24 hours of registering a new device/SIM.
- U28 / BT / XY (PSP or Acquirer/Issuer Switch Down): Network timeout between the NPCI central switch and the remitter/beneficiary bank server.
- Z9 (Insufficient Funds) & ZM (Invalid MPIN): Customer-side errors where the account balance is lower than the order amount or the user entered an incorrect UPI PIN.
1. Complete NPCI UPI Response Code Classification Table for Engineers
Most Indian payment gateways pass the raw NPCI error code inside the payment.failed webhook payload (for example, error_reason or npci_error_code). Treating every failed UPI callback identically hurts checkout conversion rates. If your backend distinguishes between transient switch timeouts (U30, U28, BT) and velocity blocks (U16, Z8), your checkout UI can automatically prompt the user with the right fallback.
According to official NPCI H2H API specifications published by Axis Bank and HDFC SmartGateway, never re-initiate a failed debit using the exact same Customer Reference Number (CRN) / merchantTransactionId; always generate a fresh unique transaction reference for any retry attempt.
{
"U30": {
"npciDescription": "Debit has been failed",
"origin": "Remitter Bank CBS",
"moneyDeducted": "Rarely (Auto-reversed within T+1 if debited)",
"retryStrategy": "RETRY_IMMEDIATE_NEW_TXN_ID",
"uiMessage": "Your bank server timed out while processing the debit. Please retry or use another bank account."
},
"U16": {
"npciDescription": "Risk threshold exceeded",
"origin": "NPCI / Issuing Bank Fraud Engine",
"moneyDeducted": "No",
"retryStrategy": "FALLBACK_TO_CARD_OR_NETBANKING",
"uiMessage": "UPI daily limit or 24-hour new device cooling limit reached. Please pay via Card, NetBanking, or a different UPI ID."
},
"U28": {
"npciDescription": "PSP not available",
"origin": "Payment Service Provider Switch",
"moneyDeducted": "No",
"retryStrategy": "SWITCH_UPI_INTENT_APP",
"uiMessage": "Your UPI app handle is temporarily unreachable. Try scanning the dynamic QR with another UPI app."
},
"Z9": {
"npciDescription": "Insufficient funds in customer (remitter) account",
"origin": "Customer Bank Account",
"moneyDeducted": "No",
"retryStrategy": "PROMPT_ALTERNATE_ACCOUNT",
"uiMessage": "Transaction declined due to insufficient balance in the selected bank account."
},
"BT": {
"npciDescription": "Acquirer/Beneficiary bank switch timeout ( Deemed Approved / Pending )",
"origin": "Issuing/Acquiring Switch",
"moneyDeducted": "Possible",
"retryStrategy": "POLL_STATUS_BEFORE_RETRY",
"uiMessage": "Bank confirmation is delayed. We are verifying your payment status automatically."
}
}2. Production Node.js Webhook Classifier & Reconciliation Handler
When building SaaS billing systems in India (such as automated container provisioning on Vexlo Cloud), handling deemed or timed-out UPI transactions (codes BT, RB, or U09) requires careful state management. If a user's bank account is debited during a CBS timeout, the gateway may initially emit a pending status before resolving via an asynchronous reconciliation webhook 5 to 15 minutes later.
Implement an idempotent webhook processor in TypeScript/Node.js that classifies NPCI error codes and triggers an automated status inquiry poll before marking an order as permanently failed.
export type UpiRetryAction =
| 'RETRY_SAME_VPA_NEW_ORDER'
| 'SWITCH_VPA_OR_PAYMENT_METHOD'
| 'POLL_RECONCILIATION_QUEUE'
| 'USER_INPUT_ERROR';
export interface UpiErrorDecision {
code: string;
retryable: boolean;
action: UpiRetryAction;
userFacingNotice: string;
}
const TRANSIENT_BANK_CODES = new Set(['U30', 'U28', 'U09', 'XY', 'XM']);
const VELOCITY_LIMIT_CODES = new Set(['U16', 'Z8', 'U66']);
const DEEMED_PENDING_CODES = new Set(['BT', 'RB', 'U31']);
export function classifyNpciErrorCode(rawCode: string): UpiErrorDecision {
const code = (rawCode || '').trim().toUpperCase();
if (TRANSIENT_BANK_CODES.has(code)) {
return {
code,
retryable: true,
action: 'RETRY_SAME_VPA_NEW_ORDER',
userFacingNotice:
'Your bank CBS experienced a temporary timeout (NPCI ' + code + '). Please tap Retry to generate a fresh UPI intent.',
};
}
if (VELOCITY_LIMIT_CODES.has(code)) {
return {
code,
retryable: false,
action: 'SWITCH_VPA_OR_PAYMENT_METHOD',
userFacingNotice:
'Bank UPI risk or daily velocity limit reached (NPCI ' + code + '). Please use another bank VPA or RuPay/Card.',
};
}
if (DEEMED_PENDING_CODES.has(code)) {
return {
code,
retryable: false,
action: 'POLL_RECONCILIATION_QUEUE',
userFacingNotice:
'Payment confirmation is pending from your bank switch. Do not pay twice; we will update your order within 5 minutes.',
};
}
return {
code: code || 'UNKNOWN',
retryable: true,
action: 'USER_INPUT_ERROR',
userFacingNotice:
'UPI payment could not be completed (Code: ' + (code || 'Declined') + '). Verify your UPI PIN and account balance.',
};
}3. Handling Late-Authorized UPI Webhooks Without Double Provisioning
If a customer experiences a U30 or BT timeout on their first attempt and immediately completes a second UPI payment using a different bank account, the first transaction can occasionally settle late as 'Deemed Approved' if the remitter bank CBS recovers. Always enforce a unique database constraint on the gateway's provider_payment_id (UTR / RRN) and automatically trigger an instant refund via the gateway Refund API if a second payment arrives for an already-fulfilled order.
-- PostgreSQL schema preventing double-provisioning on late UPI webhook callbacks
CREATE TABLE IF NOT EXISTS payment_settlements (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
order_id VARCHAR(64) NOT NULL,
upi_rrn VARCHAR(32) NOT NULL UNIQUE, -- 12-digit NPCI Retrieval Reference Number
npci_response_code VARCHAR(12) NOT NULL,
amount_paise BIGINT NOT NULL,
status VARCHAR(24) NOT NULL CHECK (status IN ('CAPTURED', 'FAILED', 'REFUNDED_DUPLICATE')),
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_payment_settlements_order_id ON payment_settlements(order_id);Pre-Deployment Verification Checklist
- Never reuse an existing merchantTransactionId / Order ID when retrying a U30 or U28 failed UPI transaction.
- Detect U16 (Risk Threshold Exceeded) in your frontend and immediately suggest an alternate UPI ID or RuPay card instead of looping UPI retries.
- Store the 12-digit NPCI RRN (Retrieval Reference Number) with a UNIQUE constraint to prevent duplicate webhook fulfillment.
- Implement a 15-minute background status polling job for transactions returning BT or pending switch codes.
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
What does UPI Error Code U30 mean and is money deducted?
UPI Error Code U30 means 'Debit has been failed' at the customer's remitter bank Core Banking System (CBS). In almost all cases, money is not deducted. If an account debit did occur during a switch drop, NPCI's online dispute resolution (ODR) and T+1 auto-reversal automatically refund the customer.
How do I fix UPI Error Code U16 (Risk Threshold Exceeded)?
Error U16 is enforced by NPCI and the issuing bank's fraud engine when a customer hits their 24-hour transaction count limit, exceeds ₹1,00,000 in 24 hours, or attempts transfers above ₹5,000 within 24 hours of changing their SIM/phone. The customer must use a different bank account on UPI or pay via Debit/Credit card.
Why do I receive UPI Error Code Z9 in Razorpay or Cashfree webhooks?
Code Z9 is the official NPCI response code for 'Insufficient funds in customer (remitter) account'. Prompt the user to check their balance or switch to another linked bank account in their UPI app.