> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# RazorPay

> Connect RazorPay to Payrails for cards in India, covering your OAuth app, webhook secret, saved cards and recurring payments.

<picture noZoom>
  ![RazorPay logo](https://assets.payrails.io/img/logos/razorpay/logo-full-bleed.svg)
</picture>

> [!NOTE]
>
> **Who should use this guide**
>
> This 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**.

> [!TIP]
>
> **What you'll need from RazorPay**
>
> Payrails 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.](https://mintcdn.com/payrails-42074109/x7324gj0d0n7tqbK/images/docs/razorpay-image-01.png?fit=max\&auto=format\&n=x7324gj0d0n7tqbK\&q=85\&s=9a6af90c86e18aba5610be4cc4863e91)

***

## 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.](https://mintcdn.com/payrails-42074109/x7324gj0d0n7tqbK/images/docs/razorpay-image-02.png?fit=max\&auto=format\&n=x7324gj0d0n7tqbK\&q=85\&s=9035b8eb2ce505bbb3b81d9301bc30a5)

> [!NOTE]
>
> **About workspaces**
>
> Workspaces 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.](https://mintcdn.com/payrails-42074109/145W1v58K5wnDMNC/images/docs/orchestration/integrations/shared/integration-instance-name.png?fit=max\&auto=format\&n=145W1v58K5wnDMNC\&q=85\&s=470be58979509680650b0cbf8b5eecc4)

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

> [!WARNING]
>
> 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**

| Field | Value |
| :- | :- |
| **OAuth client ID** | The client ID of your RazorPay OAuth app. |
| **OAuth client secret** | The client secret of your RazorPay OAuth app. Payrails also uses it to verify the signature on the 3D Secure return from the RazorPay bank page. |
| **HMAC keys** | The webhook secret you set in the RazorPay Dashboard. Select **+** to add more than one key. See [Webhooks or notifications](#webhooks-or-notifications). |

![A screenshot showing the RazorPay account section with the OAuth redirect URL, client ID, client secret and HMAC keys.](https://mintcdn.com/payrails-42074109/x7324gj0d0n7tqbK/images/docs/razorpay-image-03.png?fit=max\&auto=format\&n=x7324gj0d0n7tqbK\&q=85\&s=75ee761ff2e89d6a1c3c9865cb82b4b4)

### Payment methods

**In Payrails**

* Select **Card**.

![A screenshot showing the RazorPay payment methods with Card and the connect note.](https://mintcdn.com/payrails-42074109/x7324gj0d0n7tqbK/images/docs/razorpay-image-04.png?fit=max\&auto=format\&n=x7324gj0d0n7tqbK\&q=85\&s=77dbcc836f0ee286a01e01a85b4553f5)

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

> [!NOTE]
>
> **Reconnecting an account**
>
> A 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

> [!NOTE]
>
> Payrails uses provider webhooks or notifications to receive asynchronous
> payment status updates.

> [!WARNING]
>
> 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](#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.](https://mintcdn.com/payrails-42074109/x7324gj0d0n7tqbK/images/docs/razorpay-image-05.png?fit=max\&auto=format\&n=x7324gj0d0n7tqbK\&q=85\&s=b307ff8ff1823d780d26dff36a586dd7)

***

## Request fields for RazorPay

Send these fields in the [authorize request](https://docs.payrails.com/reference/authorizeaction.md) 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](https://docs.payrails.com/docs/orchestration/meta-fields.md).

| Field | Status | Description |
| :- | :- | :- |
| `amount` | Required | Any currency your RazorPay account accepts. Card mandates and recurring charges use INR. For KWD, BHD and OMR, the last decimal digit of the amount must be 0. |
| `instrument.holderName` | Required | Needed when you pay with a card, not with a saved card or a recurring charge. Sent as the name on the card. You can send `meta.customer.name` and `meta.customer.lastName` instead. Payrails removes accents before it sends the name. |
| `meta.customer.email` | Required | Sent as the customer's email, up to 40 characters. |
| `meta.customer.phone.number` | Required | Sent as the customer's phone number. Up to 15 characters, including the `+` in front of the dialing code. |
| `meta.customer.phone.countryCode` | Optional | Sent in front of the phone number as the dialing code. |
| `meta.clientContext.ipAddress` | Required | Needed on customer-initiated payments, and not sent on recurring charges. Sent as the customer's IP address. |
| `meta.clientContext.javaEnabled`, `meta.clientContext.javaScriptEnabled`, `meta.clientContext.timeZoneOffset`, `meta.clientContext.colorDepth`, `meta.clientContext.screenWidth`, `meta.clientContext.screenHeight` | Required | Needed on customer-initiated payments, including saved cards, and not sent on recurring charges. Sent as the browser details for the 3D Secure challenge. Payrails refuses the payment when all six are missing. |
| `meta.clientContext.language` | Optional | Sent as the browser language. |
| `meta.clientContext.userAgent` | Optional | Sent as the customer's device information. |
| `meta.clientContext.origin` | Optional | Sent as the referrer. |
| `meta.tags` | Optional | Sent as RazorPay notes, so you can match payments to your own records. Up to 13 tags, and keys and values up to 256 bytes each. Keys that start with `payrails_` are skipped. |

***

## 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:

| Field | Status | Description |
| :- | :- | :- |
| `paymentComposition[].storeInstrument` | Required | Set to `true`. |
| `paymentComposition[].paymentInstrumentData.futureUsage` | Required | `Subscription` for charges on a schedule, or `UnscheduledCardOnFile` for charges at variable times. |
| `meta.customer.email`, `meta.customer.phone` | Required | RazorPay creates a customer from them. |
| `meta.subscription.amountType` | Optional | `fixed` or `variable`. |
| `meta.subscription.fixedAmount` | Optional | The highest amount of a recurring charge. Needed when `amountType` is `fixed`. With any other `amountType`, the limit is ₹15,000. |
| `meta.subscription.chargeFrequency` | Optional | For `Subscription`, an ISO 8601 duration: `P1W` or `P7D` for weekly, `P1M` for monthly, `P1Y` or `P12M` for yearly. Other values and `UnscheduledCardOnFile` use RazorPay's `as_presented` frequency. |
| `meta.subscription.expiration` | Optional | The end of the mandate. A date means the end of that day in India. |

### Charge a recurring payment

Call [authorize a payment](https://docs.payrails.com/reference/authorizeaction.md) 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](https://docs.payrails.com/docs/orchestration/payment-acceptance/test-payments.md)


## Related topics

- [Payment providers](https://docs.payrails.com/docs/integrations/payment-providers.md)
- [PayU](https://docs.payrails.com/docs/integrations/payment-providers/payu.md)
- [QPay](https://docs.payrails.com/docs/integrations/payment-methods/qpay.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.