UPI Autopay Collect: How to Test Your Integration

Available in🇮🇳 India

Register mandates, run auto-debits, simulate failures and manage tokens in Test Mode, then work through the pre-launch checklist before you go live. Use Test Mode to check your UPI Autopay integration before you go live. Test Mode simulates the responses from NPCI and the customer’s bank, so you can register mandates, run auto-debits and handle failures without moving real money or using a UPI app. This page describes how to test the request and response payload across each API call, and what error scenarios to expect. UPI Autopay flows: Intent · QR · Collect Start with the overview for test keys and webhook setup.

1. Test Mode Coverage

Collect is deprecated from 28 February 2026. Exemptions: specific MCCs, iOS and mobile web, UPI mandates, eRupi vouchers and PACB businesses. For new registrations, everyone else should use Intent (mobile) or QR (desktop).

How live mode and test mode differ

Behaviour	Live mode	Test mode
Collect request	A mandate request lands in the customer’s UPI app for them to approve	The payment response has only a payment ID, then the webhooks. No request is sent to any UPI app.
Mandate approval by the customer	A mandate request lands in the customer’s UPI app and they approve it there with their UPI PIN.	The simulator approves or declines on its own. No Collect request reaches a UPI app, and the outcome is decided by the amount you send rather than by anything the customer does.
Auto-debit timing and the pre-debit notification window	Razorpay sends the pre-debit notification first. NPCI requires at least 24 hours between the notification and the debit, and Razorpay schedules the debit 25 hours after it. The payment sits in `created` until then.	Razorpay sends the pre-debit notification and the debit together in Test Mode, without waiting out the actual window. The debit is attempted as soon as you create the payment rather than being scheduled, so the payment reaches `captured` or `failed` within the same test run instead of a day later. Do not use Test Mode to benchmark your end-to-end debit timing or size your reconciliation windows. Coming soon: a gap between the pre-debit notification and the debit, so Test Mode mirrors the live sequence.
Pre-debit notification webhooks	The notification fires `order.notification.delivered` or `order.notification.failed`. Note the `order.` prefix.	The notification itself is simulated today and always succeeds, unless the token is in the `cancelled` state. What is not available is the two notification webhooks, which are not sent in Test Mode. Subscribe to them and verify them against live traffic.
Automatic retries of a failed auto-debit	Razorpay retries a failed attempt on a pre-debit notification, following the retry template configured on your account: the default 1-hour template retries twice, the 3-hour and 24-hour templates retry three times, and some accounts are on no retry. One notification covers one debit attempt plus its retries, and only one debit can succeed against it.	There are no retries in Test Mode. A failed debit stays `failed`, and the `payment.failed` webhook is sent to you immediately, whatever retry configuration your account is on.
Who performs the retry	On the coupled flow, Razorpay. The retries are internal, run against the same pre-debit notification, and need no code from you. On the decoupled flow there are no Razorpay retries, so recovery is yours to build.	Neither flow retries automatically in Test Mode. On the decoupled flow you can still exercise your own recovery logic: create a fresh payment on the same `order_id` — new payment ID, same notification — and it is accepted. Once one debit has succeeded against that order, any further attempt returns `mandate_already_executed`.
Customer cancels, pauses or resumes the mandate	The customer does this from their UPI app. Razorpay sends the `token.cancelled` or `token.paused` webhook, and approving a change to a mandate follows the same route.	Coming soon. These customer actions are not simulated yet, and cancelling a token through the API is coming soon too. Fetching a token and fetching all tokens for a customer do work in Test Mode.
Validate VPA	`POST /v1/payments/validate/account` resolves the customer’s VPA against their PSP.	Coming soon.
Mandate registration through a Registration Link	Razorpay hosts the registration page and the customer authorises asynchronously.	Coming soon. Only the API flow (`POST /v1/payments/create/upi`) is available in Test Mode today.
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 to wait before polling.

What you can test

Area	What you can test
Mandate registration	Successful registration on the Collect flow, and its failure scenarios, using the amounts in the scenarios below.
Auto-debits	Successful debits on both the coupled and the decoupled flow, and failure scenarios, using the amounts in the scenarios below.
Token management	Fetching a token and fetching all tokens for a customer.
Webhooks	Payment, order and token webhooks for each of the above, delivered to the URL configured in your Test Mode Dashboard. See below for which events fire today.

