UPI in depth: integration and operations. 6 chapters and a final quiz.

Chapter 1. Intent, collect, QR: measuring the loss instead of guessing at it.

The final status of a UPI transaction is spread across three separate fields, set by three different parties. The first carries the verdict, the second the cause as NPCI sees it, and the third the cause as the payer's bank sees it. Breaking out these three fields is the benchmark of a mature integration, more than watching the checkout flow. Merging them into a single metric produces misleading dashboards. If you store only the verdict, you can't tell a loss caused by the merchant's flow from a loss caused by a struggling bank.

Three fields, three sources

Next to each code, the NPCI specification publishes a classification: BD for a business decline and TD for a technical decline. That label determines what the merchant is allowed to try next. A business decline comes from the payer or their account, and retrying it unchanged returns the same code. A technical decline comes from an outage, so a second attempt makes sense. NPCI has given its members targets of under 1% for technical declines and under 5% for business declines.

The instrumentation that follows from this stores, for every attempt, the three status fields, the BD or TD classification, the payer's bank identifier, and the initiation mode. Without the payer's bank identifier, the merchant can't match its failures against NPCI's monthly publication. A single bank's degradation then looks like a regression in the merchant's app. Teams that manage their authorization rate in India compare their own breakdown with the market's every month.

Chapter 2. VPAs: the central mapper, validation, and number recycling.

A virtual payment address, or VPA, is a directory entry that stands in for payment details. It is not an account. NPCI's central mapper links each identifier to the app provider that holds it. That identifier can be a name@bank address, a mobile number, or a numeric ID. Directory entries change over time, so every payment starts with resolution. Treating the VPA as stable data leads to debiting the wrong person, or losing track of the customer.

Mapper codes, and what they require

1. NORMALIZE ON WRITE
   trim, lowercase, check for a single '@' separator
   'Ravi@okhdfcbank' and 'ravi@okhdfcbank' = ONE database row

2. NEVER KEY THE CUSTOMER ON THE ADDRESS
   primary key = your customer ID
   the address is a DATED ATTRIBUTE, with a history
   useful columns: value, validation date, returned name, status

3. REVALIDATE BEFORE ANY DEFERRED DEBIT
   an address validated six months ago is not a valid address
   revalidate before: refund, payout, mandate reactivation

4. DISPLAY THE NAME RETURNED BY THE BANK, NOT THE ONE ENTERED
   and require explicit confirmation from the customer

5. LOG FAILURES SEPARATELY
   resolution failed    -> the address was not found
   payment declined     -> the address exists, the debit was declined
   Mixing them makes the failure rate meaningless.

Mapping code source: NPCI, UPI Error and Response Codes v2.9,
Central Mapper section.

Chapter 3. UPI AutoPay: UMN, protocol thresholds, and execution windows.

UPI AutoPay rests on an object separate from the payment: the mandate, identified by a UMN, the unique mandate number. The mandate has its own life cycle, from creation through repeated execution, amendment, pause, and revocation to expiry. Each stage has its own codes. Reading a mandate execution the way you'd read an ordinary payment therefore ignores half the available information. Mandate codes tell you why a subscription can no longer be collected, and which flow the merchant needs to trigger.

The authentication threshold is written into the protocol

Regulation requires strong authentication on a mandate's first installment, then waives it below ₹15,000. Two response codes in the NPCI specification encode that threshold. V3 flags a missing PIN block on a transaction above ₹15,000. V4 flags the same gap on a transaction below ₹15,000 whose sequence number is 1. The rule is therefore hard-wired into the messages as well as written in regulation, and merchant integrations run into it as a decline code. A price increase that crosses the threshold produces V3 in production, inside the payment flow itself.

• A recurring mandate carries purpose code 14. The specification then requires the block-funds flag to be N, and codes Q3 and V5 reject the opposite.
• The same purpose code requires a revocable mandate, except for merchant category code 7322, where either value is accepted. Codes Q4 and V6 flag any mismatch.
• The sequence number identifies the installment within the mandate. It carries the first-execution logic and is the natural idempotency key for the scheduler.
• A mandate executes through its own pair of messages, distinct from a one-off payment. Your logs therefore need to group events by UMN, not just by transaction ID.
• A mandate's expiry date is known in advance: it's written into the mandate itself. A team that discovers VU in production missed an alert it could have set up weeks earlier.

Designing the billing calendar runs into a second constraint, separate from these time windows. The mandatory pre-debit notification puts the payer's decision before execution, not after a decline. An Indian subscription therefore runs on two clocks: notification, which belongs to the customer relationship, and execution, which belongs to the rail. The data model keeps them apart. A payer who opts out the day before and a bank that rejects the debit on the day have the same accounting effect but opposite causes. Merging them into a single metric leaves the retention team unable to tell a customer who is disengaging from a customer whose account declined the debit.

Chapter 4. Webhooks, idempotency, and polling discipline.

The UPI specification provides three outcomes for a transaction, including an intermediate state called DEEMED. It describes a transaction whose credit status is unknown and whose outcome will be resolved later. On UPI, no response within the expected time falls into this state, not into failure. Translating a timeout into “payment declined” therefore invents information the rail never provided. What follows is a debited customer, a canceled order, a refund to process, and a dispute that will come anyway.

Status polling is a regulated resource

