Available in🇮🇳 India
Fetch EMI plans, run successful Card EMI, Cardless EMI and Pay Later payments, simulate failures and reconcile against the webhooks in test mode before you go live.
This page covers affordability payments on S2S JSON (POST /v1/payments/create/json): Card EMI (method=emi), Cardless EMI (method=cardless_emi) and Pay Later (method=paylater).
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
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.
- 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. 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 EMI, any no-cost EMI offers, the Cardless EMI and Pay Later providers you use, the Eligibility Check API and the IIN API on your test account. They are enabled separately from live mode, so ask for both.
- Every scenario on this page needs an order. Order behaviour has scenarios of its own, all on Orders. Request errors on the order are the same for every method; run them once.
- For Card EMI, pay ₹6,000 (
amount = 600000) with a test card from the tables below, any CVV and any future expiry. Pick the shortest tenure the bank offers. - For Cardless EMI, use any of these providers:
zestmoney,walnut369,icic,hdfc,idfb,tvsc. For Pay Later, uselazypay. - For Cardless EMI and Pay Later, the amount must match one in the table below exactly. The mock lender page shows options, but what you choose on it does not change the outcome. The amount does.
Card EMI: test cards for a successful payment
Choose EMI, the bank and its shortest tenure, then click Success on the mock bank page. The payment is authorised with the EMI plan.Card EMI: test cards for errors
Cardless EMI and Pay Later: test amounts
Eligibility check test phone numbers
Send one of these ascustomer.contact on POST /v1/customers/eligibility.
More cards for other card flows are on the test card details page.
3. Scenarios to Test Your Integration
This section lists every scenario we think is worth running against your affordability 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. Run these first. They cover fetching plans, successful Card EMI, Cardless EMI and Pay Later payments, the callback and reconciliation. Other common scenarios. These come up in normal day-to-day running: processing fees, no-cost EMI and the eligibility check. Cover the ones you use before launch. Error scenarios. Failures you can bring on deliberately with a test card, a test amount, an eligibility test number or a bad request, grouped byerror.source, because the source tells you who has to act.
Not available in test mode yet. Real scenarios your integration still has to handle, but that cannot be reproduced in test mode today. Check them on live traffic or in a controlled live test before you ship.
3.1 Must-build affordability scenarios
| # | Scenario | Trigger creds | Steps to follow |
|---|---|---|---|
| 1 | Fetch payment methods and EMI plans | — | Call GET /v1/methods with your test key. Read the EMI options: the banks, tenures and rates available for the card and amount. emi_plans.<BANK> has min_amount and plans (tenure → rate); emi_options.<BANK>[] has duration, interest, min_amount and processing_fee_plan. Show only the plans returned. Refresh them instead of hard-coding tenures or rates. |
| 2 | Successful Card EMI payment | Any success test card, for example 4341 6812 3456 7896 (HDFC). Cards for every bank are in Before you begin. Any CVV, any future expiry. | 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=emi, the card details, the bank’s shortest EMI tenure (emi_duration), amount = 600000 (₹6,000), currency, email, contact and callback_url. Redirect the customer to the URL in next[]. In test mode this opens the mock bank page. Click Success. 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. |
| 3 | Successful Cardless EMI payment | ₹3,000 (amount = 300000) + a Cardless EMI provider from Before you begin | Create an order and store the returned order_id. Create the payment with that order_id: POST /v1/payments/create/json with method=cardless_emi, a provider, amount = 300000, currency, email, contact and callback_url. Redirect the customer to the URL in next[]. In test mode this opens a mock lender page. It shows options, but the outcome is decided by the amount sent in the API. Click Success. The customer returns to your callback_url. Verify razorpay_signature on your server. Fulfil on payment.captured. Webhooks received: payment.authorized, payment.captured, order.paid. Status changes: the payment moves to captured and the order to paid. |
| 4 | Successful Pay Later payment | ₹3,000 (amount = 300000) + a Pay Later provider from Before you begin | Create an order and store the returned order_id. Create the payment with that order_id: POST /v1/payments/create/json with method=paylater, a provider, amount = 300000, currency, email, contact and callback_url. Redirect the customer to the URL in next[]. In test mode this opens a mock lender page. Click Success. The customer returns to your callback_url. Verify razorpay_signature on your server. Fulfil on payment.captured. Webhooks received: payment.authorized, payment.captured, order.paid. |
| 5 | Verify the callback signature | A payment from scenario 2 | 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 scenarios 2, 3 or 4 and a failed one from scenario 12 | Call GET /v1/payments/:id and GET /v1/orders/:id/payments. Confirm the status you stored from the webhook matches the API. Call GET /v1/payments/:id?expand[]=emi and store the emi object: issuer, rate (in basis points) and duration (in months). |
3.2 Common scenarios in affordability
| # | Scenario | Trigger creds | Steps to follow |
|---|---|---|---|
| 7 | Show processing fees | GET /v1/methods | Call GET /v1/methods. Read the fee from emi_options.<BANK>[].processing_fee_plan. Types (amounts in paise): percentage, for example {"type": "percentage", "percentage": 1}; fixed, for example {"type": "fixed", "amount": 19900}; combination, for example {"type": "combination", "percentage": 2.99, "amount": 29900}. Show the fee next to each plan before the customer picks one. If a bank has no processing_fee_plan, show no fee. Processing fees are set per bank, not per merchant. |
| 8 | No-cost or low-cost EMI | A success card from Before you begin + a no-cost EMI offer on your test account. Coming soon. | Create the order with the no-cost EMI plan configured. Pay as in scenario 2 with the matching tenure. Confirm the customer is charged the subvention-adjusted amount you expect, and that the EMI details on the payment match. Webhooks received: payment.authorized, payment.captured, order.paid. |
| 9 | Check eligibility: customer is eligible | +917887948836 (all providers eligible) or any number not listed in Before you begin. | Before checkout, call POST /v1/customers/eligibility with amount, currency and customer.contact (mandatory), plus instruments to limit the check to specific methods or providers. Read eligibility.status for each instrument in the response and store its eligibility_req_id. Show only the instruments that are eligible. Create the order and pay as in scenario 2, 3 or 4 with an eligible instrument. |
| 10 | Check eligibility: customer is ineligible | A number that makes a provider ineligible, for example +917887578479 (LazyPay). All numbers are in Before you begin. | Call POST /v1/customers/eligibility as in scenario 9. Confirm eligibility.status is ineligible for that instrument, with an eligibility.error object. Hide the instrument. Branch on eligibility.error.reason, for example user_not_approved, credit_limit_exhausted, min_amt_required or max_amt_limit. Offer the customer the instruments that are still eligible. |
| 11 | Check eligibility: pending or failed, then fetch by ID | A test number that returns pending or failed. Coming soon. | Call POST /v1/customers/eligibility as in scenario 9. On pending, the provider did not respond in time. Fetch the check later with GET /v1/customers/eligibility/:eligibility_req_id, or hide the instrument for this checkout. On failed, send a new eligibility request. A failed check can be re-attempted. Do not treat pending or failed as ineligible. |
3.3 Affordability error scenarios
Each trigger returns the error in its row. Branch your handling onerror.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 or the lender declined them. Wrong details are recoverable: ask them to try again. A lender decline is not: offer another lender or method.
| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 12 | Customer cancels at the lender (Cardless EMI or Pay Later) | ₹3,000 (300000) | code: BAD_REQUEST_ERRORreason: payment_cancelled | Create an order and store the returned order_id. Create the payment with that order_id: POST /v1/payments/create/json with method=cardless_emi or paylater, a provider, the test amount, currency, email, contact and callback_url. Redirect the customer to the URL in next[]. This opens a mock lender page. Click Failure. Webhooks received: payment.failed. Confirm payment_cancelled. Let the customer retry or pick another method. |
| 13 | OTP failure at the lender (Cardless EMI or Pay Later) | ₹5,004 (500400) | code: BAD_REQUEST_ERRORreason: incorrect_otp (Cardless EMI), otp_attempts_exceeded (Pay Later) | Create an order and the payment as in scenario 12 with the test amount. Redirect the customer to the URL in next[]. Click Failure on the mock lender page. Webhooks received: payment.failed. Confirm the reason and show error.description. Offer a retry. |
| 14 | Customer not eligible with the lender | ₹5,001 (500100) | code: BAD_REQUEST_ERRORreason: user_not_eligible | Create an order and the payment as in scenario 12 with the test amount. The payment fails straight away, without opening a mock lender page. Webhooks received: payment.failed. Confirm user_not_eligible. Offer another lender or method. |
| 15 | Not enough credit limit | ₹5,002 (500200) | code: BAD_REQUEST_ERRORreason: credit_limit_exceeded (Cardless EMI), insufficient_funds (Pay Later) | Create an order and the payment as in scenario 12 with the test amount. The payment fails straight away, without opening a mock lender page. Webhooks received: payment.failed. Confirm the reason. Offer another lender or method. |
| 16 | Lender rejects the payment | ₹5,006 (500600) | Cardless EMI: code BAD_REQUEST_ERROR, reason credit_limit_not_approvedPay Later: code GATEWAY_ERROR, reason payment_failed | Create an order and the payment as in scenario 12 with the test amount. Redirect the customer to the URL in next[] and click Failure on the mock lender page. Webhooks received: payment.failed. Confirm the reason and show error.description. Offer another lender or method. Status changes: the payment moves to failed; the order stays attempted for a retry. |
| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 17 | Lender timeout | ₹5,003 (500300) | code: GATEWAY_ERRORreason: payment_timed_out | Create an order and the payment as in scenario 12 with the test amount. The payment fails straight away, without opening a mock lender page. Webhooks received: payment.failed. Confirm payment_timed_out. Let the customer retry later or pick another lender. |
| 18 | Denied by the lender on risk | ₹5,005 (500500) | code: GATEWAY_ERROR | Create an order and the payment as in scenario 12 with the test amount. Redirect the customer to the URL in next[] and click Failure on the mock lender page. Webhooks received: payment.failed. Confirm the payment failed and offer another lender or method. |
| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 19 | EMI not enabled on the card | 5186 8612 3456 7899 (ICICI), 4258 0612 3456 7892 (Axis) or 4008 2812 3456 7899 (Kotak) | code: BAD_REQUEST_ERRORdescription: “Emi is not available for the card used” | Create an order and store the returned order_id. Create the payment with that order_id: POST /v1/payments/create/json with method=emi, the card details, the EMI tenure (emi_duration), amount, currency, email, contact and callback_url. The payment is rejected on create. No mock bank page opens and no webhook is sent. Offer another card or a non-EMI payment. |
| 20 | Invalid EMI duration | 4035 6212 3456 7893 (ICICI) with emi_duration = 7, a tenure the bank does not offer | code: BAD_REQUEST_ERRORdescription: “EMI plan does not exist.” | Create the order and payment as in scenario 19. The payment is rejected on create. No mock bank page opens and no webhook is sent. Send only tenures returned by GET /v1/methods. |
| 21 | EMI duration missing | 4186 8812 3456 7890 (Axis) with no emi_duration | code: BAD_REQUEST_ERRORdescription: “Emi duration is not valid” | Create the order and payment as in scenario 19, but send no emi_duration. The payment is rejected on create. No mock bank page opens and no webhook is sent. Always send the tenure the customer picked. |
| 22 | BIN check: IIN does not exist | GET /v1/iins/000000 | code: BAD_REQUEST_ERRORreason: iin_does_not_exist | Call GET /v1/iins/000000. Confirm iin_does_not_exist. Use the IIN lookup to check a card before you show EMI plans for it. |
| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 23 | Phone number missing | POST /v1/customers/eligibility without customer.contact | code: BAD_REQUEST_ERRORreason: mobile_number_required | Call POST /v1/customers/eligibility without customer.contact. Confirm mobile_number_required. Always send the customer’s phone number. |
| 24 | Invalid amount | POST /v1/customers/eligibility with amount below 100, for example 50 | code: BAD_REQUEST_ERRORreason: invalid_amountdescription: “The amount must be at least INR 1.00” | Call POST /v1/customers/eligibility with amount = 50. Confirm invalid_amount. Send the order amount in paise, at least 100 (₹1). |
| 25 | Method not enabled | instruments with a method that is not enabled on your test account | HTTP 200, and on that instrument:eligibility.status: failederror.code: BAD_REQUEST_ERRORerror.reason: method_not_enabled | Call POST /v1/customers/eligibility with an instruments entry for a method you do not have. Confirm the request returns HTTP 200, with instruments[].eligibility.status = failed and error.reason = method_not_enabled for that instrument. Check only methods returned by GET /v1/methods. |
| 26 | Invalid eligibility ID on fetch | GET /v1/customers/eligibility/:eligibility_req_id with a malformed ID, for example elig_123 | HTTP 404{"message": "no Route matched with those values"} | Call GET /v1/customers/eligibility/elig_123. Confirm HTTP 404 with "message": "no Route matched with those values". Use the eligibility_req_id from the create response. |
| 27 | Eligibility ID does not exist on fetch | GET /v1/customers/eligibility/:eligibility_req_id with a well-formed ID that does not exist | code: BAD_REQUEST_ERRORsource: businessreason: eligibility_id_does_not_exist | Call GET /v1/customers/eligibility/:eligibility_req_id with an ID that does not exist. Confirm eligibility_id_does_not_exist. Use the eligibility_req_id from the create response. |
3.4 Not available in test mode yet
4. Common Integration Gaps to Avoid
These are the mistakes that most often cause failed payments or double charges after go-live. “Test with” points to the scenario that proves you have handled it. Webhooks and callbacks
EMI plans and fees
Eligibility check
Error handling and messaging to the payer
Fetch API when webhooks are late
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.
All best practices: Overview · Webhooks and Fetch APIs · Payment states and late authorisation · Security