E-commerce13 min read•

How to Build UPI Payments Into a Custom E-commerce Website: Checkout Flow, Webhooks and Reconciliation

How a custom store should accept UPI through a payment gateway: server-side orders, signed webhooks, idempotency, reconciliation, refunds and a test plan.

#UPI integration#custom ecommerce website#payment webhooks

How to Build UPI Payments Into a Custom E-commerce Website: Checkout Flow, Webhooks and Reconciliation

To accept UPI on a custom e-commerce website you do not integrate with UPI directly. You integrate with a payment gateway (a payment aggregator or payment service provider) that offers UPI as a method, and your website's job is to create an order on your server, hand the customer to the gateway's checkout, wait for the gateway's verified server-to-server notification, and only then mark the order as paid. Most of the engineering effort, and most of the bugs, sit in that last step and in handling the cases where the notification arrives late, twice or not at all. This guide is for founders and product owners commissioning a custom store in Pune and for the developers building it. It covers the build, not the business paperwork.

An earlier version of this article mixed technical advice with statements about licences, fee percentages and data-residency rules that we could not source properly. We have removed them. Merchant onboarding requirements, charges and settlement terms differ by provider and change, so they must come from the provider's own current documentation and from your accountant or lawyer, not from a blog post. What follows is the part we can stand behind: how the website should behave.

What is in scope and what is not

In scope: the checkout flow, UPI intent and QR behaviour, server-side order handling, webhook verification, idempotency, reconciliation, refunds as a software flow, testing and failure states.

Out of scope (ask your provider and adviser): which documents the provider needs to onboard you, what the provider charges, settlement timelines, tax treatment of fees, and which product categories a provider restricts. TODO for the business owner: collect these from two providers' current pricing and onboarding pages before choosing.

Step 1: Choose a gateway for the developer experience, not only the price

For a custom build, the gateway's technical quality matters as much as its commercial terms. When you compare providers, a developer should check:

  • Documentation: is there a clear API reference, a sandbox (test mode) and sample code in your stack?
  • Server-side order creation: can you create an order or payment session from your backend and get an identifier back?
  • Webhooks: which events are sent (payment captured, failed, refund processed), how are they signed, and how are retries handled?
  • Status API: can you query a payment's status by order ID? You need this for reconciliation.
  • Refund API: can you issue full and partial refunds programmatically, and is there a status for each?
  • UPI features: does the gateway support UPI intent on mobile, collect or QR flows, and, if you need recurring payments, UPI Autopay? Our guides on UPI Autopay for stores and checkout form design cover those cases.
  • Support: how do you reach a human during an incident, and what hours?

Also read the gateway's rules about the Reserve Bank of India's directions on payment aggregators; the gateway carries those obligations, but you should understand what it will ask of you.

Step 2: Design the checkout flow

A UPI payment on the web happens in one of a few ways. Which ones you offer depends on the gateway.

UPI intent (mobile)

On a phone, the customer taps "Pay with UPI", chooses an installed UPI app, and the app opens with the payee and amount pre-filled. The customer authenticates in the app, and control returns to the browser. The gateway's SDK or hosted checkout normally builds the intent link for you. Building UPI deep links by hand is rarely necessary and is a common source of breakage because app behaviour differs between devices.

UPI QR (desktop)

On a desktop, the usual pattern is to show a dynamic QR code generated for that specific order, which the customer scans with a UPI app on their phone. Because the browser cannot observe what happens on the phone, your page, or the gateway's checkout, must check the payment status periodically, or wait for a push from the server. Use the gateway's recommended method, set a clear expiry, and show a countdown so the customer knows what is happening.

UPI collect or VPA entry

Some gateways let the customer type a UPI ID so that a payment request is sent to their app. This works for people who are on desktop and have no camera ready, but wrong-ID errors are common. Validate the ID format on the client, use the gateway's own validation if offered, and show a plain error message.

Hosted checkout versus embedded

A hosted checkout page, redirecting to the gateway's domain, keeps more of the payment interface on the provider's side and generally reduces your own security burden. An embedded or API-driven checkout gives you more design control but more responsibility. For most custom stores, start hosted or with the provider's prebuilt SDK, and move to deeper customisation only if you can justify it. Our article on PCI DSS for a boutique website explains why keeping card data off your own servers matters if you also take cards.

Step 3: Make the server the source of truth

