Skip to main content
Available in🇮🇳 India
Test Mode lets you run your whole integration against simulated banks, card networks and NPCI before you take real payments. You use the same APIs as in live mode. Only the keys change.
Methods available for testingTest Mode for S2S currently supports Cards, UPI Intent, UPI QR and UPI Collect for one-time payments, and Card recurring, UPI Autopay Intent, UPI Autopay QR and UPI Autopay Collect for recurring payments. More methods are coming soon.
This guide is in five parts, in the order you should test:
  1. This overview — setup and the S2S payment flow.
  2. Orders — create orders and test every order scenario.
  3. Refunds — test Normal and Instant refunds, failures and the fallback between them.
  4. Best Practices — webhooks, reconciliation, retries, late authorisation and more.
  5. The page for each method you integrate. Method pages all follow the same structure, so once you’ve read one you know where to find anything on another.

Build Your Test Plan

Pick what you are integrating and read the matching pages in order. Scenario IDs are the same on every page and in support conversations, so you can reference them when you raise a ticket.

1. Before You Begin

  1. Switch the Dashboard to Test Mode with the toggle at the top.
  2. Generate test keys: Account & Settings → API Keys → Generate Test Key. Test keys start with rzp_test_.
  3. Use the same endpoints (https://api.razorpay.com) and request bodies as live mode. Nothing else changes.
  4. Add a test-mode webhook URL with a secret: Account & Settings → Webhooks. Subscribe to the events your method pages list.
Watch Out!No real money moves in Test Mode. Test VPAs, test tokens and test mandates work only in Test Mode. Webhooks set up in Test Mode do not carry over to live mode — set them up again before you go live.

2. The S2S Payment Flow

Every S2S payment follows the same eight steps. Only step 4, the next action, depends on the method. Each step has tests on one of the pages below.
1

Customer pays

Your payment page collects the method details. Only methods enabled on your account are shown and methods that are down are hidden.
2

Create a customer (recurring only)

Your server calls POST /v1/customers and stores customer_id. Card mandates and UPI Autopay need it on the authorisation order; one-time payments do not. Test a valid customer, a duplicate customer and a malformed contact or email.
3

Create order

Your server calls POST /v1/orders and stores the order_id. Test a valid order, every request error and retries with unique_receipt. See Orders.
4

Create payment

Your server calls the create-payment API with the method details and the real ip, user_agent and referer. Test success and failure triggers and a timed-out create.
5

Show the next action

Razorpay returns redirect, otp_submit, intent or poll. Test each next action your method returns.
6

Customer authenticates

3DS, OTP, UPI PIN or bank login. Test authentication success and failure triggers.
7

Callback: verify the signature

The customer returns with razorpay_payment_id, razorpay_order_id and razorpay_signature. Verify the signature against the stored order_id and reject a tampered value.
8

Webhook: fulfil

order.paid or payment.captured arrives. Fulfil once, only from the webhook. Test duplicates and out-of-order events.
9

No webhook in time? Fetch

Your reconciler calls GET /v1/orders/:id/payments. Test a missing webhook, a down endpoint and late authorisation.

3. How Simulation Works

There is no real bank on the other end, so you pick the outcome through the input you send. Cards use the card number; UPI uses the amount. UPI reserved amounts follow one pattern. Amounts are in paise, so 201 is ₹2.01. Each method page lists its own test cards or reserved amounts under “Test Kit” and the exact error.reason each one triggers under “Simulate Failures”. The same amount means the same cause on UPI one-time and UPI Autopay.
Handy TipsTesting recurring on cards and UPI? A card debit reaches its final state about 5 minutes after you create it; a UPI Autopay debit settles immediately. Poll GET /v1/payments/:id with a timeout instead of asserting straight after creation, or your automated tests will be flaky.

4. Read the Error Object

Every failure returns the same five fields. Build your handling on reason and source. Do not match on description — it is customer-facing text and can change.

5. Two Kinds of Errors

6. Webhooks and Reconciliation

  • Verify X-Razorpay-Signature with your webhook secret on every event. Reject anything that fails.
  • Return 2xx quickly and process asynchronously.
  • Webhooks are delivered at least once. Use the event ID to process each one once.
  • In Test Mode, webhooks arrive almost instantly. In live mode they can take up to 12 minutes. If nothing arrives within a minute, poll GET /v1/payments/:id.
  • When your records and the API disagree, the API is the source of truth.

7. What Test Mode Can’t Do

Every method page marks what you can test with one of these labels:

8. Go-Live Checklist

See the full Go-Live Checklist for the complete walkthrough. The essentials: Every method
  • Every scenario in your test plan passes.
  • Live keys (rzp_live_) and a live webhook URL and secret are in place. Test cards and test VPAs fail in live mode.
  • Signatures are verified on checkout callbacks and on webhooks.
  • Duplicate webhooks are ignored.
  • Failures are handled by error.reason and error.source, not by description text.
  • Polling GET /v1/payments/:id works as a fallback when webhooks are late.
  • You’ve noted your platform, checkout type and SDK versions, so you can upgrade cleanly.
One-time methods (Cards, UPI)
  • Fulfil on payment.captured (or order.paid), never on the checkout callback alone.
  • Handle the dismiss or cancel callback on Standard and Custom Checkout, so a closed checkout doesn’t leave the order in limbo.
  • Retry logic treats customer failures differently from bank and gateway failures.
  • Auto-capture settings match your refund policy.
Recurring methods (Card recurring, UPI Autopay)
  • Methods enabled. Recurring is enabled per method, and separately for test and live mode.
  • Authorisation order. The token object carries the right max_amount, frequency, expire_at and, where relevant, auth_type, recurring_type and recurring_value.
  • Recurring flag. Always send recurring and customer_id. Without the flag the payment silently becomes one-time and no token is created.
  • Signatures. Verify razorpay_signature on the checkout callback, then fetch the payment before granting service.
  • Failure handling. Tell temporary bank errors apart from permanent token failures. Retrying a dead token causes needless churn.
  • Token management. Integrate fetch token by payment ID, fetch tokens by customer ID, cancel token and delete token. Check token state before every debit.
  • Capture and late auth. Set auto-capture windows deliberately. Reconcile on the state at capture time so late authorisations aren’t dropped.
  • Webhooks with a fallback. Subscribe to at least token.confirmed, token.cancelled, payment.captured and payment.failed. Use the fetch APIs when webhooks are late.
  • Refunds. Set payment_capture to manual on the authorisation payment if you don’t want it auto-refunded. Integrate the Refunds API for debits.
  • SDK versions. Record your platform, checkout type and server SDK version.

Method Testing

Cards (One-time)

Test one-time card payments, authentication, saved cards and tokens.

UPI Intent (One-time)

Test one-time UPI Intent payments.

UPI QR (One-time)

Test one-time UPI QR payments.

UPI Collect (One-time)

Test one-time UPI Collect payments.

Card Recurring (Recurring)

Test card mandate registration and subsequent debits.

UPI Autopay Intent (Recurring)

Test UPI Autopay mandates registered through Intent.

UPI Autopay QR (Recurring)

Test UPI Autopay mandates registered through QR.

UPI Autopay Collect (Recurring)

Test UPI Autopay mandates registered through Collect.
Last modified on November 12, 2026