Skip to main content
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.
ScenarioWebhooks, in orderWhat each one lets you decideIn test mode
1 Successful paymentpayment.authorized, payment.captured, order.paidpayment.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 outpayment.failedpayment.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 redirectpayment.authorized, payment.captured, order.paid, payment.failedpayment.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 capturepayment.authorized, payment.capturedpayment.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 refundrefund.created, refund.processed, refund.failedrefund.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 OTPpayment.authorized, payment.captured, order.paid, payment.failedpayment.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 cardpayment.authorized, payment.captured, order.paid, token.initiated, token.activatedpayment.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 tokenpayment.authorized, payment.captured, order.paidpayment.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 tokenstoken.initiated, token.activated, token.deactivatedtoken.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 tokenpayment.authorized, token.confirmed, token.rejected, payment.captured, order.paidpayment.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 scenariopayment.failedpayment.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 authorisationpayment.authorizedpayment.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.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 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.
In test mode the card number that you use decides the outcome, because there is no real issuer on the other end. Pay with a success card and approve on the mock bank page, and the payment succeeds. Pay with one of the failure cards in 3.3 Card error scenarios and choose Failure, and the payment fails with the error mapped to that card.
  • 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.
Any amount works; the card number that you use decides the outcome.

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

#ScenarioTrigger credsSteps to follow
1Successful payment4100 2800 0000 1007, any CVV, any future expiry. Success, or any 4–10 digit OTP.
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id: POST /v1/payments/create/json or /create/redirect.
  3. 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 or choose Success.
  4. The customer returns to your callback_url with razorpay_payment_id, razorpay_order_id and razorpay_signature. Verify the signature on your server.
  5. Fulfil on payment.captured.
  6. Webhooks received: payment.authorized, payment.captured, order.paid.
  7. Status changes: the payment moves to captured (or authorized if you capture manually) and the order to paid.
2Declined by bank4100 2800 0005 0004 + Failure
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm card_declined. The customer sees error.description and can try another card.
  6. Status changes: the payment moves to failed; the order stays attempted for a retry.
3Customer cancels4100 2800 0007 0002 + Failure
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure (or close the bank page).
  4. Webhooks received: payment.failed.
  5. Confirm payment_cancelled. The order stays open for a retry.
4Payment times out or session expires4100 2800 0009 0000, 4100 2800 0003 0048 + Failure
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm payment_timed_out on the first card and payment_session_expired on the second. Don’t fulfil; keep the order open.
5Fetch payment and reconcileA payment ID from 1 (success) and one from 2 (failure)
  1. Call GET /v1/payments/:id after each scenario.
  2. Confirm the status matches the webhook.
  3. Call it with a wrong ID, or a test payment ID with your live keys: confirm BAD_REQUEST_ERROR with reason input_validation_failed (“The id provided does not exist”).
  4. Call GET /v1/payments/:id/card on a non-card payment: confirm BAD_REQUEST_ERROR “Payment was not done using card” (reason not set).
  5. Webhooks received: none.
63DS: redirect to the bank pageAny success card
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment and redirect to the URL in next[] (JSON) or render the returned page (Redirect).
  3. Enter a 4–10 digit OTP: the payment succeeds. Repeat with fewer than 4 digits: the payment fails.
  4. Confirm the customer returns to your callback_url both times.
  5. Webhooks received: success payment.authorized, payment.captured, order.paid; failure payment.failed.
  6. For specific authentication errors, use the cards in 3.3.
Repeat scenario 1 with each failure card to cover the card error scenarios in 3.3. Use the same order for a failed attempt and the retry that follows it.

3.2 Common scenarios in cards

#ScenarioTrigger credsSteps to follow
7Manual capture (full amount)Any success card, with manual capture
  1. Create an order with payment_capture: false (or set manual capture in your test mode Dashboard).
  2. Pay with a success card and approve on the mock bank page.
  3. Confirm the payment is authorized, not captured. Webhooks received: payment.authorized.
  4. Capture the full amount: POST /v1/payments/:id/capture with the same amount and currency.
  5. Webhooks received: payment.captured. Status changes: the payment moves to captured.
  6. Fulfil only after payment.captured. Partial capture isn’t in test mode yet (see 3.4).
