Skip to main content
Available in🇮🇳 India

Test Mode

Test mode runs the same endpoints against simulated banks and NPCI. No real money moves. Switch the Dashboard to Test Mode, generate rzp_test_ keys, and use them in the same requests.

Before You Test

  1. Generate test keys: Account & Settings → API Keys → Generate Test Key.
  2. Create your test offers in the test-mode Dashboard. Offers exist per mode: live offers don’t appear in test mode. For full scenario coverage you need five: a cart-level flat discount, a SKU-level percentage discount with a cap (SKU offers are not self-serve on the Dashboard; ask your Razorpay team to set one up in test mode), an offer with a per-card usage limit of 1, an expired offer and a No-Cost EMI offer.
  3. Have the payment test kit below ready. Offer flows end in a payment, and you drive the payment’s outcome with test credentials.

Test Kit: Driving Payment Outcomes

The offer APIs themselves have no special test credentials; their outcome depends on the offers you configured and the request you send. The payment at the end of the flow is where you pick success or failure: Test credentials are documented on the test cards and test UPI pages; this guide only needs a success trigger and a failure trigger per method.

What You Can Test in Test Mode, and What You Can’t

Simulating Failures

These are examples of each failure class, not an exhaustive list. Anything driven by your own request or your offer setup can be reproduced in test mode. Failures you can reproduce in test mode Failures you cannot reproduce in test mode
  • 429 rate limiting and 5xx server errors. To test your handling, stand in for the API in your own environment: point the Match call at a stub server that returns these errors or times out, and check the checkout still renders and payment still works (OFR-16).
  • Live-account errors. In live mode, API calls fail if your account is not activated, or if you call from an IP address outside the allowlist configured on the Dashboard (the error reads as an authentication failure). Test keys skip both checks.
  • Settlement and cashback payout failures. Money movement runs only in live mode.

Scenarios to Test Your Integration

19 scenarios in three groups. Must-have: run these before go-live; money is wrong or payments break if they fail. Other common scenarios: real situations your integration will meet in week one. Error scenarios: make sure bad inputs and failures are handled, not just the happy path. Set up the five test offers from Before You Test first.

Must-Have

IDScenarioSetupStepsCriticality
OFR-01Match returns the right offers for a cart and cardThe SKU-level test offer; a cart and card that qualify for itCall Match with the order, line_items, and instrument. Check the offer is in matched with eligible: true. Check the discount math: calculated_benefit_value equals the percentage of the price, capped at max_benefit_value, and benefit_breakup adds up to it.Must pass
OFR-02Match without an instrument, for the payment pageSame cart, no instrument selected yetCall Match without payment_instrument. Check offers across all payment methods come back. Render the offer strip from this list.Must pass
OFR-03Validate at Pay and show the final amountOrder created; the offer from OFR-01 selectedCall Validate with order_id, the instrument (single values), and offers[]. Check the offer is in valid_offers with validity.valid: true. Check the amount you show the customer equals the order amount minus the sum of calculated_benefit_value.Must pass
OFR-04Pay with offers end to end, then confirm on the orderOFR-03, then a successful test paymentCreate the payment with the original amount and the same offers[] you validated. Complete it with a success trigger from the test kit and capture. Fetch the order with expand[]=offers. Every offer shows status: redeemed, amount_paid equals amount minus discounts, and applied_quantity matches what you validated.Must pass
OFR-05Send the original amount, never the discounted amountDeliberately break the rule: send amount = order total − discountReview the code path that sets the payment amount: it must always come from the order, never from the discounted display price. The protection lives in your code. As a probe, create a payment with the discounted amount and record what the API returns.Must pass
OFR-06Customer switches cards after you validatedValidate with a qualifying card, then switch to one that doesn’t qualifyValidate with card A. It passes. The customer switches to card B. Validate again. Check the offer moves to invalid_offers with reason: instrument_not_eligible, and your UI removes the discount and re-shows the payable amount before payment. Check no payment is ever created carrying offers validated against a different instrument.Must pass
OFR-07Offer runs out between Validate and paymentThe per-card-limit-1 test offer, used up by a second session in parallelValidate successfully in session one. Consume the offer’s last slot from a second session. Create the payment in session one. What happens depends on how the offer was configured at creation: the payment fails, or it completes without the offer. Handle both outcomes: on failure, re-run Match and let the customer retry without the offer on the same order; on success without the offer, make sure totals come from Fetch Order, not from the validated discount.Must pass

Other Common Scenarios

