NPCI rails
Payment rails where the edge cases are the whole job
The happy path on UPI is a week's work. The remaining months are mandates, reversals, reconciliation and the states a payment can be in when nobody has told you yet.
The short answer
Integrate with NPCI rails through a sponsor bank or a licensed PSP rather than directly — direct membership is available only to regulated entities. Budget the effort around reconciliation and dispute handling rather than the payment call itself: settlement is asynchronous, and the system of record has to survive that.
Interfaces
How it actually exposes data.
The interfaces, the pitfalls, and how we handle each.
UPI via a PSP or sponsor bank
Collect requests, intent flows, and increasingly autopay mandates. The API surface is small; the state machine behind it is not, and that asymmetry is what estimates get wrong.
NACH mandates
e-NACH with Aadhaar or net-banking authentication, plus the physical fallback that still exists. Mandate lifecycle — registration, amendment, cancellation, rejection — is where recurring-collection products actually live or die.
IMPS and account validation
Immediate transfers, and penny-drop verification before payouts. Both are straightforward calls whose failure modes are anything but.
Settlement and reconciliation files
The daily files are the authoritative record, not your API responses. Any design that treats the synchronous response as the truth will disagree with the bank eventually, and the bank will be right.
What goes wrong
The failures that are not in the documentation.
Every one of these has cost somebody a release. They are the reason the design below looks the way it does.
Treating the API response as the outcome
A timeout is not a failure, and a success response is not settlement. Payments that are actually complete get retried, and payments that failed get treated as done. Reconciliation against the settlement file is the only correct source of truth.
No idempotency on retries
Networks retry, users tap twice, and queues redeliver. Without an idempotency key that survives a restart, duplicate collections reach real customers — and refunding them costs far more than trust.
Under-building mandate lifecycle
Most recurring-payment projects budget for creating a mandate and not for amendment, expiry, insufficient funds, and customer-initiated cancellation at the bank. Those are the majority of support load in year one.
Reconciliation as an afterthought
If it is not designed in from the start, someone ends up matching spreadsheets every morning — which is the failure mode this entire category of software exists to prevent.
Method
What we build in front of it.
- 01
Model the payment states before writing an integration
Every state a payment can occupy, including the ones you learn about hours later. This model is the product; the API calls are an implementation detail of it.
- 02
Build the ledger first
An internal double-entry record that does not depend on the rail. It is what reconciliation compares against and what survives you changing PSP.
- 03
Automate reconciliation from day one
Settlement files ingested and matched automatically, with a clear exception queue. The exception queue is the deliverable — the goal is not zero mismatches, it is that every mismatch is visible and assigned.
- 04
Instrument disputes and refunds as first-class flows
Not admin screens bolted on later. These are the flows regulators and customers both judge you on.
Questions
What people ask before starting.
Next step
Need to connect to NPCI rails?
Bring the constraint everyone has been working around. Forty-five minutes with an engineer who has done this before is usually enough to tell you whether it is a week or a quarter.
- No sales deck
- An engineer on the call, not an account manager
- NDA before you share anything