Skip to main content
Collect card details on your own checkout and process the payment server to server. This guide covers every way to create a card payment: a new card, a new card you save, a saved card, your own network token, and a one-time payment on a card saved for recurring.

How it Works

The payment follows the same five stages for every card payment scenario:
  1. Your server calls Razorpay to create an order.
  2. Your server calls Razorpay to create a payment.
  3. The customer authenticates with an OTP — on the issuer’s bank page or your own Native OTP page (recommended) — or with biometrics.
  4. Your server receives the callback and verifies the signature.
  5. Your server confirms the status with a webhook and the Fetch API, then fulfils the order.

Before You Start

  • Get S2S card payments enabled. Contact your Razorpay account manager or support. You need a valid PCI DSS certificate to get it enabled.
  • Generate API keys in the Dashboard. Use test keys (rzp_test_) while you build, and live keys (rzp_live_) after you go live. Keep the key secret on your server only.
    • Partner auth is different from merchant auth. If you are a partner calling the APIs on behalf of a business you onboarded, do not use API keys or Basic Auth. Use the business’s OAuth access token instead. Know more about generating an access token.
      • The access token expires every 90 days. Use the refresh token to get a new one before it expires. Know more about tokens.
      • Verify payment signatures with your OAuth application’s client_secret, not an API key secret. Verify webhooks with the secret you set on the application. Know more about partner signature verification.
  • Authenticate every API call with Basic Auth if you use API keys. Use your Key Id as the username and your Key Secret as the password. Know how to authenticate.
  • Set up a webhook URL in the Dashboard for payment.authorized, payment.captured, payment.failed and order.paid. You use it in Step 6: Confirm the Payment Status. See Webhooks.
  • Ask us to enable the optional features you need: Native OTP (collect the OTP on your own page; this is our recommended best practice), and the tokenisation APIs if you need to save cards authenticated on another payment gateway, use Razorpay tokens on another gateway, or provision your own network tokens.
Watch Out!Do not store card numbers, CVVs or expiry dates on your servers. Under RBI card-on-file rules, a card can be saved only as a token, with the customer’s consent. Use scenario 2 to save cards with Razorpay.
NoteSend card numbers as plain values. Don’t encrypt them.Razorpay supports 3DS2. Cards issued in India always go through additional authentication (OTP or bank page); there is no frictionless flow for them.

Different Scenarios in Cards Processing

All five scenarios use the same endpoint and the same steps. Only the request in Step 2: Create a Payment changes.
#ScenarioUse it whenWhat you sendCVV
1New cardThe customer enters a card and doesn’t save it (guest checkout).Card detailsRequired
2New card, saved for next timeThe customer enters a card and agrees to save it.Card details, save and customer_idRequired
3Saved cardA returning customer picks a card they saved with you.token instead of card detailsNot required: Visa, Mastercard and RuPay
Required: American Express and Diners Club
4Your own network tokenYou provision network tokens yourself as a token requestor, or hold a token from another payment aggregator.Token number and expiry, tokenised, cryptogram_value, token_provider, last4Not required: Visa, Mastercard and RuPay
Required: American Express and Diners Club
5One-time payment on a card saved for recurringA subscriber makes a one-off purchase with the card on their mandate.The mandate’s token, on a new orderAs scenario 3
Accepting international cards?If you also accept international cards or charge in a non-INR currency, see Forex Conversion to understand how currency conversion works and how to find the settled INR amount for each payment.

Step 1: Create an Order

Create an order on your server for every payment, with the amount you want to collect. The order ties the payment to your cart, stops the amount being changed in the browser, and makes sure a customer can’t pay twice for the same order.
Handy TipsIf you test the APIs in Postman, under the Authorization section select Basic Auth and add the Key Id and secret as the Username and Password, respectively.
Store the id from the response (for example order_Fg6IGePNMKDICF). If a payment fails and the customer tries again, reuse the same order. See the Orders API for all fields.

Optional: Fetch IIN Before You Create the Payment

