> ## 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. # PayU India > Connect PayU India to Payrails for cards and UPI in India, covering your merchant key, merchant salt, webhooks, saved cards and recurring payments. ![PayU India logo](https://assets.payrails.io/img/logos/payuindia/logo.svg) > [!NOTE] > > **Who should use this guide** > > This guide is intended for merchants who: > > * Use **Payrails** as a payment orchestrator > * Use **PayU India** for cards or [UPI](https://docs.payrails.com/docs/orchestration/payment-methods/upi/payuindia.md) in India > * Have an active PayU India merchant account *** ## Create a PayU India 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 PayU India** > > Before you begin, make sure you have your PayU India merchant key and merchant salt. You find both in the PayU dashboard under **Developers** → **API Keys**. *** ## Step 1: Choose the provider * Search for **PayU India** and select it. * Select **Next step**. ![A screenshot showing PayU India selected as the provider.](https://mintcdn.com/payrails-42074109/FjsYFukHEi9pOh_n/images/docs/payuindia-image-01.png?fit=max\&auto=format\&n=FjsYFukHEi9pOh_n\&q=85\&s=d41add8304f57b858a963b1579750c07) *** ## Step 2: Enter basic information **In Payrails** * **Integration type**: keep **Payment** selected. * **Integration name**: enter a clear, consistent name, for example `merchant_payuindia`. Routing uses this name, so include the region or environment when you run more than one PayU India integration. * **Workspaces**: select the workspaces where this integration should be available. * Select **Next step**. ![A screenshot showing the PayU India basic information step with integration type, name and workspaces.](https://mintcdn.com/payrails-42074109/FjsYFukHEi9pOh_n/images/docs/payuindia-image-02.png?fit=max\&auto=format\&n=FjsYFukHEi9pOh_n\&q=85\&s=ff790a41453e4caf085dfb781bb8c139) > [!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: Enter account information ### PayU India account details **In Payrails** | Field | Value | | :- | :- | | **Merchant Key** | Your PayU India merchant key | | **Acquirer Merchant ID Visa** | Optional. Your acquirer merchant ID for Visa. | | **Acquirer Bin Amex** | Optional. Your acquirer BIN for American Express. | | **Acquirer Bin Mastercard** | Optional. Your acquirer BIN for Mastercard. | | **Acquirer Bin Visa** | Optional. Your acquirer BIN for Visa. | | **Acquirer Merchant ID Amex** | Optional. Your acquirer merchant ID for American Express. | | **Acquirer Merchant ID Mastercard** | Optional. Your acquirer merchant ID for Mastercard. | Fill in the acquirer merchant IDs and BINs when you use external 3DS, with Payrails authenticating cards before they reach PayU India. Your acquiring bank provides them. ![A screenshot showing the PayU India account details with the merchant key and acquirer fields.](https://mintcdn.com/payrails-42074109/FjsYFukHEi9pOh_n/images/docs/payuindia-image-03.png?fit=max\&auto=format\&n=FjsYFukHEi9pOh_n\&q=85\&s=7d43b0065a711b8007cde19c63066ab4) ### API credentials **In Payrails** | Field | Value | | :- | :- | | **Merchant Salt** | Your PayU India merchant salt. Payrails signs every request with it and uses it to verify PayU India's responses and notifications. | Payrails sends requests to the PayU India test environment in test mode and to the live environment in live mode, so use the merchant key and salt for the matching environment. ![A screenshot showing the PayU India merchant salt field.](https://mintcdn.com/payrails-42074109/FjsYFukHEi9pOh_n/images/docs/payuindia-image-04.png?fit=max\&auto=format\&n=FjsYFukHEi9pOh_n\&q=85\&s=585915b983e41933ed5864139ad87290) ### Payment methods **In Payrails** * Select the payment methods to enable for this integration: **Card**, [UPI](https://docs.payrails.com/docs/orchestration/payment-methods/upi/payuindia.md) or both. ![A screenshot showing the PayU India payment methods with Card and UPI selected.](https://mintcdn.com/payrails-42074109/FjsYFukHEi9pOh_n/images/docs/payuindia-image-05.png?fit=max\&auto=format\&n=FjsYFukHEi9pOh_n\&q=85\&s=8ee179df9e40bea18f92642ceeca4bf8) ### 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 **Webhook** section. ![A screenshot showing the PayU India webhook section with the notification URL label.](https://mintcdn.com/payrails-42074109/FjsYFukHEi9pOh_n/images/docs/payuindia-image-06.png?fit=max\&auto=format\&n=FjsYFukHEi9pOh_n\&q=85\&s=aed197142daa598b6922f3c1ed8a4939) **In PayU India** 1. Log in to the PayU dashboard. 2. Go to **Developers** → **Webhooks** and select **Create Webhook**. 3. Create a webhook of type **payments** for the **successful** event, with the Payrails notification URL. 4. Create a second **payments** webhook for the **failed** event, with the same URL. ![A screenshot showing the PayU India payment webhooks for successful and failed events.](https://mintcdn.com/payrails-42074109/FjsYFukHEi9pOh_n/images/docs/payuindia-image-07.png?fit=max\&auto=format\&n=FjsYFukHEi9pOh_n\&q=85\&s=f78faa8c5bb21d89f3715e59fc6a9016) PayU India signs each notification with your merchant salt, and Payrails verifies the signature. Payrails uses the webhooks to receive UPI payment results. For card payments, Payrails confirms the result with PayU India when the customer returns from 3D Secure. ### 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 PayU India payments. *** ## Request fields for PayU India 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 PayU India when you include them. For more about meta fields, refer to [Meta fields](https://docs.payrails.com/docs/orchestration/meta-fields). | Field | Status | Description | | :- | :- | :- | | `amount` | Required | Use INR. | | `instrument.holderName` | Required | Sent as the customer's first name and the name on the card. You can send `meta.customer.name` and `meta.customer.lastName` instead. | | `meta.customer.email` | Required | Sent as the customer's email. | | `meta.customer.phone.number` | Required | Sent as the customer's phone number. | | `meta.order.description` | Required | Sent as the product information. | | `holderReference` | Optional | Needed to save the card. Payrails sends it to PayU India with your merchant key, so PayU India returns a card token. | | `meta.clientContext.ipAddress` | Optional | Sent as the customer's IP address. | | `meta.clientContext.userAgent` | Optional | Sent as the customer's device information. | *** ## How PayU India handles cards * PayU India authenticates every card payment with 3D Secure. The response includes the redirect to the PayU India authentication page, where the customer enters the OTP from their bank. * When the authorize request carries complete external 3DS data, with the ECI and CAVV, Payrails sends it to PayU India, and PayU India skips its own challenge. * PayU India supports instant and manual capture. With manual capture, you can capture the full amount or a lower amount once. * You can cancel an authorized payment, and refund a captured payment in full or in part. * PayU India completes captures, cancellations and refunds in the background. Payrails checks the status with PayU India until it gets a final result, then updates the payment. A refund can take up to 22 days to complete. *** ## Save cards and recurring payments ### Save a card Set `storeInstrument` to `true` and send `holderReference` on the first payment. Payrails saves the PayU India card token as a payment instrument. For later customer-initiated payments, authorize with the saved `paymentInstrumentId`. ### Register a recurring payment PayU India runs recurring payments on a standing instruction that the customer approves with 3D Secure on the first payment. To register one, 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. | | `holderReference` | Required | Your reference for the customer. | | `meta.subscription.amountType` | Required | `fixed` or `variable`. | | `meta.subscription.fixedAmount` | Required | Needed when `amountType` is `fixed`. Sent to PayU India as the amount of each recurring charge. | | `meta.subscription.maxAmount` | Required | Needed when `amountType` is `variable`. Sent to PayU India as the highest amount of a recurring charge, in place of the first payment amount. | | `meta.subscription.expiration` | Required | The end of the standing instruction. Must be after the start date. | | `meta.subscription.chargeFrequency` | Optional | For `Subscription` with a fixed amount. An ISO 8601 duration of whole days, weeks, months or years, for example `P1M`. Unscheduled and variable-amount instructions have no fixed schedule. | | `meta.subscription.startDate` | Optional | The start of the standing instruction. Defaults to today in India time. Payrails rejects a date in the past. | When the customer completes 3D Secure, Payrails saves the card and the standing instruction on the payment instrument. ### Charge a recurring payment A recurring charge has two steps: PayU India notifies the customer of the upcoming debit, then you confirm the charge. 1. Call [authorize a payment](https://docs.payrails.com/reference/authorizeaction.md) with the saved `paymentInstrumentId`, `meta.order.processingType` set to `Subscription` or `UnscheduledCardOnFile`, and `meta.customer.email` and `meta.customer.phone.number`. Use instant capture. 2. Payrails checks with PayU India that the standing instruction is still active, then asks PayU India to send the pre-debit notification to the customer. The payment stays pending, and the response asks you to confirm it. It includes `earliestConfirmAt`, the earliest time you can confirm. 3. On or after `earliestConfirmAt`, call [confirm a payment](https://docs.payrails.com/reference/confirmaction.md) on the same execution. Payrails sends the debit to PayU India and the payment is captured. `earliestConfirmAt` is 48 hours after the notification, or the debit date if that's later. To set the debit date, send `meta.subscription.scheduledDate`. Without it, the debit date is 48 hours from the request. Payrails checks the status with PayU India before it sends the debit, so confirming twice never charges the customer twice. A confirm before `earliestConfirmAt` is rejected, and you can send it again later. ### Recurring charge results | PayU India result | Payment result in Payrails | | :- | :- | | Captured | Captured | | In progress, or no reply in time | Pending. Payrails keeps checking with PayU India. | | Already processed | Captured when it was this payment, otherwise `DuplicateOperation` | | Declined | Failed, with PayU India's reason | | Standing instruction cancelled by the cardholder | Failed with `InvalidInstrument`, before the customer is notified | | Confirm before `earliestConfirmAt` | Rejected. Send the confirm again later. | *** ## Enable the integration **In Payrails** * Select **Enable integration**. * Confirm the integration shows as **Enabled**. Your **PayU India** integration is now ready to process payments. *** ## Next steps 1. Run a test payment in the PayU India test environment. 2. Verify that: * The payment appears in the PayU 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 - [UPI via PayU India](https://docs.payrails.com/docs/orchestration/payment-methods/upi/payuindia.md) - [UPI](https://docs.payrails.com/docs/orchestration/payment-methods/upi.md) - [Integrations](https://docs.payrails.com/docs/orchestration/integrations.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.