8Full and partial refundA captured payment from scenario 1
  1. Refund one payment in full and another in part: POST /v1/payments/:id/refund.
  2. Webhooks received: refund.created, refund.processed (or refund.failed if the refund fails).
  3. Status changes: the payment shows refund_status as full or partial; the order stays paid.
  4. Refund errors are on the Refunds page.
9Native OTP: generate, submit, resend (S2S JSON V2, on-demand)4895 1911 1111 1115 (supports Native OTP)
  1. Optional: check the card supports Native OTP with POST /v1/payment/flows.
  2. Create an order (POST /v1/orders) and store the returned order_id.
  3. Create the payment with POST /v1/payments/create/json, the order_id and auth_type=otp.
  4. Call POST /v1/payments/:id/otp_generate (the URL is in next[]), show your OTP screen, and submit with POST /v1/payments/:id/otp/submit. Any 4–10 digit OTP succeeds.
  5. Resend once with otp/resend, then submit again.
  6. Verify razorpay_signature from the successful submit.
  7. Webhooks received: payment.authorized, payment.captured, order.paid. A wrong OTP sends no webhook; payment.failed comes only when the payment finally fails.
  8. Errors to test: Native OTP API errors in 3.3.
10Save a card during paymentAny success card + save=1 + customer_id
  1. Create a customer: POST /v1/customers.
  2. Create an order (POST /v1/orders) and store the returned order_id.
  3. Pay on POST /v1/payments/create/json with save=1 and the customer_id.
  4. Confirm the token appears in GET /v1/customers/:id/tokens.
  5. Webhooks received: payment.authorized, payment.captured, order.paid. With the tokenisation APIs, also token.initiated, token.activated.
  6. Send a customer_id that doesn’t exist or belongs to another account: confirm BAD_REQUEST_ERROR “The id provided does not exist or access is unauthorised” (reason not set).
  7. If the issuer doesn’t support tokenisation, you get card_not_eligible. No test card triggers it.
11Pay with a saved tokenToken from scenario 10 + CVV
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Pay with customer_id, the token and the CVV.
  3. Confirm success without the card number.
  4. Webhooks received: payment.authorized, payment.captured, order.paid.
  5. Send a token that doesn’t exist or belongs to another customer: confirm invalid_token.
  6. Send a 2-digit CVV: confirm card_cvv_invalid.
12Pay with your own network token (token requestors only)Your network token + cryptogram
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with card.tokenised=true, cryptogram_value, token_provider and provider_type=network.
  3. Webhooks received: payment.authorized, payment.captured, order.paid.
  4. Leave out cryptogram_value or token_provider: confirm input_validation_failed naming the missing field.
13Create, fetch and delete tokens (tokenisation APIs, on-demand)Valid and invalid token requests
  1. Tokenisation APIs: call POST /v1/tokens, /tokens/fetch and /tokens/delete.
  2. Saved cards: call GET /v1/customers/:id/tokens, GET …/tokens/:token_id and DELETE …/tokens/:token_id.
  3. Webhooks received: create token.initiated, token.activated; delete token.deactivated. Sent by the network later: token.expiry_updated, token.suspended.
  4. Errors to test: Token API errors in 3.3.
14One-time payment on a recurring token (needs recurring enabled)A recurring token (register with Visa 4718 6091 0820 4366)
  1. Register the mandate: create a payment with recurring=1 and customer_id on POST /v1/payments/create/json using the recurring test card. Wait for token.confirmed.
  2. Create a new order, then pay with customer_id and token. Don’t send recurring (or send 0). CVV is optional for tokenised cards; don’t send a dummy CVV.
  3. Complete authentication from next[] (3DS on the mock bank page, or Native OTP as in scenario 9).
  4. Confirm the payment succeeds, no pre-debit notification is sent, and the mandate stays active.
  5. Webhooks received: registration payment.authorized (has the token_id), then token.confirmed or token.rejected; one-time payment.authorized, payment.captured, order.paid, and no notification.delivered.
  6. Send a token that doesn’t exist or belongs to another customer: confirm invalid_token.
