Cards: How to Test Your Integration

Available in🇮🇳 India

This page covers one-time card payments on S2S JSON (POST /v1/payments/create/json) and S2S Redirect (POST /v1/payments/create/redirect). Standard Checkout and Custom Checkout are out of scope for this page. Start with the overview for test keys and webhook setup.

Before you startEvery scenario on this page needs an order. Order behaviour has scenarios of its own, all on Orders. The ones that matter for this method: 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.

1. Test Mode Coverage

Behaviour	Live mode	Test mode
Authentication	Issuer ACS page (3DS) or Native OTP	Mock bank page with Success and Failure buttons. Any OTP of 4–10 digits succeeds; fewer than 4 digits fails.
Card numbers	Real cards	Test cards only. In live mode they fail with “card issuer is invalid”.
Networks and international	As enabled on your live account	As enabled on your test account. A disabled network returns `card_network_not_enabled`.
Webhook delivery	Razorpay sends the webhook once the gateway has authorised the payment. That round trip is real, so delivery can take minutes and your reconciler has to allow for it.	The gateway is simulated, so the webhook is sent as soon as the create-payment request succeeds, almost instantly. Do not use test mode to size your reconciliation windows or to judge how long to wait before polling.
On-demand features (S2S JSON V2, IIN API, Token HQ)	Enabled per account	Enabled separately for test mode

Area	Available on test mode	Note
Payments	Available	Success, declines, cancel and timeout, fetch
Authentication	Available	3DS redirect, Native OTP, authentication failures
Saved cards and tokens	Available	Save, pay with a token, network tokens, Token HQ APIs, one-time on a recurring token
BIN / IIN lookup	Available	`GET /v1/iins/:iin`
Refunds	Available	Full and partial
Manual and partial capture	Coming soon · TBD	—
Apple Pay, Card Sync, passkeys, CVV-less, fee bearer, debit card TPV, bulk BIN	Coming soon · TBD	—

2. Test Kit

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.
For a specific error, pay with a card from Simulate Failures and choose Failure. Any other card + Failure returns gateway_technical_error.

Success cards

Network	Sub type	Credit	Debit	Prepaid
Visa	Consumer	⚑ New — number TBD	`4100 2800 0000 1007`	⚑ New — number TBD
Visa	Business	⚑ New — number TBD	⚑ New — number TBD	n/a
Mastercard	Consumer	⚑ New — number TBD	⚑ New — number TBD	`5180 2872 0009 1001`
Mastercard	Business	`5555 5100 0008 1006`	⚑ New — number TBD	n/a
RuPay	Consumer	`6527 6589 0000 1005`	⚑ New — number TBD	⚑ New — number TBD
RuPay	Business	⚑ New — number TBD	⚑ New — number TBD	n/a
American Express	Consumer	`3402 560004 01007`	n/a	n/a
American Express	Business	⚑ New — number TBD	n/a	n/a
Diners Club	Consumer	`3608 280009 1007`	n/a	n/a
Diners Club	Business	⚑ New — number TBD	n/a	n/a

Cards for specific flows

Use it to test	Card number	Notes
Native OTP: card that supports it	`4895 1911 1111 1115`	Used in CARD-B2
Native OTP: card that doesn’t support it	`4386 2894 0766 0153`	`/v1/payment/flows` returns `otp: false`; use 3DS
International card	`4012 8888 8888 1881`	—
International card with billing address	`5105 1051 0510 5100`	Asks for a billing address
Card EMI	`5241 8100 0000 0000`	—

3. Scenarios to Test Your Integration

Must-have (6) — the paths where money moves or is lost: a successful payment, a decline, a cancel, a fetch-and-reconcile, and the 3DS redirect. Other common scenarios (8) — refunds, Native OTP, saved cards and tokens, network tokens, Token HQ, one-time payments on a recurring token, and an IIN lookup. Error scenarios (6) — failures you trigger deliberately with a test card, so you can check your error handling without waiting for a real one. Not available in test mode yet (5) — real scenarios your integration still has to handle, but can’t be reproduced here today. 25 scenarios in all: 20 you can run in test mode today, 5 you cannot.

3.1 Must-have

