Skip to main content
Who should use this guideThis guide is intended for merchants who:
  • Use Payrails as a payment orchestrator
  • Use RazorPay for card payments in India
  • Have access to the RazorPay Dashboard

Create a RazorPay integration in Payrails

  1. Log in to the Payrails portal.
  2. Go to Settings → Integrations.
  3. Select New integration.
What you’ll need from RazorPayPayrails connects to your RazorPay account through an OAuth app that you create in the RazorPay Dashboard. Before you begin, make sure you can create an OAuth app there. Each app has a development client for test mode and a production client for live mode.

Step 1: Choose the provider

  • Search for RazorPay and select it.
  • Select Next step.
A screenshot showing RazorPay selected as the provider.

Step 2: Enter basic information

In Payrails
  • Integration type: keep Payment selected.
  • Workspaces: select the workspaces where this integration should be available.
  • Select Next step.
A screenshot showing the RazorPay basic information step with integration type and workspaces.
About workspacesWorkspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.

Step 3: Connect your RazorPay account

Name the integration

In Payrails
  • Integration instance name: enter a clear, consistent name, for example merchant_razorpay. Routing uses this name, so include the region or environment when you run more than one RazorPay integration.
A screenshot showing the integration instance name field.

Create an OAuth app in RazorPay

Each merchant connects RazorPay through an OAuth app of its own. In Payrails
  • Copy the OAuth redirect URL from the RazorPay account section. Use it exactly as shown.
In RazorPay
  1. Log in to the RazorPay Dashboard.
  2. Create an OAuth app. Use the development client for test mode and the production client for live mode.
  3. Add the Payrails OAuth redirect URL to the app’s redirect URLs, exactly as shown.
  4. Copy the app’s client ID and client secret.
Register the OAuth redirect URL in the RazorPay Dashboard before you select Go to Razorpay. If the app doesn’t list the URL exactly as the portal shows it, RazorPay fails the OAuth consent and client authentication, and Payrails can’t connect the account.

Credentials

In Payrails A screenshot showing the RazorPay account section with the OAuth redirect URL, client ID, client secret and HMAC keys.

Payment methods

In Payrails
  • Select Card.
A screenshot showing the RazorPay payment methods with Card and the connect note. In RazorPay
  • Ask RazorPay to turn on server-to-server card payments on your account. Without it, RazorPay refuses every payment request.

Connect the account

In Payrails
  1. Select Save account, then Go to Razorpay. Payrails saves the integration as a draft before it opens RazorPay.
  2. In RazorPay, sign in, and approve Payrails.
  3. RazorPay sends you back to the portal. Payrails connects the account, then enables the integration.
Reconnecting an accountA connected integration keeps its client ID. To use a different OAuth app, create a new integration. If RazorPay stops accepting the connection, select the same RazorPay account again through the same flow to store a fresh authorization.

Webhooks or notifications

Payrails uses provider webhooks or notifications to receive asynchronous payment status updates.
Create webhooks in the same mode (test or live) as your Payrails integration.
In Payrails
  • Copy the Notification URL from the Account configuration section.
  • Enter the secret you plan to use in HMAC keys.
In RazorPay
  1. Log in to the RazorPay Dashboard and switch to the mode that matches your integration.
  2. Go to Accounts & Settings → Webhooks, and add a webhook.
  3. Webhook URL: paste the Payrails notification URL.
  4. Secret: enter the same value you entered in HMAC keys.
  5. Events: select payment.captured, payment.failed, refund.processed and refund.failed. Also select payment.authorized when you capture payments manually.
RazorPay signs each notification with your secret, and Payrails checks the signature. You can list several keys in HMAC keys, so you can rotate a secret without refusing notifications signed with the previous one. An update to the integration replaces the stored keys, so keep every key you still need in the list. RazorPay treats any answer other than 2xx, or no answer within 5 seconds, as a failed delivery. It retries for 24 hours, then disables the webhook. To replay events, go to Developers → Webhooks → Replay events in the RazorPay Dashboard.

RazorPay specific meta fields

Select View fields to see the meta fields this integration uses. Request fields for RazorPay describes them.

Additional data

In Payrails
  • Optional. Select Add field to add key-value pairs that Payrails includes in the authorization webhook notification. Payrails doesn’t use them to process RazorPay payments.
A screenshot showing the RazorPay additional data section.

Request fields for RazorPay

Send these fields in the authorize request for card payments, in addition to the standard authorize fields. Required fields must be present for the payment to succeed. Payrails sends Optional fields to RazorPay when you include them. For more about meta fields, refer to Meta fields.

How RazorPay handles cards

  • RazorPay authenticates card payments with 3D Secure. The response includes the redirect to the RazorPay bank page, and the customer returns to Payrails when they finish.
  • RazorPay supports instant and manual capture. With manual capture, you capture the full authorized amount within 5 days. RazorPay releases a payment you don’t capture in time, and Payrails then marks it as canceled.
  • You can refund a captured payment in full or in part, as many times as you need up to the captured amount. Refunds use normal speed, and a refund can stay pending until RazorPay sends its refund.processed or refund.failed notification. RazorPay can’t refund a payment more than six months old.
  • A RazorPay account that accepts domestic cards only refuses international cards.
  • Payrails reports RazorPay’s failure reasons as Payrails result codes.

Save cards and recurring payments

Save a card

Set storeInstrument to true on the first payment. When the payment succeeds, Payrails saves the RazorPay card token as a payment instrument. For later customer-initiated payments, authorize with the saved paymentInstrumentId. The customer still completes 3D Secure.

Register a recurring payment

For payments in INR, a first payment that stores the card for Subscription or UnscheduledCardOnFile also registers a card mandate with RazorPay. Send the first payment with:

Charge a recurring payment

Call authorize a payment with the saved paymentInstrumentId and meta.order.processingType set to Subscription or UnscheduledCardOnFile. Send meta.customer.email and meta.customer.phone, and use INR. The cardholder isn’t present, so you send no browser fields. RazorPay debits only after it notifies the customer of the upcoming debit, so the payment stays pending until the debit. Payrails settles it from the RazorPay notification or a status check.

Enable the integration

In Payrails
  • Confirm the integration shows as Enabled.
Your RazorPay integration is now ready to process payments.

Next steps

  1. Run a test payment in RazorPay test mode. Use a test card from the RazorPay documentation, and select Success or Failure on the RazorPay test bank page.
  2. Verify that:
    • The payment appears in the RazorPay Dashboard.
    • The payment status updates correctly in Payrails.
  3. Once verified in test mode, repeat the setup in live mode.
→ Continue to: Test a payment
Last modified on November 17, 2026