UPI Switch Infrastructure: How to Build It

How to use this page

This page walks you through building on UPI: an app that pays, a checkout that collects, or the switch underneath either. Not how UPI works for a user — how you connect to it, get certified, stay up, and settle.

Ten guides on this site describe a rulebook written by a regulator. This one describes a rulebook written by a company. NPCI is not a regulator. It is a not-for-profit umbrella organisation operating an RBI-authorised payment system — and its circulars will constrain your product more tightly, day to day, than most regulations do.

What you are actually building

Four different products get called “building on UPI” and they have almost nothing in common except the rails:

Who is who on the rails:

What this is not:

• Not a licence you can hold. Participation is approved by NPCI and sponsored by a bank. You are always on somebody’s paper.
• Not a feature race. The product is uptime and decline rate. Step 8.
• Not free forever. It was, until this week.

The whole journey, in one table

Steps 1 to 3 — shape, bank, certification

Step 1 — Pick the shape

The question that settles it: do you need to hold the customer’s UPI handle? If you do, you are a TPAP and you need a PSP bank. If you only need to be paid, you need an aggregator and this page is mostly background.

Step 2 — Find a bank

This is a partnership negotiation, not an integration, and it is the step that decides your timeline. The bank is taking on your risk: NPCI holds the PSP bank responsible for auditing your app and systems, for the grievance mechanism your customers use, and for keeping all UPI transaction data in India. A bank that signs you is accepting audit findings on your code.

Two routes, and the trade is the usual one:

Step 3 — Certify with NPCI

NPCI approves participation. Certification covers the technical implementation and the compliance posture, and the specification moves — the common library, the PIN handling, the API versions and the dispute hooks all get revised, and revisions come with dates.

Steps 4 and 5 — the payment path and the deemed state

Steps 4 and 5 — The payment path, and the deemed state

from datetime import datetime, timedelta

# STEP 4. FOUR FLOWS, ONE RULEBOOK.
FLOWS = {
    "intent":  "customer taps, app opens, customer approves",     # best success
    "collect": "you request, customer approves later",            # worst success
    "qr":      "customer scans and pays",                         # merchant default
    "mandate": "recurring, pre-authorised",                       # see Guide 05
}

# Collect requests are the flow most abused and the flow with the worst
# conversion. Treat a high collect share as a product smell, not a feature.

# STEP 5. THE DEEMED STATE. THIS IS THE ONE.
# A UPI transaction that does not return a clean result is NOT a failure. It
# is an UNKNOWN. The debit may have happened. The credit may have happened.
# Your system knows neither, and the customer is looking at your screen.

TERMINAL = {"SUCCESS", "FAILURE"}

def on_response(txn, response):
    if response and response["result"] in TERMINAL:
        return {"state": response["result"], "final": True}
    # Deemed. Do not guess. Do not retry with a new reference.
    return {"state": "DEEMED", "final": False,
            "action": "poll_status",
            "customer_message": "We are confirming this payment",   # not "Failed"
            "never": "initiate_a_second_debit"}

def poll_plan(txn):
    """Back off. A thundering herd of status checks is how an incident
    becomes an outage -- yours and everyone else's on the same switch."""
    return [5, 15, 30, 60, 120, 300]        # seconds, then hand to reconciliation

def resolve(txn, npci_status, ledger):
    # NPCI reconciles and the outcome is guaranteed to settle one way or the
    # other. Your job is to make sure YOUR ledger ends up agreeing with it,
    # and to never have told the customer something the ledger contradicts.
    assert txn["reference"] == npci_status["reference"], "same intent, same reference"
    ledger.apply(npci_status["final_state"])
    return npci_status["final_state"]

# WHAT TO CHECK
# [ ] "deemed" is a first-class state in your schema, with its own screen,
#     its own message and its own queue. Not a null, not a failure
# [ ] a retry uses the SAME reference derived from the intent, stored BEFORE
#     the call. A fresh reference on an unknown outcome is how a customer
#     gets debited twice -- the same rule as payouts in Build Sheet 05
# [ ] status polling backs off. Fixed-interval polling during a switch
#     incident is load you are adding to an outage
# [ ] never show "Payment failed" on a deemed transaction. The money may be
#     gone, and you have just told someone it is not
# [ ] every state change is idempotent and keyed on the event id, applied in
#     the same database transaction as the ledger write
# [ ] reconcile in IST against NPCI settlement cut-offs, not against your own
#     calendar day

The gotcha that produces the worst customer outcomes on this rail: a pending UPI transaction is an unknown, not a failure, and the two demand opposite behaviour. On a failure you retry. On an unknown you must not, because the debit may already have happened.

The ecosystem resolves this for you eventually — NPCI reconciles, and a failed debit is auto-reversed under the RBI turnaround-time framework with a per-day penalty for delay. What the framework does not do is tell your customer what is happening in the ninety seconds they are staring at your screen. That copy is yours to write, and writing “Payment failed” on a deemed transaction is the single most damaging string in a UPI product.

Steps 6 to 8 — disputes, settlement, running it

Steps 6 to 8 — Disputes, settlement, and running it

