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

# Netbanking: How to Test Your Integration

> Test one-time Netbanking payments on your S2S integration in Test Mode, including success, TPV, corporate and failure scenarios.

Available in
🇮🇳 India

Run successful payments, simulate failures with reserved contact numbers and reconcile against the webhooks in test mode, then check refunds, TPV and the fetch APIs before you go live.

This page covers one-time Netbanking payments on S2S JSON (`POST /v1/payments/create/json` with `method`=`netbanking`), including TPV (third-party validation) and partner (Shopify) payments.

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 |
| - | - | - |
| Authentication | The customer is redirected to their bank's netbanking page, logs in and approves the debit. | The customer is redirected to a mock bank page instead. It shows options, but the outcome is decided by the `contact` (phone) number sent in the API, not by what is chosen on the page. |
| Banks | The banks enabled on your live account, which depend on onboarding approvals. | `GET /v1/methods` returns a test bank list for your business category. It isn't copied from live mode. |
| TPV | The bank checks that the payer's account matches the account on the order. | Enabled separately on your test account. The outcome is controlled by the test account number you send in the order (`bank_account`), not by a real customer account. |
| Corporate approval (maker-checker) | On corporate banks, one user (the maker) starts the payment and another (the checker) approves it later in the bank's portal. The payment can stay pending for hours or days until the checker acts. | There is no real checker. Send the maker-checker reserved number and the payment stays pending, then is approved after a short simulated delay (scenario 13). |
| Webhook delivery | Razorpay sends the webhook once the bank confirms the debit. That round trip is real, so delivery can take minutes and your reconciler has to allow for it. | The bank is simulated, so the webhook is sent almost as soon as the create-payment request succeeds. 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 |
| - | - |
| Payments | Success, cancel, drop-off, wrong credentials, low balance and bank errors, using the triggers in [Scenarios to test your integration](#3-scenarios-to-test-your-integration) and [3.3 Netbanking error scenarios](#3-3-netbanking-error-scenarios). |
| Banks | Fetching the supported bank list with `GET /v1/methods` and rendering retail and corporate banks. Includes the corporate maker-checker wait (scenario 13). |
| TPV | A successful payment and an account mismatch decline, controlled by the test account number in the order. Needs TPV enabled on your test account. |
| Callback and signature | The redirect back to your `callback_url` and verifying `razorpay_signature`. |
| Reconciliation | Fetching a payment by ID and fetching the payments on an order, so you can prove your reconciler agrees with the webhook. |
| Capture | Manual capture of an authorised payment. |
| Refunds | Full and partial refunds on a captured payment. |
| Partner (Shopify) payments | Payments where the partner sends only the parent merchant key in the request header. Coming soon. |
| Webhooks | Payment, order and refund webhooks for each of the above. See [Webhooks: what fires, and what it lets you decide](#webhooks-what-fires-and-what-it-lets-you-decide). |
| Intent and QR, downtime webhooks | Coming soon. Downtime webhooks are covered in [3.4 Not available in test mode yet](#3-4-not-available-in-test-mode-yet). |

### Endpoint coverage in test mode

| API | Endpoint | Available on test mode |
| - | - | - |
| Fetch supported banks | `GET /v1/methods` | Available |
| Create an order | `POST /v1/orders` | Available |
| Create a payment (S2S JSON) | `POST /v1/payments/create/json` | Available |
| Fetch a payment | `GET /v1/payments/:id` | Available |
| Fetch payments on an order | `GET /v1/orders/:id/payments` | Available |
| Capture a payment | `POST /v1/payments/:id/capture` | Available |
| Refund a payment | `POST /v1/payments/:id/refund` | Available |
| Fetch a refund | `GET /v1/payments/:id/refunds/:refund_id` | Available |
| Fetch bank 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. | Available |
| `payment.failed` | The payment attempt fails. | Available |
| `order.paid` | The order is fully paid. | Available |
| `refund.created` | A refund is accepted. | Available |
| `refund.processed` | A refund has left Razorpay. | Available |
| `refund.failed` | A refund could not be processed. | Coming soon |
| `payment.downtime.started`, `payment.downtime.resolved` | A bank goes down, then recovers. | Coming soon |

**Which webhooks each scenario fires**

Netbanking events arrive in an order that matters, and each one entitles you to do something different. Most integration bugs that reach production are not missing webhooks; they are acting on the wrong one.

| Scenario | Webhooks, in order | What each one lets you decide | In test mode |
| - | - | - | - |
| 1, 2, 12, 13 Successful payment, TPV, corporate, maker-checker | `payment.authorized`, `payment.captured`, `order.paid` | `payment.authorized`: funds are held for you but they're not yet yours. Do not fulfil services on this alone. `payment.captured`: funds are yours, fulfil services on this. `order.paid`: the order is settled and will not accept another payment. Close the cart and stop any retry loop. | Available |
| 3, 4, 14–18, 21 Cancelled, dropped off, declined, TPV mismatch | `payment.failed` | `payment.failed`: this attempt is over. The error `reason` tells you whether to offer the same method again or move the customer to another one. | Available |
| 9 Manual capture | `payment.authorized`, `payment.captured` | `payment.authorized`: funds are held, not yours yet. `payment.captured`: funds are yours, fulfil services on this. | Available |
| 8 Full and partial refund | `refund.created`, `refund.processed`, `refund.failed` | `refund.created`: the refund is accepted, not settled. Do not tell the customer the money is back yet. `refund.processed`: the money has left Razorpay. This is when you confirm the refund to the customer. `refund.failed`: the refund did not go through. It needs a retry or a manual payout. | Available (`refund.failed` coming soon) |
| 22 Bank downtime | `payment.downtime.started`, `payment.downtime.resolved` | `payment.downtime.started`: the bank is degraded or down. Hide it or warn the customer before they pick it. `payment.downtime.resolved`: the bank has recovered. Show it again. | 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. Netbanking customers often close the bank tab after paying. 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.
* 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.
* Ask us to enable TPV on your test account if you use it. It is enabled separately from live mode, so ask for both.
* Every scenario on this page needs an order. Order behaviour has scenarios of its own on [Orders](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md). Request errors on the order are the same for every method; run them once.

In test mode the contact number you send on the create-payment call decides the outcome, because there is no real bank on the other end. Send any normal contact number and the payment succeeds. Send one of the reserved numbers below and the payment fails with the error mapped to that number.

* Use any bank code returned by `GET /v1/methods`. The bank you pick does not change the outcome.
* The mock bank page shows options, but what you choose on it doesn't change the outcome. The phone number you sent does.
* For a specific error, send its reserved number from [3.3](#3-3-netbanking-error-scenarios) as `contact`.
* Any amount works; the contact number decides the outcome.

### Test banks

| Use it to test | Bank | Notes |
| - | - | - |
| Retail netbanking | Any retail bank code from `GET /v1/methods` | Send it as `bank` on create-payment. |
| Corporate netbanking | Any corporate bank code from `GET /v1/methods` | Corporate codes end in `_C`. Some need maker-checker approval in live mode. To simulate it in test mode, send the maker-checker reserved number (scenario 13). |
| TPV | Any TPV-supported bank from the list | Send a test account number in the order: the success account for scenario 2, the mismatch account for scenario 21. Needs TPV on your test account. |

### Reserved contact numbers

| Use it to test | Contact number | Returns |
| - | - | - |
| Successful payment | Any number not listed below | `captured` (or `authorized` with manual capture) |
| Invalid credentials | Phone number ending with 03 | `authentication_failed` |
| Customer cancelled | Phone number ending with 07 | `payment_cancelled` |
| Customer dropped off mid-way | Phone number ending with 06 | `payment_timed_out` |
| Bank-side error | Phone number ending with 01 | `bank_technical_error` |
| Insufficient balance | Phone number ending with 08 | `insufficient_funds` |
| Invalid OTP | Phone number ending with 02 | `invalid_otp` |
| Invalid account | Phone number ending with 04 | `invalid_account` |
| Payment failed | Phone number ending with 05 | `payment_failed` |

**Partner (Shopify) payments.** In partner mode, the partner sends only the parent merchant key in the request header. Everything else in the request is unchanged and behaves exactly as for a normal S2S merchant. Run scenario 10 with the parent key in the header.

## 3. Scenarios to Test Your Integration

This section lists every scenario we think is worth running against your netbanking 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 payment, TPV, the redirect and callback, and the 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: fetching banks, refunds, manual capture, partner payments, retries, corporate netbanking and the maker-checker wait. They are not errors as such, but your integration still needs to recognise them and respond correctly, so we recommend covering the ones you use before launch.

**Error scenarios.** These are failures you can bring on deliberately, with a reserved contact number or a bad API request, so that you can check your error handling without waiting for a real failure to happen. They are grouped by `error.source`, because the source tells you who has to act.

**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 netbanking scenarios

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

    <col width="18%" />

    <col width="18%" />

    <col width="58%" />
  </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 (non-TPV)</td><td>Any bank from `GET /v1/methods` + any normal contact number</td><td>[Create an order](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) (`POST /v1/orders`) and store the returned `order_id`. Create the payment with that `order_id`: `POST /v1/payments/create/json` with `method`=`netbanking`, `bank` (a code from `GET /v1/methods`), `amount`, `currency`, `email`, `contact` and `callback_url`. Redirect the customer to the URL in `next[]`. In test mode this opens the mock bank page. Whatever is chosen there, the outcome follows the `contact` number you sent. The customer returns to your `callback_url` with `razorpay_payment_id`, `razorpay_order_id` and `razorpay_signature`. Verify the signature on your server. Fulfil on `payment.captured`. Webhooks received: `payment.authorized`, `payment.captured`, `order.paid`. Status changes: the payment moves to `captured` (or `authorized` if you capture manually) and the order to `paid`.</td></tr>
    <tr><td>2</td><td>Successful payment (TPV)</td><td>TPV-enabled test account + a test account number in the order (`bank_account.account_number`): *coming soon*</td><td>Create the order with the test account in `bank_account` (`account_number`, `name`, `ifsc`). Create the payment with that `order_id` and the TPV bank, as in scenario 1. Redirect the customer to the URL in `next[]`. In test mode this opens the mock bank page. Whatever is chosen there, the outcome follows the `contact` number you sent. Confirm the payment succeeds and the account on the payment matches the order. Webhooks received: `payment.authorized`, `payment.captured`, `order.paid`.</td></tr>
    <tr><td>3</td><td>Customer cancels</td><td>Reserved contact: phone number ending with 07</td><td>[Create an order](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) (`POST /v1/orders`) and store the returned `order_id`. Create the payment with that `order_id` and the reserved number as `contact`: `POST /v1/payments/create/json` with `method`=`netbanking` and any `bank` from `GET /v1/methods`. Redirect the customer to the URL in `next[]`. In test mode this opens the mock bank page. Whatever is chosen there, the outcome follows the `contact` number you sent. Webhooks received: `payment.failed`. Confirm `payment_cancelled` (error object: scenario 16). The order stays open for a retry.</td></tr>
    <tr><td>4</td><td>Customer drops off mid-way</td><td>Reserved contact: phone number ending with 06</td><td>[Create an order](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) (`POST /v1/orders`) and store the returned `order_id`. Create the payment with that `order_id` and the reserved number as `contact`: `POST /v1/payments/create/json` with `method`=`netbanking` and any `bank` from `GET /v1/methods`. Redirect the customer to the URL in `next[]`. In test mode this opens the mock bank page. Whatever is chosen there, the outcome follows the `contact` number you sent. Webhooks received: `payment.failed`. Confirm `payment_timed_out` (error object: scenario 17). Treat it differently from a cancel: stop polling and let the customer retry on the same order. Status changes: the payment moves to `failed`; the order stays `attempted` for a retry.</td></tr>
    <tr><td>5</td><td>Verify the callback signature</td><td>A payment from scenario 1</td><td>On the callback, compute `hmac_sha256(razorpay_order_id + "|" + razorpay_payment_id, key_secret)`. Compare it with `razorpay_signature`. Reject the callback on a mismatch. Send a callback with a changed payment ID and confirm your server rejects it.</td></tr>
    <tr><td>6</td><td>Fetch the payment and reconcile</td><td>A payment ID from scenario 1 and one from any 3.3 row</td><td>Call `GET /v1/payments/:id` and `GET /v1/orders/:id/payments`. Confirm the status you stored from the webhook matches the API. Run this before trusting a callback that arrived without a webhook.</td></tr>
  </tbody>
</table>

### 3.2 Common scenarios in netbanking

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

    <col width="18%" />

    <col width="18%" />

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

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

  <tbody>
    <tr><td>7</td><td>Fetch supported banks</td><td>—</td><td>Call `GET /v1/methods` with your test key. Read the `netbanking` object and render the retail and corporate banks on your checkout. Refresh the list regularly instead of hard-coding bank codes.</td></tr>
    <tr><td>8</td><td>Full and partial refund</td><td>A captured payment from scenario 1</td><td>Refund one payment in full and another in part: `POST /v1/payments/:id/refund`. Fetch the refund: `GET /v1/payments/:id/refunds/:refund_id`. Webhooks received: `refund.created`, `refund.processed`. Confirm the refund to the customer only on `refund.processed`.</td></tr>
    <tr><td>9</td><td>Manual capture</td><td>Any normal contact, with manual capture</td><td>Create an order with `payment_capture`: `false` (or set manual capture in your test mode Dashboard). Pay as in scenario 1. Confirm the payment is `authorized`, not `captured`. Webhooks received: `payment.authorized`. Capture it: `POST /v1/payments/:id/capture` with the same `amount` and `currency`. Webhooks received: `payment.captured`. Fulfil only after this.</td></tr>
    <tr><td>10</td><td>Partner (Shopify) payment with the parent key</td><td>Parent merchant key in the header (coming soon)</td><td>Send the create-order and create-payment calls with the **parent merchant key** in the request header. Keep the rest of the request exactly as in scenario 1. Confirm the payment succeeds and the webhooks reach the sub-merchant's configured URL.</td></tr>
    <tr><td>11</td><td>Retry on the same order after a failure</td><td>Scenario 15's reserved number, then a normal number</td><td>Run scenario 15 and keep the order. Create a second payment on the **same** order with a normal contact number. Confirm the order goes `attempted` → `paid` and only one payment is `captured`.</td></tr>
    <tr><td>12</td><td>Corporate netbanking payment</td><td>A corporate bank code (ends in `_C`) + any normal contact</td><td>[Create an order](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) (`POST /v1/orders`) and store the returned `order_id`. Create the payment as in scenario 1 with a corporate `bank` code. Redirect the customer to the URL in `next[]`. In test mode this opens the mock bank page. Whatever is chosen there, the outcome follows the `contact` number you sent. Webhooks received: `payment.authorized`, `payment.captured`, `order.paid`. In live mode, corporate payments that need maker-checker approval can stay pending for hours or days. See scenario 13 for what your integration has to handle.</td></tr>
    <tr><td>13</td><td>Corporate maker-checker approval</td><td>A corporate bank code (ends in `_C`) + the maker-checker reserved contact (coming soon)</td><td>[Create an order](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) (`POST /v1/orders`) and store the returned `order_id`. Create the payment with that `order_id`, a corporate `bank` code and the maker-checker number as `contact`. Redirect the customer to the URL in `next[]`. The mock bank page stands in for the maker's step, and the customer returns to your `callback_url` before the payment is final. Confirm the payment is pending, not failed. Show "waiting for approval in your bank" and keep the order open. Don't ask the customer to pay again. The checker's approval is simulated after a short delay. Webhooks received: `payment.authorized`, `payment.captured`, `order.paid`. Fulfil on `payment.captured`. Check that your reconciler kept polling through the wait and didn't time the order out. In live mode the wait can be hours or days.</td></tr>
  </tbody>
</table>

### 3.3 Netbanking error scenarios

Send the reserved contact number as `contact` on `POST /v1/payments/create/json`. Each number returns the error in its row. Branch your handling on `error.reason` and `error.source`, never on the description text. Errors from creating the order (bad `amount`, `currency`, `receipt` and so on) are on [Orders](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md).

**Customer errors**

The customer entered something wrong, stopped the payment or doesn't have the money. Wrong credentials and a cancel are recoverable: let them try again. Low balance is not: ask them to use another account or method.

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

    <col width="16%" />

    <col width="16%" />

    <col width="22%" />

    <col width="41%" />
  </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>14</td><td>Invalid credentials</td><td>Reserved contact: phone number ending with 03</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` customer\
    `step` payment\_authentication\
    `reason` authentication\_failed\
    `description` "Your payment could not be completed due to incorrect account details. Try again."</td><td>[Create an order](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) (`POST /v1/orders`) and store the returned `order_id`. Create the payment with that `order_id` and the reserved number as `contact`: `POST /v1/payments/create/json` with `method`=`netbanking` and any `bank` from `GET /v1/methods`. Redirect the customer to the URL in `next[]`. In test mode this opens the mock bank page. Whatever is chosen there, the outcome follows the `contact` number you sent. Webhooks received: `payment.failed`. Confirm `authentication_failed` and show `error.description`. Offer a retry on the same bank.</td></tr>
    <tr><td>15</td><td>Insufficient balance</td><td>Reserved contact: phone number ending with 08</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` customer\
    `step` payment\_authorization\
    `reason` insufficient\_funds\
    `description` "Your payment could not be completed due to insufficient account balance. Try again with another account."</td><td>[Create an order](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) (`POST /v1/orders`) and store the returned `order_id`. Create the payment with that `order_id` and the reserved number as `contact`: `POST /v1/payments/create/json` with `method`=`netbanking` and any `bank` from `GET /v1/methods`. Redirect the customer to the URL in `next[]`. In test mode this opens the mock bank page. Whatever is chosen there, the outcome follows the `contact` number you sent. Webhooks received: `payment.failed`. Confirm `insufficient_funds` and show `error.description`. Show a "use another account or method" message.</td></tr>
    <tr><td>16</td><td>Customer cancelled</td><td>Reserved contact: phone number ending with 07</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` customer\
    `step` payment\_authentication\
    `reason` payment\_cancelled\
    `description` "Your payment has been cancelled. Try again or complete the payment later."</td><td>[Create an order](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) (`POST /v1/orders`) and store the returned `order_id`. Create the payment with that `order_id` and the reserved number as `contact`: `POST /v1/payments/create/json` with `method`=`netbanking` and any `bank` from `GET /v1/methods`. Redirect the customer to the URL in `next[]`. In test mode this opens the mock bank page. Whatever is chosen there, the outcome follows the `contact` number you sent. Webhooks received: `payment.failed`. Confirm `payment_cancelled` and show `error.description`. Keep the order open for a retry.</td></tr>
    <tr><td>17</td><td>Customer dropped off mid-way</td><td>Reserved contact: phone number ending with 06</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` customer\
    `step` payment\_authentication\
    `reason` payment\_timed\_out\
    `description` "Your payment has been cancelled. Try again or complete the payment later."</td><td>[Create an order](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) (`POST /v1/orders`) and store the returned `order_id`. Create the payment with that `order_id` and the reserved number as `contact`: `POST /v1/payments/create/json` with `method`=`netbanking` and any `bank` from `GET /v1/methods`. Redirect the customer to the URL in `next[]`. In test mode this opens the mock bank page. Whatever is chosen there, the outcome follows the `contact` number you sent. Webhooks received: `payment.failed`. Confirm `payment_timed_out` and show `error.description`. Stop polling and let the customer retry. Distinct from an explicit cancel.</td></tr>
  </tbody>
</table>

**Bank errors**

The customer's bank couldn't complete the debit. These are usually temporary: offer a retry later or another bank.

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

    <col width="16%" />

    <col width="16%" />

    <col width="22%" />

    <col width="41%" />
  </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>18</td><td>Bank-side error</td><td>Reserved contact: phone number ending with 01</td><td>`code` GATEWAY\_ERROR\
    `source` bank\
    `step` payment\_authorization\
    `reason` bank\_technical\_error\
    `description` "Your payment didn't go through due to a temporary issue. Any debited amount will be refunded in 4-5 business days."</td><td>[Create an order](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) (`POST /v1/orders`) and store the returned `order_id`. Create the payment with that `order_id` and the reserved number as `contact`: `POST /v1/payments/create/json` with `method`=`netbanking` and any `bank` from `GET /v1/methods`. Redirect the customer to the URL in `next[]`. In test mode this opens the mock bank page. Whatever is chosen there, the outcome follows the `contact` number you sent. Webhooks received: `payment.failed`. Confirm `bank_technical_error` and show `error.description`. Offer a retry later or a different bank.</td></tr>
  </tbody>
</table>

**Business errors**

Your request was wrong. Fix the request; the customer can't.

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

    <col width="16%" />

    <col width="16%" />

    <col width="22%" />

    <col width="41%" />
  </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>19</td><td>Bank not enabled for your account</td><td>`bank`: a code that isn't enabled on your test account</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` business\
    `step` payment\_initiation\
    `reason` bank\_not\_enabled\
    `description` "Your payment could not be completed as this bank is not enabled by the business. To complete the payment, use another account."</td><td>[Create an order](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) (`POST /v1/orders`) and store the returned `order_id`. Create the payment with a `bank` code that isn't enabled for you. Confirm the API returns the error synchronously; no payment is created and no webhook fires. Refresh your bank list from `GET /v1/methods`.</td></tr>
    <tr><td>20</td><td>Missing or invalid order ID</td><td>Omit `order_id`, or send one that doesn't exist</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` business\
    `step` payment\_initiation\
    `reason` invalid\_order\_id\
    `description` "Your payment could not be completed due to a temporary technical issue. To complete the payment, use another payment method."</td><td>[Create an order](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) (`POST /v1/orders`) and store the returned `order_id`. Create the payment without `order_id`, then again with a made-up one. Confirm the API returns the error synchronously; no payment is created and no webhook fires.</td></tr>
  </tbody>
</table>

**TPV errors**

The customer paid from a bank account that isn't the one registered on the order. They can't fix this by retrying: ask them to pay from the registered account.

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

    <col width="16%" />

    <col width="16%" />

    <col width="22%" />

    <col width="41%" />
  </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>21</td><td>TPV account mismatch</td><td>TPV-enabled test account + the mismatch test account number in the order (`bank_account.account_number`): coming soon</td><td>`code` BAD\_REQUEST\_ERROR\
    `source` customer\
    `step` payment\_authorization\
    `reason` bank\_account\_validation\_failed\
    `description` "Your payment is declined due to a mismatch in account details. Try again with the account registered with the business only."</td><td>Create the order with the mismatch test account in `bank_account` (`account_number`, `name`, `ifsc`). Create the payment with that `order_id` and the TPV bank, as in scenario 2. Redirect the customer to the URL in `next[]`. In test mode this opens the mock bank page. Whatever is chosen there, the outcome follows the `contact` number you sent. Webhooks received: `payment.failed`. Confirm `bank_account_validation_failed` and show `error.description`. Ask them to pay from the account registered on the order; don't offer a plain retry. Status changes: the payment moves to `failed`; the order stays `attempted`.</td></tr>
  </tbody>
</table>

### 3.4 Not available in test mode yet

| # | Scenario | What your integration has to do, and what to assert |
| - | - | - |
| 22 | Bank downtime webhooks — Coming soon | Hide or flag a bank on `payment.downtime.started` and show it again on `payment.downtime.resolved`. Check in live mode. |
| 23 | `refund.failed` — Coming soon | Retry the refund or send a manual payout. It will not resolve itself. |
| 24 | Late authorisation — Live only | Handle `payment.authorized` arriving after you showed a failure (up to 3 days). Common on netbanking when the bank's response is delayed. Check in a controlled live test. |

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

**Webhooks and callbacks**

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Fulfilling on the checkout callback | The customer closes the bank tab or loses network after paying. You never get the callback, so a paid order looks unpaid. | Fulfil on `payment.captured` or `order.paid`. Treat the callback as a hint, not proof. | 1, [Webhooks](#webhooks-what-fires-and-what-it-lets-you-decide) |
| Skipping the callback signature | A forged callback marks an order paid. | Verify `razorpay_signature` on every callback. | 5 |
| Duplicate or unsigned events processed | One payment fulfils twice, or a forged event marks an order paid. | Verify `X-Razorpay-Signature`. Store event IDs and skip repeats. | [Webhooks](#webhooks-what-fires-and-what-it-lets-you-decide) |

**Error handling and messaging to the payer**

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Showing raw codes | The customer sees `BAD_REQUEST_ERROR` and drops off. | Show `error.description`. It is written for the customer. | 14–18 |
| Same message for every failure | A customer with low balance retries the same account again and again. | Branch on `error.reason` and `error.source`: retry on `authentication_failed`, another account on `insufficient_funds`, retry later or another bank on `bank_technical_error`. | 14, 15, 18 |
| Treating a drop-off as a cancel | You close the order on a timeout and the customer can't finish paying. | Keep the order open on `payment_timed_out` and let the customer retry on the same order. | 4, 16, 17 |

**Redirect and bank selection**

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Building the bank page URL yourself | You hard-code or rebuild the bank URL and the customer lands on an error page. | Redirect to the URL in `next[]` exactly as returned. | 1 |
| Hard-coded bank list | A bank is removed, renamed or not enabled for you, and payments to it fail. | Load banks from `GET /v1/methods` and refresh the list regularly. | 7, 19 |

**Fetch API when webhooks are late**

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Waiting forever for the webhook | The webhook is delayed and the order sits in limbo. | Poll `GET /v1/payments/:id` with back-off until the payment reaches a final state. | 6 |
| Ignoring late authorisation | A payment you marked failed becomes authorised hours later and is never fulfilled or refunded. | Listen for `payment.authorized` on failed orders; capture it or let it auto-refund. | 24 |
| Treating a pending corporate payment as failed | A corporate payment waiting for the checker is shown as failed. The customer pays again, then the checker approves and the customer is charged twice. | Keep the order open, show "waiting for approval", and poll on a long schedule. Retry on the same order so a late approval on a paid order is auto-refunded. | 12, 13 |

**Refunds, TPV and partner payments**

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Confirming a refund too early | The customer is told the money is back, but the refund later fails. | Confirm on `refund.processed`, not on the refund API response. | 8 |
| TPV account missing on the order | TPV payments fail because the payer's account wasn't sent on the order. | Pass `bank_account` on every TPV order, and show a "pay from your registered account" message on a mismatch. | 2, 21 |
| Partner key mix-up | Sub-merchant payments fail because the wrong key is sent in the header. | In partner mode, send only the parent merchant key in the request header. | 10 |

## 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. | A cancelled netbanking attempt and the retry with another bank are two payments on one 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. | Run scenario 15 then scenario 1 on the same order: the order should go `attempted` → `paid`. | 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`. Listen for `payment.authorized` and capture it, or let it auto-refund. | More common on netbanking than on cards, because bank responses are often delayed. | 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. | Manual capture in test mode is scenario 9. | 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. | Reuse the order when the customer retries after a cancel or a drop-off. | BP-09 | [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) |
| Downtime handling | Banks go down. Show the customer which banks are affected before they pick one, instead of letting the payment fail. | Use `payment.downtime.*` webhooks or `GET /v1/payments/downtimes`. Coming soon in test mode. | BP-17, BP-36 | [Payment downtime ↗](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/downtime-handling.md) |

### Related Information

* [UPI Intent (One-time)](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/one-time/upi-intent.md)
* [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)
