UPI QR: How to Test Your Integration

Available in🇮🇳 India

Create QR payments, simulate failures and reconcile against the webhooks in test mode, then check the scan and approve journey on real devices before you go live. This page covers one-time UPI QR payments on S2S: you take the Intent upi:// link and render it as a QR code, typically on desktop. The customer scans it with any UPI app. QR uses the same API calls and test triggers as Intent. UPI flows: Intent · QR · Collect Start with the overview for test keys and webhook setup.

1. Test Mode Coverage

How live mode and test mode differ

Behaviour	Live mode	Test mode
Customer approval	The customer scans the QR with any UPI app on any device and approves the payment there with their UPI PIN.	The simulator approves or declines on its own. Nothing is scanned, and the outcome is decided by the amount you send rather than by anything the customer does.
QR	You render the `upi://` link returned on the payment as a QR image and show it at checkout.	The link is returned with the same shape, so render it exactly as you would in live mode and check that the image your code produces is scannable. Nothing is scanned here, so the outcome still comes from the amount.
Scanning	A real UPI app on the customer’s phone reads the QR off your checkout screen.	Client-side. Not part of test mode. Whether your QR actually scans, at the size and contrast you render it, has to be checked on real devices.
Fund source (`payer_account_type`)	The customer pays from whatever their UPI app is set to use, so `payer_account_type` comes back as `bank_account`, `credit_card`, `credit_line` or `ppiwallet`.	Always `bank_account`. Nothing you send changes it, so you cannot exercise the branches of your code that key off a credit card, a credit line or a wallet. Read the field, but verify the branching against live traffic.
Late authorisation	A payment with no bank response is marked `failed`, but Razorpay keeps polling the bank for up to 3 days. If the bank confirms late, the payment becomes `authorized` and `payment.authorized` arrives long after you showed the customer a failure.	Not simulated. There is no way to make a payment authorise late in test mode, so the handler that has to cope with a success arriving after a failure is one you have to verify in a controlled live test.
Webhook delivery	Razorpay sends the webhook once the gateway has authorised the payment. That round trip is real, so delivery can take up to 12 minutes and your reconciler has to allow for it.	The gateway is simulated, so the webhook is sent as soon as the create-payment request succeeds, almost instantly. Do not use test mode to size your reconciliation windows or to judge how long you should wait before polling.

What you can test

Area	What you can test
Payments	Successful payments on the QR flow, and failure scenarios, using the calls in Scenarios to test your integration and the reserved amounts in 3.3 UPI error scenarios.
Reconciliation	Fetching a payment by ID and fetching the payments on an order, so you can prove your reconciler agrees with the webhook.
Capture and refunds	Capturing an authorised payment and refunding a captured one, in full and in part.
Webhooks	Payment, order and refund webhooks for each of the above, delivered to the URL configured in your test mode Dashboard. See Webhooks: what fires, and what it lets you decide for which events fire today.
Rendering and scanning the QR	Rendering is yours to check here, since the link comes back with the same shape. Whether the image actually scans has to be checked on real devices.

Endpoint coverage in test mode

API	Endpoint	Available on test mode
Create an order	`POST /v1/orders`	Available
Create a payment	`POST /v1/payments/create/upi`	Available
Fetch a payment	`GET /v1/payments/:payment_id`	Available
Fetch payments on an order	`GET /v1/orders/:order_id/payments`	Available
Capture a payment	`POST /v1/payments/:payment_id/capture`	Available
Refund a payment	`POST /v1/payments/:payment_id/refund`	Available
Fetch downtimes	`GET /v1/payments/downtimes`	Coming soon

Webhooks: what fires, and what it lets you decide

Every webhook this flow fires in live mode is listed below, along with whether it also fires in test mode. Test mode webhooks have the same shape as live mode ones and are delivered to the URL set in your test mode Dashboard.

Webhook	Fires when	In test mode
`payment.authorized`	The payment is authorised. The money is held, not captured.	Available
`payment.captured`	The payment is captured, when the order was created with `payment_capture` set to true.	Available
`payment.failed`	The payment attempt fails.	Available
`order.paid`	The order is fully paid.	Available
`refund.processed`	A refund has left Razorpay.	Available
`refund.failed`	A refund could not be processed.	Coming soon
`payment.downtime.started, updated, resolved`	A method, bank or UPI app goes down and recovers.	Coming soon