Scenario ID	Method	Scenario	Trigger	Steps to follow
P01	S2S JSON, S2S Redirect	Successful payment	`4100 2800 0000 1007`, any CVV, any future expiry + Success (or any 4–10 digit OTP)	Create an order. Create the payment. Complete authentication on the mock bank page. Verify the signature. Confirm `payment.captured` and `order.paid`.
P03	All	Declined by bank	`4100 2800 0005 0004` + Failure	Pay with the card and choose Failure. Confirm `payment.failed` with `card_declined`. Let the customer try another card.
P04	All	Customer cancels	`4100 2800 0007 0002` + Failure	Pay and choose Failure (or close the bank page). Confirm `payment_cancelled`. The order stays open for a retry.
P05	All	Payment times out or session expires	`4100 2800 0009 0000`, `4100 2800 0003 0048` + Failure	Pay and choose Failure. Confirm `payment_timed_out` / `payment_session_expired`. Don’t fulfil.
P10	All	Fetch payment and reconcile	A payment ID from P01 (success) and one from P03 (failure)	Call `GET /v1/payments/:id` after each scenario. Confirm the status matches the webhook. Call it with a wrong ID and confirm the error.
CARD-B1	S2S Redirect, S2S JSON	3DS: redirect to the bank page	Any success card	Create the payment and redirect to `next[]` (JSON) or render the page (Redirect). Enter a 4–10 digit OTP; repeat with fewer than 4 digits. Confirm the customer returns to your `callback_url`.

3.2 Other common scenarios

Scenario ID	Method	Scenario	Trigger	Steps to follow
P12	All	Full and partial refund	A captured payment from P01	Refund one payment in full and one in part (`POST /v1/payments/:id/refund`). Confirm `refund.processed` and `refund_status`.
CARD-B2	S2S JSON V2 (on-demand)	Native OTP: generate, submit, resend	`4895 1911 1111 1115`	Create the payment with `auth_type: "otp"`. Call `otp_generate`, then `otp/submit`. Submit a wrong OTP: expect `action: "RETRY"`. Then resend and submit again.
CARD-C1	Saved cards	Save a card during payment	Any success card + `save: 1` + `customer_id`	Create a customer. Pay with `save: 1`. Confirm the token appears in `GET /v1/customers/:id/tokens`.
CARD-C2	Saved cards	Pay with a saved token	Token from CARD-C1 + CVV	Pay with `customer_id` and `token`. Confirm success without the card number.
CARD-C3	Token requestors	Pay with your own network token	Your network token + cryptogram	Create the payment with `card.tokenised: true`, `cryptogram_value`, `token_provider`. Leave out a field and confirm `input_validation_failed`.
CARD-C4	Token HQ (on-demand)	Create, fetch and delete tokens	Valid and invalid token requests	Call `POST /v1/tokens`, `/tokens/fetch`, `/tokens/delete`. Send each invalid request. Confirm `token.activated` and `token.deactivated`.
CARD-C5	Recurring + one-time	One-time payment on a recurring token	Token from a card mandate registration	Register a mandate. Create a new order and pay with `customer_id` + `token`, without `recurring`. Confirm the mandate stays active.
CARD-D1	IIN API (on-demand)	Look up card details by IIN	`GET /v1/iins/410028`; invalid: `000000`, `41002`	Call the IIN API for a card IIN and a token IIN. Send each invalid IIN and confirm the error.

3.3 Error scenarios

Scenario ID	Method	Scenario	Trigger	Steps to follow
P02	All	Insufficient funds	`4100 2800 0008 0001` + Failure	Pay and choose Failure. Confirm `insufficient_funds` and a “try another card” message.
P06	All	Authentication fails	`4100 2800 0000 0009` + Failure, or an OTP under 4 digits	Pay and fail authentication. Confirm `error.step: "payment_authentication"`.
P07	All	Bank technical error	`4100 2800 0007 0036` + Failure	Pay and choose Failure. Confirm `bank_technical_error` and a retry option.
P08	All	Gateway technical error	`4100 2800 0002 0007`, or any test card + Failure	Pay and choose Failure. Confirm `gateway_technical_error`.
P09	All	API validation errors	Missing `amount`, `amount: 0`, wrong key secret	Send each bad request. Confirm HTTP 4xx, no payment created, no webhook.
CARD-N1	All	Network or international card not enabled	Amex `3402 560004 01007`, international `4012 8888 8888 1881`	Pay with each card while that network or international payments is disabled. Confirm `card_network_not_enabled` / `international_transaction_not_allowed`.

