How it Works
The payment follows the same five stages for every card payment scenario:- Your server calls Razorpay to create an order.
- Your server calls Razorpay to create a payment.
- The customer authenticates with an OTP — on the issuer’s bank page or your own Native OTP page (recommended) — or with biometrics.
- Your server receives the callback and verifies the signature.
- 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.
- 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.
- 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.failedandorder.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.
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.| # | Scenario | Use it when | What you send | CVV |
|---|---|---|---|---|
| 1 | New card | The customer enters a card and doesn’t save it (guest checkout). | Card details | Required |
| 2 | New card, saved for next time | The customer enters a card and agrees to save it. | Card details, save and customer_id | Required |
| 3 | Saved card | A returning customer picks a card they saved with you. | token instead of card details | Not required: Visa, Mastercard and RuPay Required: American Express and Diners Club |
| 4 | Your own network token | You 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, last4 | Not required: Visa, Mastercard and RuPay Required: American Express and Diners Club |
| 5 | One-time payment on a card saved for recurring | A subscriber makes a one-off purchase with the card on their mandate. | The mandate’s token, on a new order | As 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.
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
CallPOST /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
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
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 theotp_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.Option A: OTP on Your Own Page (Native OTP) (Recommended)
Step 3.1: Trigger the OTP Request to the Bank
When the create payment response returnsotp_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.
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 theotp_submit URL.
Resend OTP
Call theotp_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 theredirect 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 theredirect 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 yourcallback_url with a POST request.
Step 5: Verify the Signature
Signature verification is a mandatory step to ensure that the callback is sent by Razorpay. Therazorpay_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
Sample code
Sample code
Step 6: Confirm the Payment Status
Fulfil the order only when the payment iscaptured. 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.capturedororder.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:- Log in to the Razorpay Dashboard and navigate to Transactions → Payments.
- Check if a Payment Id has been generated and note the status. In case of a successful payment, the status is marked as Captured.
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
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 Razorpaytoken_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 inauthentication.
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.
Best Practices
- Use Native OTP. Collect the OTP on your own page so the customer doesn’t leave your checkout. Keep the
redirectURL as the fall-back for cards or accounts whereotp_submitisn’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_submitorotp_resendURLs. - 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.capturedororder.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.descriptionto customers, and branch onerror.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.