> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Affordability: How to Test Your Integration

> Test Card EMI, Cardless EMI and Pay Later payments on your S2S integration in Test Mode, including success, failure and eligibility check scenarios.

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](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s.md) for test keys and webhook setup.

## 1. Test Mode Coverage

### How live mode and test mode differ

| Behaviour | Live mode | Test mode |
| - | - | - |
| Authentication | Issuer ACS page (3DS) or OTP for the EMI card. | The customer is redirected to a mock bank page. Clicking **Success** authorises the payment. Clicking **Failure** fails it, and the test card decides which error is returned. |
| Card numbers | Real cards that are eligible for EMI with the issuing bank. | Test EMI cards for each bank, plus cards that trigger specific errors, all listed in [Before you begin](#2-before-you-begin). Use any CVV and any future expiry. |
| EMI plans | The banks, tenures and interest rates enabled on your live account, including any no-cost EMI offers. | Test plans returned by `GET /v1/methods`. They are the same as the plans on your live account. |
| Eligibility check | The provider checks whether the customer is approved for the order amount. | The outcome is set by the test phone number you send as `customer.contact`. See [Before you begin](#2-before-you-begin). |
| Cardless EMI and Pay Later | The customer is redirected to the lender or provider to check eligibility, pick a plan and approve. | The customer is redirected to a mock lender page. It shows options, but the outcome is decided by the amount sent in the API. |
| Webhook delivery | Razorpay sends the webhook once the bank confirms. That round trip is real, so delivery can take minutes and your reconciler has to allow for it. | The bank is simulated, so the webhook is sent almost as soon as the create-payment request succeeds. Do not use test mode to size your reconciliation windows. |

### What you can test

| Area | What you can test |
| - | - |
| Payment methods | Fetching the instruments enabled for you with `GET /v1/methods`, including EMI options and processing fees. |
| Card EMI payments | Successful payments and payments rejected when created (EMI not enabled on the card, invalid or missing tenure), using the triggers in [Scenarios to test your integration](#3-scenarios-to-test-your-integration). |
| Cardless EMI and Pay Later payments | Successful payments through the mock lender page, and failures triggered by the amount you send. |
| Eligibility check | Checking whether a customer is eligible for Debit Card EMI (HDFC debit cards only), Cardless EMI and Pay Later before checkout (`POST /v1/customers/eligibility`), the eligible, ineligible, pending and failed states, and fetching a check by ID. Not available for Credit Card EMI. |
| Card errors | EMI not enabled on the card, invalid or missing tenure, and BIN checks. See [3.3 Affordability error scenarios](#3-3-affordability-error-scenarios). |
| EMI details on the payment | `GET /v1/payments/:id?expand[]=emi`, which returns the issuer, rate and duration. |
| Reconciliation | Fetching a payment by ID and fetching the payments on an order, so you can prove your reconciler agrees with the webhook. |
| Webhooks | Payment and order webhooks for each of the above. See [Webhooks: what fires, and what it lets you decide](#webhooks-what-fires-and-what-it-lets-you-decide). |

### Endpoint coverage in test mode

| API | Endpoint | Available on test mode |
| - | - | - |
| Fetch payment methods and EMI plans | `GET /v1/methods` | Available |
| Create an order | `POST /v1/orders` | Available |
| Create a Card EMI payment | `POST /v1/payments/create/json` with `method=emi` | Available |
| Create a Cardless EMI payment | `POST /v1/payments/create/json` with `method=cardless_emi` and `provider` | Available |
| Create a Pay Later payment | `POST /v1/payments/create/json` with `method=paylater` and `provider` | Available |
| Fetch a payment | `GET /v1/payments/:id` | Available |
| Fetch a payment with EMI details | `GET /v1/payments/:id?expand[]=emi` | Available |
| Fetch payments on an order | `GET /v1/orders/:id/payments` | Available |
| Check eligibility (on-demand) | `POST /v1/customers/eligibility` | Available |
| Fetch an eligibility check | `GET /v1/customers/eligibility/:eligibility_req_id` | Available |
| IIN lookup (BIN check, on-demand) | `GET /v1/iins/:iin` | Available |

### 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.

| Webhook | Fires when | In test mode |
| - | - | - |
| `payment.authorized` | The affordability payment is authorised. The money is held, not captured. | Available |
| `payment.captured` | The payment is captured. | Available |
| `payment.failed` | The affordability payment fails. | Available |
| `order.paid` | The order is fully paid. | Available |

**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.

| Scenario | Webhooks, in order | What each one lets you decide | In test mode |
| - | - | - | - |
| 2, 3, 4, 8 Successful Card EMI, Cardless EMI, Pay Later, no-cost EMI | `payment.authorized`, `payment.captured`, `order.paid` | `payment.authorized`: funds are held for you but are not yet yours. Do not fulfil services on this alone. `payment.captured`: funds are yours, fulfil services on this. `order.paid`: the order is settled and will not accept another payment. Close the cart and stop any retry loop. | Available |
| 12–18 Failed Cardless EMI and Pay Later payments | `payment.failed` | This attempt is over. The error reason tells you whether to offer the same method again or move the customer to another one. | Available |

**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.captured` lands before `order.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](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/webhooks-and-fetch-apis.md) 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](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md). Request errors on the order are the same for every method; run them once.

In test mode there is no real issuer or lender on the other end. For Card EMI, the test card number and the button you click on the mock bank page decide the outcome. For Cardless EMI and Pay Later, the exact payment amount decides it.

* 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, use `lazypay`.
* 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.

| Bank | Card number |
| - | - |
| American Express | `3798 6112 3456 780` |
| AU Small Finance Bank | `6526 2412 3456 7891` |
| Axis Bank | `4186 8812 3456 7890` |
| Bank of Baroda | `5277 5312 3456 7898` |
| Federal Bank | `5368 8112 3456 7894` |
| HDFC Bank | `4341 6812 3456 7896` |
| HSBC | `5120 4212 3456 7891` |
| ICICI Bank | `4035 6212 3456 7893` |
| IDFC First Bank | `4023 6812 3456 7891` |
| IndusInd Bank | `4077 1212 3456 7893` |
| Kotak Mahindra Bank | `5276 7212 3456 7896` |
| OneCard | `6529 9212 3456 7895` |
| RBL Bank | `5220 1212 3456 7896` |
| Standard Chartered | `5431 8612 3456 7892` |
| Yes Bank | `5241 6712 3456 7895` |

### Card EMI: test cards for errors

| Use it to test | Card number | What to do | Result |
| - | - | - | - |
| EMI not enabled on the card (ICICI) | `5186 8612 3456 7899` | Create the payment. It is rejected at create, with no mock bank page. | Rejected: Emi is not available for the card used |
| EMI not enabled on the card (Axis) | `4258 0612 3456 7892` | Create the payment. It is rejected at create, with no mock bank page. | Rejected: Emi is not available for the card used |
| EMI not enabled on the card (Kotak) | `4008 2812 3456 7899` | Create the payment. It is rejected at create, with no mock bank page. | Rejected: Emi is not available for the card used |
| Invalid EMI duration (ICICI) | `4035 6212 3456 7893` | Create the payment with `emi_duration = 7`, a tenure the bank does not offer. | Rejected: EMI plan does not exist. |
| EMI duration missing (Axis) | `4186 8812 3456 7890` | Create the payment with `method = emi` and no `emi_duration`. | Rejected: Emi duration is not valid |

### Cardless EMI and Pay Later: test amounts

| Use it to test | Amount | What to do | Cardless EMI returns | Pay Later returns |
| - | - | - | - | - |
| Successful payment | ₹3,000 (`300000`) | Click **Success** on the mock lender page. | Authorized | Authorized |
| Customer cancels | ₹3,000 (`300000`) | Click **Failure** on the mock lender page. | `payment_cancelled` | `payment_cancelled` |
| Customer not eligible | ₹5,001 (`500100`) | Create the payment. It fails with no mock lender page. | `user_not_eligible` | `user_not_eligible` |
| Not enough limit | ₹5,002 (`500200`) | Create the payment. It fails with no mock lender page. | `credit_limit_exceeded` | `insufficient_funds` |
| Provider timeout | ₹5,003 (`500300`) | Create the payment. It fails with no mock lender page. | `payment_timed_out` | `payment_timed_out` |
| OTP failure at the provider | ₹5,004 (`500400`) | Click **Failure** on the mock lender page. | `incorrect_otp` | `otp_attempts_exceeded` |
| Denied by the provider on risk | ₹5,005 (`500500`) | Click **Failure** on the mock lender page. | Failed (risk) | Failed (risk) |
| Provider rejects the payment | ₹5,006 (`500600`) | Click **Failure** on the mock lender page. | `credit_limit_not_approved` | `payment_failed` |

### Eligibility check test phone numbers

Send one of these as `customer.contact` on `POST /v1/customers/eligibility`.

| Use it to test | Contact number | Not eligible for | Result |
| - | - | - | - |
| All providers eligible | `+917887948836` | — | All providers shown as eligible. |
| All providers eligible (default) | Any other number | — | All providers shown as eligible. |
| LazyPay not eligible | `+917887578479` | LazyPay | LazyPay ineligible, others eligible. |
| ICICI not eligible | `+916127912480` | ICICI | ICICI ineligible, others eligible. |
| Simpl not eligible | `+917511365863` | Simpl | Simpl ineligible, others eligible. |
| Several providers not eligible | `+918708408282` | Walnut369, LazyPay, ICICI, FlexMoney banks | Only ZestMoney, Simpl and Amazon Pay eligible. |
| Most providers not eligible | `+918066317208` | Walnut369, Simpl, ICICI, Amazon Pay, FlexMoney banks | Only LazyPay and HDFC Debit EMI eligible. |

More cards for other card flows are on the [test card details](https://razorpay.com/docs/payments/payments/test-card-details.md) 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 by `error.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

<table>
  <colgroup>
    <col width="6%" />

    <col width="18%" />

    <col width="18%" />

    <col width="58%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger creds</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>1</td><td>Fetch payment methods and EMI plans</td><td>—</td><td>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.</td></tr>
    <tr><td>2</td><td>Successful Card EMI payment</td><td>Any success test card, for example `4341 6812 3456 7896` (HDFC). Cards for every bank are in [Before you begin](#2-before-you-begin). Any CVV, any future expiry.</td><td>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`.</td></tr>
    <tr><td>3</td><td>Successful Cardless EMI payment</td><td>₹3,000 (`amount = 300000`) + a Cardless EMI provider from [Before you begin](#2-before-you-begin)</td><td>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`.</td></tr>
    <tr><td>4</td><td>Successful Pay Later payment</td><td>₹3,000 (`amount = 300000`) + a Pay Later provider from [Before you begin](#2-before-you-begin)</td><td>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`.</td></tr>
    <tr><td>5</td><td>Verify the callback signature</td><td>A payment from scenario 2</td><td>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.</td></tr>
    <tr><td>6</td><td>Fetch the payment and reconcile</td><td>A payment ID from scenarios 2, 3 or 4 and a failed one from scenario 12</td><td>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).</td></tr>
  </tbody>
</table>

### 3.2 Common scenarios in affordability

<table>
  <colgroup>
    <col width="6%" />

    <col width="18%" />

    <col width="18%" />

    <col width="58%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger creds</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>7</td><td>Show processing fees</td><td>`GET /v1/methods`</td><td>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.</td></tr>
    <tr><td>8</td><td>No-cost or low-cost EMI</td><td>A success card from [Before you begin](#2-before-you-begin) + a no-cost EMI offer on your test account. Coming soon.</td><td>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`.</td></tr>
    <tr><td>9</td><td>Check eligibility: customer is eligible</td><td>`+917887948836` (all providers eligible) or any number not listed in [Before you begin](#2-before-you-begin).</td><td>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.</td></tr>
    <tr><td>10</td><td>Check eligibility: customer is ineligible</td><td>A number that makes a provider ineligible, for example `+917887578479` (LazyPay). All numbers are in [Before you begin](#2-before-you-begin).</td><td>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.</td></tr>
    <tr><td>11</td><td>Check eligibility: pending or failed, then fetch by ID</td><td>A test number that returns `pending` or `failed`. Coming soon.</td><td>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.</td></tr>
  </tbody>
</table>

### 3.3 Affordability error scenarios

Each trigger 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](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md).

**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.

<table>
  <colgroup>
    <col width="6%" />

    <col width="16%" />

    <col width="14%" />

    <col width="18%" />

    <col width="46%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger creds</th><th>Error object</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>12</td><td>Customer cancels at the lender (Cardless EMI or Pay Later)</td><td>₹3,000 (`300000`)</td><td>`code`: `BAD_REQUEST_ERROR`\
    `reason`: `payment_cancelled`</td><td>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.</td></tr>
    <tr><td>13</td><td>OTP failure at the lender (Cardless EMI or Pay Later)</td><td>₹5,004 (`500400`)</td><td>`code`: `BAD_REQUEST_ERROR`\
    `reason`: `incorrect_otp` (Cardless EMI), `otp_attempts_exceeded` (Pay Later)</td><td>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.</td></tr>
    <tr><td>14</td><td>Customer not eligible with the lender</td><td>₹5,001 (`500100`)</td><td>`code`: `BAD_REQUEST_ERROR`\
    `reason`: `user_not_eligible`</td><td>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.</td></tr>
    <tr><td>15</td><td>Not enough credit limit</td><td>₹5,002 (`500200`)</td><td>`code`: `BAD_REQUEST_ERROR`\
    `reason`: `credit_limit_exceeded` (Cardless EMI), `insufficient_funds` (Pay Later)</td><td>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.</td></tr>
    <tr><td>16</td><td>Lender rejects the payment</td><td>₹5,006 (`500600`)</td><td>Cardless EMI: `code` `BAD_REQUEST_ERROR`, `reason` `credit_limit_not_approved`\
    Pay Later: `code` `GATEWAY_ERROR`, `reason` `payment_failed`</td><td>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.</td></tr>
  </tbody>
</table>

**Bank and lender errors**

The bank or lender declined the payment or did not respond. The customer can retry later, or use another card, lender or method.

<table>
  <colgroup>
    <col width="6%" />

    <col width="16%" />

    <col width="14%" />

    <col width="18%" />

    <col width="46%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger creds</th><th>Error object</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>17</td><td>Lender timeout</td><td>₹5,003 (`500300`)</td><td>`code`: `GATEWAY_ERROR`\
    `reason`: `payment_timed_out`</td><td>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.</td></tr>
    <tr><td>18</td><td>Denied by the lender on risk</td><td>₹5,005 (`500500`)</td><td>`code`: `GATEWAY_ERROR`</td><td>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.</td></tr>
  </tbody>
</table>

**Business errors**

The card or request is not eligible. The customer cannot fix this by retrying: offer another plan or method.

<table>
  <colgroup>
    <col width="6%" />

    <col width="16%" />

    <col width="20%" />

    <col width="18%" />

    <col width="40%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger creds</th><th>Error object</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>19</td><td>EMI not enabled on the card</td><td>`5186 8612 3456 7899` (ICICI), `4258 0612 3456 7892` (Axis) or `4008 2812 3456 7899` (Kotak)</td><td>`code`: `BAD_REQUEST_ERROR`\
    `description`: "Emi is not available for the card used"</td><td>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.</td></tr>
    <tr><td>20</td><td>Invalid EMI duration</td><td>`4035 6212 3456 7893` (ICICI) with `emi_duration = 7`, a tenure the bank does not offer</td><td>`code`: `BAD_REQUEST_ERROR`\
    `description`: "EMI plan does not exist."</td><td>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`.</td></tr>
    <tr><td>21</td><td>EMI duration missing</td><td>`4186 8812 3456 7890` (Axis) with no `emi_duration`</td><td>`code`: `BAD_REQUEST_ERROR`\
    `description`: "Emi duration is not valid"</td><td>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.</td></tr>
    <tr><td>22</td><td>BIN check: IIN does not exist</td><td>`GET /v1/iins/000000`</td><td>`code`: `BAD_REQUEST_ERROR`\
    `reason`: `iin_does_not_exist`</td><td>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.</td></tr>
  </tbody>
</table>

**Eligibility Check API errors**

Your eligibility request was wrong. Fix the request; the customer cannot.

<table>
  <colgroup>
    <col width="6%" />

    <col width="16%" />

    <col width="20%" />

    <col width="18%" />

    <col width="40%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger creds</th><th>Error object</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>23</td><td>Phone number missing</td><td>`POST /v1/customers/eligibility` without `customer.contact`</td><td>`code`: `BAD_REQUEST_ERROR`\
    `reason`: `mobile_number_required`</td><td>Call `POST /v1/customers/eligibility` without `customer.contact`. Confirm `mobile_number_required`. Always send the customer's phone number.</td></tr>
    <tr><td>24</td><td>Invalid amount</td><td>`POST /v1/customers/eligibility` with `amount` below 100, for example 50</td><td>`code`: `BAD_REQUEST_ERROR`\
    `reason`: `invalid_amount`\
    `description`: "The amount must be at least INR 1.00"</td><td>Call `POST /v1/customers/eligibility` with `amount = 50`. Confirm `invalid_amount`. Send the order amount in paise, at least 100 (₹1).</td></tr>
    <tr><td>25</td><td>Method not enabled</td><td>`instruments` with a method that is not enabled on your test account</td><td>HTTP 200, and on that instrument:\
    `eligibility.status`: `failed`\
    `error.code`: `BAD_REQUEST_ERROR`\
    `error.reason`: `method_not_enabled`</td><td>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`.</td></tr>
    <tr><td>26</td><td>Invalid eligibility ID on fetch</td><td>`GET /v1/customers/eligibility/:eligibility_req_id` with a malformed ID, for example `elig_123`</td><td>HTTP 404\
    `{"message": "no Route matched with those values"}`</td><td>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.</td></tr>
    <tr><td>27</td><td>Eligibility ID does not exist on fetch</td><td>`GET /v1/customers/eligibility/:eligibility_req_id` with a well-formed ID that does not exist</td><td>`code`: `BAD_REQUEST_ERROR`\
    `source`: `business`\
    `reason`: `eligibility_id_does_not_exist`</td><td>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.</td></tr>
  </tbody>
</table>

### 3.4 Not available in test mode yet

| # | Scenario |
| - | - |
| 28 | Late authorisation — Live only. Handle `payment.authorized` arriving after you showed a failure (up to 3 days). Check in a controlled live test. |

## 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**

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Fulfilling on the checkout callback | The customer closes the bank page or loses network after paying. You never get the callback, so a paid order looks unpaid. | Fulfil on `payment.captured` or `order.paid`. Treat the callback as a hint, not proof. | 2, 3, 4, Webhooks |
| Skipping the callback signature | A forged callback marks an order paid. | Verify `razorpay_signature` on every callback. | 5 |
| Duplicate or unsigned events processed | One payment fulfils twice, or a forged event marks an order paid. | Verify `X-Razorpay-Signature`. Store event IDs and skip repeats. | Webhooks |

**EMI plans and fees**

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Hard-coded tenures or rates | A bank changes its plans and the customer picks one that no longer exists, so the payment fails. | Load plans from `GET /v1/methods` for each card and amount. | 1 |
| Hiding the processing fee | The customer sees a different total on their statement and raises a dispute. | Show the processing fee next to each plan before the customer picks one. | 7 |
| Not storing EMI details | Support cannot tell the customer which bank, rate or tenure they chose. | Store the `emi` object from `GET /v1/payments/:id?expand[]=emi`. | 6 |
| Showing EMI on ineligible cards | The customer picks EMI on a card that does not support it and the payment fails. | Check the card with the IIN lookup and show EMI only when it is eligible. | 19–22 |

**Eligibility check**

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Showing every option without checking eligibility | The customer picks Cardless EMI or Pay Later, is declined by the lender and drops off. | Call `POST /v1/customers/eligibility` before checkout and show only eligible instruments. | 9, 10 |
| Treating `pending` as ineligible | An eligible customer loses an option because the provider was slow. | On `pending`, fetch the check later by ID; on `failed`, send a new request. | 11 |

**Error handling and messaging to the payer**

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Showing raw codes | The customer sees `BAD_REQUEST_ERROR` and drops off. | Show `error.description`. It is written for the customer. | 12–21 |
| Same message for every failure | A customer whose card is not eligible retries EMI again and again. | Branch on `error.reason`: retry on `payment_cancelled` or `payment_timed_out`, another lender or method on a lender decline, another card or method on an eligibility error. | 12–21 |

**Fetch API when webhooks are late**

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Waiting forever for the webhook | The webhook is delayed and the order sits in limbo. | Poll `GET /v1/payments/:id` with back-off until the payment reaches a final state. | 6 |
| Ignoring late authorisation | A payment you marked failed becomes authorised later and is never fulfilled or refunded. | Listen for `payment.authorized` on failed orders; capture it or let it auto-refund. | 28 |

## 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.

| Topic | What to know | On this method | Test it | Read more |
| - | - | - | - | - |
| Difference between order and payment | An order is what you want to collect. A payment is one attempt to pay it. One order can have many attempts but only one captured payment. Create the order on your server so the amount cannot be tampered with. | A failed EMI attempt and the retry on another plan or lender are two payments on one order. | BP-24, BP-25 | [Difference between order and payment ↗](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices) |
| Order states | Orders move `created` → `attempted` → `paid`. An order stays `attempted` through failed attempts, and stays `paid` even after a refund. | Run scenario 12 then scenario 3 on the same order: the order should go `attempted` → `paid`. | [Payment states](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/payment-states-and-late-authorisation.md) · [Orders errors](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) | [Order states ↗](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/order-payment-relationship.md) |
| Late authorisation | A payment with no bank response is marked `failed` after 10 minutes, but Razorpay keeps polling the bank for 3 days. If the bank confirms, the payment becomes `authorized`. Listen for `payment.authorized` and capture it, or let it auto-refund. | Can happen on any affordability method when the bank's or lender's response is delayed. | BP-06 | [Late authorisation ↗](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/payment-states-and-late-authorisation.md) |
| Multiple payments on the same order | Once an order is `paid`, no more payments are accepted on it. Retry on the same order so a customer cannot pay twice. | Reuse the order when the customer retries with another plan or card. | BP-09 | [Multiple payments on the same order ↗](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/order-payment-relationship.md) |
| EMI plans and fees | EMI plans, rates and processing fees change by bank, card and amount. | Always fetch plans from `GET /v1/methods` and show the fee before the customer picks a plan. | 1, 7 | [EMI ↗](https://razorpay.com/docs/payments/payment-gateway/emi) |

All best practices: [Overview](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices) · [Webhooks and Fetch APIs](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/webhooks-and-fetch-apis.md) · [Payment states and late authorisation](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/payment-states-and-late-authorisation.md) · [Security](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/security.md)

### Related Information

* [UPI Collect (One-time)](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/one-time/upi-collect.md)
* [Cards (One-time)](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/one-time/cards.md)
* [Orders](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md)
* [Best Practices](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices)