3.4 Not available in test mode yet

Scenario ID	Method	Scenario	Why it is not in test mode
CARD-X1	All	Manual and partial capture	Coming soon · TBD. Check in a small live test.
CARD-X2	Saved cards	CVV-less saved card payments	Coming soon · TBD. Check in a small live test.
CARD-X3	Device tokens	Apple Pay, Card Sync (CRED, Google)	Coming soon · TBD. Check in a small live test.
CARD-X4	Authentication	Visa and Mastercard passkeys	Coming soon · TBD. Check in a small live test.
CARD-X5	Pricing	Customer fee bearer (convenience fee)	Coming soon · TBD. Check in a small live test. Changing fee bearer in test mode also changes it in live — be careful.

4. Scenario Details

Each block follows the same format: before you start, how to test, expected result, webhooks, and errors to test.

P01 — Successful card payment (covers P09, CARD-N1)

Before you start: an order created with POST /v1/orders (every payment needs an order_id). Test order creation once on Orders. How to test: create the payment with the order’s order_id and a success card from the test kit (for example Visa 4100 2800 0000 1007) using S2S JSON (POST /v1/payments/create/json) or S2S Redirect (POST /v1/payments/create/redirect). Redirect the customer to the URL in next[] (JSON) or render the returned page (Redirect). On the mock bank page, enter any 4–10 digit OTP. Expected result: payment captured (or authorized if you capture manually). The customer returns to your callback_url with razorpay_payment_id, razorpay_order_id and razorpay_signature; verify the signature server-side. Webhooks: payment.authorized, payment.captured, order.paid Your integration should: verify the signature server-side and fulfil on payment.captured.

P04 — Customer cancels, times out or session expires (covers P05)

How to test: start a payment, then close the mock bank page or choose cancel. Use the cancel and timeout cards for the exact errors: payment_cancelled (4100 2800 0007 0002), payment_timed_out (4100 2800 0009 0000), payment_session_expired (4100 2800 0003 0048). Expected result: the payment ends failed. The order stays unpaid so the customer can retry. Webhooks: payment.failed

P06 — Authentication failures

How to test: pay with each authentication-failure card and choose Failure: 4100 2800 0000 0009 (authentication_failed), 4100 2800 0004 0039 (declined_by_bank), 4100 2800 0004 0047 (acs_maximum_attempts_reached), 4100 2800 0002 0031 (incorrect_pin), 4100 2800 0005 0046 (pin_attempts_exceeded), 4100 2800 0004 0013 (card_not_enrolled). Expected result: payment fails at error.step: "payment_authentication". Ask the customer to retry or use another card. Webhooks: payment.failed

P10 — Fetch payment and reconcile

How to test: call GET /v1/payments/:id after each scenario above. Also call it with a wrong ID, and with a test-mode payment ID using live keys. Expected result: the status matches the webhook you received. A wrong ID returns an error.

CARD-B1 — 3DS: redirect to the bank page

How to test: pay with any success card. You’re redirected to the mock bank page; any 4–10 digit OTP succeeds, an OTP under 4 digits fails the payment. Webhooks: success payment.authorized, payment.captured, order.paid; failure payment.failed

CARD-B2 — Native OTP: generate, submit and resend

Before you start: S2S JSON V2 enabled on your account (on-demand). How to test: optionally check Native OTP support with POST /v1/payment/flows. Create the payment with auth_type: "otp" using a Native OTP card. Call POST /v1/payments/:payment_id/otp_generate (URL is in next[]). Submit the OTP with POST /v1/payments/:payment_id/otp/submit. Any 4–10 digit OTP succeeds in test mode. Test resend once with otp/resend, then submit again. Expected result: otp_generate and otp/resend return next[] with otp_submit and otp_resend. A successful submit returns the signature fields. Webhooks: success payment.authorized, payment.captured, order.paid. A wrong OTP that returns action: "RETRY" sends no webhook; payment.failed comes only when the payment finally fails. Your integration should: treat action: "RETRY" as “ask again”, not as a failure.

CARD-C1 — Save a card during payment

