> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# UPI Intent: How to Test Your Integration

> Test one-time UPI Intent payments on your S2S integration in Test Mode, including success and failure scenarios.

Available in
🇮🇳 India

Run successful payments, simulate failures and reconcile against the webhooks in test mode, then check the handoff into the UPI app on real devices before you go live.

This page covers one-time UPI Intent payments on S2S: you get a `upi://` link and open the customer's UPI app on the same phone. It is the default and recommended flow on mobile.

**UPI flows:** Intent · [QR](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/one-time/upi-qr.md) · [Collect](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/one-time/upi-collect.md)

Start with the [overview](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s.md) 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 is deep-linked into their UPI app from the `upi://` link and approves the payment there with their UPI PIN. | The simulator approves or declines on its own. No request reaches a UPI app, the link does not need to be opened, and the outcome is decided by the amount you send rather than by anything the customer does. |
| Intent link | Opens the customer's UPI app on the same phone with the payment pre-filled. | An intent URL is returned so you can see the shape of the response, but no request reaches a UPI app. Use it to check that you parse and hand off the link correctly; the outcome is simulated from the amount instead. |
| App detection (Smart Intent) | Your app lists the UPI apps installed on the device so the customer can pick one, and you hand off to the one they choose. | Client-side. Not part of test mode. There is no simulator UPI app to detect or hand off to, so build this and check it on real Android and iOS 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 intent flow, and failure scenarios, using the calls in [Scenarios to test your integration](#3-scenarios-to-test-your-integration) and the reserved amounts in [3.3 UPI error scenarios](#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](#webhooks-what-fires-and-what-it-lets-you-decide) for which events fire today. |
| App detection and the deep link | Not here. There is no simulator UPI app to detect or hand off to, so build this against real Android and iOS 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 |
| 25 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](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/webhooks-and-fetch-apis.md) 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](#3-3-upi-error-scenarios) on both calls to fail with the error mapped to that amount.
* You do not need to open the intent link or approve anything in a UPI app.
* 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 Intent 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

<table>
  <colgroup>
    <col width="6%" />

    <col width="18%" />

    <col width="14%" />

    <col width="62%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger creds</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>1</td><td>Successful payment</td><td>`amount: 100`</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). 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`.</td></tr>
    <tr><td>2</td><td>Customer cancels or declines in the app</td><td>`302`, `304`</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `payment.failed` with `payment_cancelled` / `payment_declined`. The order stays open.</td></tr>
    <tr><td>3</td><td>Request times out</td><td>`105`</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `payment_timed_out`. Stop polling and let the customer retry.</td></tr>
    <tr><td>4</td><td>Fetch payment and reconcile (all methods)</td><td>A payment ID from 1 (success) and one from any row in 3.3 UPI error scenarios</td><td>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. App detection and the `upi://` deep link are client-side, so check those on real devices rather than here.</td></tr>
  </tbody>
</table>

### 3.2 Common scenarios in UPI

<table>
  <colgroup>
    <col width="6%" />

    <col width="18%" />

    <col width="14%" />

    <col width="62%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger creds</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>5</td><td>Full and partial refund (all methods)</td><td>A captured payment from 1</td><td>Refund in full and in part. Confirm `refund.processed`.</td></tr>
  </tbody>
</table>

### 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.

<table>
  <colgroup>
    <col width="5%" />

    <col width="18%" />

    <col width="10%" />

    <col width="22%" />

    <col width="45%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger creds</th><th>Error object</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>6</td><td>Bank technical error</td><td>`102`, `104`</td><td>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</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `bank_technical_error` and a retry option.</td></tr>
    <tr><td>7</td><td>Gateway technical error</td><td>`101`, `103`</td><td>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</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `gateway_technical_error`.</td></tr>
    <tr><td>8</td><td>UPI app / PSP not available</td><td>`107`</td><td>`code` GATEWAY\_ERROR\
    `source` customer\_psp\
    `step` payment\_request\
    `reason` upi\_app\_not\_available</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `upi_app_not_available` and a retry option.</td></tr>
  </tbody>
</table>

**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.

<table>
  <colgroup>
    <col width="5%" />

    <col width="18%" />

    <col width="10%" />

    <col width="22%" />

    <col width="45%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger creds</th><th>Error object</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>9</td><td>Insufficient funds</td><td>`201`</td><td>`code` GATEWAY\_ERROR\
    `source` customer\
    `step` payment\_debit\_request\
    `reason` insufficient\_funds</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `insufficient_funds` and a "use another account" message.</td></tr>
    <tr><td>10</td><td>Wrong UPI PIN</td><td>`204`</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` customer\
    `step` payment\_authentication\
    `reason` incorrect\_pin</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `incorrect_pin` and a retry option.</td></tr>
    <tr><td>11</td><td>Per-transaction limit exceeded</td><td>`208`</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` customer\
    `step` payment\_debit\_response\
    `reason` transaction\_limit\_exceeded</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `transaction_limit_exceeded` and an "amount too high" message.</td></tr>
    <tr><td>12</td><td>Daily / net debit limit exceeded</td><td>`209`</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` customer\
    `step` payment\_debit\_response\
    `reason` transaction\_limit\_exceeded</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `transaction_limit_exceeded` and a "daily limit reached, try again tomorrow" message.</td></tr>
    <tr><td>13</td><td>UPI PIN not set</td><td>`205`</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` customer\
    `step` payment\_authentication\
    `reason` pin\_not\_set</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `pin_not_set` and a "set your UPI PIN" message, not a retry-PIN prompt.</td></tr>
    <tr><td>14</td><td>UPI PIN attempts exceeded (locked)</td><td>`206`</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` customer\
    `step` payment\_authentication\
    `reason` pin\_attempts\_exceeded</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `pin_attempts_exceeded` and a "try later or use another method" message, not a retry-PIN prompt.</td></tr>
    <tr><td>15</td><td>Remitter account blocked</td><td>`212`</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` issuer\_bank\
    `step` payment\_debit\_request\
    `reason` debit\_instrument\_blocked</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `debit_instrument_blocked` and an "account blocked, use another" message.</td></tr>
    <tr><td>16</td><td>Beneficiary account does not exist</td><td>`213`</td><td>`code` GATEWAY\_ERROR\
    `source` gateway\
    `step` payment\_credit\_request\
    `reason` beneficiary\_account\_does\_not\_exist</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `beneficiary_account_does_not_exist` (receiver account inactive).</td></tr>
    <tr><td>17</td><td>Transaction frequency limit exceeded</td><td>`210`</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` business\
    `step` payment\_initiation\
    `reason` transaction\_frequency\_limit\_exceeded</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `transaction_frequency_limit_exceeded` and a "try again later" message.</td></tr>
    <tr><td>18</td><td>Registered mobile number not found</td><td>`202`</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` customer\
    `step` payment\_request\
    `reason` mobile\_number\_invalid</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `mobile_number_invalid` and a "use another method" message.</td></tr>
    <tr><td>19</td><td>Invalid bank account</td><td>`203`</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` customer\
    `step` payment\_debit\_request\
    `reason` bank\_account\_invalid</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `bank_account_invalid` and a "use another account" message.</td></tr>
  </tbody>
</table>

**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.

<table>
  <colgroup>
    <col width="5%" />

    <col width="18%" />

    <col width="10%" />

    <col width="22%" />

    <col width="45%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger creds</th><th>Error object</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>20</td><td>Declined by bank or risk check</td><td>`402`, `404`</td><td>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</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `payment_risk_check_failed` / `payment_declined`.</td></tr>
    <tr><td>21</td><td>API validation errors (all methods)</td><td>Missing `amount`, `amount: 0`, wrong key secret</td><td>—</td><td>Send each bad request. Confirm HTTP 4xx, no payment created, no webhook.</td></tr>
    <tr><td>22</td><td>Invalid UPI ID (VPA resolution failed)</td><td>`401`</td><td>`code` GATEWAY\_ERROR\
    `source` network\
    `step` payment\_request\
    `reason` vpa\_resolution\_failed</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `vpa_resolution_failed` and an "incorrect UPI ID" message.</td></tr>
    <tr><td>23</td><td>Invalid device</td><td>`407`</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` customer\
    `step` payment\_authentication\
    `reason` invalid\_device</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `invalid_device` and a "use another method" message.</td></tr>
    <tr><td>24</td><td>Duplicate request</td><td>`406`</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` gateway\
    `step` payment\_request\
    `reason` duplicate\_request</td><td>Create an order with the trigger amount. Create the payment: `POST /v1/payments/create/upi` with `upi.flow: "intent"`. Read the `upi://` link (in test mode you don't need to open it). Confirm `duplicate_request` (temporary) and allow retry.</td></tr>
  </tbody>
</table>

The full list of UPI error reasons, including the ones no trigger reproduces in test mode, is on the [Error index](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/error-index.md).

### 3.4 Not available in test mode yet

| # | Scenario |
| - | - |
| 25 | Late authorisation — Live only. Handle `payment.authorized` arriving after you showed failure (up to 3 days). Check in a controlled live test. |
| 26 | Detect installed UPI apps and open the deep link — Client-side. Test app detection (Smart Intent on Android) and the `upi://` deep link on real Android and iOS devices. |
| 27 | Customer returns to your app after approving — Client-side. Approve in a real UPI app and check your app resumes and shows the result from the webhook or a poll. |
| 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 — 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 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 link 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 |
| Relying on the app returning to you | The customer approves in the UPI app but never switches back, so your page never learns the result. | Resolve the payment from the webhook, and poll when your app comes back to the foreground. | 4, 27 |

**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. | 9, 10, 6 |
| No fallback when no UPI app is installed | The deep link does nothing and the customer is stuck. | Detect installed apps first; if none, offer QR or another method. | 26 |

**Intent link and app switching**

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Rebuilding the intent link yourself | You reconstruct `pa`, `am`, `cu` or `tr` and the UPI app rejects the link or shows the wrong amount. | Open `next[].action: "intent"` verbatim. The only change allowed is the iOS scheme rewrite below. | 26 |
| Android 11+ `<queries>` not declared | App detection returns nothing, so you target the wrong package and `startActivity` throws `ActivityNotFoundException`. | Declare the UPI packages in `<queries>`. Catch the exception, re-fire without `setPackage` so the native chooser opens, then fall back to QR. | 26 |
| Opening `upi://` directly on iOS | Nothing happens — iOS cannot open `upi://`, so the customer sees a dead button. | Keep everything after the `?` and swap `upi://pay` for the app's own path (`tez://upi/pay`, `phonepe://pay`, `paytmmp://upi/pay`). URL-encode the query, declare the schemes in `LSApplicationQueriesSchemes`, and handle the `open()` completion callback. | 26 |
| Treating "the app never opened" as a failed payment | The payment already exists on Razorpay. You mark it failed locally and the customer pays anyway. | The payment is created before the app switch. Resolve it from the webhook or a fetch, never from whether the deep link opened. | 4, 27 |

**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 ↗](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/payment-states-and-late-authorisation.md). | 25 (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 time the customer opens the intent link again, that is a new payment on the same order. | BP-24, BP-25 | [Difference between order and payment ↗](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/order-payment-relationship.md) |
| 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 customer is in the UPI app. | BP-09 | [Order states ↗](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/payment-states-and-late-authorisation.md) · [Orders API error codes ↗](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) |
| 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 ↗](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/payment-states-and-late-authorisation.md) |
| 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 ↗](https://razorpay.com/docs/payments/payment-gateway/rainy-day/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 a QR and also open the intent link. Only one payment captures; the other is auto-refunded. | BP-09 · BP-08 | [Multiple payments on the same order ↗](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/payment-states-and-late-authorisation.md) |

All best practices: [Overview](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices) · [Webhooks and Fetch APIs](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/webhooks-and-fetch-apis.md) · [Payment states and late authorisation](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/payment-states-and-late-authorisation.md) · [Error handling](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/error-handling.md) · [Downtime handling](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/downtime-handling.md) · [Security](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/security.md)

### Related Information

* [UPI QR (One-time)](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/one-time/upi-qr.md)
* [UPI Collect (One-time)](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/one-time/upi-collect.md)
* [Cards (One-time)](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/one-time/cards.md)
* [Orders](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md)
* [Refunds](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/refunds.md)
* [Best Practices](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices)