15Look up card details by IIN (IIN API, on-demand)GET /v1/iins/410028
  1. Call GET /v1/iins/:iin before you create the payment, to check card type, international, EMI or recurring eligibility, or Native OTP support.
  2. Send a 6-digit card IIN (all networks), e.g. 410028: expect tokenised_iin: false, card_iin: null, plus network, type, sub_type, issuer, international, emi.available, recurring.available and authentication_types.
  3. Send a 9-digit token IIN (Visa, Mastercard, RuPay): expect tokenised_iin: true and card_iin set to the actual card IIN (Visa and Mastercard only), plus the same card details.
  4. An American Express token IIN is 6 digits and returns tokenised_iin: true. Diners Club token IINs aren’t supported.
  5. Webhooks received: none.
  6. Errors to test: IIN API errors in 3.3.

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

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.
#ScenarioTrigger credsError objectSteps to follow
16Authentication fails4100 2800 0000 0009 + Failure, or an OTP under 4 digitscode GATEWAY_ERROR
source customer
step payment_authentication
reason authentication_failed
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm authentication_failed at error.step = payment_authentication, and a retry or another-card option.
17Insufficient funds4100 2800 0008 0001 + Failurecode BAD_REQUEST_ERROR
source customer
step payment_authorization
reason insufficient_funds
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm insufficient_funds and a “try another card” message.
18CVV in the wrong format4100 2800 0007 0051 + Failurecode BAD_REQUEST_ERROR
source customer
step —
reason card_cvv_invalid
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm card_cvv_invalid and a “re-enter the CVV” prompt.
19Incorrect CVV4100 2800 0000 0033 + Failurecode BAD_REQUEST_ERROR
source customer
step payment_authorization
reason incorrect_cvv
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm incorrect_cvv and a “re-enter the CVV” prompt.
20Card expired4100 2800 0009 0034 + Failurecode BAD_REQUEST_ERROR
source customer
step payment_authentication
reason card_expired
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm card_expired and a “use another card” message.
21Incorrect expiry date4100 2800 0002 0049 + Failurecode BAD_REQUEST_ERROR
source customer
step payment_authentication
reason incorrect_card_expiry_date
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm incorrect_card_expiry_date and a “re-enter the expiry” prompt.
22Incorrect card number4100 2800 0001 0008 + Failurecode BAD_REQUEST_ERROR
source customer
step payment_authentication
reason card_number_invalid
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm card_number_invalid and a “re-enter the card number” prompt.
23Incorrect card details4100 2800 0001 0040 + Failurecode BAD_REQUEST_ERROR
source customer
step payment_authorization
reason incorrect_card_details
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm incorrect_card_details and a “check the card details” prompt.
24Card not enrolled for online payments4100 2800 0004 0013 + Failurecode GATEWAY_ERROR
source customer
step card_enrollment_check
reason card_not_enrolled
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm card_not_enrolled and a “use another card or contact your bank” message.
25Card blocked4100 2800 0001 0032 + Failurecode BAD_REQUEST_ERROR
source customer
step payment_authorization
reason debit_instrument_blocked
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm debit_instrument_blocked and a “use another card” message.
26Card inactive for online payments4100 2800 0005 0038 + Failurecode BAD_REQUEST_ERROR
source customer
step payment_authorization
reason debit_instrument_inactive
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm debit_instrument_inactive and a “use another card or contact your bank” message.
27Incorrect PIN4100 2800 0002 0031 + Failurecode BAD_REQUEST_ERROR
source customer
step payment_authentication
reason incorrect_pin
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm incorrect_pin and a retry option.
28PIN attempts exceeded4100 2800 0005 0046 + Failurecode BAD_REQUEST_ERROR
source customer
step payment_authentication
reason pin_attempts_exceeded
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm pin_attempts_exceeded and a “try later or use another card” message, not a retry-PIN prompt.
29Per-transaction limit exceeded4100 2800 0008 0035 + Failurecode BAD_REQUEST_ERROR
source customer
step payment_authorization
reason transaction_limit_exceeded
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm transaction_limit_exceeded and an “amount too high for this card” message.
30Daily amount limit exceeded4100 2800 0009 0042 + Failurecode BAD_REQUEST_ERROR
source customer
step payment_authorization
reason transaction_daily_limit_exceeded
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm transaction_daily_limit_exceeded and a “daily limit reached, use another card” message.
31Daily transaction count exceeded4100 2800 0008 0043 + Failurecode BAD_REQUEST_ERROR
source customer
step payment_authorization
reason transaction_daily_count_exceeded
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm transaction_daily_count_exceeded and a “too many payments today, use another card” message.

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.
#ScenarioTrigger credsError objectSteps to follow
32Bank technical error4100 2800 0007 0036 + Failurecode GATEWAY_ERROR
source issuer_bank
step payment_authorization
reason bank_technical_error
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm bank_technical_error and a retry option.
33Card declined (other triggers)4100 2800 0006 0003, 4100 2800 0004 0005 + Failureon 0006 0003
code BAD_REQUEST_ERROR
source issuer_bank
step payment_authorization
reason card_declined

