UPI via Unlimit

Accept UPI payments from customers in India with Unlimit as the payment service provider (PSP). The customer approves the payment in a UPI app, either through a deep link or by scanning a QR code.

Supported workflows

Workflow	Supported
Payrails SDK	✔
Payrails API	✔
Delayed / Manual Capture	✖
Instant Capture	✔
Cancel / Void	✖
Refund / Reverse	✔
Save Instruments	✖
Merchant Initiated Transaction (MIT)	✖

Before you begin

Complete these steps before you send your first UPI payment through Unlimit:

Set up an Unlimit integration in your workspace. Follow the Unlimit integration setup guide if you don’t have one yet.
Ask Unlimit to enable UPI on your Unlimit terminal.
In the Payrails Portal, go to Settings → Integrations, open your Unlimit integration, select UPI under Payment methods, and save. Turn on Processing payments in India if the Unlimit account processes payments in India.
Add UPI as a payment option in your workflow.

Request fields for Unlimit

Send these fields in the authorize request, in addition to the standard authorize fields. Required fields must be present for the payment to succeed. Payrails sends Optional fields to the PSP when you include them.

Field	Status	Description
`amount.currency`	Required	Send `INR`. Payrails passes the currency to Unlimit unchanged.
`returnInfo.success`	Required	The URL the customer returns to after a successful payment.
`meta.order.description`	Required	Sent to Unlimit as the order description.
`meta.customer.email`	Required	Sent to Unlimit as the customer email.
`meta.clientContext.ipAddress`	Required	Sent to Unlimit as the customer’s IP address.
`meta.customer.phone.number`	Required	Needed for accounts that process payments in India. Payrails returns an error when Processing payments in India is on and the phone number is missing. Sent to Unlimit as the customer phone.
`meta.paymentMethods.upi.flow`	Optional	`intent` or `qr`. Payrails rejects any other value. See choose the journey.
`meta.customer.reference`	Optional	Sent to Unlimit as your customer ID.
`meta.customer.language`	Optional	Sent to Unlimit as the customer locale, as a two-letter language code.

Authorize a UPI payment

Choose the journey

Unlimit returns both a deep link and QR code content for every UPI payment. Payrails picks the journey when it maps the response:

When meta.paymentMethods.upi.flow is qr, Payrails shows the QR code on a Payrails-hosted page.
Otherwise, including when you send no flow, the response redirects the customer to their UPI app through the deep link. If Unlimit returns only QR code content, Payrails shows the QR code page.

Unlimit doesn’t use appId. The deep link comes from Unlimit. Call authorize a payment with upi as the paymentMethodCode. This example uses the QR code journey on an account that processes payments in India.

Authorize request

{
  "amount": {
    "value": "500.00",
    "currency": "INR"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "upi",
      "amount": {
        "value": "500.00",
        "currency": "INR"
      }
    }
  ],
  "meta": {
    "paymentMethods": {
      "upi": {
        "flow": "qr"
      }
    },
    "customer": {
      "email": "aarav.sharma@example.com",
      "reference": "customer-1234",
      "phone": {
        "countryCode": "91",
        "number": "9876543210"
      }
    },
    "order": {
      "description": "Wallet top-up"
    },
    "clientContext": {
      "ipAddress": "203.0.113.10"
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "error": "https://example.com/error"
  }
}

The customer approves the payment in their UPI app, and Unlimit sends the result to Payrails asynchronously. Confirm the result through webhook notifications or the execution status before you fulfill the order.

How Unlimit handles UPI

Unlimit charges UPI payments directly and reports only the completed payment. Payrails records the authorization and the capture from that single notification.
Unlimit doesn’t return acquirer reference, retrieval reference or authorization code values for UPI payments.
Merchant-initiated transactions (MIT) through Unlimit work only with cards, Apple Pay, and Google Pay. Payrails returns an error for a UPI MIT.

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Supported workflows

Before you begin

Request fields for Unlimit

Authorize a UPI payment

Choose the journey

How Unlimit handles UPI

​Supported workflows

​Before you begin

​Request fields for Unlimit

​Authorize a UPI payment

​Choose the journey

​How Unlimit handles UPI

Supported workflows

Before you begin

Request fields for Unlimit

Authorize a UPI payment

Choose the journey

How Unlimit handles UPI