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 for test keys and webhook setup.
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
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.
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.
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.capturedlands beforeorder.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 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. Request errors on the order are the same for every method; run them once.
- 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 as
contact. - Any amount works; the contact number decides the outcome.
Test banks
Reserved contact numbers
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 byerror.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
| # | Scenario | Trigger creds | Steps to follow |
|---|---|---|---|
| 1 | Successful payment (non-TPV) | Any bank from GET /v1/methods + any normal contact number | Create an order (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. |
| 2 | Successful payment (TPV) | TPV-enabled test account + a test account number in the order (bank_account.account_number): coming soon | 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. |
| 3 | Customer cancels | Reserved contact: phone number ending with 07 | Create an order (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. |
| 4 | Customer drops off mid-way | Reserved contact: phone number ending with 06 | Create an order (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. |
| 5 | Verify the callback signature | A payment from scenario 1 | 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. |
| 6 | Fetch the payment and reconcile | A payment ID from scenario 1 and one from any 3.3 row | 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. |
3.2 Common scenarios in netbanking
| # | Scenario | Trigger creds | Steps to follow |
|---|---|---|---|
| 7 | Fetch supported banks | — | 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. |
| 8 | Full and partial refund | A captured payment from scenario 1 | 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. |
| 9 | Manual capture | Any normal contact, with manual capture | 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. |
| 10 | Partner (Shopify) payment with the parent key | Parent merchant key in the header (coming soon) | 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. |
| 11 | Retry on the same order after a failure | Scenario 15’s reserved number, then a normal number | 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. |
| 12 | Corporate netbanking payment | A corporate bank code (ends in _C) + any normal contact | Create an order (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. |
| 13 | Corporate maker-checker approval | A corporate bank code (ends in _C) + the maker-checker reserved contact (coming soon) | Create an order (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. |
3.3 Netbanking error scenarios
Send the reserved contact number ascontact 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.
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.
| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 14 | Invalid credentials | Reserved contact: phone number ending with 03 | code BAD_REQUEST_ERRORsource customerstep payment_authenticationreason authentication_faileddescription “Your payment could not be completed due to incorrect account details. Try again.” | Create an order (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. |
| 15 | Insufficient balance | Reserved contact: phone number ending with 08 | code BAD_REQUEST_ERRORsource customerstep payment_authorizationreason insufficient_fundsdescription “Your payment could not be completed due to insufficient account balance. Try again with another account.” | Create an order (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. |
| 16 | Customer cancelled | Reserved contact: phone number ending with 07 | code BAD_REQUEST_ERRORsource customerstep payment_authenticationreason payment_cancelleddescription “Your payment has been cancelled. Try again or complete the payment later.” | Create an order (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. |
| 17 | Customer dropped off mid-way | Reserved contact: phone number ending with 06 | code BAD_REQUEST_ERRORsource customerstep payment_authenticationreason payment_timed_outdescription “Your payment has been cancelled. Try again or complete the payment later.” | Create an order (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. |
| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 18 | Bank-side error | Reserved contact: phone number ending with 01 | code GATEWAY_ERRORsource bankstep payment_authorizationreason bank_technical_errordescription “Your payment didn’t go through due to a temporary issue. Any debited amount will be refunded in 4-5 business days.” | Create an order (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. |
| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 19 | Bank not enabled for your account | bank: a code that isn’t enabled on your test account | code BAD_REQUEST_ERRORsource businessstep payment_initiationreason bank_not_enableddescription “Your payment could not be completed as this bank is not enabled by the business. To complete the payment, use another account.” | Create an order (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. |
| 20 | Missing or invalid order ID | Omit order_id, or send one that doesn’t exist | code BAD_REQUEST_ERRORsource businessstep payment_initiationreason invalid_order_iddescription “Your payment could not be completed due to a temporary technical issue. To complete the payment, use another payment method.” | Create an order (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. |
| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 21 | TPV account mismatch | TPV-enabled test account + the mismatch test account number in the order (bank_account.account_number): coming soon | code BAD_REQUEST_ERRORsource customerstep payment_authorizationreason bank_account_validation_faileddescription “Your payment is declined due to a mismatch in account details. Try again with the account registered with the business only.” | 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. |
3.4 Not available in test mode yet
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
Error handling and messaging to the payer
Redirect and bank selection
Fetch API when webhooks are late
Refunds, TPV and partner payments