Before you start: a customer created with POST /v1/customers. How to test: pay with a success card, save: 1 and customer_id on POST /v1/payments/create/json. Expected result: payment succeeds and a token is created for the customer, visible in GET /v1/customers/:customer_id/tokens. Webhooks: payment.authorized, payment.captured, order.paid. If you use Token HQ, also token.initiated, token.activated.

CARD-C2 — Pay with a saved Razorpay token

Before you start: a token saved in CARD-C1. How to test: pay again with customer_id and the token, plus the CVV. Expected result: payment succeeds without the card number. Webhooks: payment.authorized, payment.captured, order.paid

CARD-C3 — Pay with your own network token

Before you start: you’re a token requestor with a network token and cryptogram. How to test: create the payment with card.tokenised: true, cryptogram_value, token_provider and provider_type: "network". Webhooks: payment.authorized, payment.captured, order.paid

CARD-C4 — Create, fetch and delete tokens

Before you start: Token HQ enabled on your account for the /v1/tokens APIs. How to test: Token HQ — call POST /v1/tokens, POST /v1/tokens/fetch, POST /v1/tokens/delete. Saved cards — call GET /v1/customers/:customer_id/tokens, GET .../tokens/:token_id and DELETE .../tokens/:token_id. Webhooks: create token.initiated, token.activated. Delete token.deactivated. Sent by the network later: token.expiry_updated, token.suspended.

CARD-C5 — One-time payment with a recurring token

Before you start: recurring payments enabled on your account, and a customer. How to test: use this if you save cards through a recurring (mandate) registration and also charge the same token for one-time purchases. Register the mandate with recurring: 1 and customer_id, using the recurring test card Visa 4718 6091 0820 4366. Wait until the token is confirmed. For the one-time purchase, create a new order, then call POST /v1/payments/create/json with customer_id and token, without recurring (or recurring: 0). CVV is optional for tokenised cards. Complete authentication from next[] (3DS on the mock bank page, or Native OTP as in CARD-B2). Expected result: the one-time payment succeeds like any saved-card payment: the customer authenticates, and no pre-debit notification is sent. The mandate and token stay active. Webhooks: mandate registration — payment.authorized (carries token_id), then token.confirmed or token.rejected. One-time payment — payment.authorized, payment.captured, order.paid, and order.notification.delivered is not sent (note the order. prefix on the live-mode event name).

CARD-D1 — Look up card details by IIN

Before you start: IIN API enabled on your account (on-demand). How to test: call GET /v1/iins/:iin before creating the payment — for example to check card type, international, EMI or recurring eligibility, or Native OTP support. A 6-digit card IIN (for example 410028) works for all networks. A 9-digit token IIN works for Visa, Mastercard and RuPay; a 6-digit token IIN works for Amex; Diners Club isn’t supported. Then send invalid IINs: 000000 (doesn’t exist), 41002 (wrong length).

P12 — Full and partial refunds

Before you start: a captured payment from P01. How to test: refund one captured payment in full and another in part, with POST /v1/payments/:payment_id/refund. Expected result: you receive refund.created and refund.processed. The payment shows refund_status as full or partial. Webhooks: refund.created, refund.processed, or refund.failed if the refund fails. Refund errors are covered on Refunds.

5. Webhooks: What Fires, and What It Lets You Decide

Every scenario above delivers a specific set of events, in a specific order. This table is the one place that says which, and — the part that actually matters — what each one entitles you to do. Most integration bugs that reach production are not missing webhooks; they are acting on the wrong one.

Scenario	What it is	Events, in order	What it lets you decide
P01	Successful payment	`payment.authorized`, `payment.captured`, `order.paid`	Fulfil the order.
P03	Declined by bank	`payment.failed`	Let the customer try another card.
P04	Customer cancels, times out or session expires	`payment.failed`	Keep the order open for a retry.
CARD-B1	3DS redirect	success: `payment.authorized`, `payment.captured`, `order.paid`; failure: `payment.failed`	Fulfil only after `payment.captured`, never on the browser callback alone.
P12	Full and partial refund	`refund.created`, `refund.processed` (or `refund.failed`)	Update `refund_status` only on `refund.processed`.
CARD-B2	Native OTP: generate, submit, resend	success: `payment.authorized`, `payment.captured`, `order.paid`; a wrong OTP with `action: "RETRY"` sends nothing	Ask for the OTP again on `action: "RETRY"`; don’t treat it as a failure.
CARD-C1	Save a card during payment	`payment.authorized`, `payment.captured`, `order.paid`; with Token HQ also `token.initiated`, `token.activated`	Mark the saved card usable only after `token.activated`.
CARD-C2 to CARD-C5	Pay with a saved card, network token or recurring token	`payment.authorized`, `payment.captured`, `order.paid`	Fulfil the same way as a fresh card payment.
P06	Authentication fails	`payment.failed`	Ask the customer to retry or use another card.

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.

