UPI via Pine Labs

Accept UPI payments from customers in India with Pine Labs as the payment service provider (PSP). The customer goes to a Pine Labs payment page, approves the payment in their UPI app and returns to your site.

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 Pine Labs:

Set up a Pine Labs integration in your workspace. Follow the Pine Labs integration setup guide if you don’t have one yet. The Payrails Portal lists it as PineLabs.
Ask Pine Labs to enable UPI on your Pine Labs merchant account.
In the Payrails Portal, go to Settings → Integrations, open your PineLabs integration, select UPI under Payment methods, and save.
Add UPI as a payment option in your workflow.

Request fields for Pine Labs

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 sends the amount to Pine Labs in minor units, without a currency.
`meta.customer.email`	Optional	Sent to Pine Labs as the customer email.
`meta.customer.name`, `meta.customer.lastName`	Optional	Sent to Pine Labs as the customer’s first and last name.
`meta.customer.phone`	Optional	Sent to Pine Labs as the customer’s mobile number.
`meta.customer.reference`	Optional	Sent to Pine Labs as your customer ID.
`meta.order.billingAddress`	Optional	Sent to Pine Labs as the billing address.
`meta.order.deliveryAddress`	Optional	Sent to Pine Labs as the shipping address, including the recipient’s name and phone.

Authorize a UPI payment

Call authorize a payment with upi as the paymentMethodCode. The response includes the redirect to the Pine Labs payment page.

Authorize request

{
  "amount": {
    "value": "500.00",
    "currency": "INR"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "upi",
      "amount": {
        "value": "500.00",
        "currency": "INR"
      }
    }
  ],
  "meta": {
    "customer": {
      "name": "Aarav",
      "lastName": "Sharma",
      "email": "aarav.sharma@example.com",
      "reference": "customer-1234",
      "phone": {
        "countryCode": "91",
        "number": "9876543210"
      }
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "error": "https://example.com/error"
  }
}

After the customer approves the payment, Pine Labs returns them to your success or error URL. Confirm the result through webhook notifications or the execution status before you fulfill the order.

How Pine Labs handles UPI

Pine Labs accepts only instant capture. Payrails captures UPI payments immediately.
Pine Labs serves its payment pages to customers with an Indian IP address.
When the customer returns, Payrails checks the signature on the Pine Labs response before it updates the payment.
Payrails sends full and partial refunds to Pine Labs against the original transaction.

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Supported workflows

Before you begin

Request fields for Pine Labs

Authorize a UPI payment

How Pine Labs handles UPI

​Supported workflows

​Before you begin

​Request fields for Pine Labs

​Authorize a UPI payment

​How Pine Labs handles UPI

Supported workflows

Before you begin

Request fields for Pine Labs

Authorize a UPI payment

How Pine Labs handles UPI