Webhook vs polling is a key decision when your website must know whether a UPI order has been paid. Use a webhook as the primary server-to-server event, then use a status check as a controlled fallback for return pages and reconciliation.
Polling vs webhooks
Polling means your application repeatedly asks an API for the latest state. For example, your checkout might call GET /api/order_status/{client_txn_id} every few seconds until the order becomes successful, pending for too long, or reaches another terminal state.
A webhook reverses the direction. You expose an HTTPS endpoint, and the payment verification service sends an HTTP request to your server when it has a payment event for that order. Your application verifies the signed request, matches it to a local order, and changes the order state once.
The difference is easiest to remember this way:
| Method | Who starts the request? | Best use | Typical timing |
|---|---|---|---|
| Polling | Your application | A deliberate status read or reconciliation job | At the interval you choose |
| Webhook | The service sending the event | Server-side notification of a state change | When the event is available |
HTTP is fundamentally a client-server protocol in which a client sends a request and receives a response. That is why polling feels natural in a browser or backend. A webhook is an application pattern built on HTTP: the service makes a request to your endpoint when it has something useful to report.
For a UPI checkout, PaymentSetu is a payment verification service, not a payment gateway. The customer pays directly into your own connected Paytm Business or PhonePe Business merchant account; PaymentSetu matches the UTR and amount to the order and sends your application the verification event.
Webhook vs polling: strengths and trade-offs
Both patterns are useful, but they solve different problems. The right comparison is not “which one replaces the other?” It is “which path handles the normal event, and which path gives me a safe way to check again?”
| Concern | Webhook | Polling |
|---|---|---|
| Normal event delivery | The service pushes an event to your HTTPS endpoint | Your code keeps asking for the current state |
| Request volume | Usually one delivery per event, plus any documented retries | Grows with the number of open orders and polling attempts |
| Customer return page | Does not depend on the customer staying on the page | Can update a waiting page while the customer is present |
| Server requirements | Needs a public endpoint, signature verification and idempotent handling | Needs a protected server-side API call and an interval policy |
| Recovery and reconciliation | Works with a status read when you need to investigate or repair state | Naturally provides a fresh read, but needs a stopping rule |
| Fulfilment trigger | Good for marking an order paid after validation | Better as a check; do not create a new payment side effect from it |
Polling is not automatically wrong. It is useful for a customer-facing “checking payment” screen, for a scheduled job that reviews old pending orders, and for recovering from an event that your local system has not recorded. It becomes wasteful when every browser polls forever, or when the browser is treated as the authority for fulfilment.
Webhooks also need engineering care. A webhook endpoint must be reachable, authenticate the request, handle duplicate deliveries safely and return a response promptly. GitHub’s webhook best-practices documentation is a useful general reference for HTTPS, secrets, event checks and redelivery handling; apply the same principles to a payment event.
The recommended pattern: webhook first, status check second
For payment status, use this sequence:
- Create the order on your server with a unique local reference.
- Display the returned QR or hosted payment page to the customer.
- Keep the local order in
pendinguntil a trusted server-side result is accepted. - Receive the PaymentSetu webhook at your HTTPS endpoint.
- Verify the timestamp and HMAC signature over the exact raw request body.
- Check the order reference, amount and successful state against your database.
- Apply the paid transition once, store the UTR, and return a 2xx response.
- Use
GET /api/order_status/{client_txn_id}from your server when the return page needs a read or when a reconciliation job reviews a pending order.
This gives each path a clear job. The webhook is the event path that can update fulfilment without relying on the customer’s browser. Polling is the read path that helps your application display or reconcile the latest known state.
Do not mark an order paid just because the customer reached a redirect URL, closed a QR page, or showed a screenshot. Those are customer-facing signals. Your backend should make the state transition only after the signed webhook or a trusted status response matches the local order.
Create an order, then wait for the webhook
PaymentSetu’s custom integration starts with POST /api/create_order. Keep this call on your backend and send the amount as an integer number of paisa. For example, ₹249 is 24900.
curl -X POST 'https://paymentsetu.com/api/create_order' \
-H 'Authorization: Bearer YOUR_PAYMENTSETU_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"order_id": "ORD-20261023-1042",
"amount": 24900,
"redirect_url": "https://example.com/payment-return"
}'
Save the local order_id, expected amount and pending state before redirecting the customer. Use the response’s payment URL or the integration path configured for your account to show the order-specific QR checkout. Never calculate the payable amount only from a hidden browser field; load prices from trusted server-side order data.
Your webhook handler should be short and deliberate:
receive raw body and PaymentSetu timestamp/signature headers
verify HMAC-SHA256(timestamp + "." + raw body, API key)
reject the request if the signature or timestamp is invalid
parse JSON only after signature verification succeeds
load the local order by the received order reference
compare amount and successful payment state
record the UTR/event identifier with a uniqueness rule
change pending to paid once
return HTTP 200 after the database transaction commits
The signature proves that the request was signed with the shared secret and that the body was not changed in transit. It does not remove the need to validate your order ID, amount, payment state and fulfilment rules. For a language-specific implementation, see the guide to verifying HMAC webhook signatures in PHP, Python and Node.js.
Use polling as a controlled fallback
The fallback endpoint is:
GET /api/order_status/{client_txn_id}
Call it from your server with the same bearer API-key authentication. URL-encode the transaction identifier and keep the response private. A simple request looks like this:
curl 'https://paymentsetu.com/api/order_status/ORD-20261023-1042' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_PAYMENTSETU_API_KEY'
For a return page, your backend can perform one status read immediately after the customer comes back. If the result is still pending, let the page ask your own backend for a short period rather than exposing the PaymentSetu key to JavaScript. Your backend can either read its local order state, which the webhook updates, or make a carefully limited status check when appropriate.
For reconciliation, run a scheduled server-side job over orders that are still pending. Use a backoff schedule and a maximum age, such as checking more frequently at first and less frequently later. The exact interval should match your order expiry and operations needs; do not build an unbounded loop.
The MDN reference for GET describes GET as safe and idempotent for retrieving data. That makes a status read suitable for retrying, but it does not mean every response is fresh forever, nor does it make a client-side read a payment confirmation by itself. Always inspect the returned order reference and amount before changing local state.
Make both paths safe to retry
A payment integration must assume that network calls can be repeated. Your webhook may be delivered again, a status request may time out after the remote server has already answered, and a worker may restart after writing part of a database transaction.
Use these safeguards:
- Give every payment order a unique
client_txn_idor local order reference. - Store the expected amount before creating the QR order.
- Verify HMAC over the raw webhook body before parsing or processing it.
- Store the webhook event or UTR with a database uniqueness constraint.
- Make the paid transition atomic: update only an order that is still
pending. - Treat a repeated valid event as an acknowledgement, not as a second fulfilment.
- Keep status checks read-only; do not create a new order from a retry of a status request.
- Log request IDs, order references and outcomes without logging API keys or webhook secrets.
The HTTP concept of idempotency means that repeating an identical request has the same intended effect as making it once. MDN’s idempotency reference explains why idempotent operations are safer to retry. Your application still has to enforce idempotent fulfilment because sending an email, releasing a download or activating a service can otherwise happen twice.
A practical state machine for payment status
Keep payment state separate from page state. The customer may leave the page while the payment is being matched, and a webhook may arrive before or after the return request.
| Local state | What your application may do | What it should not do |
|---|---|---|
pending | Show “payment being checked”; accept a verified event or status read | Fulfil the order from a screenshot or redirect alone |
paid | Fulfil once, show the receipt and retain the UTR | Create a second fulfilment for a duplicate event |
failed or expired | Show the next supported action and retain the audit record | Silently turn it into paid from an unverified browser message |
The webhook handler and reconciliation worker should both use the same state-transition function. That avoids one code path checking an amount while another updates the order without the same validation.
For WooCommerce, the PaymentSetu WooCommerce plugin provides the ready-made order integration. For a custom application, use the API and webhook flow above. In both cases, the principle is the same: direct UPI payment into your own merchant account, verified order matching, then an idempotent order update.
How to choose the right implementation
Choose webhook-first when a payment event must trigger a server action, such as marking a WooCommerce order paid, activating a SaaS account, or updating a WHMCS invoice. It is also the cleaner architecture when customers may close their browser before the payment is matched.
Add a status fallback when your return page needs to show current progress, when support staff need a server-side lookup, or when a scheduled reconciliation process reviews pending orders. Keep it bounded and authenticated.
Polling-only can be reasonable for a small internal tool or an API that offers no webhook, but it requires a clear interval, timeout, terminal-state rule and request budget. When a signed webhook is available, using it as the normal event path usually gives your order system a simpler source of state changes.
PaymentSetu Pro is ₹999 per 30 days for 1,000 credits, with one credit representing one successful payment verified. It includes dynamic QR, webhooks, API access, a unified dashboard, real-time notifications and the WooCommerce and WHMCS integrations. See the PaymentSetu plans or create an account when you are ready to connect the flow.
FAQ
Is a webhook better than polling for payment status?
For server-side payment updates, use the webhook as the primary path because your application receives the event without repeatedly asking. Keep polling as a bounded fallback for return-page checks and reconciliation.
Should the browser poll the payment API directly?
No. Keep the API key on your server and let the browser call your own backend if it needs a progress update. Your backend should decide whether to read local state, make a limited status request, or show that the order is still pending.
Can a webhook arrive more than once?
Your handler should be safe if the same event is delivered again. Verify the signature, store a unique event or UTR, and update the order only when its current state is pending; then acknowledge a duplicate without repeating fulfilment.
Does a payment return URL confirm payment?
No. A return URL only tells your application where the customer went after the payment page. Confirm the order with a verified PaymentSetu webhook or a trusted status response that matches the local reference and amount.
What is the PaymentSetu status endpoint?
Use GET /api/order_status/{client_txn_id} with bearer API-key authentication from your server. It is useful as a status read and reconciliation fallback; the normal automatic update path should remain the signed webhook.
DONE webhooks-vs-polling-payment-status words=2026