Endpoint coverage in test mode

API	Endpoint	Available on test mode
Create a customer	`POST /v1/customers`	Supported
Create an order	`POST /v1/orders`	Supported
Create an authorisation payment	`POST /v1/payments/create/upi`	Supported on the Collect flow
Create a recurring payment	`POST /v1/payments/create/recurring`	Supported
Fetch a payment	`GET /v1/payments/:payment_id`	Supported
Fetch a token by payment ID	`GET /v1/payments/:payment_id`	Supported
Fetch a token	`GET /v1/customers/:customer_id/tokens/:token_id`	Supported
Fetch all tokens for a customer	`GET /v1/customers/:customer_id/tokens`	Supported
Cancel a token	`PUT /v1/customers/:customer_id/tokens/:token_id/cancel`	Coming soon
Delete a token	`DELETE /v1/customers/:customer_id/tokens/:token_id`	Coming soon
Validate VPA	`POST /v1/payments/validate/vpa`	Coming soon
Create a registration link	`POST /v1/subscription_registration/auth_links`	Coming soon

Webhooks: what fires, and what it lets you decide

Every webhook UPI Autopay 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 registration or debit payment is authorised. Carries the token ID.	Yes
`payment.captured`	The payment is captured, when the order was created with `payment_capture` set to true.	Yes
`payment.failed`	The registration or debit fails.	Yes
`order.paid`	The order is fully paid.	Yes
`token.confirmed`	The mandate is registered and the token is active.	Yes
`token.rejected`	Registration failed, so the token was never confirmed.	Yes
`token.cancellation_initiated`	A cancellation has been requested and is awaiting the gateway callback.	Coming soon
`token.cancelled`	The cancellation is confirmed and the token is closed.	Coming soon
`token.paused`	The customer paused the mandate from their UPI app.	Coming soon
`order.notification.delivered`	The pre-debit notification reached the customer.	Coming soon
`order.notification.failed`	The pre-debit notification could not be delivered.	Coming soon
`refund.processed`	A refund on a captured debit has left Razorpay.	Available
`refund.failed`	A refund could not be processed.	Coming soon

Which webhooks each scenario fires

Scenario	Webhooks	In test mode
Registration succeeds	`payment.authorized`, `payment.captured`, `order.paid`, `token.confirmed`	Available
Registration fails	`payment.failed`, `token.rejected`	Available
Registration rejected before the payment is created, for example a validation failure	None. The request is rejected before a payment exists, so no webhook fires. Read the API error response instead.	Available
Registration through a Registration Link	None	Coming soon
Debit succeeds	`payment.captured`, `order.paid`	Available
Debit fails	`payment.failed`	Available
Token cancelled	`token.cancellation_initiated`, then `token.cancelled` once the gateway confirms	Coming soon

Watch out. Note the order. prefix. The pre-debit notification events are named order.notification.delivered and order.notification.failed, not notification.delivered and notification.failed. We recommend subscribing to them and verifying them against live traffic, since neither fires in Test Mode yet.

Handy tip. A webhook can be delivered more than once. Use the event ID to make sure you process each event only once. This applies in live mode as well.

Token states

Charge a token only while it is confirmed.

State	Means	Can you debit?	Webhook	Available on test mode
`initiated`	Registration request sent to the customer’s UPI app	No	—	Supported
`confirmed`	Mandate approved (or resumed)	Yes	`token.confirmed`	Supported
`rejected`	The customer declined, or registration failed	No	`token.rejected`	Supported
`paused`	The customer paused the mandate in their UPI app	No	`token.paused`	Coming soon
`cancellation_initiated`	You called Cancel Token; waiting for confirmation	No	—	Coming soon
`cancelled`	Cancelled by the customer or by you	No	`token.cancelled`	Coming soon

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.

Send 100 (₹1) on both the order and the payment to succeed.
Send a reserved amount from 3.3 Autopay error scenarios on both calls to fail. For debits, keep it below the mandate’s max_amount.
No collect request reaches a UPI app, so there is nothing to approve.
Any amount that is not in the reserved list succeeds.