6. Common Integration Gaps to Avoid

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.	P02–P08
Same message for every failure	A customer whose card was declined retries the same card again and again.	Branch on `error.reason` and `error.source`: ask for another card on issuer declines, ask to re-enter on wrong details, offer a plain retry on technical errors.	P02, P03, P07
Wrong OTP treated as failure	With Native OTP, a wrong OTP returns `action: "RETRY"`, but the integration ends the payment.	On `incorrect_otp` with `action: "RETRY"`, show the OTP screen again with resend.	CARD-B2

Webhook and token updates

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.	P01
Saved card marked usable too early	The card shows as saved but the first token payment fails because the network token isn’t active yet.	Mark the card usable only after `token.activated`. Remove it on `token.deactivated`; update or hide it on `token.expiry_updated` and `token.suspended`.	CARD-C1, CARD-C4
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

Fetch API when webhooks are late

Gap	What goes wrong in production	What to do	Test with
Marking the order failed when nothing arrives	The bank responds slowly. You mark the order failed and the payment captures minutes later.	If no webhook arrives within a minute, poll `GET /v1/payments/:id` or `GET /v1/orders/:id/payments`. Treat the API as the source of truth.	P10
No reconciliation job	Payments captured during a webhook outage never reach your system.	Run a periodic job that fetches orders still `attempted` and reconciles them.	P10

7. Best Integration Practices

These apply to every Razorpay integration. “On this method” says what each one means for cards; “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 new order is needed for every payment attempt once the previous attempt has reached a terminal state.	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.	P10 fetches a payment to reconcile its status against the order.	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.	BP-06	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.	BP-14 covers manual and partial capture, coming soon for cards.	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.	CARD-C5 pays a new order with a recurring token, never the same order twice.	BP-09 · BP-08	Multiple payments on the same order ↗

All best practices: Overview · Webhooks and Fetch APIs · Payment states and late authorisation · Error handling · Downtime handling · Security

8. Simulate Failures

The full list of Cards error reasons, including the ones no trigger reproduces in test mode, is on the Error index. Branch your handling on error.reason and error.source, never on the description text. These are payment errors; errors from creating the order are on Orders.

Errors available in test mode (33 triggers → 31 distinct error.reason values)

Grouped by source: Customer (19), Issuing bank (8), Bank (1), Gateway (2), Your request (business) (1), Razorpay internal (2), Source not mapped (1). Pay with the card and choose Failure on the mock bank page.

