Skip to main content
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.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 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.
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 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 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

#ScenarioTrigger credsSteps to follow
1Successful payment (non-TPV)Any bank from GET /v1/methods + any normal contact numberCreate 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.
2Successful payment (TPV)TPV-enabled test account + a test account number in the order (bank_account.account_number): coming soonCreate 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.
3Customer cancelsReserved contact: phone number ending with 07Create 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.
4Customer drops off mid-wayReserved contact: phone number ending with 06Create 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.
5Verify the callback signatureA payment from scenario 1On 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.
6Fetch the payment and reconcileA payment ID from scenario 1 and one from any 3.3 rowCall 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

#ScenarioTrigger credsSteps to follow
7Fetch 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.
8Full and partial refundA captured payment from scenario 1Refund 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.
9Manual captureAny normal contact, with manual captureCreate 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.
10Partner (Shopify) payment with the parent keyParent 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.
11Retry on the same order after a failureScenario 15’s reserved number, then a normal numberRun 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.
12Corporate netbanking paymentA corporate bank code (ends in _C) + any normal contactCreate 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.
13Corporate maker-checker approvalA 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 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. 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.
#ScenarioTrigger credsError objectSteps to follow
14Invalid credentialsReserved contact: phone number ending with 03code 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.”
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.
15Insufficient balanceReserved contact: phone number ending with 08code 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.”
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.
16Customer cancelledReserved contact: phone number ending with 07code BAD_REQUEST_ERROR
source customer
step payment_authentication
reason payment_cancelled
description “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.
17Customer dropped off mid-wayReserved contact: phone number ending with 06code 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.”
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.
Bank errors The customer’s bank couldn’t complete the debit. These are usually temporary: offer a retry later or another bank.
#ScenarioTrigger credsError objectSteps to follow
18Bank-side errorReserved contact: phone number ending with 01code 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.”
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.
Business errors Your request was wrong. Fix the request; the customer can’t.
#ScenarioTrigger credsError objectSteps to follow
19Bank not enabled for your accountbank: a code that isn’t enabled on your test accountcode 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.”
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.
20Missing or invalid order IDOmit order_id, or send one that doesn’t existcode 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.”
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.
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.
#ScenarioTrigger credsError objectSteps to follow
21TPV account mismatchTPV-enabled test account + the mismatch test account number in the order (bank_account.account_number): coming sooncode 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.”
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

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.
Last modified on November 17, 2026