on 0004 0005
code BAD_REQUEST_ERROR
source issuer_bank
step payment_initiation
reason card_declined
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm card_declined on both, and read error.step: one fails at initiation, the other at authorisation.
34Declined by bank at authentication4100 2800 0004 0039 + Failurecode BAD_REQUEST_ERROR
source issuer_bank
step payment_authentication
reason declined_by_bank
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm declined_by_bank and a “try another card” message.
35Card disabled for online payments4100 2800 0003 0006 + Failurecode BAD_REQUEST_ERROR
source issuer_bank
step payment_authorization
reason card_disabled_for_online_payments
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm card_disabled_for_online_payments and a “contact your bank or use another card” message.
36Blocked by issuer4100 2800 0007 0044 + Failurecode BAD_REQUEST_ERROR
source issuer_bank
step payment_authorization
reason issuer_declined
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm issuer_declined and a “try another card” message.
37Risk check failed4100 2800 0003 0030 + Failurecode BAD_REQUEST_ERROR
source issuer_bank
step payment_authorization
reason payment_risk_check_failed
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm payment_risk_check_failed and a “try another card” message.
38Card restricted4100 2800 0006 0045 + Failurecode GATEWAY_ERROR
source bank
step payment_authorization
reason card_restricted
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm card_restricted and a “try another card” message.

Gateway Errors

Something went wrong between Razorpay and the bank. These are temporary, so offer the customer the same card again.
#ScenarioTrigger credsError objectSteps to follow
39Gateway technical error4100 2800 0002 0007, or any other test card + Failurecode GATEWAY_ERROR
source gateway
step payment_authorization
reason gateway_technical_error
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm gateway_technical_error and a retry option.
40Payment failed4100 2800 0006 0037 + Failurecode BAD_REQUEST_ERROR
source gateway
step payment_authorization
reason payment_failed
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm payment_failed and a retry option.

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.
#ScenarioTrigger credsError objectSteps to follow
41Card holder name in the wrong format4100 2800 0008 0050 + Failurecode GATEWAY_ERROR
source business
step payment_authentication
reason card_name_invalid
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm card_name_invalid. Fix the name you send; don’t ask the customer to retry the same input.
42API validation errors (all methods)Missing amount, amount: 0, wrong key secretmissing field
code BAD_REQUEST_ERROR
reason input_validation_failed

amount 0
code BAD_REQUEST_ERROR
reason invalid_amount

wrong key
code BAD_REQUEST_ERROR
reason not set
  1. Send each bad request to POST /v1/payments/create/json.
  2. Confirm HTTP 4xx (401 on a wrong key), no payment created and no webhook.
43Network or international card not enabledAmex 3402 560004 01007, international 4012 8888 8888 1881on Amex
code BAD_REQUEST_ERROR
reason card_network_not_enabled

on international
code BAD_REQUEST_ERROR
reason international_transaction_not_allowed
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Pay with each card while that network, or international payments, is disabled on your test account.
  3. Confirm card_network_not_enabled / international_transaction_not_allowed and a “use another card” message.

Internal Errors