Coupled or decoupled? Both debit flows are covered below as scenarios — scenario 2 (coupled) and scenario 4 (decoupled). The flows themselves, the notification object and who owns the retries are defined in the published integration doc: Subsequent Payments. This page does not redefine them.

3. Scenarios to Test Your Integration

This section lists every scenario we think is worth running against your UPI Autopay 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. Most rows use a single trigger, which keeps the error you get back unambiguous. 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 Autopay scenarios

#	Scenario	Trigger creds	Steps to follow
1	Register a mandate	`amount: 100`	Create a customer (`POST /v1/customers`) and store the returned `customer_id`. Create an order (`POST /v1/orders`) with `method: "upi"`, the `customer_id` and a `token` object, using the trigger amount. Create the authorisation payment (`POST /v1/payments/create/upi`, `recurring: 1`) with the same amount. `upi.flow: "collect"` and `upi.vpa` (any well-formed VPA). Show an “approve the mandate in your UPI app” state. Confirm `token.confirmed`. Store the token ID from `payment.authorized`. On the order and the payment.
2	Subsequent debit succeeds	`amount: 100`	Register a mandate (#1). Create a debit order without the `notification` object, which is what places the payment on the coupled flow, and a recurring payment (`POST /v1/payments/create/recurring`) with the trigger amount. Confirm `payment.captured` and `order.paid`. Token stays `confirmed`.
3	Debit fails: insufficient funds	`amount: 201`	Register a mandate (#1). Create a debit order and a recurring payment (`POST /v1/payments/create/recurring`) with the trigger amount. Confirm `payment.failed` with `insufficient_funds`. Token stays active.

3.2 Common scenarios in UPI

#	Scenario	Trigger creds	Steps to follow
4	Debit with your own pre-debit notification	`amount: 100`	Register a mandate (#1). Create the debit order (`POST /v1/orders`) with the `notification` object, setting `notification.token_id` and `notification.payment_after`. Create the recurring payment (`POST /v1/payments/create/recurring`) with the same amount, passing `order_id`, `customer_id`, `token` and `recurring: true`. Confirm `payment.captured`.
5	Fetch tokens	A sample token ID	Take a sample token ID from a mandate you registered earlier. `GET /v1/customers/:customer_id/tokens/:token_id` and `GET /v1/customers/:customer_id/tokens`. Confirm `status`, `max_amount`, `expire_at`, `frequency`.
6	Fetch a payment and reconcile (also on one-time UPI)	A payment ID from the registration in scenario 1 and one from any row in 3.3	Poll `GET /v1/payments/:payment_id` for each payment. Confirm the status your reconciler reads matches the status the webhook carried. Confirm a payment still in `created` is never treated as final.
7	Full and partial refund (also on one-time UPI)	A captured debit payment from scenario 2	Refund in full with `POST /v1/payments/:payment_id/refund`, and refund another captured debit in part. Webhooks received: `refund.processed`. Confirm the mandate is untouched. A refund does not cancel the token, and the next debit still runs.
8	API validation errors (also on one-time UPI)	Missing `amount`, `amount: 0`, wrong key secret	Send each bad request to the order and the payment endpoints. Confirm HTTP 4xx, no payment created and no webhook. Read the API error response rather than waiting for an event, because none fires.

3.3 Autopay error scenarios

Registration These happen while the customer is setting the mandate up, so the token never reaches confirmed and no debit is possible. In each case the customer has to start the registration again.

#	Scenario	Trigger creds	Error object	Steps to follow
9	Customer cancels the mandate request — `mandate_cancelled_by_user`, source: internal	`amount: 302`	`code` BAD_REQUEST_ERROR `source` internal `step` payment_response `reason` mandate_cancelled_by_user	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Show an “approve the mandate in your UPI app” state. Confirm `payment.failed` and `token.rejected`. Let the customer restart.
10	Customer declines the mandate request — `mandate_cancelled_by_user`, source: customer	`amount: 304`	`code` GATEWAY_ERROR `source` customer `step` payment_authentication `reason` mandate_cancelled_by_user	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Show an “approve the mandate in your UPI app” state. Confirm `payment.failed` and `token.rejected`. Let the customer restart.
11	Customer never approves it and the request expires — `mandate_collect_request_expired`	`amount: 301`	`code` GATEWAY_ERROR `source` customer `step` payment_authentication `reason` mandate_collect_request_expired	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Show an “approve the mandate in your UPI app” state. Confirm `payment.failed` and `token.rejected`. Let the customer restart.
12	Registration fails: insufficient funds	`amount: 201`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_response `reason` insufficient_funds	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Show an “approve the mandate in your UPI app” state. Confirm `insufficient_funds`.
13	Account not allowed for Autopay	`amount: 203`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_authentication `reason` account_state_forbidden	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Show an “approve the mandate in your UPI app” state. Confirm `remitter_account_dormant` (source: customer, step: payment_debit_request).
14	Invalid UPI ID	`amount: 401`	`code` GATEWAY_ERROR `source` customer `step` payment_debit_request `reason` invalid_vpa	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Show an “approve the mandate in your UPI app” state. Confirm `invalid_vpa` and ask the customer to re-enter their UPI ID.
15	Duplicate registration request — `duplicate_request`	`amount: 406`	`code` BAD_REQUEST_ERROR `source` internal `step` payment_request `reason` duplicate_request	Register as above with the trigger amount, sending it on both the order and the authorisation payment. Confirm 400 Bad Request with `duplicate_request` (source: internal, step: payment_request) and the description “The request is duplicate”. Do not retry the same request. If the earlier payment succeeded no action is needed, otherwise start a fresh registration.
16	Bank technical error — “Your bank is temporarily unavailable. Please try again later or use a different account.”	`amount: 102`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_response `reason` bank_technical_error	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
17	Timeout at remitter bank — “Your bank took too long to respond. Please try again.”	`amount: 104`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_response `reason` timeout_at_remitter_bank	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
18	Bank technical error — “UPI Autopay setup couldn’t be completed due to a temporary issue. Any debited amount will be refunded in 4-5 business days.”	`amount: 107`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_authentication `reason` bank_technical_error	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
19	Customer invalid mobile number — “Your mobile number has been changed or removed from this account. Please update your details or use a different account.”	`amount: 202`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_debit_response `reason` customer_invalid_mobile_number	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
20	Incorrect pin entered — “Payment authorisation failed due to incorrect MPIN. Please retry with the correct MPIN.”	`amount: 204`	`code` GATEWAY_ERROR `source` customer `step` payment_initiation `reason` incorrect_pin_entered	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
21	Customer mpin not set — “UPI PIN is not set for this account. Please set up your UPI PIN and try again.”	`amount: 205`	`code` GATEWAY_ERROR `source` customer `step` payment_debit_response `reason` customer_mpin_not_set	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
22	Incorrect pin entered — “You’ve exceeded the number of PIN attempts. Please wait and try again later, or contact your bank if you’ve forgotten your PIN.”	`amount: 206`	`code` GATEWAY_ERROR `source` customer `step` payment_response `reason` incorrect_pin_entered	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
23	Transaction amount limit exceeded — “This amount is above your transaction limit. Please try a lower amount or contact your bank for assistance.”	`amount: 208`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_initiation `reason` transaction_amount_limit_exceeded	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
24	Transaction amount limit exceeded — “This amount is above your transaction limit. Please try a lower amount or contact your bank for assistance.”	`amount: 209`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_authentication `reason` transaction_amount_limit_exceeded	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
25	Transaction frequency limit exceeded — “You’ve exceeded the number of allowed transactions on this account. Please try again later or contact your bank.”	`amount: 210`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_response `reason` transaction_frequency_limit_exceeded	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
26	Account state blocked — “Your account is blocked or frozen. Please contact your bank to resolve this.”	`amount: 212`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_status_request `reason` account_state_blocked	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
27	Beneficiary account not found — “Payment authorisation failed due to a technical issue. Please try again or contact your bank if this continues.”	`amount: 213`	`code` BAD_REQUEST_ERROR `source` business `step` payment_response `reason` beneficiary_account_not_found	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
28	Risk declined by remitter bank — “Autopay setup was blocked for security reasons. Please contact your bank or use a different account.”	`amount: 404`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_response `reason` risk_declined_by_remitter_bank	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
29	Risk declined by remitter bank — “Autopay setup was declined for security reasons. Please contact your bank for assistance.”	`amount: 405`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_initiation `reason` risk_declined_by_remitter_bank	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.
30	Customer PSP fingerprint mismatch — “Payment was declined for security reasons. Please contact your bank for more details.”	`amount: 407`	`code` GATEWAY_ERROR `source` customer `step` payment_response `reason` customer_psp_fingerprint_mismatch	Create a customer, an order and the authorisation payment as in #1, using the trigger amount. Confirm the error object above, and that the token ends at `rejected`.

Auto-debit A debit on a live mandate can run on either of two flows. On the coupled flow you create the order and the payment together and Razorpay raises the pre-debit notification, schedules the debit and runs the retries for you. On the decoupled flow you send the notification object on the order, raise the notification yourself and create the payment separately once the window has passed, and no retries are run on your behalf. For the full description of both, see Subsequent Payments. These happen on a mandate that is already live. The token stays usable, so the right response is to handle the failed charge rather than to ask the customer to register again.

#	Scenario	Trigger creds	Error object	Steps to follow
31	Debit above `max_amount`	amount above the token’s `max_amount`	—	Create a debit order and a recurring payment (`POST /v1/payments/create/recurring`) for an amount higher than the token’s `max_amount`. Confirm you get 400 Bad Request with `transaction_limit_exceeded` (source: remitter_bank), and that no payment object is created.
32	Debit fails: bank error — `remitter_bank_error`	`amount: 101`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_response `reason` remitter_bank_error	Register a mandate (#1). Create a debit order and a recurring payment with the trigger amount. Confirm the failure and that your retry logic treats it as temporary.
33	Debit fails: unmapped gateway error — `gateway_technical_error`	`amount: 103`	`code` GATEWAY_ERROR `source` gateway `step` payment_response `reason` gateway_technical_error	Register a mandate (#1). Create a debit order and a recurring payment with the trigger amount. Confirm `gateway_technical_error` (source: gateway, step: payment_response). This is the simulator’s catch-all for an error it has no mapping for, so treat it as a temporary failure and retry.
34	Remitter bank unavailable — “Your bank is temporarily unavailable. Please try again in a few moments.”	`amount: 102`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_debit_request `reason` remitter_bank_unavailable	Register a mandate first. Create a debit order and a recurring payment with the trigger amount. Confirm the error object above, and that the token stays `confirmed` so the mandate can be charged again.
35	Timeout at remitter bank — “Your bank took too long to respond. Please try again.”	`amount: 104`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_debit_response `reason` timeout_at_remitter_bank	Register a mandate first. Create a debit order and a recurring payment with the trigger amount. Confirm the error object above, and that the token stays `confirmed` so the mandate can be charged again.
36	Remitter bank unavailable — “Your bank is temporarily unavailable. Please try again in a few moments.”	`amount: 107`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_request `reason` remitter_bank_unavailable	Register a mandate first. Create a debit order and a recurring payment with the trigger amount. Confirm the error object above, and that the token stays `confirmed` so the mandate can be charged again.
37	Customer mobile changed — “Your registered mobile number has been updated. Please update your UPI profile or contact your bank.”	`amount: 202`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_request `reason` customer_mobile_changed	Register a mandate first. Create a debit order and a recurring payment with the trigger amount. Confirm the error object above, and that the token stays `confirmed` so the mandate can be charged again.
38	Customer mpin not set — “UPI PIN is not set for this account. Please set up your UPI PIN and try again.”	`amount: 205`	`code` GATEWAY_ERROR `source` customer `step` payment_authentication `reason` customer_mpin_not_set	Register a mandate first. Create a debit order and a recurring payment with the trigger amount. Confirm the error object above, and that the token stays `confirmed` so the mandate can be charged again.
39	Incorrect pin entered — “You’ve exceeded the number of PIN attempts. Please wait and try again later, or contact your bank if you’ve forgotten your PIN.”	`amount: 206`	`code` GATEWAY_ERROR `source` customer `step` payment_authentication `reason` incorrect_pin_entered	Register a mandate first. Create a debit order and a recurring payment with the trigger amount. Confirm the error object above, and that the token stays `confirmed` so the mandate can be charged again.
40	Transaction limit exceeded — “Payment amount exceeds your bank’s limit. Please try with a lower amount or contact your bank to increase the limit.”	`amount: 208`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_debit_response `reason` transaction_limit_exceeded	Register a mandate first. Create a debit order and a recurring payment with the trigger amount. Confirm the error object above, and that the token stays `confirmed` so the mandate can be charged again.
41	Spending limit exceeded — “You’ve exceeded your total UPI spending limit. Please try again later or contact your bank to increase the limit.”	`amount: 209`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_debit_response `reason` spending_limit_exceeded	Register a mandate first. Create a debit order and a recurring payment with the trigger amount. Confirm the error object above, and that the token stays `confirmed` so the mandate can be charged again.
42	Frequency limit exceeded — “You’ve exceeded the number of allowed transactions. Please try again later or contact your bank.”	`amount: 210`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_initiation `reason` frequency_limit_exceeded	Register a mandate first. Create a debit order and a recurring payment with the trigger amount. Confirm the error object above, and that the token stays `confirmed` so the mandate can be charged again.
43	Account blocked — “Your account is blocked or frozen. Please contact your bank to resolve this.”	`amount: 212`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_debit_request `reason` account_blocked	Register a mandate first. Create a debit order and a recurring payment with the trigger amount. Confirm the error object above, and that the token stays `confirmed` so the mandate can be charged again.
44	Risk declined — “Payment was declined for security reasons. Please contact your bank for assistance.”	`amount: 404`	`code` BAD_REQUEST_ERROR `source` business `step` payment_debit_response `reason` risk_declined	Register a mandate first. Create a debit order and a recurring payment with the trigger amount. Confirm the error object above, and that the token stays `confirmed` so the mandate can be charged again.
45	Risk declined — “Payment was declined for security reasons. Please contact your bank for assistance.”	`amount: 405`	`code` GATEWAY_ERROR `source` remitter_bank `step` payment_debit_response `reason` risk_declined	Register a mandate first. Create a debit order and a recurring payment with the trigger amount. Confirm the error object above, and that the token stays `confirmed` so the mandate can be charged again.

If you are on the decoupled flow Everything above assumes the coupled flow, which is where most integrations start and which Razorpay recommends. If you send the notification object on the debit order you are on the decoupled flow, and four things change. Run the cases above first, then these.

What changes	Why it matters	Scenario
You raise the pre-debit notification yourself	You send `notification.token_id` and `notification.payment_after` on the order, and create the payment separately once the window has passed.	Scenario 4
Razorpay does not retry for you	A failed decoupled debit goes terminal immediately. There is no ladder and no `created` holding state, so every recovery attempt is yours to make.	Scenario 3, then retry it yourself
You retry with a new payment on the same order	Create a fresh payment against the same `order_id`. It is a new payment ID on the same notification, and it is accepted. This is the recovery loop a coupled merchant never has to build.	Scenario 4 after scenario 3
Only one debit can succeed per notification	Once a debit has succeeded against that order, any further attempt returns `mandate_already_executed`. This is what stops your retry loop double-charging.	Scenario 4 twice on one order

If you integrate against coupled behaviour and later move to decoupled without building the retry loop, every failed debit is silently lost. That is the single most expensive mistake on this flow. The full list of UPI Autopay error reasons, including the ones no trigger reproduces in test mode, is on the Error index.

3.4 Not available in test mode yet

Not being able to trigger a scenario is not a reason to leave it out of your test suite. Each row below gives the behaviour your code has to implement and the assertion worth writing now, so that the test is already in place when the trigger arrives and so that you can run it against live traffic in the meantime.

Scenario	What it is	What your integration has to do, and what to assert
46	Customer pauses, resumes or revokes in the UPI app	On `token.paused` stop debiting and hold the schedule; on `token.confirmed` resume it; on `token.cancelled` close the mandate and stop permanently. Assert that a debit attempted while your stored state is paused or cancelled is never sent to Razorpay.
47	Cancel and delete tokens	The token moves to `cancellation_initiated` first and only later to `cancelled`. It is not chargeable from the moment cancellation starts. Assert that a token in `cancellation_initiated` is treated as not chargeable, rather than waiting for `cancelled`.
48	Pre-debit notification fails	Razorpay sends `order.notification.failed` and the debit cannot proceed. A fresh order, and so a fresh notification, is required. Assert that you do not create a payment against an order whose notification failed, and that you raise a new order instead.
49	Retries and the 25-hour debit window	On the coupled flow the payment stays in `created` through every retry and only goes terminal once the ladder is exhausted. Assert that `created` is never treated as a final state and that you do not start your own recovery before a terminal status arrives.
50	Validate VPA before registering	Once available, call Validate VPA before you create the authorisation payment, so a mistyped UPI ID is caught before the mandate request goes out.
51	TPV: the payer approves the mandate from the bank account you registered them with	This only applies if you are a TPV merchant, where the payer’s bank account is fixed at onboarding. The payer picks an account inside their UPI app, and nothing stops them picking a different one. A mandate authorised from the wrong account registers successfully and then fails every single debit, so the damage does not show up until the first charge. There is no simulator UPI app and no account picker in test mode, so this cannot be reproduced here. Prompt the payer to choose their registered account before app selection, and assert that your own records tie the token back to the account you onboarded them with rather than assuming a confirmed token is chargeable.

4. Common Integration Gaps to Avoid

These are the mistakes that most often cause failed payments, missed debits or double charges after go-live. Webhook and token updates

Gap	What goes wrong in production	What to do
Token ID not stored at registration	You can’t debit the customer next cycle.	Store the token ID from `payment.authorized` against the customer.
Customer actions in the UPI app not handled	The customer pauses or revokes the mandate in their UPI app; you keep debiting.	Update token status on `token.paused`, `token.cancelled` and `token.confirmed` (resume). Treat `cancellation_initiated` as not chargeable.
Notification webhooks ignored	The pre-debit notification fails and the debit fails 25 hours later with no warning.	Subscribe to `order.notification.delivered` and `order.notification.failed` (note the `order.` prefix). Re-send a notification before a fresh debit.

Error handling and messaging to the payer

Gap	What goes wrong in production	What to do
Temporary and permanent failures handled the same	Retrying a revoked mandate burns attempts. Not retrying a bank outage loses collectable money.	Retry on `remitter_bank` and `customer_psp` errors. Stop on mandate cancelled or revoked. Notify the customer on `insufficient_funds`.
Registration failure messages not shown	The customer declines or the request expires in the UPI app, and your page just spins.	Show `error.description` and let the customer restart registration.
Customer not told a debit failed	The customer isn’t present at debit time and the plan silently lapses.	Notify the customer with the reason once the payment is final, not after the first attempt.
Collect offered for new registrations without an exemption	From 28 February 2026 these registrations fail.	Use Intent or QR for new mandates unless your business is exempt.
Invalid UPI ID not handled	The customer mistypes their UPI ID and sees a generic failure.	On `invalid_vpa`, ask them to re-enter the UPI ID.

Fetch API when webhooks are late

Gap	What goes wrong in production	What to do
Starting your own recovery while Razorpay is still retrying	On the coupled flow the payment stays `created` while retries run. A fresh order and debit from you can lead to two debit attempts.	Wait for the final status. Retries finish within about 32–120 hours depending on your retry template.
Polling too early or not at all	Live webhooks can take up to 12 minutes. Without a fallback you miss registrations during outages.	If nothing arrives within a minute, poll `GET /v1/payments/:payment_id` and the token fetch APIs.

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.	One debit order is one pre-debit notification. Each debit attempt is a payment on that 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.	On the coupled flow, the debit order stays `attempted` while Razorpay retries.	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.	Applies to the registration payment, approved in the customer’s UPI app after the Collect request.	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.	Pass `payment_capture: true` on debit orders to capture automatically.	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.	Coupled: create one payment per order; Razorpay retries under it, and extra payments you create fail. Decoupled: up to 4 payment IDs per order. After that, a new order (and a new notification) is needed.	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 Autopay 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

Token states

2. Before you begin

3. Scenarios to Test Your Integration

3.1 Must-build Autopay scenarios

3.2 Common scenarios in UPI

3.3 Autopay 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

Token states

2. Before you begin

3. Scenarios to Test Your Integration

3.1 Must-build Autopay scenarios

3.2 Common scenarios in UPI

3.3 Autopay error scenarios

3.4 Not available in test mode yet

4. Common Integration Gaps to Avoid

5. Best Integration Practices

Related Information