Help Center

Checkout

Coverage

Capabilities

Principle of operation

1. Selection at checkout
   Customer selects UPI as the payment method and initiates mandate authorization.
2. Mandate initiation
   Send a payment request to Solidgate with payment_method_flow set to redirect , plus future_usage max_amount and billing_period . Solidgate returns a UPI deeplink in payment_type_data deep_link_value .
3. 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.
4. 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.
5. 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.

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.

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.

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:

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

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

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

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

Schemes for additional apps are added to the 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 .

1. Selection at checkout
   Customer selects UPI on the Payment Form.
2. 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.
3. 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.
4. Payment result
   Payment Form receives the result via webhook and transitions to the success or error screen.

1. Selection at checkout
   Customer selects UPI on the Payment Form.
2. QR display
   Payment Form generates a QR code from the Intent deep link and displays supported UPI app logos above it.
3. Scan and authorize
   Customer scans the QR with their UPI app, then authenticates and confirms in the app.
4. 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

Schemes for additional apps are added to the 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 with payment_type recurring , max_amount , and billing_period
• customer_email, customer_first_name, customer_last_name, customer_phone
• billing_address country and billing_address zip

See the UPI Intent tab in APM buttons for the full paymentIntent payload and upiButtonParams object.

{
    "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
        }
    }
}

{
    "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.

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.

• 0.02 Order expired
  Customer did not complete authorization within the 15 minute session window.
• 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.