• NPCI's circular of April 26, 2025, which sets the rules for using the status check API, puts the first call at 90 seconds after the original transaction is initiated. A later communication shortened that delay to 45–60 seconds.
• The same circular caps status checks at three calls, preferably within two hours of initiation. After that, members consult the settlement files instead of the switch.
• A defined list of codes means stop polling: receiving any of them requires treating the transaction as failed and ending the queries.
• The status check API rejects any original transaction more than 90 days old: code X09 flags a date outside the window. Past that point, the truth is in the files, not in a query.
• The Guidelines on the usage of UPI API of May 21, 2025 cap balance inquiries at 50 per app, per customer, per day, and restrict certain inventory APIs to off-peak hours. The compliance deadlines were July 31 and then August 31, 2025.

KEYS AND WHO OWNS THEM
  order_ref      -> YOU. Set when the order is written, sent in the request,
                    echoed back in every event.
  txnId / RRN    -> THE RAIL. Unknown until the transaction exists.
  UMN            -> THE RAIL. Identifies the mandate, not the installment.
  seqNum         -> THE INSTALLMENT within a mandate. The natural idempotency
                    key for a subscription scheduler.

RECEIVING AN EVENT
  1. verify the signature BEFORE reading the body
  2. uniqueness key = (order_ref, event_type, txnId)
     already seen -> return 200 and EXIT, without replaying any business effect
  3. acknowledge immediately; business processing is asynchronous
  4. apply a state transition only if it is ALLOWED
     PENDING     -> SUCCEEDED | FAILED | UNKNOWN
     UNKNOWN     -> SUCCEEDED | FAILED
     SUCCEEDED   -> (none)        <- a late event never downgrades it
     FAILED      -> SUCCEEDED     <- allowed: the rail can confirm late

STATUS POLLING (NPCI limits, circular of 2025-04-26)
  t = 90 s          first call
  then 2 more calls max, preferably within 2 hours
  stop code received -> FAILED, stop querying
  after that         -> settlement files, no more per-transaction calls
  transaction older than 90 days -> rejected (code X09)

DUPLICATES
  U01 THE REQUEST IS DUPLICATE      -> your request had already been sent
  DF / DT DUPLICATE RRN FOUND       -> RRN collision on the beneficiary side
                                       or the remitter side
  In both cases: DO NOT recreate the transaction. Query its status.

One last practice becomes unworkable in India: querying the payer's balance to anticipate a decline. The cap of 50 inquiries per app, per customer, per day makes that architecture untenable at scale, and NPCI has explicitly identified API overuse as a cause of rail outages. The merchant receives the information anyway, first through the execution event and then through the settlement file. The expected architecture therefore consumes those two inbound feeds instead of querying the rail transaction by transaction.

Chapter 5. UPI reconciliation: settlement cycles, UDIR flags, and disputes.

UPI reconciliation relies on daily settlement cycles, on the files produced at each cycle, and on a central clearing system that resolves discrepancies. The model differs from card networks, which separate authorization from capture, apply a presentment window, and send a monthly network statement. None of those three mechanisms exists on UPI. Reconciliation therefore runs at three levels, each with its own key.

Reading UDIR flags

LEVEL 1 — ORDER <-> TRANSACTION
  key:    your order reference, sent at initiation
  source: your events + the aggregator's report
  typical gap: order with no transaction (abandonment), or transaction
               with no order (double submission on the customer side)

LEVEL 2 — TRANSACTION <-> SETTLEMENT CYCLE
  key:    transaction ID and RRN
  source: files produced at each cycle
  since 2025-11-03: cycles 1-10 = authorizations,
                    cycles 11-12 = disputes (labels DC1, DC2)
  typical gap: successful transaction not settled in the expected cycle
               -> this is NOT a failure, it is a cycle shift

LEVEL 3 — SETTLEMENT <-> FUNDS IN THE BANK
  key:    the aggregator's payout reference
  source: statement for the payout account
  typical gap: net amount differs from the expected gross
               -> fees, withholdings, dispute reversals

DESIGN RULE
  Never reconcile on (amount, timestamp). On a rail that processes
  more than 20 billion transactions a month, collisions are certain,
  not just likely.

Chapter 6. NPCI decline codes and limits: the decision table.

A decision table maps every decline code to the next step. It answers three questions: where the decline came from, whether another attempt is worthwhile, and whether to notify the customer. The NPCI specification already answers the first with the BD or TD classification, which separates business declines from technical declines. The other two are up to the table itself. The operations team keeps it up to date as the specification evolves.

Limits don't all come from the same place

A UPI limit comes from one of three sources, and the decline code tells you which one applied. NPCI sets a framework by category, while the payer's bank applies its own limits, flagged by ZU, Z8, and Z7. The UPI service layer adds its own amount and net debit limits, flagged by U02 and U03. Blaming every limit on NPCI leads you to request a pointless exemption when the limit you hit belongs to the customer's bank.

• Sort your codes into three buckets: don't retry (ZA, Z9, B3, U16), retry later (U28, U78, U67), and fix before retrying (XH, U02, ZH).
• Count declines by payer bank, not just in aggregate. A single bank's degradation gets lost in an overall rate.
• Never chase a customer over a code that points to you: U77, X6, and ZN describe your acceptance setup.
• Store the raw code, never a translated label. Declines get replayed months later, and the code table changes.
• Every month, compare your BD and TD breakdown with NPCI's bank-by-bank publication: it's the only external benchmark available.

You can tell a mature UPI operation by what it does with each decline. Code by code and bank by bank, it knows what it can fix and what it has to accept. An overall failure rate lumps those two categories together, so it can't separate them. The choice of collection mode, the retry policy, and the design of the mandate calendar all follow from this table. Build it before ramping up volume, and maintain it with the same discipline as application code.