These come back with a Razorpay internal source, or no source yet. Treat them as temporary and offer a retry.
#ScenarioTrigger credsError objectSteps to follow
44Transaction not permitted4100 2800 0000 0041 + Failurecode GATEWAY_ERROR
source internal
step payment_initiation
reason Transaction not permitted to issuer/cardholder
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm the error and a retry option.
45Authentication attempts exceeded4100 2800 0004 0047 + Failurecode BAD_REQUEST_ERROR
source —
step —
reason acs_maximum_attempts_reached
  1. Create an order (POST /v1/orders) and store the returned order_id.
  2. Create the payment with that order_id and the trigger card, any future expiry and any CVV: POST /v1/payments/create/json or /create/redirect.
  3. On the mock bank page, choose Failure.
  4. Webhooks received: payment.failed.
  5. Confirm acs_maximum_attempts_reached and a “try later or use another card” message.

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.
#ScenarioTrigger credsError objectSteps to follow
46Wrong OTPOTP under 4 digits on otp/submitcode BAD_REQUEST_ERROR
reason incorrect_otp
  1. Submit an OTP with fewer than 4 digits.
  2. Confirm the payment isn’t failed: the response has action=RETRY and next[]. Show the OTP screen again with resend.
  3. Expect HTTP 400 and the description “Payment processing failed because of incorrect OTP”. No webhook.
47OTP missing from submitotp/submit with no otpcode BAD_REQUEST_ERROR
reason not set
  1. Call otp/submit with no otp in the body.
  2. Expect HTTP 400 and the description “Request is expected in JSON but is in incorrect format”. No webhook.
48OTP generated twiceotp_generate twicecode BAD_REQUEST_ERROR
reason not set
  1. Call otp_generate twice for the same payment.
  2. Expect HTTP 400 and the description “Something went wrong, please try again after sometime”. No webhook.
49Resend on a non-OTP paymentotp/resend without auth_type=otpcode BAD_REQUEST_ERROR
reason input_validation_failed
  1. Call resend on a payment that wasn’t created with auth_type=otp.
  2. Until the error-mapping fix ships, this returns reason auth type not supported and the description “Auth type is invalid.” Until then, branch on HTTP 400 and error.code for this error, not on the reason.
  3. Expect HTTP 400 and the description “The auth_type sent is not supported for this payment. Use 3ds, or enable headless OTP (auth_type otp) or direct debit (auth_type skip) for your account and check the card supports it”. No webhook.
50Submit after successotp/submit againcode BAD_REQUEST_ERROR
reason gateway_technical_error
  1. Call submit again after the payment has succeeded.
  2. Expect HTTP 400 and the description “The payment has already been processed”. No webhook.
51Wrong payment ID on OTP callsA wrong payment_idcode BAD_REQUEST_ERROR
reason input_validation_failed
  1. Call otp_generate or otp/submit with a wrong payment_id.
  2. Expect HTTP 400 and the description “The id provided does not exist”. No webhook.

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.
#ScenarioTrigger credsError objectSteps to follow
52Create: required field missingPOST /v1/tokens without e.g. numbercode BAD_REQUEST_ERROR
reason input_validation_failed
  1. Leave out a required field.
  2. Expect HTTP 400 and the description “The <field name> is required”. No webhook.
53Create: field in the wrong formatPOST /v1/tokenscode BAD_REQUEST_ERROR
reason input_validation_failed
  1. Send a field in the wrong format.
  2. Expect HTTP 400 and the description “The <field name> is invalid”. No webhook.
54Create: invalid card numberPOST /v1/tokenscode BAD_REQUEST_ERROR
reason input_validation_failed
  1. Send an invalid card number.
  2. Expect HTTP 400 and the description “The card number is invalid”. No webhook.
55Create: CVV lengthPOST /v1/tokens with a 2- or 5-digit cvvcode BAD_REQUEST_ERROR
reason input_validation_failed
  1. Send a 2-digit or 5-digit cvv.
  2. Expect HTTP 400 and the description “The cvv must be between 3 and 4 digits”. No webhook.
56Fetch: token ID doesn’t exist (live mode only)POST /v1/tokens/fetchcode BAD_REQUEST_ERROR
reason input_validation_failed
  1. Send an id that doesn’t exist, has no token_ prefix, or belongs to another account.
  2. Expect HTTP 400 and the description “The id provided does not exist”. No webhook.
57Fetch: badly formed token ID (live mode only)POST /v1/tokens/fetchcode BAD_REQUEST_ERROR
reason input_validation_failed
  1. Send token_ followed by the wrong number of characters.
  2. Expect HTTP 400 and the description “<id> is not a valid id”. No webhook.