Trigger	error.code	error.source	error.step	error.reason	error.description
`4100 2800 0000 0009` + Failure	GATEWAY_ERROR	customer	payment_authentication	authentication_failed	Your payment could not be completed due to incorrect OTP or verification details. Try another payment method or contact your bank for details.
`4100 2800 0007 0051` + Failure	BAD_REQUEST_ERROR	customer	—	card_cvv_invalid	You have entered an incorrect CVV number. Try again.
`4100 2800 0009 0034` + Failure	BAD_REQUEST_ERROR	customer	payment_authentication	card_expired	Your payment could not be completed as your card has expired. Try another payment method.
`4100 2800 0004 0013` + Failure	GATEWAY_ERROR	customer	card_enrollment_check	card_not_enrolled	Your payment could not be completed as this card is not enabled for online payments. Try another payment method or contact your bank for details.
`4100 2800 0001 0008` + Failure	BAD_REQUEST_ERROR	customer	payment_authentication	card_number_invalid	You’ve entered an incorrect card number. Try again.
`4100 2800 0001 0032` + Failure	BAD_REQUEST_ERROR	customer	payment_authorization	debit_instrument_blocked	Your payment could not be completed as your card is blocked. Try another payment method or contact your bank for details.
`4100 2800 0005 0038` + Failure	BAD_REQUEST_ERROR	customer	payment_authorization	debit_instrument_inactive	Your payment could not be completed as this card is not enabled for online payments. Try another payment method or contact your bank for details.
`4100 2800 0001 0040` + Failure	BAD_REQUEST_ERROR	customer	payment_authorization	incorrect_card_details	You’ve entered incorrect card details. Try again or retry the payment with another card or method.
`4100 2800 0002 0049` + Failure	BAD_REQUEST_ERROR	customer	payment_authentication	incorrect_card_expiry_date	You’ve entered an incorrect expiration date. Try again.
`4100 2800 0000 0033` + Failure	BAD_REQUEST_ERROR	customer	payment_authorization	incorrect_cvv	You’ve entered an incorrect CVV number. Try again.
`4100 2800 0002 0031` + Failure	BAD_REQUEST_ERROR	customer	payment_authentication	incorrect_pin	Incorrect PIN entered. Please try again.
`4100 2800 0008 0001` + Failure	BAD_REQUEST_ERROR	customer	payment_authorization	insufficient_funds	Your payment could not be completed due to insufficient account balance. Try another card or payment method.
`4100 2800 0007 0002` + Failure	BAD_REQUEST_ERROR	customer	payment_authentication	payment_cancelled	Your payment has been cancelled. Try again or complete the payment later.
`4100 2800 0003 0048` + Failure	GATEWAY_ERROR	customer	payment_authentication	payment_session_expired	Your payment could not be completed on time. Try again later.
`4100 2800 0009 0000` + Failure	BAD_REQUEST_ERROR	customer	payment_authentication	payment_timed_out	Payment was not completed on time.
`4100 2800 0005 0046` + Failure	BAD_REQUEST_ERROR	customer	payment_authentication	pin_attempts_exceeded	You’ve entered an incorrect pin too many times. Try again in sometime.
`4100 2800 0008 0043` + Failure	BAD_REQUEST_ERROR	customer	payment_authorization	transaction_daily_count_exceeded	You’ve reached the maximum transaction limit on this card for today. Try another payment method or contact your bank.
`4100 2800 0009 0042` + Failure	BAD_REQUEST_ERROR	customer	payment_authorization	transaction_daily_limit_exceeded	Payment failed because card has reached its limit.
`4100 2800 0008 0035` + Failure	BAD_REQUEST_ERROR	customer	payment_authorization	transaction_limit_exceeded	You’ve reached the maximum transaction limit for this card. Try another payment method or contact your bank.
`4100 2800 0007 0036` + Failure	GATEWAY_ERROR	issuer_bank	payment_authorization	bank_technical_error	Your payment did not go through due to a temporary technical issue at the bank. Any debited amount will be refunded in 4-5 business days.
`4100 2800 0006 0003` + Failure	BAD_REQUEST_ERROR	issuer_bank	payment_authorization	card_declined	Your payment didn’t go through as it was declined by the bank. Try another payment method or contact your bank.
`4100 2800 0005 0004` + Failure	BAD_REQUEST_ERROR	issuer_bank	payment_authorization	card_declined	Your payment didn’t go through as it was declined by the bank. Try another payment method or contact your bank.
`4100 2800 0004 0005` + Failure	BAD_REQUEST_ERROR	issuer_bank	payment_initiation	card_declined	Your payment didn’t go through as it was declined by the bank. Try another payment method or contact your bank.
`4100 2800 0003 0006` + Failure	BAD_REQUEST_ERROR	issuer_bank	payment_authorization	card_disabled_for_online_payments	Your card has been disabled for online payments by your issuing bank. Please reach out to your bank or re-try with another card or method.
`4100 2800 0004 0039` + Failure	BAD_REQUEST_ERROR	issuer_bank	payment_authentication	declined_by_bank	Your payment did not go through as it was declined by the bank. Try another payment method or contact your bank.
`4100 2800 0007 0044` + Failure	BAD_REQUEST_ERROR	issuer_bank	payment_authorization	issuer_declined	Transaction not supported/blocked by issuer.
`4100 2800 0003 0030` + Failure	BAD_REQUEST_ERROR	issuer_bank	payment_authorization	payment_risk_check_failed	Your payment did not go through as it was declined by the bank. Try another payment method or contact your bank.
`4100 2800 0006 0045` + Failure	GATEWAY_ERROR	bank	payment_authorization	card_restricted	Payment processing failed due to error at bank or wallet gateway.
`4100 2800 0002 0007` + Failure	GATEWAY_ERROR	gateway	payment_authorization	gateway_technical_error	Payment processing failed due to error at bank or wallet gateway.
`4100 2800 0006 0037` + Failure	BAD_REQUEST_ERROR	gateway	payment_authorization	payment_failed	Payment failed.
`4100 2800 0008 0050` + Failure	GATEWAY_ERROR	business	payment_authentication	card_name_invalid	Your payment could not be completed as the card holder name is not of correct format. Enter the card holder name in correct format or try with another card.
`4100 2800 0000 0041` + Failure	GATEWAY_ERROR	internal	payment_initiation	—	Your payment didn’t go through due to a temporary issue. Any debited amount will be refunded in 4-5 business days.
`4100 2800 0004 0047` + Failure	BAD_REQUEST_ERROR	—	—	acs_maximum_attempts_reached	Payment was unsuccessful as you exceeded the number of authentication attempts.

