Available in🇮🇳 India
Run successful payments, simulate failures with test cards and reconcile against the webhooks in test mode, then check saved cards, tokens and the on-demand APIs before you go live.
This page covers one-time card payments on S2S JSON (POST /v1/payments/create/json) and S2S Redirect (POST /v1/payments/create/redirect), including saved cards and tokens. Start with the hub for 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
Card 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 |
|---|---|---|---|
| 1 Successful payment | payment.authorized, payment.captured, order.paid | payment.authorized — Funds are held for you but they’re 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 |
| 2–4 Declined, cancelled, timed out | payment.failed | 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 |
| 6 3DS redirect | payment.authorized, payment.captured, order.paid, payment.failed | payment.authorized — Funds are held for you but they’re 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.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 |
| 7 Manual capture | payment.authorized, payment.captured | payment.authorized — Funds are held for you but they’re not yet yours. Do not fulfil services on this alone.payment.captured — Funds are yours, fulfil services on this. | Available |
| 8 Full and partial refund | refund.created, refund.processed, refund.failed | refund.created — The refund is accepted, not settled. Do not tell the customer the money is back yet.refund.processed — The money has left Razorpay. This is when you confirm the refund to the customer.refund.failed — The refund did not go through. It needs a retry or a manual payout — it will not resolve itself. | Available (refund.failed coming soon) |
| 9 Native OTP | payment.authorized, payment.captured, order.paid, payment.failed | payment.authorized — Funds are held for you but they’re 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.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 |
| 10 Save a card | payment.authorized, payment.captured, order.paid, token.initiated, token.activated | payment.authorized — Funds are held for you but they’re 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.token.initiated — Tokenisation has started but the card is not yet usable. Wait for token.activated.token.activated — The saved card is usable. Show it to the customer now, not before. | Available |
| 11, 12 Pay with a saved or network token | payment.authorized, payment.captured, order.paid | payment.authorized — Funds are held for you but they’re 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 |
| 13 Create, fetch and delete tokens | token.initiated, token.activated, token.deactivated | token.initiated — Tokenisation has started but the card is not yet usable. Wait for token.activated.token.activated — The saved card is usable. Show it to the customer now, not before.token.deactivated — The saved card is gone. Remove it from your UI or the customer will pick a card that cannot pay. | Available |
| 14 One-time on a recurring token | payment.authorized, token.confirmed, token.rejected, payment.captured, order.paid | payment.authorized — Funds are held for you but they’re not yet yours. Do not fulfil services on this alone.token.confirmed — The mandate is live. Only now can you schedule debits against it.token.rejected — Registration failed. The customer has to start again — do not retry against this token.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 |
| 16–45 Every card error scenario | payment.failed | 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 |
| 75 Late authorisation | payment.authorized | payment.authorized — Funds are held for you but they’re not yet yours. Do not fulfil services on this alone. | Live only |
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. An endpoint that skips this is an open write to your order state.
- 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 the on-demand features you use (S2S JSON V2 for Native OTP, the IIN API, the tokenisation APIs) 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. The ones that matter here: ORD-01 create · ORD-02 lifecycle · ORD-03 retry after a failure · ORD-04 signature · ORD-05 idempotent create · ORD-06 fetch · ORD-07 already paid · ORD-16 partial payments. Request errors (ORD-08 to ORD-15) are the same for every method; run them once.
- Use any future expiry date and any 3-digit CVV (4 digits for Amex).
- On the mock bank page, enter any OTP of 4–10 digits, or choose Success, to approve. An OTP of fewer than 4 digits fails.
- For a specific error, pay with its card from 3.3 and choose Failure. Any other card + Failure returns
gateway_technical_error.
Success cards
Cards for specific flows
3. Scenarios to Test Your Integration
This section lists every scenario we think is worth running against your card 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. We highly recommend running these scenarios first. They cover the successful payment, the 3DS redirect and the handful of outcomes you are almost certain to meet once you are live, so getting through them is the shortest route to an integration you can trust.
- Other common scenarios. These come up in normal day-to-day running: manual capture, refunds, Native OTP, saved cards and tokens, and the IIN lookup. They are not errors as such, but your integration still needs to recognise them and respond correctly, so we recommend covering the ones you use before launch.
- Error scenarios. These are failures you can bring on deliberately, with a failure test card or a bad API request, so that you can check your error handling without waiting for a real failure to happen. They are grouped by
error.source, because the source tells you who has to act. - Not available in test mode yet. These scenarios are real and your integration still has to handle them, but they cannot be reproduced in test mode today. We recommend reading through them and checking your handling on live traffic or in a controlled live test before you ship.
3.1 Must-build card scenarios
| # | Scenario | Trigger creds | Steps to follow |
|---|---|---|---|
| 1 | Successful payment | 4100 2800 0000 1007, any CVV, any future expiry. Success, or any 4–10 digit OTP. |
|
| 2 | Declined by bank | 4100 2800 0005 0004 + Failure |
|
| 3 | Customer cancels | 4100 2800 0007 0002 + Failure |
|
| 4 | Payment times out or session expires | 4100 2800 0009 0000, 4100 2800 0003 0048 + Failure |
|
| 5 | Fetch payment and reconcile | A payment ID from 1 (success) and one from 2 (failure) |
|
| 6 | 3DS: redirect to the bank page | Any success card |
|
3.2 Common scenarios in cards
| # | Scenario | Trigger creds | Steps to follow |
|---|---|---|---|
| 7 | Manual capture (full amount) | Any success card, with manual capture |
|
| 8 | Full and partial refund | A captured payment from scenario 1 |
|
| 9 | Native OTP: generate, submit, resend (S2S JSON V2, on-demand) | 4895 1911 1111 1115 (supports Native OTP) |
|
| 10 | Save a card during payment | Any success card + save=1 + customer_id |
|
| 11 | Pay with a saved token | Token from scenario 10 + CVV |
|
| 12 | Pay with your own network token (token requestors only) | Your network token + cryptogram |
|
| 13 | Create, fetch and delete tokens (tokenisation APIs, on-demand) | Valid and invalid token requests |
|
| 14 | One-time payment on a recurring token (needs recurring enabled) | A recurring token (register with Visa 4718 6091 0820 4366) |
|
| 15 | Look up card details by IIN (IIN API, on-demand) | GET /v1/iins/410028 |
|
3.3 Card error scenarios
Pay with the card and choose Failure on the mock bank page. Each card 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 their card or account stopped the payment. Wrong details and a wrong PIN are recoverable: ask them to re-enter. Expired, blocked or over-limit cards are not: ask for another card.| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 16 | Authentication fails | 4100 2800 0000 0009 + Failure, or an OTP under 4 digits | code GATEWAY_ERRORsource customerstep payment_authenticationreason authentication_failed |
|
| 17 | Insufficient funds | 4100 2800 0008 0001 + Failure | code BAD_REQUEST_ERRORsource customerstep payment_authorizationreason insufficient_funds |
|
| 18 | CVV in the wrong format | 4100 2800 0007 0051 + Failure | code BAD_REQUEST_ERRORsource customerstep — reason card_cvv_invalid |
|
| 19 | Incorrect CVV | 4100 2800 0000 0033 + Failure | code BAD_REQUEST_ERRORsource customerstep payment_authorizationreason incorrect_cvv |
|
| 20 | Card expired | 4100 2800 0009 0034 + Failure | code BAD_REQUEST_ERRORsource customerstep payment_authenticationreason card_expired |
|
| 21 | Incorrect expiry date | 4100 2800 0002 0049 + Failure | code BAD_REQUEST_ERRORsource customerstep payment_authenticationreason incorrect_card_expiry_date |
|
| 22 | Incorrect card number | 4100 2800 0001 0008 + Failure | code BAD_REQUEST_ERRORsource customerstep payment_authenticationreason card_number_invalid |
|
| 23 | Incorrect card details | 4100 2800 0001 0040 + Failure | code BAD_REQUEST_ERRORsource customerstep payment_authorizationreason incorrect_card_details |
|
| 24 | Card not enrolled for online payments | 4100 2800 0004 0013 + Failure | code GATEWAY_ERRORsource customerstep card_enrollment_checkreason card_not_enrolled |
|
| 25 | Card blocked | 4100 2800 0001 0032 + Failure | code BAD_REQUEST_ERRORsource customerstep payment_authorizationreason debit_instrument_blocked |
|
| 26 | Card inactive for online payments | 4100 2800 0005 0038 + Failure | code BAD_REQUEST_ERRORsource customerstep payment_authorizationreason debit_instrument_inactive |
|
| 27 | Incorrect PIN | 4100 2800 0002 0031 + Failure | code BAD_REQUEST_ERRORsource customerstep payment_authenticationreason incorrect_pin |
|
| 28 | PIN attempts exceeded | 4100 2800 0005 0046 + Failure | code BAD_REQUEST_ERRORsource customerstep payment_authenticationreason pin_attempts_exceeded |
|
| 29 | Per-transaction limit exceeded | 4100 2800 0008 0035 + Failure | code BAD_REQUEST_ERRORsource customerstep payment_authorizationreason transaction_limit_exceeded |
|
| 30 | Daily amount limit exceeded | 4100 2800 0009 0042 + Failure | code BAD_REQUEST_ERRORsource customerstep payment_authorizationreason transaction_daily_limit_exceeded |
|
| 31 | Daily transaction count exceeded | 4100 2800 0008 0043 + Failure | code BAD_REQUEST_ERRORsource customerstep payment_authorizationreason transaction_daily_count_exceeded |
|
Issuing Bank Errors
The bank declined the payment or had a problem of its own. A technical error is temporary, so offer a retry. A decline is the bank’s decision, so ask for another card rather than retrying the same one.| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 32 | Bank technical error | 4100 2800 0007 0036 + Failure | code GATEWAY_ERRORsource issuer_bankstep payment_authorizationreason bank_technical_error |
|
| 33 | Card declined (other triggers) | 4100 2800 0006 0003, 4100 2800 0004 0005 + Failure | on 0006 0003 code BAD_REQUEST_ERRORsource issuer_bankstep payment_authorizationreason card_declinedon 0004 0005 code BAD_REQUEST_ERRORsource issuer_bankstep payment_initiationreason card_declined |
|
| 34 | Declined by bank at authentication | 4100 2800 0004 0039 + Failure | code BAD_REQUEST_ERRORsource issuer_bankstep payment_authenticationreason declined_by_bank |
|
| 35 | Card disabled for online payments | 4100 2800 0003 0006 + Failure | code BAD_REQUEST_ERRORsource issuer_bankstep payment_authorizationreason card_disabled_for_online_payments |
|
| 36 | Blocked by issuer | 4100 2800 0007 0044 + Failure | code BAD_REQUEST_ERRORsource issuer_bankstep payment_authorizationreason issuer_declined |
|
| 37 | Risk check failed | 4100 2800 0003 0030 + Failure | code BAD_REQUEST_ERRORsource issuer_bankstep payment_authorizationreason payment_risk_check_failed |
|
| 38 | Card restricted | 4100 2800 0006 0045 + Failure | code GATEWAY_ERRORsource bankstep payment_authorizationreason card_restricted |
|
Gateway Errors
Something went wrong between Razorpay and the bank. These are temporary, so offer the customer the same card again.| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 39 | Gateway technical error | 4100 2800 0002 0007, or any other test card + Failure | code GATEWAY_ERRORsource gatewaystep payment_authorizationreason gateway_technical_error |
|
| 40 | Payment failed | 4100 2800 0006 0037 + Failure | code BAD_REQUEST_ERRORsource gatewaystep payment_authorizationreason payment_failed |
|
Business Errors
What you sent, or what is enabled on your account, stopped the payment. Fix it on your side; a retry by the customer won’t help.| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 41 | Card holder name in the wrong format | 4100 2800 0008 0050 + Failure | code GATEWAY_ERRORsource businessstep payment_authenticationreason card_name_invalid |
|
| 42 | API validation errors (all methods) | Missing amount, amount: 0, wrong key secret | missing field code BAD_REQUEST_ERRORreason input_validation_failedamount 0 code BAD_REQUEST_ERRORreason invalid_amountwrong key code BAD_REQUEST_ERRORreason not set |
|
| 43 | Network or international card not enabled | Amex 3402 560004 01007, international 4012 8888 8888 1881 | on Amex code BAD_REQUEST_ERRORreason card_network_not_enabledon international code BAD_REQUEST_ERRORreason international_transaction_not_allowed |
|
Internal Errors
These come back with a Razorpay internal source, or no source yet. Treat them as temporary and offer a retry.| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 44 | Transaction not permitted | 4100 2800 0000 0041 + Failure | code GATEWAY_ERRORsource internalstep payment_initiationreason Transaction not permitted to issuer/cardholder |
|
| 45 | Authentication attempts exceeded | 4100 2800 0004 0047 + Failure | code BAD_REQUEST_ERRORsource — step — reason acs_maximum_attempts_reached |
|
Native OTP API errors
Request errors on the OTP calls in scenario 9. They don’t fail the payment and send no webhook; fix the request, or let the customer re-enter.| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 46 | Wrong OTP | OTP under 4 digits on otp/submit | code BAD_REQUEST_ERRORreason incorrect_otp |
|
| 47 | OTP missing from submit | otp/submit with no otp | code BAD_REQUEST_ERRORreason not set |
|
| 48 | OTP generated twice | otp_generate twice | code BAD_REQUEST_ERRORreason not set |
|
| 49 | Resend on a non-OTP payment | otp/resend without auth_type=otp | code BAD_REQUEST_ERRORreason input_validation_failed |
|
| 50 | Submit after success | otp/submit again | code BAD_REQUEST_ERRORreason gateway_technical_error |
|
| 51 | Wrong payment ID on OTP calls | A wrong payment_id | code BAD_REQUEST_ERRORreason input_validation_failed |
|
Token API errors
Request errors on the tokenisation and saved-card token APIs in scenario 13. Rows marked live mode only can’t be reproduced in test mode.| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 52 | Create: required field missing | POST /v1/tokens without e.g. number | code BAD_REQUEST_ERRORreason input_validation_failed |
|
| 53 | Create: field in the wrong format | POST /v1/tokens | code BAD_REQUEST_ERRORreason input_validation_failed |
|
| 54 | Create: invalid card number | POST /v1/tokens | code BAD_REQUEST_ERRORreason input_validation_failed |
|
| 55 | Create: CVV length | POST /v1/tokens with a 2- or 5-digit cvv | code BAD_REQUEST_ERRORreason input_validation_failed |
|
| 56 | Fetch: token ID doesn’t exist (live mode only) | POST /v1/tokens/fetch | code BAD_REQUEST_ERRORreason input_validation_failed |
|
| 57 | Fetch: badly formed token ID (live mode only) | POST /v1/tokens/fetch | code BAD_REQUEST_ERRORreason input_validation_failed |
|
| 58 | Fetch: extra field sent (live mode only) | POST /v1/tokens/fetch | code BAD_REQUEST_ERRORreason extra_field_sent |
|
| 59 | Fetch: card not compliant (live mode only) | POST /v1/tokens/fetch | code BAD_REQUEST_ERRORreason card_not_compliant |
|
| 60 | Fetch: token not found | POST /v1/tokens/fetch | code BAD_REQUEST_ERRORreason not set |
|
| 61 | Delete: token not found | POST /v1/tokens/delete | code BAD_REQUEST_ERRORreason input_validation_failed |
|
| 62 | Delete: API not enabled (live mode only) | POST /v1/tokens/delete | code BAD_REQUEST_ERRORreason not set |
|
| 63 | Saved card: ID doesn’t exist | /v1/customers/:id/tokens | code BAD_REQUEST_ERRORreason input_validation_failed |
|
| 64 | Saved card: badly formed ID | /v1/customers/:id/tokens | code BAD_REQUEST_ERRORreason input_validation_failed |
|
| 65 | Saved card: token of another customer | /v1/customers/:id/tokens/:token_id | code BAD_REQUEST_ERRORreason not set |
|
IIN API errors
Request errors on the IIN lookup in scenario 15.| # | Scenario | Trigger creds | Error object | Steps to follow |
|---|---|---|---|---|
| 66 | IIN doesn’t exist | GET /v1/iins/000000 | code BAD_REQUEST_ERRORreason iin_does_not_exist |
|
| 67 | Card IIN of the wrong length | GET /v1/iins/41002 | code BAD_REQUEST_ERRORreason invalid_iin_length |
|
| 68 | Token IIN of the wrong length | GET /v1/iins/:token_iin | code BAD_REQUEST_ERRORreason invalid_iin_length |
|
| 69 | IIN API not enabled | GET /v1/iins/:iin | code BAD_REQUEST_ERRORreason not set |
|
error.reason for that error today. Branch on the HTTP status and error.code instead.
The full list of card error reasons, including the 37 no test card reproduces, is on the Error index. Mandate errors are on Card recurring.
3.4 Not available in test mode yet
4. Common Integration Gaps to Avoid
These are the mistakes that most often cause failed payments, missed debits or double charges after go-live. “Test with” points to the scenario that proves you’ve handled it.Webhook and token updates
Error handling and messaging to the payer
3DS, OTP and saved cards
Fetch API when webhooks are late
Capture & refunds
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 can’t be tampered with. | A declined card and the retry with another card are two payments on one order. | BP-24, BP-25 | Difference between order and payment ↗ |
| Order states | Orders move created → attempted → paid. An order stays attempted through failed attempts, and stays paid even after a refund. Handle Orders API errors (for example an invalid amount or currency) when you create the order. | Run scenario 17 then scenario 1 on the same order: the order should go attempted → paid. | Payment states · Orders errors | Order states ↗ Orders API error codes ↗ |
| 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 (under 0.5% of payments). Listen for payment.authorized and capture it, or let it auto-refund. | Less common on cards, but it happens when the bank’s 3DS response is delayed. | BP-06 | Late authorisation ↗ |
| Capture settings | Choose auto-capture or manual capture and set the timeouts. An authorized payment you don’t capture in time is auto-refunded. You can set capture behaviour per order through the Orders API. | Manual and partial capture Coming soon in test mode. Check them in a small live test. | BP-14 | Capture settings ↗ |
| Multiple payments on the same order | Once an order is paid, no more payments are accepted on it. While a payment on the order is authorized, a new attempt isn’t allowed. An attempt that authorises late on a paid order is auto-refunded. Retry on the same order so a customer can’t pay twice. | Reuse the order when the customer retries after a decline. | BP-09 · BP-08 | Multiple payments on the same order ↗ |