If you want to know a card’s network, type, issuer, international status, EMI or recurring eligibility, or supported authentication types before you create the payment, call the IIN API with the first 6 digits of the card number (9 digits for a Visa, Mastercard or RuPay token). For example, use it to decide whether to accept a card type, or to show Native OTP only for cards that support it.
Feature RequestThe IIN API is an on-demand feature. Please raise a request with our Support team to get this feature activated on your Razorpay account.See Fetch Card IIN Information for the request, response fields and errors.

Step 2: Create a Payment

Call POST /v1/payments/create/json from your server. Every scenario also sends the customer’s ip, user_agent and browser details, which the bank uses for risk checks.

Scenario 1: New Card

Scenario 2: New Card, Saved for Next Time

The card is saved only if the customer completes authentication. After the payment succeeds, fetch it (GET /v1/payments/:id) and store token_id against your customer, or list the customer’s saved cards (see Save and Manage Cards).

Scenario 3: Saved Card

Scenario 4: Your Own Network Token

All the values inside card in this sample are token values; none is the actual card number or expiry. To create, fetch and delete tokens, see Tokenisation APIs.

Scenario 5: One-time Payment on a Card Saved for Recurring

Response

All five scenarios return the payment ID and the next actions available to you, as shown in the Response tabs of the samples above. Each sample shows two possible responses: one where you call the otp_generate URL to ask the bank for an OTP and one where the bank has already sent it. Don’t hard-code these URLs: always use the ones in the response.

Step 3: Authenticate the Customer

Choose one of the two ways the response offers. We recommend Native OTP: see Best Practices.

Step 3.1: Trigger the OTP Request to the Bank

When the create payment response returns otp_generate, call that URL from your server. The bank sends the OTP to the customer, and the response gives you the otp_submit, otp_resend and redirect URLs for Step 3.2.
If this call fails, don’t fail the payment. Send the customer to the bank page with the redirect URL from the create payment response (Option B).

Step 3.2: Give the Customer Three Options

Show your OTP screen with these three options and call the URL that matches what the customer does.
Submit OTP
Send the OTP the customer entered to the otp_submit URL.
On success, the response carries the same fields as the callback in Step 4: Handle the Callback. Verify the signature as in Step 5. An incorrect OTP doesn’t fail the payment: show the OTP screen again and offer Resend OTP.
Resend OTP
Call the otp_resend URL from your server. The bank sends a new OTP, and you get fresh otp_submit, otp_resend and redirect URLs to use from then on.
Go to the Bank Page
Send the customer’s browser to the redirect URL from Step 3.1. After they authenticate, Razorpay sends them to your callback_url with the result, as in Option B.
Handy TipsIf the OTP is slow to arrive or the customer prefers it, send them to the redirect URL (Option B) instead. Switching to the bank page saves the payment instead of losing it.

Option B: Send Customer to Bank’s OTP Page

Redirect the customer to the redirect URL. After they authenticate, Razorpay sends them to your callback_url with the result (Step 4: Handle the Callback).

Step 4: Handle the Callback

After authentication, Razorpay sends the customer to your callback_url with a POST request.
Watch Out!The callback can be lost if the customer closes the browser or loses network after paying. Don’t treat a missing callback as a failed payment: confirm the status in Step 6: Confirm the Payment Status.

Step 5: Verify the Signature

Signature verification is a mandatory step to ensure that the callback is sent by Razorpay. The razorpay_signature contained in the callback can be regenerated by your system and verified as follows. Create a string to be hashed using the razorpay_payment_id contained in the callback and the Order ID generated in the first step, separated by a |. Hash this string using SHA256 and your API Secret.

Generate Signature on your Server

Step 6: Confirm the Payment Status

Fulfil the order only when the payment is captured. We recommend you use both methods below together: subscribe to webhooks and also poll the Fetch API, so you still confirm the status if a webhook is delayed or missed.
  • Webhooks. Fulfil on payment.captured or order.paid. Verify the webhook signature, and make your handler idempotent: the same event can arrive more than once, and events don’t always arrive in order.
  • Fetch API. Poll the payment or the order’s payments to confirm the status:
Fetch a payment
Fetch an order's payments

Check the Status on the Dashboard

