UPI Intent

Principle of operation

Recurring payments

Recurring payments up to ₹15,000 per individual transaction are processed without customer intervention. For amounts above ₹15,000 per transaction, an additional authentication factor is required for each debit. These debits are not supported.

Customer receives a notification 24 hours before the scheduled charge.

• If the customer declines the follow-up charge, a decline response is returned.
• If the customer does not decline the charge, a success response is issued.

When creating the initial payment, specify the amount to be debited for future subscription charges. This amount appears in the customer’s UPI app when the mandate is created. The mandate authorizes follow-up payments.

For example, if the merchant has sold the customer a subscription plan for up to ₹3,000, the customer sees this amount at the time of mandate creation, along with a notice that payments may be up to ₹3,000.

Any payment below the amount specified in the initial request occurs without additional confirmation from the customer. However, the customer still receives notifications the day before the follow-up payment and can cancel the subscription at any time.

Billing periods

The future_usage.billing_period maps to the UPI Autopay mandate frequency. Only the combinations of billing_period.unit and billing_period.value below are accepted.

These rules apply when the billing period is sent directly in future_usage.billing_period and when you use product_id , the product configuration must match the table.

UPI Intent checkout

The init-payment API response contains payment_type_data.deep_link_value, a generic UPI mandate URI.

1

upi://mandate?pa=merchant@upi&pn=MerchantName&tr=pay_ID&tn=description&am=299.00&cu=INR

1

upi://mandate?pa=merchant@upi&pn=MerchantName&tr=pay_ID&tn=description&am=299.00&cu=INR

1

tez://upi/mandate?pa=x@bank&am=29900

1

phonepe://mandate?pa=x@bank&am=29900

1

paytmmp://mandate?pa=x@bank&am=29900

Payment Form

Integrate UPI Intent via APM buttons. Payment Form detects the device and renders the Intent flow on mobile or a QR code on desktop. Set upiButtonParams.enabled to true to display the button when UPI is enabled for the merchant.

Do not use a payment provider QR generation API. Payment Form generates the QR directly from the Intent deep link returned in payment_type_data.deep_link_value.

Supported UPI apps

Schemes for additional apps are added to the Guide
Review product updates, new features, and integration changes. changelog as they are confirmed.

Required paymentIntent fields

Pass these fields when initializing the Payment Form for UPI Intent.

• payment_method_flow redirect
• future_usage.payment_type recurring , future_usage.max_amount, and future_usage.billing_period
• customer_email, customer_first_name, customer_last_name, customer_phone
• billing_address.country and billing_address.zip

See the Guide
Add alternative payment method buttons to your payment form with customizable styling, placement, and method-specific display conditions. UPI Intent tab in APM buttons for the full paymentIntent payload and upiButtonParams object.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
    "payment_method": "upi",
    "payment_method_flow": "redirect",
    "order_id": "order_rec_001",
    "amount": 29900,
    "currency": "INR",
    "order_description": "Monthly subscription",
    "customer_email": "buyer@example.in",
    "customer_first_name": "Arjun",
    "customer_last_name": "Sharma",
    "customer_phone": "+919876543210",
    "ip_address": "103.21.56.78",
    "platform": "WEB",
    "billing_address":
    {
        "country": "IND",
        "zip_code": "110001"
    },
    "future_usage":
    {
        "payment_type": "recurring",
        "max_amount": 99900,
        "billing_period":
        {
            "unit": "month",
            "value": 1
        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
    "order":
    {
        "amount": 29900,
        "currency": "INR",
        "order_id": "order_rec_001",
        "status": "processing",
        "method": "upi",
        "customer_email": "buyer@example.in",
        "ip_address": "103.21.56.78",
        "order_description": "Monthly subscription",
        "created_at": "2026-05-18 10:31:44",
        "updated_at": "2026-05-18 10:31:44"
    },
    "pay_form":
    {
        "token": "pft1ymnx6gq32ej3dvr9p45w",
        "return_url": "https://merchant.example.com/return",
        "script_url": ""
    },
    "payment_type_data":
    {
        "deep_link_value": "upi://mandate?pa=merchant@upi&pn=MerchantName&tr=pay_KfyQIVi7wcL8Po&tn=Monthly+subscription&am=299.00&cu=INR&mc=5411"
    },
    "transactions":
    []
}

Mandates

future_usage.max_amount sets the maximum single charge amount the customer preauthorizes during mandate creation. It is displayed to the customer in their UPI app. Provide the value in paise, the minor currency unit. Any charge above this amount is declined.

• This field is required if no product_id or product_price_id is provided.

future_usage.billing_period sets the recurring billing interval for the UPI mandate.

• This field is required when payment_type is recurring and no product_id or product_price_id is provided.

Mandate display at checkout

Merchants must display mandated terms clearly at checkout, including the maximum charge amount and billing frequency, so customers can review them before mandate creation.

Customers can revoke a mandate at any time in their UPI app by selecting Delete AutoPay. When a mandate is revoked, Solidgate automatically cancels the associated subscription and sends a notification Webhook notification to the merchant.

Handle UPI errors

Specific errors may occur when a UPI payment attempt fails.

• Guide
  The payment was not completed within the allocated timeframe, leading to order expiration. 0.02 Order expired
  Customer did not complete authorization within the 15 minute session window.
• Guide
  This error indicates an issue with the provided data format. 2.01 Invalid data
  Incorrect VPA format on UPI Collect or incorrectly formatted phone number. Validate customer_phone . Only digits 0 through 9 and the + symbol are permitted.