How the payment ecosystem works
A. UPI architecture
The main participants are:
| Participant | Responsibility |
|---|---|
| Customer | Initiates payment |
| Your application (TPAP) | Provides the UPI user interface |
| PSP Bank | Provides the UPI banking connection and responsibilities |
| NPCI | Operates the UPI network |
| Remitter bank | Customer's bank |
| Beneficiary bank | Merchant's bank |
For example:
A customer scans your merchant's QR code and pays ₹500.
- Your application creates the payment request through its authorised UPI integration.
- The customer authenticates the transaction using the supported UPI authentication method.
- The PSP bank and NPCI network participate in processing.
- The relevant banks process the debit and credit.
- Your application receives the transaction result through the approved integration.
- Your platform updates the transaction status and displays confirmation.
Important: You cannot independently connect a newly built app to the UPI network just by developing a UPI API. You need the appropriate NPCI/PSP bank onboarding and approvals.
B. Payment gateway architecture
Imagine an online shopping merchant integrates your payment gateway.
Customer
Purchases a product worth ₹2,000
Merchant Website / App
Your Payment Gateway
API · Authentication · Routing · Transaction management
Acquiring Bank / Authorised Payment Partner
Payment Network / Issuer Bank
Transaction Result
Success / Failed / Pending → Merchant callback
C. Other external integrations you will need
A super app cannot independently provide every service. It connects to specialised providers.
Think of your application as the central platform and the external providers as service engines.
| Service | External ecosystem / integration |
|---|---|
| UPI | NPCI through a PSP bank |
| Payment gateway | Acquiring banks / authorised payment partners |
| Bill payments | BBPS through an eligible operating unit |
| Mobile recharge | Recharge aggregators / telecom partners |
| FASTag | Relevant issuer banks and authorised partners |
| Flights | Airline / travel API providers |
| Hotels | Hotel distribution providers |
| Bus booking | Bus inventory aggregators |
| Insurance | Licensed insurers / authorised intermediaries |
| Mutual funds | Appropriate SEBI-regulated entities |
| Lending | RBI-regulated lending partners |
| Shopping | Sellers, distributors and logistics providers |
| Maps and location | Mapping API providers |
| SMS and OTP | SMS / authentication providers |
D. Backend architecture
Let's understand the responsibilities of the important backend services.
| Backend service | What it handles |
|---|---|
| Identity Service | Users, login, OTP, devices, sessions |
| User Service | Customer profiles and preferences |
| Merchant Service | Merchant onboarding, KYC, business details |
| Payment Service | Payment initiation and orchestration |
| UPI Integration | PSP bank integration |
| Transaction Service | Transaction lifecycle and status |
| Ledger Service | Financial debit and credit entries |
| Wallet Service | Regulated wallet operations, if applicable |
| Recharge Service | Recharge requests and provider responses |
| Bill Payment Service | Bill fetching and payment |
| Commerce Service | Products, cart, orders and sellers |
| Travel Service | Bookings, cancellation and ticketing |
| Reward Service | Cashback and reward points |
| Notification Service | SMS, email, push notifications |
| Settlement Service | Merchant payouts and settlement tracking |
| Reconciliation Service | Internal versus provider/bank records |
| Risk Service | Fraud monitoring and transaction limits |
| Support Service | Complaints, refunds and disputes |
Regulatory and compliance requirements in India
This is something you should investigate before starting payment development.
A PhonePe-like platform operates across several regulated business areas. You cannot assume that one company registration or one payment gateway agreement authorises every service.
Here are the major areas.
| Area | Important framework / authority |
|---|---|
| UPI | NPCI rules and PSP bank requirements |
| Payment Aggregation | RBI Payment Aggregator Directions |
| Wallet / PPI | RBI PPI Directions |
| Bill Payments | RBI BBPS Directions and NBBL requirements |
| Insurance distribution | IRDAI licensing and applicable rules |
| Lending | RBI digital lending framework and regulated lender requirements |
| Investments | SEBI regulations and appropriate registrations |
| Customer data | Digital Personal Data Protection framework |
| Cybersecurity | Applicable RBI, NPCI, CERT-In and other security requirements |
| Card payments | PCI DSS and relevant card-network rules |
Important regulatory distinctions
- UPI
You need to work through an approved PSP bank and comply with NPCI requirements to participate as a TPAP.
- Payment Aggregator
RBI distinguishes a Payment Aggregator from a Payment Gateway:
- A PA facilitates collection of payments and settlement to merchants.
- A PG provides technology infrastructure to route payments without handling funds. RBI issued its consolidated Payment Aggregator Directions on September 15, 2025. The framework covers authorisation, capital requirements, governance, security, merchant due diligence, disputes and escrow accounts. The latest RBI page also shows an update dated November 11, 2026. Reserve Bank of India+1
- BBPS
Bill payment services have their own regulated ecosystem. The RBI's 2024 directions define the roles of NBBL, BBPOUs, customer operating units, biller operating units and technology service providers. Reserve Bank of India
- Wallet
If you want to issue your own stored-value wallet, you need to assess the applicable RBI PPI authorisation and requirements. Alternatively, integrate with an authorised PPI issuer.
- Financial products
Do not independently start selling or issuing insurance, providing loans or offering investment products without the appropriate regulated structure. Work with authorised partners and obtain specialist legal and compliance advice.
Security architecture
For a financial super app, security is not an optional feature. It must be part of the system architecture from day one.
I would divide it into these areas.
| Security component | Responsibility |
|---|---|
| Authentication | OTP, device binding and secure login |
| Authorisation | RBAC and permission-based access |
| Transaction authentication | UPI PIN through approved bank/UPI flows |
| Encryption | Data encryption in transit and at rest |
| API security | OAuth, signed requests, rate limiting |
| Fraud detection | Suspicious transactions and behaviour |
| Device security | Root detection, app integrity and device risk |
| Session management | Token expiry and session revocation |
| Audit logging | Record sensitive administrative actions |
| Data protection | Consent, retention and access controls |
| Monitoring | Real-time security and operational alerts |
Fraud prevention examples
Your platform should be able to detect:
- Multiple transactions within a short period.
- Unusual transaction amounts.
- Suspicious device changes.
- Repeated failed authentication.
- Unusual account activity.
- Merchant transaction anomalies.
- Potential account takeover.
- Duplicate payment requests.
You should also build a dispute management system.
For example:
Customer says:
"My ₹2,000 payment was deducted, but the merchant did not receive it."
Your system should:
- Find the original transaction.
- Check the bank/provider transaction status.
- Verify the settlement or credit status.
- Identify whether it is pending, successful or failed.
- Create a complaint reference.
- Track the resolution.
- Notify the customer.
A customer-facing transaction status should never be marked successful simply because your API returned HTTP 200.
Research documents and resources
These are the resources I would use as the starting point for your product and architecture research.
PhonePe official website
Study the product categories, consumer experience, merchant offerings and financial services.
PhonePe investor prospectus
Study the business model, revenue sources, business segments and risk disclosures.
RBI Payment Aggregator Directions
Understand PA authorisation, merchant due diligence, escrow, security and settlement.
RBI BBPS Directions
Understand the bill payment ecosystem and operating units.
NPCI / UPI participant responsibilities
Understand the relationship between NPCI, PSP banks and TPAP applications.
Read UPI roles and responsibilities
Public APIs and developer sandboxes:
UPI, bill payment and recharge APIs:
1. Setu:
One of the best options for your project
- Website: https://setu.co
- Developer documentation: https://docs.setu.co
- Sandbox: Available through its developer platform.
Setu is particularly relevant because it provides APIs for India's financial infrastructure.
Available API categories:
| API category | What you can access |
|---|---|
| UPI | QR, payment requests, mandates and payment status |
| BBPS BillPay | Biller information, bill fetching and payments |
| Prepaid Recharge | Mobile recharge workflows |
| Account Aggregator | Consent and financial information retrieval |
| KYC | PAN, Aadhaar-related and identity workflows |
| Bank Verification | Bank account verification |
| eSign | Digital signature workflows |
| Reports | Transaction and settlement reports |
What can you build?
- Electricity bill payment.
- Water bill payment.
- Gas bill payment.
- Broadband bill payment.
- FASTag recharge.
- Mobile recharge.
- UPI payment flow.
- Bill fetching and validation.
- Transaction status tracking.
Official links:
- Setu BillPay documentation: https://docs.setu.co/payments/billpay
- Setu Payments documentation: https://docs.setu.co/payments
- Setu Identity documentation: https://docs.setu.co/identity
2. Kotak Mahindra Bank
- Website: https://www.kotak.bank.in
- API information: https://www.kotak.bank.in/en/open-banking/bbps-apis.html
Its BBPS sandbox exposes useful bill-payment workflows:
| API | Data returned / functionality |
|---|---|
| Biller MDM | Biller IDs, names and details |
| Bill Fetch | Customer bill information |
| Bill Validation | Subscriber information validation |
| Bill Payment | Bill payment processing |
| Bill Transaction | Previous transaction status |
| Complaint Registration | Register bill-payment complaints |
| Complaint Status | Track complaint status |
Loans Related:
1. ICICI Bank API Banking:
- Developer portal: https://developer.icicibank.com
Available API categories include:
- Building Blocks.
- Banking.
- Cards and Loans.
- Auto Loan.
- Cash Management.
- Banking Offers.
- Payment Gateway integration.
It provides a sandbox-to-UAT-to-production onboarding journey. Production access is subject to business approval and agreements
E-commerce and product marketplace APIs:
- xcommerce http://xcommerce.uniphi.digital/
Movies, entertainment and ticket booking APIs
- ETX - Event Booking & Tickets: https://qa.paypoint.com.na/event/
Flight, hotel and travel booking APIs
1. Amadeus for Developers:
- Developer portal: https://developers.amadeus.com
- Documentation: https://amadeus4dev.github.io/developer-guides
- Test data: https://amadeus4dev.github.io/developer-guides/test-data
It offers a free limited test environment for developers.
Available APIs and data:
| API | Data |
|---|---|
| Flight Offers Search | Flight options, airlines, prices |
| Flight Offers Price | Confirmed offer pricing |
| Flight Create Orders | Flight booking creation |
| Airport & City Search | Airport and city information |
| Flight Inspiration | Suggested destinations |
| Flight Price Analysis | Flight price insights |
| Hotel List | Hotel information |
| Hotel Search | Hotel availability and offers |
| Hotel Booking | Hotel reservation workflows |
| Hotel Ratings | Hotel ratings |
| Tours and Activities | Travel experiences |
You can build:
- Flight search.
- Departure and arrival selection.
- Airline selection.
- Flight details.
- Price comparison.
- Passenger details.
- Booking confirmation.
- Hotel search.
- Hotel details.
- Travel experiences.
2. Duffel:
- Website: https://duffel.com
- Documentation: https://duffel.com/docs/api/overview/test-mode
You can explore:
- Flight offers.
- Airline information.
- Passenger details.
- Seat and service information where supported.
- Order creation.
- Booking management.
- Cancellation-related workflows where supported.
The test environment uses separate test access tokens and does not spend real money or create real bookings.
Stocks, market data and investment APIs
1. Alpha Vantage
- Website: https://www.alphavantage.co/
- Documentation: https://www.alphavantage.co/documentation
Available APIs:
| API | Data |
|---|---|
| Daily Time Series | Daily stock prices |
| Intraday Time Series | Intraday stock data |
| Weekly Time Series | Weekly stock data |
| Monthly Time Series | Monthly stock data |
| Global Quote | Stock quote |
| Symbol Search | Company and stock symbol search |
| Company Overview | Company fundamentals |
| Income Statement | Revenue and expenses |
| Balance Sheet | Assets and liabilities |
| Cash Flow | Cash flow data |
| Technical Indicators | RSI, SMA, EMA and others |
| News & Sentiment | Financial news and sentiment |
| Forex | Currency exchange data |
| Crypto | Cryptocurrency data |
Stock data generally includes:
- Open price.
- High price.
- Low price.
- Close price.
- Volume.
- Historical prices.
- Symbol.
- Company information. You can also query supported Indian stock symbols, such as BSE-listed instruments.
The documentation provides demo examples and free API key registration. However, intraday and realtime entitlements are restricted by plan, and commercial data usage has additional licensing considerations.
2. Upstox:
- Developer portal: https://upstox.com/developer/api-documentation/
- Sandbox: https://upstox.com/developer/api-documentation/sandbox
Available functionality:
| API | What it provides |
|---|---|
| Market Quotes | Stock market quotes |
| Historical Data | Historical candle data |
| WebSocket | Live market streaming |
| Instruments | Instrument information |
| Portfolio | Holdings and positions |
| Funds | Available funds |
| Orders | Order management |
| Option Chain | Options information |
| News | Market-related news where supported |
The Upstox sandbox allows developers to test supported API workflows without placing actual live-market orders.
Insurance APIs:
1. Insurex24:
- Documentation: https://insurex24.com/docs.html
Available endpoints described in its documentation:
| Feature | What you can test |
|---|---|
| KYC | Customer identity verification workflow |
| Quotes | Insurance quote generation |
| Policies | Policy issuance workflow |
| Claims | Claim-related workflows |
| OCR | Document extraction |
| Renewals | Policy renewal |
| Notifications | Notification events |
| Webhooks | Asynchronous status updates |
The documentation provides a sample test credential and an end-to-end KYC → Quote → Policy → Webhook example.
2*.* HDFC ERGO:
- Website: https://www.hdfcergo.com/
- Developer portal: https://apifactory.hdfcergo.com/
- API catalogue: https://apifactory.hdfcergo.com/api-overview
Its portal identifies these API categories:
| API category | What you can build |
|---|---|
| Motor | Motor insurance quote and customisation workflows |
| Health | Health insurance product workflows |
| Health Claims | Health claim service integrations |
| Identity | Identity-related services |
| Mobile | Mobile-related data append |
| Geo / Location | Location-related data |
| Notifications | Policy-related notifications |
You can use the portal to register, explore documentation and request access to its APIs. The actual API specifications and credentials depend on approved access.
Cryptocurrency:
1. CoinGecko
- Website: https://www.coingecko.com/
- Documentation: https://docs.coingecko.com/
- Free API: https://support.coingecko.com/articles/9471335603-user-guide-how-to-sign-up-for-coingecko-demo-api-and-generate-an-api-key
Available data:
- Cryptocurrency prices.
- Market capitalisation.
- Trading volume.
- Historical prices.
- Price changes.
- Market rankings.
- Coin information.
- Exchange information.
- Trending cryptocurrencies.
The Demo API requires a free account and API key.
Food and grocery product information:
Open Food Facts
- Website: https://world.openfoodfacts.org/
- API documentation: https://openfoodfacts.github.io/openfoodfacts-server/api/
Available data:
- Product name.
- Barcode.
- Brand.
- Ingredients.
- Nutrition values.
- Product categories.
- Packaging.
- Product images.
You can build:
- Grocery product discovery.
- Barcode scanning.
- Product details.
- Nutritional information.
- Food category listings.
It is a product-information database, not a grocery ordering and delivery API.
API directories where you can discover hundreds more APIs
Apart from individual providers, there are websites that maintain collections of APIs.
Public API Lists:
Best for discovering free APIs
https://github.com/public-api-lists/public-api-listsA community-maintained collection of more than 730 APIs across 48 categories, including finance, shopping, cryptocurrency, weather, maps, news and more.
APIs.guru:
https://github.com/APIs-guru/openapi-directory
A directory of API specifications in OpenAPI and Swagger formats. Useful for finding API schemas and importing them into Postman or other API tools.
RapidAPI:
https://rapidapi.com/
A marketplace where developers discover APIs from different providers. Categories include finance, travel, entertainment, weather, sports and e-commerce.
Check the individual API provider's ownership, pricing, usage limits and data rights.
Postman Public API Network:
https://www.postman.com/explore
Discover API collections, documentation, example requests, environments and ready-made integration examples.
API Setu:
https://directory.apisetu.gov.in/
Particularly useful for India-specific government, banking, identity and insurance-related APIs.
About the author
- Passionate about programming, I see its impact everywhere in the modern world. I believe that I will be a great addition to the team and organization. Making a positive impact through hands-on experience and continuous learning.
Comments
Join the discussionNo comments yet. Be the first to comment.