Which webhooks each scenario fires

Scenario	Webhooks	In test mode
1 Successful payment	`payment.authorized`, `payment.captured`, `order.paid`	Available
2 Customer cancels or declines in the app	`payment.failed`	Available
5 Full and partial refund	`refund.processed`	Available
10 Stop showing the QR at a final state	`payment.captured`, `payment.failed`	Available
26 Late authorisation	`payment.authorized`	Coming soon

Before you trust any of them

Verify the signature on every event. Replay one event to your endpoint and send one with a changed body. The replay must be ignored and the tampered event rejected. An endpoint that skips this is an open write to your order state.
Expect duplicates. The same event can arrive more than once. Key your handler on the event ID and make it idempotent.
Order is not guaranteed across events. Do not assume payment.captured lands before order.paid; handle whichever arrives first.
Webhook first, callback second. The browser callback can be lost, blocked or forged. Fulfil on the webhook.

2. Before you begin

Generate your test mode API keys from the Dashboard. Keys that start with rzp_test_ send all requests to test mode. You do not need to enable any separate flag.
Use the same APIs and request formats you use in live mode. Only the API keys change.
Pass every amount in paise, as you do in live mode. For example, send 201 for ₹2.01 and 100 for ₹1.
Configure a webhook URL in your test mode Dashboard to receive test events. Test mode webhooks are separate from live mode ones and do not carry over.

In test mode the amount you send decides the outcome, because there is no real bank on the other end. Send 100 (₹1) and the payment succeeds. Send one of the reserved amounts and the payment fails with the error mapped to that amount. For example, create the order for 201 (₹2.01) and the payment always fails with an insufficient balance error, so you can check that your code handles that case without waiting for a real account to run out of money.

Send 100 (₹1) on both the order and the payment to succeed.
Send a reserved amount from 3.3 UPI error scenarios on both calls to fail with the error mapped to that amount.
You do not need to scan the QR you render.
Any amount that is not in the reserved list succeeds.

Amounts are in paise and follow one pattern: 1xx bank and network, 2xx account and limits, 3xx customer action, 4xx validation and risk.

3. Scenarios to Test Your Integration

This section lists every scenario we think is worth running against your UPI QR integration before you go live. They are grouped by what each one proves, rather than by how urgent they are, so that you can work down the page in order and know that you have covered the integration end to end. Must-have. We highly recommend running these scenarios first. They cover the successful path and the handful of outcomes you are almost certain to meet once you are live, so getting through them is the shortest route to an integration you can trust. Other common scenarios. These come up in normal day-to-day running and are shared across one-time UPI and UPI Autopay, so the same handling has to work on both. They are not errors as such, but your integration still needs to recognise them and respond correctly, so we recommend covering them before launch. Error scenarios. These are failures you can bring on deliberately, using a reserved trigger, so that you can check your error handling without waiting for a real failure to happen. Most rows use a single trigger; where a row lists two, each one is shown separately in the error object column. Not available in test mode yet. These scenarios are real and your integration still has to handle them, but they cannot be reproduced in test mode today. We recommend reading through them and checking your handling on live traffic or in a controlled live test before you ship.

3.1 Must-build UPI scenarios

#	Scenario	Trigger creds	Steps to follow
1	Successful payment	`amount: 100`	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Verify the signature on your server. Confirm `payment.captured`. Webhooks received: `payment.authorized`, `payment.captured`, `order.paid`. Status changes: the payment moves to `captured` and the order to `paid`.
2	Customer cancels or declines in the app	`302`, `304`	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `payment.failed` with `payment_cancelled` / `payment_declined`. The order stays open.
3	Request times out	`105`	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `payment_timed_out`. Stop polling and let the customer retry.
4	Fetch payment and reconcile (all methods)	A payment ID from 1 (success) and one from any row in 3.3 UPI error scenarios	Poll `GET /v1/payments/:id` while the customer is in the UPI app. Confirm the status matches the webhook. Repeat scenario 1 with each reserved amount to cover the error scenarios in 3.3, and replace the QR with the result once the payment is final (scenario 10). Scanning the QR is client-side, so check that on real devices.