IDScenarioSetupStepsCriticality
OFR-12Payment fails, customer retries with the same offerAn offer is applied, then a payment fails with a failure triggerValidate, create the payment with the offer, and fail it using a failure trigger. Retry on the same order with the same offer. Check Validate passes again and the retry succeeds with the discount. The failed attempt must not have consumed the offer. Fetch the order and check that exactly one redemption is recorded.Should pass
OFR-13Show locked offers as nudgesineligible.include: true, with a cart just below an offer’s minimumCall Match with ineligible.include: true. Check the offer appears under ineligible with eligible: false and its full rules. Build the nudge (“Add ₹500 more to unlock”) from rules[].criteria.includes, and make sure an ineligible offer can never be selected.Should pass
OFR-15Two offers on one paymentThe cart-level and SKU-level test offers, both eligible on one orderValidate both in one call. Both come back valid. Create the payment with both; fetch the order and check both show redeemed. Check amount_paid equals the amount minus both discounts, and the invoice shows both lines.Should pass
OFR-17No-Cost EMI tenuresThe NCE test offer, restricted to specific tenuresValidate with method: emi and a covered emi.duration. It passes, and the EMI plan shows zero-interest math. Validate with a tenure the offer doesn’t cover. It fails with instrument_not_eligible. Check the discount math: the NCE benefit reduces amount_paid (the interest applied as an upfront discount). Confirm your order summary matches Fetch Order.Good to have
OFR-18Refund a discounted paymentThe captured payment from OFR-04; a full refundRefund the payment in full. Check that the refund amount is the paid (discounted) amount, not the original order amount. Check your refund ledger reconciles against amount_paidand note the customer’s usage slot is not restored (refund rules).Good to have
OFR-19Offers shown on home, product, and cart pages match checkoutAn offer surfaced pre-checkout via Match (When to Call)Call Match with no criteria.order (home page) and with an inline one-item order (product page). The offer returns; render it from display_name and terms, with no price math. Go to checkout with the same item. Checkout re-runs Match and shows the same offer, or no longer shows it if it expired in between. Check no discounted price appears anywhere before Validate runs at Pay.Good to have

Error Scenarios

IDScenarioSetupStepsCriticality
OFR-08Expired or disabled offerThe expired test offer, and one you disable by handValidate each. Check invalid_offers carries reason: offer_expired and offer_inactive respectively. Check your UI no longer shows the offer and checkout continues at full price.Should pass
OFR-09Cart edits drop the order below the offer minimumMatch with a qualifying cart, then remove an itemMatch shows the offer. Remove an item so the order falls below min_amount, and validate. Check reason: order_amount_below_minimum with field: order.amount. Check you re-run Match on every cart change, so a stale offer never reaches Pay.Should pass
OFR-10Wrong SKU or brand on a SKU-level offerThe SKU-level test offer; a SKU it doesn’t cover, then a wrong brandValidate with a sku outside the offer’s list. Check reason: sku_not_mapped_to_offer, with field pointing at the exact line item. Repeat with a mismatched brand. Check brand_not_matched. Check brand matching ignores case: "Apple" and "apple" both pass when the brand is right.Should pass
OFR-11Usage limit reached, or partially reachedThe per-card-limit test offer; a customer near the capValidate with a quantity above the customer’s remaining allowance, passing customer identifiers. Check eligible_quantity comes back lower than requested, your price math uses the lower number, and the UI explains the partial discount. Use up the limit fully and check quantity_exceeds_offer_limit.Should pass
OFR-14Invalid requests return 400 and name the failing fieldBad inputs, one at a timeSend a few deliberately invalid requests, for example: more than 20 offer IDs (20 is the most you can pass in the offers array in one request); an offers[] entry without an id; a SKU-level offer without line_items; quantity: 0; Validate without payment_instrument. Check each returns HTTP 400 with reason: input_validation_failed and a precise field. Check your code logs these as integration bugs and never shows them to the customer as payment failures.Should pass
OFR-16Offers service is unavailableRazorpay test mode cannot produce an outage, so stand in for the API yourself: in your test environment, point the Match call at a stub server that returns errors or times out (Simulating Failures)Run the checkout against the failing stub. Check the checkout renders without offers and payment still works end to end. Check retries back off instead of looping.Good to have

Common Integration Gaps to Avoid

Best Practices

  • Decide upfront what happens when an offer fails at payment time. The offer’s configuration controls it: fail the payment, or continue without the offer. If your offers fail the payment, build the retry path (OFR-07). Separately, keep the display path safe: wrap Match in a timeout (1 to 2 seconds) and render the checkout without offers if it errors.
  • Call Match again whenever the cart changes. Results are specific to the cart you sent. If the call included customer identifiers, the results are specific to that customer too, so never reuse them for another customer.
  • Validate once the full instrument is known. Running it as soon as the card number is complete is common and fine. Re-validate if the instrument or the cart changes after that, and avoid firing it on every keystroke.
  • Display price = order amount − Σ valid calculated_benefit_value of instant_discount and no_cost_emi benefits. Cashback changes the messaging, not the charged amount.
  • Reconcile after capture: once the payment is captured, fetch the order with expand[]=offers and persist offers_applied against your order. Treat that record as the source of truth for invoices and refunds.
  • Log validity.reason distributions in production. A spike in instrument_not_eligible or cap-exhaustion failures is your earliest signal of a misconfigured campaign.

Go-Live Checklist

  1. All seven must-have scenarios pass.
  2. Live keys replace test keys; the offers you tested against exist in live mode (test and live offers are separate).
  3. Payment amount is always the original order amount, never the discounted amount.
  4. Validation runs once the full instrument is known, and again after any instrument switch or cart edit.
  5. You know your offers’ pay-time failure configuration (fail the payment vs continue without the offer) and have tested the path you chose (OFR-07).
  6. Fulfilment and invoicing read from Fetch Order offers_applied, not from Match or Validate responses.
  7. Refund ceilings come from amount_paid.

Errors

API Errors

Sample Error Response

Validation Failure Reasons

When an offer fails an eligibility check, Validate Offers returns HTTP 200 and lists the offer in invalid_offers with a validity object.
Sample Response
Last modified on November 17, 2026