UPI Collect: How to Test Your Integration

Available in🇮🇳 India

Collect is deprecated from 28 February 2026. Exemptions: specific MCCs, iOS and mobile web, UPI Mandates, eRupi vouchers and PACB businesses. Everyone else should build and test Intent (mobile) and QR (desktop).

Send collect requests, simulate failures and reconcile against the webhooks in test mode, then check VPA validation and the approval window on live traffic before you go live. This page covers one-time UPI Collect payments on S2S: you send a payment request to the customer’s UPI ID and they approve it inside their UPI app. 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	A collect request lands in the customer’s UPI app and they approve it there with their UPI PIN, within the expiry window you set.	The simulator approves or declines on its own. No request reaches a UPI app, and the outcome is decided by the VPA and the amount you send rather than by anything the customer does.
Collect request	Razorpay sends the request to the VPA you pass. It shows up in the customer’s UPI app as a pending request carrying your business name and the amount.	Never sent. The payment response carries only a payment ID, followed by the relevant webhooks. Send `success@razorpay` to have it approved and `failure@razorpay` with a reserved amount to have it declined.
Validate VPA	`POST /v1/payments/validate/vpa` resolves the UPI ID against the customer’s PSP before you send the collect request, and returns the name on the account.	Coming soon. You cannot exercise the validate-then-send sequence here yet. Build it anyway, since a collect request sent to a VPA that does not resolve fails without reaching anyone.
Saved VPA	Pass `save` on the payment to store the customer’s UPI ID so they do not have to type it again next time.	Coming soon. Saving and reusing a VPA is not simulated yet, so check it on live traffic.
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 collect 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.
Validate VPA and saved VPA	Neither is simulated yet. Build the validate-then-send sequence anyway, and verify both against live traffic.

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
Validate a VPA	`POST /v1/payments/validate/vpa`	Coming soon
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	`payment.failed`	Available
5 Full and partial refund	`refund.processed`	Available
11 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 success@razorpay as the VPA with 100 (₹1) on both the order and the payment to succeed.
Send failure@razorpay with a reserved amount from 3.3 UPI error scenarios to fail with the error mapped to that amount.
No collect request reaches a UPI app, so there is nothing to approve.
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 Collect 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. 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	`success@razorpay` + `amount: 100`	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "collect"` and `upi.vpa`. Show a “complete the payment in your UPI app” state with a timer. 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	`failure@razorpay` + `302`	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "collect"` and `upi.vpa`. Show a “complete the payment in your UPI app” state with a timer. Confirm `payment.failed` with `payment_cancelled`. The order stays open.
3	Request expires	`failure@razorpay` + `301`	Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "collect"` and `upi.vpa`. Show a “complete the payment in your UPI app” state with a timer. Confirm `payment_collect_request_expired`. 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 `failure@razorpay` and each reserved amount to cover the error scenarios in 3.3, and show the expiry timer so the customer knows how long they have to approve in their UPI app.

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	`failure@razorpay` + `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: "collect"` and `upi.vpa`. Show a “complete the payment in your UPI app” state with a timer. Confirm `bank_technical_error` and a retry option.

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
7	Insufficient funds	`failure@razorpay` + `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: "collect"` and `upi.vpa`. Show a “complete the payment in your UPI app” state with a timer. Confirm `insufficient_funds` and a “use another account” message.
8	Wrong UPI PIN	`failure@razorpay` + `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: "collect"` and `upi.vpa`. Show a “complete the payment in your UPI app” state with a timer. Confirm `incorrect_pin` and a retry option.

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
9	Declined by bank or risk check	`failure@razorpay` + `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: "collect"` and `upi.vpa`. Show a “complete the payment in your UPI app” state with a timer. Confirm `payment_risk_check_failed`.
10	API validation errors (all methods)	Missing `amount`, `amount: 0`, wrong key secret	—	Send each bad request. Confirm HTTP 4xx, no payment created, no webhook.

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
11	Late authorisation — Live only. Handle `payment.authorized` arriving after you showed failure (up to 3 days). Check in a controlled live test.
12	Invalid UPI ID entered — Coming soon. Handle `invalid_vpa` from the API. Check live.
13	Validate VPA before sending — Coming soon. Build to spec (`POST /v1/payments/validate/vpa`). Check live.
14	Save and reuse a VPA — Coming soon. Build to spec. Check live.
15	Fund source: credit card, credit line, PPI — Coming soon. Read `payer_account_type`. Test mode always returns `bank_account`.

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. Before you send — validate the VPA (Collect only)

Gap	What goes wrong in production	What to do	Test with
Not validating the VPA before sending	Collect requests fire at mistyped or non-existent UPI IDs, so they fail only after the full expiry wait.	Call `POST /v1/payments/validate/vpa` first and send the collect only if it resolves.	13
Branching on HTTP status instead of the `success` field	`success: false` is returned as an HTTP 200, so a valid “VPA does not exist” is mistaken for a server error. `@paytm` handles also return 200 with `success: false`.	Branch on the `success` boolean, not the HTTP status; `customer_name` appears only when `success: true`; treat `@paytm` as a negative result, not an error.	12

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

Saved VPA (Collect only)

Gap	What goes wrong in production	What to do	Test with
Saved VPA not refreshed	A customer’s saved UPI ID stops working and every Collect fails.	Refresh saved methods from the API before showing them.	14
Treating a saved VPA as proven-good	The VPA is saved when the payment is created (before the bank replies), so it is saved even if that payment later failed.	Don’t assume a saved VPA has ever succeeded; confirm it on the first successful payment.	14
Showing duplicate saved UPI IDs	Every `save: 1` payment creates a new saved token, so the same customer + VPA can appear in the saved list several times.	De-duplicate by VPA before showing the saved list.	14

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.	7, 8, 6
Collect shown to customers who can’t use it	After 28 Feb 2026, non-exempt Collect requests fail.	Show Intent and QR. Keep Collect only if you are exempt.	—
No expiry timer	The customer doesn’t know how long they have to approve, and the request expires.	Show the time left and a “resend request” option after expiry.	3
Resending a collect while one is still pending	The customer gets multiple collect prompts and may approve more than one, risking a double debit that is later reconciled or refunded.	Allow a resend only after the current request expires; show the expiry timer meanwhile.	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 ↗.	11 (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 Collect request is pending approval.	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 get more than one Collect request and approve both. Only one payment captures; the other is auto-refunded.	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 Collect: 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