3.2 Common scenarios in UPI

#	Scenario	Trigger creds	Steps to follow
5	Full and partial refund (all methods)	A captured payment from 1	Refund in full and in part. Confirm `refund.processed`.

3.3 UPI error scenarios

Bank and network (1xx) The payment reached the rails and something outside the customer’s control went wrong. These are temporary, so offer the customer the same method again.

#	Scenario	Trigger creds	Error object	Steps to follow
6	Bank technical error	`102`, `104`	on 102 `code` GATEWAY_ERROR `source` issuer_bank `step` payment_debit_request `reason` bank_technical_error on 104 `code` GATEWAY_ERROR `source` issuer_bank `step` payment_debit_response `reason` bank_technical_error	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `bank_technical_error` and a retry option.
7	Gateway technical error	`101`, `103`	on 101 `code` GATEWAY_ERROR `source` gateway `step` payment_response `reason` gateway_technical_error on 103 `code` GATEWAY_ERROR `source` gateway `step` payment_response `reason` gateway_technical_error	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `gateway_technical_error`.
8	UPI app / PSP not available	`107`	`code` GATEWAY_ERROR `source` customer_psp `step` payment_request `reason` upi_app_not_available	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `upi_app_not_available` and a retry option.
9	Stop showing the QR at a final state	`amount: 100`, then `302`	on 302 `code` BAD_REQUEST_ERROR `source` customer `step` payment_authentication `reason` payment_cancelled	Create an order with the trigger amount. Render the QR. Confirm the QR is replaced by the result on `payment.captured` / `payment.failed`.

Account and limits (2xx) The customer’s account, their PIN or their bank’s limits stopped the debit. A few are recoverable on the same account, a wrong PIN above all; most are not. Read the reason before you offer a retry.

#	Scenario	Trigger creds	Error object	Steps to follow
10	Insufficient funds	`201`	`code` GATEWAY_ERROR `source` customer `step` payment_debit_request `reason` insufficient_funds	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `insufficient_funds` and a “use another account” message.
11	Wrong UPI PIN	`204`	`code` BAD_REQUEST_ERROR `source` customer `step` payment_authentication `reason` incorrect_pin	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `incorrect_pin` and a retry option.
12	Per-transaction limit exceeded	`208`	`code` BAD_REQUEST_ERROR `source` customer `step` payment_debit_response `reason` transaction_limit_exceeded	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `transaction_limit_exceeded` and an “amount too high” message.
13	Daily / net debit limit exceeded	`209`	`code` BAD_REQUEST_ERROR `source` customer `step` payment_debit_response `reason` transaction_limit_exceeded	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `transaction_limit_exceeded` and a “daily limit reached, try again tomorrow” message.
14	UPI PIN not set	`205`	`code` BAD_REQUEST_ERROR `source` customer `step` payment_authentication `reason` pin_not_set	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `pin_not_set` and a “set your UPI PIN” message, not a retry-PIN prompt.
15	UPI PIN attempts exceeded (locked)	`206`	`code` BAD_REQUEST_ERROR `source` customer `step` payment_authentication `reason` pin_attempts_exceeded	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `pin_attempts_exceeded` and a “try later or use another method” message, not a retry-PIN prompt.
16	Remitter account blocked	`212`	`code` BAD_REQUEST_ERROR `source` issuer_bank `step` payment_debit_request `reason` debit_instrument_blocked	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `debit_instrument_blocked` and an “account blocked, use another” message.
17	Beneficiary account does not exist	`213`	`code` GATEWAY_ERROR `source` gateway `step` payment_credit_request `reason` beneficiary_account_does_not_exist	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `beneficiary_account_does_not_exist` (receiver account inactive).
18	Transaction frequency limit exceeded	`210`	`code` BAD_REQUEST_ERROR `source` business `step` payment_initiation `reason` transaction_frequency_limit_exceeded	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `transaction_frequency_limit_exceeded` and a “try again later” message.
19	Registered mobile number not found	`202`	`code` BAD_REQUEST_ERROR `source` customer `step` payment_request `reason` mobile_number_invalid	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `mobile_number_invalid` and a “use another method” message.
20	Invalid bank account	`203`	`code` BAD_REQUEST_ERROR `source` customer `step` payment_debit_request `reason` bank_account_invalid	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `bank_account_invalid` and a “use another account” message.

