Skip to main content

How the payment ecosystem works

Updated 14 min readMarkdown

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.

  1. Your application creates the payment request through its authorised UPI integration.
  2. The customer authenticates the transaction using the supported UPI authentication method.
  3. The PSP bank and NPCI network participate in processing.
  4. The relevant banks process the debit and credit.
  5. Your application receives the transaction result through the approved integration.
  6. 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

  1. UPI

You need to work through an approved PSP bank and comply with NPCI requirements to participate as a TPAP.

  1. 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
  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

  1. 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.

  1. 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:

  1. Find the original transaction.
  2. Check the bank/provider transaction status.
  3. Verify the settlement or credit status.
  4. Identify whether it is pending, successful or failed.
  5. Create a complaint reference.
  6. Track the resolution.
  7. 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.

Explore PhonePe

PhonePe investor prospectus

Study the business model, revenue sources, business segments and risk disclosures.

Read PhonePe's UDRHP-I

RBI Payment Aggregator Directions

Understand PA authorisation, merchant due diligence, escrow, security and settlement.

Read RBI's directions

RBI BBPS Directions

Understand the bill payment ecosystem and operating units.

Read BBPS regulations

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

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:

2. Kotak Mahindra Bank

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

1. ICICI Bank API Banking:

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:

Movies, entertainment and ticket booking APIs

Flight, hotel and travel booking APIs

1. Amadeus for Developers:

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:

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

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:

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:

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:

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

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

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.

  1. Public API Lists:
    Best for discovering free APIs
    https://github.com/public-api-lists/public-api-lists

    A community-maintained collection of more than 730 APIs across 48 categories, including finance, shopping, cryptocurrency, weather, maps, news and more.

  2. 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.

  3. 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.

  1. Postman Public API Network:

    https://www.postman.com/explore

    Discover API collections, documentation, example requests, environments and ready-made integration examples.

  2. 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.

No comments yet. Be the first to comment.

How the payment ecosystem works