58Fetch: extra field sent (live mode only)POST /v1/tokens/fetchcode BAD_REQUEST_ERROR
reason extra_field_sent
  1. Send any field other than id in the body.
  2. Expect HTTP 400 and the description “<field> is/are not required and should not be sent”. No webhook.
59Fetch: card not compliant (live mode only)POST /v1/tokens/fetchcode BAD_REQUEST_ERROR
reason card_not_compliant
  1. Fetch a token for a card that isn’t network-tokenised.
  2. Expect HTTP 400 and the description “the saved card is no longer compliant with RBI guidelines. Please use another card/payment”. No webhook.
60Fetch: token not foundPOST /v1/tokens/fetchcode BAD_REQUEST_ERROR
reason not set
  1. Send a token ID that doesn’t exist or was deleted.
  2. Expect HTTP 400 and the description “Token not found”. No webhook.
61Delete: token not foundPOST /v1/tokens/deletecode BAD_REQUEST_ERROR
reason input_validation_failed
  1. Send an id that doesn’t exist, has no token_ prefix, is badly formatted, belongs to another account, or was already deleted.
  2. Expect HTTP 400 and the description “Token not found”. No webhook.
62Delete: API not enabled (live mode only)POST /v1/tokens/deletecode BAD_REQUEST_ERROR
reason not set
  1. Call it when the tokenisation APIs aren’t enabled on your account.
  2. Expect HTTP 400 and the description “The requested URL was not found on the server”. No webhook.
63Saved card: ID doesn’t exist/v1/customers/:id/tokenscode BAD_REQUEST_ERROR
reason input_validation_failed
  1. Use a customer_id or token_id that doesn’t exist, belongs to another account, or was already deleted.
  2. Expect HTTP 400 and the description “The id provided does not exist”. No webhook.
64Saved card: badly formed ID/v1/customers/:id/tokenscode BAD_REQUEST_ERROR
reason input_validation_failed
  1. Use an ID with the wrong length.
  2. Expect HTTP 400 and the description “<id> is not a valid id”. No webhook.
65Saved card: token of another customer/v1/customers/:id/tokens/:token_idcode BAD_REQUEST_ERROR
reason not set
  1. Use a token that belongs to a different customer of yours. The error names the id field.
  2. Expect HTTP 400 and the description “Token not found for id: <token_id> customer id: <customer_id>”. No webhook.

IIN API errors

Request errors on the IIN lookup in scenario 15.
#ScenarioTrigger credsError objectSteps to follow
66IIN doesn’t existGET /v1/iins/000000code BAD_REQUEST_ERROR
reason iin_does_not_exist
  1. Send an IIN that doesn’t exist, e.g. 000000.
  2. Expect HTTP 400 and the description “IIN 000000 does not exist”. No webhook.
67Card IIN of the wrong lengthGET /v1/iins/41002code BAD_REQUEST_ERROR
reason invalid_iin_length
  1. Send a card IIN that isn’t 6 digits.
  2. Expect HTTP 400 and the description “The requested IIN is a card IIN & should be 6 digits long”. No webhook.
68Token IIN of the wrong lengthGET /v1/iins/:token_iincode BAD_REQUEST_ERROR
reason invalid_iin_length
  1. Send a Visa, Mastercard or RuPay token IIN that isn’t 9 digits.
  2. Expect HTTP 400 and the description “The requested IIN is a token IIN & should be 9 digits long”. No webhook.
69IIN API not enabledGET /v1/iins/:iincode BAD_REQUEST_ERROR
reason not set
  1. Call it before the IIN API is enabled on your account.
  2. Expect HTTP 400 and the description “The requested URL was not found on the server”. No webhook.
not set means Razorpay doesn’t return an 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.
TopicWhat to knowOn this methodTest itRead more
Difference between order and paymentAn 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-25Difference between order and payment ↗
Order statesOrders 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 errorsOrder states ↗
Orders API error codes ↗
Late authorisationA 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-06Late authorisation ↗
Capture settingsChoose 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-14Capture settings ↗
Multiple payments on the same orderOnce 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-08Multiple payments on the same order ↗
All best practices: Overview · Webhooks · Fetch APIs and reconciliation · Payment states and late authorisation · Error handling · Downtime handling · Security
Last modified on November 18, 2026