Validation and risk (4xx) The request or the customer failed a check before or during the debit. Read the reason before you decide whether a retry is worth anything.

#	Scenario	Trigger creds	Error object	Steps to follow
21	Declined by bank or risk check	`402`, `404`	on 402 `code` GATEWAY_ERROR `source` issuer_bank `step` payment_debit_request `reason` payment_declined on 404 `code` GATEWAY_ERROR `source` issuer_bank `step` payment_debit_response `reason` payment_risk_check_failed	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `payment_risk_check_failed` / `payment_declined`.
22	API validation errors (all methods)	Missing `amount`, `amount: 0`, wrong key secret	—	Send each bad request. Confirm HTTP 4xx, no payment created, no webhook.
23	Invalid UPI ID (VPA resolution failed)	`401`	`code` GATEWAY_ERROR `source` network `step` payment_request `reason` vpa_resolution_failed	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `vpa_resolution_failed` and an “incorrect UPI ID” message.
24	Invalid device	`407`	`code` BAD_REQUEST_ERROR `source` customer `step` payment_authentication `reason` invalid_device	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `invalid_device` and a “use another method” message.
25	Duplicate request	`406`	`code` BAD_REQUEST_ERROR `source` gateway `step` payment_request `reason` duplicate_request	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Render the `upi://` link as a QR code. Confirm `duplicate_request` (temporary) and allow retry.

The full list of UPI error reasons, including the ones no trigger reproduces in test mode, is on the Error index.

3.4 Not available in test mode yet

#	Scenario
26	Late authorisation — Live only. Handle `payment.authorized` arriving after you showed failure (up to 3 days). Check in a controlled live test.
27	Scan the QR with a real UPI app — Client-side. Scan on a real phone and approve. Check in a small live test.
28	Fund source: credit card, credit line, PPI — Coming soon. Read `payer_account_type`. Test mode always returns `bank_account`.
29	`upi.expiry_time` on the intent link behind the QR — supported in live mode, not in test mode. In live mode you can set `upi.expiry_time` on the authorisation payment to cap how long the intent link behind the QR stays valid, and the payment fails once that window closes. Test mode ignores it: the outcome is decided by the amount you send, so no amount makes the link expire and the parameter has no observable effect. Send it exactly as you would in live mode and assert that your code treats an expired QR as a terminal failure rather than something to keep polling, then check the timing itself against live traffic.

4. Common Integration Gaps to Avoid

These are the mistakes that most often cause failed payments, missed debits or double charges after go-live. “Test with” points to the scenario that proves you’ve handled it. Webhook and token updates

Gap	What goes wrong in production	What to do	Test with
Waiting for a redirect that never comes	UPI has no redirect back to you. The customer approves in their app and your page waits forever.	Drive the result from `payment.captured` / `payment.failed`, with polling as backup while the customer is in the UPI app.	1
Duplicate or unsigned events processed	One payment fulfils twice.	Verify `X-Razorpay-Signature`. Store event IDs and skip repeats.	Webhooks
QR left on screen after the payment ends	The customer scans an old QR again and pays a second time, which is then auto-refunded.	Replace the QR with the result as soon as you get a final status.	9

Error handling and messaging to the payer

Gap	What goes wrong in production	What to do	Test with
Failing the payment while the customer is still in the app	You show “payment failed” while the request is still open in the UPI app, and the customer pays anyway.	Show a “complete the payment in your UPI app” state with the expiry timer. Show failure only on a final status.	2, 3
Same message for every failure	The customer retries a wrong PIN or empty account the same way.	Branch on `error.reason`: `incorrect_pin` → retry, `insufficient_funds` → use another account, bank errors → retry later.	10, 11, 6
QR shown on mobile	A customer on a phone can’t scan their own screen and drops off.	Show QR on desktop. Use Intent on mobile.	27
QR not scanned in time	The QR / intent link expires and the payment fails before the customer scans it.	Regenerate the payment and QR and show it again.	3

