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, generaterzp_test_ keys, and use them in the same requests.
Before You Test
- Generate test keys: Account & Settings → API Keys → Generate Test Key.
- 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.
- 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
| ID | Scenario | Setup | Steps | Criticality |
|---|---|---|---|---|
| OFR-01 | Match returns the right offers for a cart and card | The SKU-level test offer; a cart and card that qualify for it | Call 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-02 | Match without an instrument, for the payment page | Same cart, no instrument selected yet | Call Match without payment_instrument. Check offers across all payment methods come back. Render the offer strip from this list. | Must pass |
| OFR-03 | Validate at Pay and show the final amount | Order created; the offer from OFR-01 selected | Call 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-04 | Pay with offers end to end, then confirm on the order | OFR-03, then a successful test payment | Create 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-05 | Send the original amount, never the discounted amount | Deliberately break the rule: send amount = order total − discount | Review 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-06 | Customer switches cards after you validated | Validate with a qualifying card, then switch to one that doesn’t qualify | Validate 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-07 | Offer runs out between Validate and payment | The per-card-limit-1 test offer, used up by a second session in parallel | Validate 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
| ID | Scenario | Setup | Steps | Criticality |
|---|---|---|---|---|
| OFR-12 | Payment fails, customer retries with the same offer | An offer is applied, then a payment fails with a failure trigger | Validate, 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-13 | Show locked offers as nudges | ineligible.include: true, with a cart just below an offer’s minimum | Call 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-15 | Two offers on one payment | The cart-level and SKU-level test offers, both eligible on one order | Validate 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-17 | No-Cost EMI tenures | The NCE test offer, restricted to specific tenures | Validate 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-18 | Refund a discounted payment | The captured payment from OFR-04; a full refund | Refund 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-19 | Offers shown on home, product, and cart pages match checkout | An 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
| ID | Scenario | Setup | Steps | Criticality |
|---|---|---|---|---|
| OFR-08 | Expired or disabled offer | The expired test offer, and one you disable by hand | Validate 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-09 | Cart edits drop the order below the offer minimum | Match with a qualifying cart, then remove an item | Match 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-10 | Wrong SKU or brand on a SKU-level offer | The SKU-level test offer; a SKU it doesn’t cover, then a wrong brand | Validate 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-11 | Usage limit reached, or partially reached | The per-card-limit test offer; a customer near the cap | Validate 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-14 | Invalid requests return 400 and name the failing field | Bad inputs, one at a time | Send 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-16 | Offers service is unavailable | Razorpay 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
customeridentifiers, 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_valueofinstant_discountandno_cost_emibenefits. Cashback changes the messaging, not the charged amount. - Reconcile after capture: once the payment is captured, fetch the order with
expand[]=offersand persistoffers_appliedagainst your order. Treat that record as the source of truth for invoices and refunds. - Log
validity.reasondistributions in production. A spike ininstrument_not_eligibleor cap-exhaustion failures is your earliest signal of a misconfigured campaign.
Go-Live Checklist
- All seven must-have scenarios pass.
- Live keys replace test keys; the offers you tested against exist in live mode (test and live offers are separate).
- Payment
amountis always the original order amount, never the discounted amount. - Validation runs once the full instrument is known, and again after any instrument switch or cart edit.
- 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).
- Fulfilment and invoicing read from Fetch Order
offers_applied, not from Match or Validate responses. - 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 HTTP200 and lists the offer in invalid_offers with a validity object.
Sample Response