Errors not available in test mode (38 rows → 38 distinct error.reason values)

These happen on live card payments but can’t be triggered here. Handle them by error.reason the same way. Grouped by source: Customer (1), Your request (business) (1), Razorpay internal (36), of which source not mapped (33). 17 mandate errors are left out of this count — simulate those on Card recurring.

error.code	error.source	error.step	error.reason	error.description
BAD_REQUEST_ERROR	customer	pre_debit_notification	token_deleted	The requested token has been deleted
GATEWAY_ERROR	business	payment_initiation	token_expired	Gateway Error Technical Error.
GATEWAY_ERROR	internal	payment_initiation	bin_disabled	Your payment could not be completed as your card is not supported. Try another payment method.
SERVER_ERROR	internal	payment_creation	internal	The server encountered an error. The incident has been reported to admins.
SERVER_ERROR	internal	get_token	server_error	Your payment could not be completed due to a temporary technical issue. To complete the payment, use another payment method.
BAD_REQUEST_ERROR	—	—	amount_mismatch	The amount does not match with payment amount
BAD_REQUEST_ERROR	—	—	avs_failure	Payment failed as it did not pass all risk checks. Please try again or use another card.
BAD_REQUEST_ERROR	—	—	bank_account_validation_failed	Your payment is declined due to a mismatch in account details. Try again with the account registered with the business only.
BAD_REQUEST_ERROR	—	—	card_bin_not_found	Card could not be processed. Please try a different card
BAD_REQUEST_ERROR	—	—	card_not_eligible	The card is not eligible for tokenisation.
BAD_REQUEST_ERROR	—	—	card_read_error	Card could not be read properly. Please try again
SERVER_ERROR	—	—	cross_border_error	Error unmarshalling HTTP response
BAD_REQUEST_ERROR	—	—	decryption_failed	Decryption failed
BAD_REQUEST_ERROR	—	—	duplicate_transaction	This transaction has already been processed
BAD_REQUEST_ERROR	—	—	expired_otp	Payment processing failed because of expired OTP
BAD_REQUEST_ERROR	—	—	fallback_declined	Payment could not be processed. Please try again
BAD_REQUEST_ERROR	—	—	fees_greater_than_amount	Invalid Fee
BAD_REQUEST_ERROR	—	—	giftcard_limits_exhausted	Your payment didn’t go through as you have exhausted the Giftcard limits. You can buy more giftcards next cycle.
GATEWAY_ERROR	—	—	incorrect_cardholder_name	You’ve entered an incorrect card name. Try again.
BAD_REQUEST_ERROR	—	—	incorrect_request	Something went wrong, please try again after sometime.
BAD_REQUEST_ERROR	—	—	invalid_data	Your payment didn’t go through due to a temporary issue. Please reach out to the business.
BAD_REQUEST_ERROR	—	—	invalid_iin	The requested IIN is not a valid token IIN
BAD_REQUEST_ERROR	—	—	invalid_transaction	This transaction could not be processed. Please try again
BAD_REQUEST_ERROR	—	—	invalid_txn_id	The transaction id is invalid
BAD_REQUEST_ERROR	—	—	issuer_special_condition	Payment could not be processed. Please contact your card issuer
INTERNAL_SERVER_ERROR	—	—	key_exchange_failed	Payment could not be processed. Please try again
BAD_REQUEST_ERROR	—	—	NA	Could not validate payment callback request
BAD_REQUEST_ERROR	—	—	no_checking_account	No active checking account linked to the card. Contact your issuer or use another payment method.
BAD_REQUEST_ERROR	—	—	no_saving_account	No active savings account linked to the card. Contact your issuer or use another payment method.
BAD_REQUEST_ERROR	—	—	otp_length_invalid	Payment was unsuccessful as the OTP length is incorrect. Please submit a valid OTP with length of 4, 6 or 8 digits.
GATEWAY_ERROR	—	payment_authorization	—	Your payment didn’t go through due to a temporary issue. Any debited amount will be refunded in 4-5 business days.
BAD_REQUEST_ERROR	—	—	pending_confirmation	The transaction is pending final confirmation from the payment provider.
BAD_REQUEST_ERROR	—	—	pin_required	PIN is required for this transaction. Please try again
INTERNAL_SERVER_ERROR	—	—	pricing_not_configured	Payment could not be processed. Please contact the merchant
GATEWAY_ERROR	—	—	terminal_error	Your payment could not be completed due to a temporary technical issue. To complete the payment, use another payment method.
BAD_REQUEST_ERROR	—	—	terminal_not_found	Payment could not be processed. Please contact the merchant
BAD_REQUEST_ERROR	—	—	tpv_not_enabled	Your payment was unsuccessful as this seller is not enabled for card payments. Try using another method.
GATEWAY_ERROR	—	—	transaction_frequency_limit_exceeded	Payment was unsuccessful as the number of transactions exceeds the max limit set by the bank. You can use another bank account or retry after some time.