This is the most important rule in the whole build.

  1. Create the order on your server first, with status "pending payment", and compute the amount on the server from your own price data. Never accept an amount from the browser.
  2. Call the gateway's create-order API with that amount and your order reference. Store the gateway's order or payment ID on your order.
  3. Send the customer to pay, using the identifier the gateway returned.
  4. Do not treat the browser's return as success. When the customer comes back to your site, show a holding state such as "Confirming your payment" and look up the order on your server.
  5. Mark the order as paid only when you have a verified result, either from the gateway's signed webhook or from your own server-side call to the gateway's status API.

Why not trust the redirect?

The redirect carries information that the customer's browser holds, and it can be interrupted (the customer closes the tab after paying), repeated (the customer refreshes), or manipulated. If your site marks an order paid because a URL contains status=success, a determined person can create that URL without paying.

Step 4: Webhooks done properly

A webhook is an HTTP request the gateway sends to your server when something happens. A reliable receiver does the following.

Verify the signature

Gateways sign webhook payloads, usually with a secret you configure, and publish how to verify the signature. Verify it using the raw request body before reading anything. Reject unsigned or mismatched requests. Keep the secret in server configuration, not in client-side code or a code repository.

Be idempotent

Gateways can send the same event more than once, for example if your server was slow to answer. Your handler must give the same result if the same event arrives twice. A simple approach is to store each event's unique ID and ignore repeats, and to make state changes conditional, such as "set paid only if currently pending".

Respond quickly

Return a success response promptly, then do slow work such as sending emails in a background job. A handler that takes too long may be retried, which creates duplicates if it is not idempotent.

Check the amount and currency

When the event says the payment succeeded, confirm that the amount and currency match the order stored on your server. A mismatch should flag the order for review, not mark it paid.

Handle events out of order

A "failed" event may arrive after a "captured" event for the same order in unusual cases, or an event may arrive before your own database commit finishes. Design the state machine so that an order that is already paid is not downgraded by a late failure event without a human check. Document the allowed transitions.

Log everything

Store the raw event, the verification result and what your system did. When a customer says "I paid but my order says pending", the log is how you answer them.

Step 5: Reconciliation, the safety net

Even a well-built webhook receiver can miss events: your server may be down, a network may drop, or a deployment may reset a queue. A reconciliation job catches those.

  1. Run on a schedule, for example every few minutes for recent orders and once a day for older ones.
  2. Select orders still pending after a reasonable time.
  3. Query the gateway's status API for each one.
  4. Update your order based on the gateway's answer, with the same checks as the webhook path.
  5. Alert a person when orders have been pending for an unusually long time or when the totals do not match.

Separately, a daily or weekly comparison of your orders against the gateway's settlement reports lets your accountant tie payments to bank credits. Our guide on order and payment status, webhooks and settlement reconciliation explains that second layer for store owners, and our guide on donation reconciliation shows the same ideas on an NGO site.

Step 6: Failures, timeouts and customer messages

A good UPI integration is judged by what happens when things go wrong. Design the following states and the message each one shows.

Situation What the website should do
Customer abandons the UPI app Keep the order pending; let them retry from the order page; expire the order after your chosen window
Payment declined by bank or app Show the gateway's reason in plain words if provided; offer another method
Payment pending (no result yet) Say "We are confirming your payment. Please do not pay again"; poll or wait for the webhook; email when resolved
Money debited but order not confirmed Reconciliation picks it up; support sees it flagged; the customer is told the order is being checked
Gateway outage Show other payment options if you have them; do not let customers pay into a flow you know is failing
QR expired Offer to generate a new one for the same order, and make sure an old QR cannot confirm a new order

Our article on what to do when UPI fails at checkout is a useful companion on layout and wording.

Do not promise refund times you cannot control

Refund timing depends on the gateway, the bank and the customer's UPI app. State what the gateway documents, and avoid precise promises on your own pages unless your provider confirms them. TODO: copy the refund timeline wording from your provider's current documentation.

Step 7: Refunds as a software flow

Build refunds into the order system, not as a manual task in the gateway dashboard that nobody records.

  • Store each refund request with a reason, an amount and who approved it.
  • Call the gateway's refund API and store the refund ID and status.
  • Support partial refunds if customers can return part of an order, and make sure the refund amount cannot exceed what was paid.
  • Update the order status and notify the customer once the gateway confirms.
  • Reconcile refunds with the gateway's reports in the same way as payments.

