PhonePe

PhonePe is a mobile wallet in India. Customers approve the payment in the PhonePe app instead of entering card details. Payrails processes PhonePe through Unlimit as the payment service provider (PSP).

How a PhonePe payment works

PhonePe is an app-based wallet payment method:

The customer selects PhonePe at checkout.
Payrails returns a redirect from Unlimit. It opens the PhonePe app through a deep link, or the Unlimit payment page when Unlimit returns only a page URL.
The customer approves the payment in the PhonePe app.
The customer returns to your returnInfo URL.
Unlimit sends the result to Payrails, and Payrails updates the payment.

Each payment is single-use: the customer approves every payment on its own. Payrails captures PhonePe payments immediately, so a successful payment is final. To return funds, refund the payment.

Supported currencies and countries

PhonePe supports INR (Indian rupee) as its only presentment currency.

Supported workflows

The response redirects to an app deep link, so integrate PhonePe through the Payrails API and handle the redirect in your own checkout.

Before you begin

Complete these steps before you send your first PhonePe 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 PhonePe on your Unlimit terminal.
In the Payrails Portal, go to Settings → Integrations, open your Unlimit integration, and turn on Processing payments in India. Select PhonePe under Payment methods, and save.
Add PhonePe as a payment option in your workflow.

Payrails rejects PhonePe payments on an Unlimit integration that doesn’t have Processing payments in India turned on.

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.customer.phone.number`	Required	The customer’s PhonePe mobile number. Sent to Unlimit as the wallet account and the customer phone.
`meta.clientContext.ipAddress`	Required	Sent to Unlimit as the customer’s IP address.
`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.
`meta.clientContext.userAgent`	Optional	Sent to Unlimit as the customer’s user agent.

Authorize a PhonePe payment

Call authorize a payment with phonePe as the paymentMethodCode. The response includes the redirect to the PhonePe app or the Unlimit payment page.

Authorize request

{
  "amount": {
    "value": "500.00",
    "currency": "INR"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "phonePe",
      "amount": {
        "value": "500.00",
        "currency": "INR"
      }
    }
  ],
  "meta": {
    "customer": {
      "email": "priya.nair@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 the PhonePe 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 PhonePe

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

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

How a PhonePe payment works

Supported currencies and countries

Supported workflows

Before you begin

Request fields for Unlimit

Authorize a PhonePe payment

How Unlimit handles PhonePe

​How a PhonePe payment works

​Supported currencies and countries

​Supported workflows

​Before you begin

​Request fields for Unlimit

​Authorize a PhonePe payment

​How Unlimit handles PhonePe

How a PhonePe payment works

Supported currencies and countries

Supported workflows

Before you begin

Request fields for Unlimit

Authorize a PhonePe payment

How Unlimit handles PhonePe