You can also verify a payment’s status manually on the Razorpay Dashboard:
  1. Log in to the Razorpay Dashboard and navigate to Transactions → Payments.
  2. Check if a Payment Id has been generated and note the status. In case of a successful payment, the status is marked as Captured.
Payment details on Dashboard
Handy TipsSet auto-capture in the Dashboard, or capture with POST /v1/payments/:id/capture. An authorised payment that isn’t captured in time is refunded. See Capture settings.
NoteA payment marked failed can still be authorised by the bank later (late authorisation). Keep listening for payment.authorized for up to 3 days, then capture and fulfil, or let it refund. See Late authorisation.

Step 7: Integrate Payments Rainy Day Kit

Use the Payments Rainy Day Kit to overcome payment exceptions such as:

Handle Errors

Errors come back either in the API response (for example, a bad request) or in the failure callback. Every error has the same shape:
Error
Show error.description to the customer: it’s written for them. Decide what to do next from error.reason and error.source, never from the description text.

Errors to Handle by Scenario

Full list of card errors: Card error codes.

Save and Manage Cards

With Razorpay as your token requestor, Razorpay creates and stores the network token for each saved card. You never see the card number again: you keep the Razorpay token_id and use it to show the card and to pay with it.

When You Call Which API

List a Customer’s Saved Cards

Curl

Fetch a Token

Curl
Response

Delete a Token

Curl

Save a Card Authenticated on Another Payment Gateway

If you route some payments through another gateway, you can still save those cards with Razorpay. Call this only after the customer has agreed to save the card and has completed authentication (3DS) on that gateway. Pass the other gateway’s name and its payment ID in authentication.
Curl
NoteFor American Express, also send authentication.authentication_reference_number from the gateway that handled the payment. For RuPay, send it when that gateway provides one.

Use a Razorpay Token on Another Payment Gateway

Fetch the network token data for the token and pass it to the other gateway.
Curl

Keep Saved Cards Up to Date

  • Fetch a token’s status before you show it, or after a payment with it fails, and hide any card that isn’t active.
  • If the tokenisation APIs are enabled for you, subscribe to token webhooks (token.activated, token.deactivated, token.suspended, token.expiry_updated) to update your checkout without polling.
  • Show a saved card by network, last 4 digits and expiry; never ask for or store the full card number.
Full request and response fields: Tokenisation APIs.

Best Practices

  • Use Native OTP. Collect the OTP on your own page so the customer doesn’t leave your checkout. Keep the redirect URL as the fall-back for cards or accounts where otp_submit isn’t returned, or if the customer prefers the bank page. See Step 3: Authenticate the Customer.
  • Use webhooks and the Fetch API together. Subscribe to webhooks and also poll, so you confirm the status even if a webhook is delayed or missed. See Step 6: Confirm the Payment Status.
  • Reuse the order on a retry. If a payment fails, let the customer retry against the same order.
  • Use the URLs in the response. Don’t hard-code the redirect, otp_submit or otp_resend URLs.
  • Save cards only as tokens, with consent. Never store card numbers, CVVs or expiry dates.

Test Your Integration

Test every payment scenario and failure case before you go live. See Cards: How to Test Your Integration for test cards, scenarios and the errors you can simulate.

Go-live Checklist

  • Switch to live API keys on your server.
  • Set up the webhook URL and its secret in live mode; live and test webhooks are separate.
  • Create an order for every payment, and verify the signature on every success.
  • Fulfil only on payment.captured or order.paid, never on the callback alone.
  • Handle late authorisation and auto-capture timeouts.
  • Don’t store card numbers or CVVs; save cards only as tokens, with consent.
  • For saved Visa, Mastercard and RuPay cards, remove the CVV field from your checkout. Keep it for American Express and Diners Club.
  • Show error.description to customers, and branch on error.reason.
  • Make one small live payment for each scenario you use. Some saved-card checks, such as whether a token belongs to your account, run only in live mode.

Parameter Reference

Create a Payment: POST /v1/payments/create/json

Response

Next Steps

Proceed to testing your Cards integration.
Last modified on November 20, 2026