UPI Intent

Accept UPI Intent payments in India where customers select their UPI app directly or scan a QR code on desktop for one-time and mandate-based checkout

CategoryAccount-to-account (A2A)

Payment flowRedirect

Coverage

Countries	India (IN)
Currencies	Indian Rupee (INR)
Min amount	29.50 INR
Max amount	Bank dependent

Checkout

Integration type	API v1
	Payment Form

Billing logics

One-time	Yes
1-click	No
Recurring	Yes
Unscheduled MIT	Yes

Operations

Refund	Yes
Partial refunds	Yes
Multiple partial refunds	No
Chargeback	No

UPI Intent is an app-to-app redirect flow. The merchant checkout launches the customer's UPI app with payment details prefilled via a deep link. No VPA entry is required. On desktop, the same deep link is rendered as a QR code for scanning. Set payment_method_flow to redirect .

UPI Intent is the recommended integration. It improves mobile conversion and enables QR checkout on desktop. NPCI guidelines effective February 2026 restrict manual VPA entry on mobile transactions, making Intent the compliance standard for mobile checkouts.

UPI Intent is the migration target for existing UPI Collect integrations, due to deprecation plans of the latter.

Principle of operation

One-time

Selection at checkout
Customer selects UPI as the payment method.
Payment initiation
Send a payment request to Solidgate with payment_method_flow redirect and future_usage.payment_type unscheduled . Do not pass future_usage.billing_period. Solidgate returns a UPI deeplink in payment_type_data.deep_link_value.
App launch / QR display
On mobile, render buttons for specific UPI apps using deeplinks constructed from the deep_link_value. On desktop, render the deep_link_value as a QR code for the customer to scan with their phone.
Authorization
The customer authorizes the payment in their UPI app by entering their UPI PIN.
Merchant notification
You receive a notification Webhook confirming the payment status.

Recurring

Selection at checkout
Customer selects UPI as the payment method and initiates mandate authorization.
Mandate initiation
Send a payment request to Solidgate with payment_method_flow redirect , future_usage.payment_type recurring , plus future_usage.max_amount and future_usage.billing_period. Solidgate returns a UPI deeplink in payment_type_data.deep_link_value.
App launch / QR display
On mobile, render buttons for specific UPI apps using deeplinks constructed from the deep_link_value. On desktop, render the deep_link_value as a QR code for the customer to scan with their phone.
Mandate authorization
The customer reviews the mandate terms, including maximum charge amount and billing frequency, and authorizes the setup by entering their UPI PIN. A token is issued for subsequent charges.
Merchant notification
You receive a notification Webhook confirming the payment status.

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.

`billing_period.unit`	`billing_period.value`	Interval
day	1	Daily
day	7	Weekly
week	1	Weekly
month	1	Monthly
year	1	Yearly

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.

Desktop

deep_link_value

1

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

Render the deep_link_value as a QR code. Display logos of supported UPI apps above the QR code. Show a countdown timer reflecting the 15 minute session window. Generate the QR code directly from the URI. Do not use a payment provider's QR generation API.

Mobile

deep_link_value

1

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

Render a button for each supported UPI app. Construct app specific deeplinks by replacing the generic upi://mandate prefix with an app specific scheme:

UPI app	App specific scheme
GPay	tez://upi/mandate
PhonePe	phonepe://mandate
Paytm	paytmmp://mandate

Example deep links after replacing upi://mandate in deep_link_value:

GPay

1

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

PhonePe

1

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

Paytm

1

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

On iOS, the universal UPI app tray does not work due to OS level restrictions. Prepend a per-app URL prefix before opening the deep link. This requires explicit app level handling on the frontend.

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

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.

Mobile

Selection at checkout
Customer selects UPI on the Payment Form.
App selection
Payment Form displays up to 6 to 8 UPI apps. Top apps appear first: Google Pay, PhonePe, Paytm, BHIM. Additional apps are under Show all.
App launch
Customer selects an app and is redirected to authenticate and confirm the mandate. On iOS, Payment Form prepends the per app URL prefix before opening the deep link.
Payment result
Payment Form receives the result via webhook and transitions to the success or error screen.

Desktop

Selection at checkout
Customer selects UPI on the Payment Form.
QR display
Payment Form generates a QR code from the Intent deep link and displays supported UPI app logos above it.
Scan and authorize
Customer scans the QR with their UPI app, then authenticates and confirms in the app.
Payment result
Payment Form receives the result via webhook and transitions to the success or error screen. If the session expires, the QR is marked expired and the customer is prompted to restart.

Supported UPI apps

Platform	Apps
Android	Google Pay, PhonePe, CRED, Paytm, BHIM, Amazon Pay, iMobile by ICICI, PayZapp, Mobikwik, Navi
iOS	Google Pay, PhonePe, CRED, Paytm, BHIM

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
- unscheduled for one-time. Do not pass future_usage.billing_period.
- recurring for recurring, future_usage.max_amount, and future_usage.billing_period Required
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.

One-time

Request

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

{
    "payment_method": "upi",
    "payment_method_flow": "redirect",
    "order_id": "order_ot_001",
    "amount": 29900,
    "currency": "INR",
    "order_description": "Premium package",
    "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": "110001"
    },
    "future_usage":
    {
        "payment_type": "unscheduled"
    }
}

Response

 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_ot_001",
        "status": "processing",
        "method": "upi",
        "customer_email": "buyer@example.in",
        "ip_address": "103.21.56.78",
        "order_description": "Premium package",
        "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://pay?pa=merchant@upi&pn=MerchantName&tr=pay_KfyQIVi7wcL8Po&tn=Premium+package&am=299.00&cu=INR&mc=5411"
    },
    "transactions":
    []
}

One-time product

Request

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

{
    "payment_method": "upi",
    "payment_method_flow": "redirect",
    "order_id": "order_otp_001",
    "product_id": "ac43b415-5522-4373-b026-a365462f9657",
    "customer_account_id": "4dad42f808",
    "currency": "INR",
    "order_description": "Premium package",
    "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": "110001"
    },
    "future_usage":
    {
        "payment_type": "unscheduled"
    }
}

Response

 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_otp_001",
        "status": "processing",
        "method": "upi",
        "customer_email": "buyer@example.in",
        "ip_address": "103.21.56.78",
        "order_description": "Premium package",
        "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://pay?pa=merchant@upi&pn=MerchantName&tr=pay_KfyQIVi7wcL8Po&tn=Premium+package&am=299.00&cu=INR&mc=5411"
    },
    "transactions":
    []
}

Recurring

Request

 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": "110001"
    },
    "future_usage":
    {
        "payment_type": "recurring",
        "max_amount": 99900,
        "billing_period":
        {
            "unit": "month",
            "value": 1
        }
    }
}

Response

 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. Solidgate does not cancel the associated subscription immediately. The next charge attempt fails with Guide
Invalid card token. 5.02 , then the subscription is cancelled with cancel code Guide
The customer revoked the billing token by contacting customer support or the bank. 8.11 Token revoked by customer. Merchants receive the failed payment notification Webhook and the subscription cancel webhook.

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
Invalid or incorrectly formatted request fields. Validate customer_phone (E.164, digits and
only), billing_address.zip (6 characters for India), and billing_address.city when provided.

Looking for help? Contact us

Stay informed with Changelog