Handle credit notes and invoice adjustments in the way your accountant instructs; the website should expose the data, but it should not decide tax treatment.

Step 8: Security checklist

  • Keep gateway API keys and webhook secrets on the server, in environment configuration, never in front-end code or public repositories. Use separate test and live keys.
  • Serve the entire checkout over HTTPS.
  • Do not store sensitive payment data. For UPI you normally store only identifiers and status; for cards, rely on the gateway's tokenisation.
  • Rate-limit endpoints that create orders or check status to deter abuse.
  • Protect order confirmation URLs from guessing, as described in our article on order confirmation pages.
  • Review personal data you store, such as phone numbers and addresses, under India's Digital Personal Data Protection Act, 2023, with a legal adviser. See our overview of DPDP compliance for websites.
  • Keep dependencies and the platform patched; payment pages are an attractive target.

Step 9: Testing before launch

Use the gateway's sandbox with its documented test scenarios.

  1. Successful payment on intent and on QR, if both are offered.
  2. Declined payment, then successful retry on the same order.
  3. Customer closes the tab after paying; confirm via webhook only.
  4. Delayed webhook; confirm that the pending state resolves.
  5. Duplicate webhook; confirm no duplicate order, email or stock deduction.
  6. Webhook with a bad signature; confirm it is rejected and logged.
  7. Amount mismatch; confirm the order is flagged and not marked paid.
  8. Full and partial refund; confirm the order and the customer notification.
  9. Expired QR and a retry.
  10. A very slow mobile connection and a low-end Android phone.

After the sandbox passes, run one real low-value live payment and refund it, to confirm your live keys, webhook URL and settlement route. Keep a written record of the results.

Cost and timeline: what we can and cannot say

The build effort for a UPI integration depends on your stack, your gateway's SDK, how much of the checkout you customise, and how thoroughly you test failure states. A simple hosted-checkout integration on an existing store can take days; a custom flow with reconciliation, refunds and reporting takes longer. We do not quote a generic figure because a number without your scope would mislead. Ask any developer for a scoped estimate that lists the nine steps above and states what is included. Gateway charges are separate and come from the provider's current price list.

Common mistakes in custom UPI builds

  1. Trusting the redirect as proof of payment.
  2. Skipping signature verification on webhooks.
  3. No idempotency, so duplicate events create duplicate orders or emails.
  4. No reconciliation job, so paid orders stay "pending" forever.
  5. Taking the amount from the browser.
  6. Hand-built UPI deep links that break on some devices.
  7. No pending state, so customers pay twice.
  8. Testing only the happy path.
  9. Secrets in front-end code.

Frequently Asked Questions

Can a website accept UPI without a payment gateway?

In practice, a business website accepts UPI through a payment gateway or aggregator that provides the order, checkout and notification APIs. Showing a personal QR code gives you no automated order matching, so it is not suitable for a store with many orders.

Should I rely on the redirect after payment to mark an order paid?

No. Mark the order paid only after your server verifies the gateway's signed webhook or checks the status through the gateway's API. The redirect can be interrupted, repeated or forged.

What is a webhook in a payment integration?

A webhook is a request that the gateway's server sends to a URL on your server when an event occurs, such as a payment being captured or a refund being processed. Your server must verify its signature and handle repeats safely.

What happens if the customer pays and my site goes down?

The gateway records the payment. When your site returns, a reconciliation job queries the gateway for pending orders and updates them. This is why the job is essential.

What do I need to ask a gateway before choosing it?

Ask for the sandbox, API and webhook documentation, the refund API, the UPI methods supported, and their current charges, onboarding documents and settlement terms in writing. Do not rely on third-party blog figures for these.

Where to Start

Write down your order states and the allowed transitions between them. Then ask two gateways for sandbox access and have a developer build the pending-to-paid path using webhooks and a status check, before touching design. Once that is solid, add refunds and reconciliation.

Govindani Infotech is a website and software development company in Pune, at Landmark Plaza, Satara Road, Parvati Paytha. We build custom checkout systems and e-commerce websites. To scope a UPI integration for your store, contact us or call 092019 58274.

Sources:

Need Help With Your Digital Strategy?

Govindani Infotech helps Indian businesses and NGOs build websites, run ads, and grow online. Contact us for a free consultation.