# STEP 6. DISPUTES GO THROUGH UDIR, NOT THROUGH YOUR SUPPORT INBOX.
# Unified Dispute and Issue Resolution is the ecosystem's protocol. If you
# are a partner application on a sponsor bank's SDK, integrating UDIR is a
# requirement, not an option -- your customers' eligible complaints have to
# be raised into it.

def raise_dispute(txn, reason, udir):
    case = udir.open(reference=txn["reference"], reason=reason,
                     raised_at=now_ist())
    return {"case_id": case["id"], "track_in": "UDIR",
            "your_job": "keep the customer informed while it runs"}

# STEP 7. SETTLEMENT. The cut-offs are NPCI's, not yours.
def settlement_day(txn_time_ist, cutoffs):
    """A transaction after the cut-off settles in the next cycle. Aggregating
    on a UTC day boundary moves 5.5 hours of transactions into the wrong
    settlement day, every single day."""
    return cutoffs.cycle_for(txn_time_ist)

# STEP 8. WHAT YOU ARE ACTUALLY MEASURED ON.
# Declines split two ways and only one of them is your problem -- but the
# ecosystem measures BOTH against you, and the split is the whole
# conversation with your bank and with NPCI.

def classify_decline(code_, who):
    TECHNICAL = {"switch_timeout", "psp_unavailable", "issuer_down",
                 "beneficiary_unreachable"}          # infrastructure
    BUSINESS  = {"insufficient_funds", "wrong_pin", "limit_exceeded",
                 "account_blocked"}                  # the customer or their bank
    if code_ in TECHNICAL:
        return {"type": "TD", "owner": who, "counts_against_you": True}
    if code_ in BUSINESS:
        return {"type": "BD", "owner": "customer", "counts_against_you": False}
    return {"type": "UNCLASSIFIED", "action": "map_it_before_it_ships"}

def health(window):
    return {
        "td_rate": technical_declines(window) / total(window),
        "td_by_issuer": td_split(window, "issuer"),      # not your fault, your problem
        "success_by_flow": success_split(window, "flow"),
        "deemed_rate": deemed(window) / total(window),
        "deemed_unresolved_over_1h": aging_deemed(window),
        "market_share_rolling_3m": share_rolling(window, months=3),  # the 30% cap
    }

# WHAT TO CHECK
# [ ] every decline code is MAPPED to technical or business before launch.
#     An unclassified bucket is where your real TD rate hides
# [ ] plot TD by issuer bank. You cannot fix another bank's infrastructure,
#     but you can route around it, warn the customer, and take it to your PSP
# [ ] track market share on a ROLLING THREE-MONTH basis if you are anywhere
#     near scale. That is how the cap is computed
# [ ] the deemed queue has an owner and an age, like the EDPMS queue in
#     Guide 06. Unresolved deemed transactions are a support backlog that
#     arrives all at once
# [ ] build the per-rail, per-ticket-size fee engine NOW. The threshold is
#     fixed at 2,000 rupees. The rate is not yours to choose or to schedule

THE finding, and it is the reason this page exists: your technical decline rate is not a metric, it is the condition of your participation. UPI publishes bank-level performance, NPCI can audit participants, and a switch that declines transactions for infrastructure reasons is a problem the ecosystem addresses rather than tolerates. Feature roadmaps do not survive that conversation; decline rates do.

And the part that makes it hard: a large share of your declines will not be your fault. An issuer bank you have no relationship with, on infrastructure you cannot see, will fail your customers’ payments and the customer will blame your app. You cannot fix it. You can measure it per issuer, route around it where a second option exists, tell the customer something truthful about why, and take the data to your PSP bank — which is the only party with standing to escalate it. Teams that do not split declines by issuer spend years believing their own switch is worse than it is.

The 30% cap, still scheduled

NPCI proposed in November 2020 that no single third-party application provider should process more than 30% of UPI transaction volume, measured over the preceding three months on a rolling basis, with breach met by a halt on onboarding new customers rather than by blocking transactions. Bank-owned UPI apps are outside it.

The deadline has moved three times — 2022, then 31 December 2024, then 31 December 2026, which is where it stands. Two apps have been well above the cap throughout, at roughly three-quarters of monthly volume between them.

What it costs

Three versions you could build

Accept UPI

Build: an aggregator integration, webhook signature verification over raw bytes, a settlement-file reconciliation, and a fee engine that can price per rail and per ticket size.

You get: UPI acceptance in days. You are a customer of this ecosystem, and Build Sheet 05 is the page you want.

Ship a UPI app on a sponsor bank

Build: sponsor bank agreement → SDK integration → UDIR → deemed-state handling with its own screen and queue → decline mapping before launch → data resident in India → a grievance route that reaches the PSP bank’s mechanism.

Trade: speed against a ceiling. You inherit the enabler’s roadmap and their certification, and you own the customer who is looking at a spinner.

Build the switch

Build: the whole transaction path, certified with NPCI, sized for peak, with per-issuer decline telemetry, rolling three-month share measurement, an idempotent ledger keyed on intent, and a fee engine waiting for a rate.

It breaks when: the team optimises for the happy path. Success rate on a good day is not the product. Behaviour during an issuer outage is, and it is the only thing that is visible to NPCI, to your bank and to your customers simultaneously.

What goes wrong

Where to go next

Sources

Every figure, rule and date on this page, and where to check it. Entries are typed so you can see which are primary-sourced and which are industry reporting.