Fetch API when webhooks are late

Gap	What goes wrong in production	What to do	Test with
Polling stops too early	The customer approves near the end of the window and you miss it.	Poll the status URL or `GET /v1/payments/:id` until a final state or the request expiry, then keep reconciling.	4
Late authorisation ignored	A payment marked failed after 10 minutes is authorised by the bank hours later. The customer is debited and you have no order.	Listen for `payment.authorized` for 3 days. Capture and fulfil, or let it auto-refund. See Late authorisation ↗.	26 (Live only)

Capture & refunds

Gap	What goes wrong in production	What to do	Test with
Not capturing an authorised payment in time	Uncaptured `authorized` payments are auto-refunded — the customer is debited and then refunded, and you treat it as a failure.	Capture within the capture window or enable auto-capture; expect `refund.processed` if you don’t.	BP-14
Multiple payments on the same order	More than one attempt succeeds or late-authorises on the same order, so the customer is charged twice.	Use the Orders API — it clubs attempts to one order; the duplicate or late-authorised payment auto-refunds and only one is marked paid.	BP-08, BP-09

5. Best Integration Practices

These apply to every Razorpay integration. “On this method” says what each one means here; “Test it” links to where it is tested once for every method.

Topic	What to know	On this method	Test it	Read more
Difference between order and payment	An order is what you want to collect. A payment is one attempt to pay it. One order can have many attempts but only one captured payment. Create the order on your server so the amount can’t be tampered with.	Each Intent, QR or Collect request is a separate payment on the same order.	BP-24, BP-25	Difference between order and payment ↗
Order states	Orders move `created` → `attempted` → `paid`. An order stays `attempted` through failed attempts, and stays `paid` even after a refund. Handle Orders API errors (for example an invalid amount or currency) when you create the order.	The order stays `attempted` while the QR is on screen and unpaid.	BP-09	Order states ↗ · Orders API error codes ↗
Late authorisation	A payment with no bank response is marked `failed` after 10 minutes, but Razorpay keeps polling the bank for 3 days. If the bank confirms, the payment becomes `authorized` (under 0.5% of payments). Listen for `payment.authorized` and capture it, or let it auto-refund.	Most common on UPI. A payment you showed as failed can turn `authorized` later. Live only.	BP-06	Late authorisation ↗
Capture settings	Choose auto-capture or manual capture and set the timeouts. An `authorized` payment you don’t capture in time is auto-refunded. You can set capture behaviour per order through the Orders API.	The auto-capture window defaults to 2 days for UPI.	BP-14	Capture settings ↗
Multiple payments on the same order	Once an order is `paid`, no more payments are accepted on it. While a payment on the order is `authorized`, a new attempt isn’t allowed. An attempt that authorises late on a paid order is auto-refunded. Retry on the same order so a customer can’t pay twice.	A customer can scan an old QR and pay twice. Only one payment captures; the other is auto-refunded. Replace the QR once the order is paid.	BP-09 · BP-08	Multiple payments on the same order ↗

All best practices: Overview · Webhooks and Fetch APIs · Payment states and late authorisation · Error handling · Downtime handling · Security

1. Build Integration

2. Test S2S Integration

3. Go Live Checklist

Features

UPI QR: How to Test Your Integration

1. Test Mode Coverage

How live mode and test mode differ

What you can test

Endpoint coverage in test mode

Webhooks: what fires, and what it lets you decide

2. Before you begin

3. Scenarios to Test Your Integration

3.1 Must-build UPI scenarios

3.2 Common scenarios in UPI

3.3 UPI error scenarios

3.4 Not available in test mode yet

4. Common Integration Gaps to Avoid

5. Best Integration Practices

1. Test Mode Coverage

How live mode and test mode differ

What you can test

Endpoint coverage in test mode

Webhooks: what fires, and what it lets you decide

2. Before you begin

3. Scenarios to Test Your Integration

3.1 Must-build UPI scenarios

3.2 Common scenarios in UPI

3.3 UPI error scenarios

3.4 Not available in test mode yet

4. Common Integration Gaps to Avoid

5. Best Integration Practices

Related Information