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

Before you begin

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

Set up an Unlimit integration in your workspace. Contact your Payrails account team if Unlimit isn’t listed in your Payrails Portal 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. Payrails checks Required fields and returns an error when one is missing. Fields required by the PSP pass the Payrails checks but the PSP can decline the payment without them.

Field	Status	Description
`amount.currency`	Required by Unlimit	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 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.

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.

Authorize a UPI payment

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

Choose the journey

Authorize a UPI payment

How Unlimit handles UPI

​Supported workflows

​Before you begin

​Request fields for Unlimit

​Choose the journey

​Authorize a UPI payment

​How Unlimit handles UPI

Supported workflows

Before you begin

Request fields for Unlimit

Choose the journey

Authorize a UPI payment

How Unlimit handles UPI