Handy TipsFor a full picture of what fires when, see Webhooks and Fetch APIs. Verify the signature on every event, key your handler on the event ID, and never assume event order.

1. Build Integration

2. Test S2S Integration

3. Go Live Checklist

Features

Cards: How to Test Your Integration

1. Test Mode Coverage

2. Test Kit

3. Scenarios to Test Your Integration

3.1 Must-have

3.2 Other common scenarios

3.3 Error scenarios

3.4 Not available in test mode yet

4. Scenario Details

P01 — Successful card payment (covers P09, CARD-N1)

P04 — Customer cancels, times out or session expires (covers P05)

P06 — Authentication failures

P10 — Fetch payment and reconcile

CARD-B1 — 3DS: redirect to the bank page

CARD-B2 — Native OTP: generate, submit and resend

CARD-C1 — Save a card during payment

CARD-C2 — Pay with a saved Razorpay token

CARD-C3 — Pay with your own network token

CARD-C4 — Create, fetch and delete tokens

CARD-C5 — One-time payment with a recurring token

CARD-D1 — Look up card details by IIN

P12 — Full and partial refunds

5. Webhooks: What Fires, and What It Lets You Decide

6. Common Integration Gaps to Avoid

Webhook and token updates

Fetch API when webhooks are late

7. Best Integration Practices

8. Simulate Failures

Errors available in test mode (33 triggers → 31 distinct error.reason values)

Errors not available in test mode (38 rows → 38 distinct error.reason values)

1. Test Mode Coverage

2. Test Kit

3. Scenarios to Test Your Integration

3.1 Must-have

3.2 Other common scenarios

3.3 Error scenarios

3.4 Not available in test mode yet

4. Scenario Details

P01 — Successful card payment (covers P09, CARD-N1)

P04 — Customer cancels, times out or session expires (covers P05)

P06 — Authentication failures

P10 — Fetch payment and reconcile

CARD-B1 — 3DS: redirect to the bank page

CARD-B2 — Native OTP: generate, submit and resend

CARD-C1 — Save a card during payment

CARD-C2 — Pay with a saved Razorpay token

CARD-C3 — Pay with your own network token

CARD-C4 — Create, fetch and delete tokens

CARD-C5 — One-time payment with a recurring token

CARD-D1 — Look up card details by IIN

P12 — Full and partial refunds

5. Webhooks: What Fires, and What It Lets You Decide

6. Common Integration Gaps to Avoid

Webhook and token updates

Fetch API when webhooks are late

7. Best Integration Practices

8. Simulate Failures

Errors available in test mode (33 triggers → 31 distinct error.reason values)

Errors not available in test mode (38 rows → 38 distinct error.reason values)

Related Information