UPI Intent

Use this API to initiate a UPI payment using the customer’s UPI app (like PhonePe, GPay, Paytm, etc.). Based on the device OS, the targetApp field is configured differently.

Environment

Environment	HTTP Method	API
Sandbox	`POST`	https://api-preprod.phonepe.com/apis/pg-sandbox/payments/v2/pay
Production	`POST`	https://api.phonepe.com/apis/pg/payments/v2/pay

⚠️ Setup Required to Avoid Errors!

Before initiating a payment, install the PhonePe Test App and configure the payment template. Skipping this step may result in HTTP 500 errors.

Request

Request Header

Header Name	Header Value	Description
Content-Type	application/json
`Authorizatio`n	O-Bearer <access_token>	Pass `access_token` received in Authorization call

⚠️ For Partner Integrations!

It is mandatory to include the X-MERCHANT-ID header with the MerchantID of the end merchant.

Request Parameters

Parameter Name	Data Type	Mandatory	Description	Constraints
`merchantOrderId`	String	Yes	Unique merchant order id generated by merchant.	Max Length = 63 charactersNo Special characters allowed except underscore “_” and hyphen “-“
`amount`	Long	Yes	Order amount in paisa.	Min Value = 100 (In paise)
`expireAfter`	Long	No	Order expiry in seconds. If not passed default value will be used.	Min Value = 300, Max Value = 5184000 Default Value (in Secs): UPI QR: 480 UPI Intent : 600 UPI Collect: 480 Card : 720 NetBanking : 480
`metaInfo`	Object	No	Merchant defined meta info to store additional information.same data will be returned in status and callback response.
`deviceContext.deviceOS`	String	Yes	device OS required only in case of UPI_INTENT	Values Allowed = [IOS, ANDROID]
`deviceContext.merchantCallBackScheme`	String	Yes	Merchant Callback Scheme. Required only in case targetApp = PHONEPE and deviceContext.deviceOS = IOS
`paymentFlow`	Object	Yes	Additional details required by this flow.
`merchantUrls.redirectUrl`	String	Yes	Url where user will be redirected after completing the payment. Mandatory only for [NET_BANKING, TOKEN, CARD] Payment Mode.	Valid Http url.

The metaInfo object contains additional parameters, which are explained in the table below.

Request Parameters of metoInfo Object:

Parameter Name	Data Type	Mandatory	Description	Constraints
`metaInfo.udf1-15`	String	No	Merchant defined additional information	Max length = 256 characters

⚠️ Do Not Rename metainfo Parameters!

It is mandatory to keep the parameter names udf1, udf2, etc., exactly as they are in the metainfo block. Renaming these key values will result in a production error.

The paymentMode object contains additional parameters, which are explained in the table below.

Request Parameters of paymentMode Object:

Parameter Name	Data Type	Mandatory	Description	Constraints
`paymentMode.type`	String	Yes	Type of payment mode	Values Allowed: • UPI_INTENT • UPI_COLLECT • UPI_QR • NET_BANKING • TOKEN • CARD
`paymentMode.`targetApp	application/json	Yes	Target app to use. • Android: Package name for UPI app selected by the user. • iOS: Allowed Values:[PHONEPE, GPAY, PAYTM, CRED, SUPERMONEY, BHIM, AMAZON]

Android

Sample Request

{
    "merchantOrderId": "TX123456",
    "amount": 1000,
    "expireAfter": 1200,
   "metaInfo": {
        "udf1": "<additional-information-1>",
        "udf2": "<additional-information-2>",
        "udf3": "<additional-information-3>",
        "udf4": "<additional-information-4>",
        "udf5": "<additional-information-5>",
        "udf6": "<additional-information-6>",
        "udf7": "<additional-information-7>",
        "udf8": "<additional-information-8>",
        "udf9": "<additional-information-9>",
        "udf10": "<additional-information-10>",
        "udf11": "<additional-information-11>",
        "udf12": "<additional-information-12>",
        "udf13": "<additional-information-13>",
        "udf14": "<additional-information-14>",
        "udf15": "<additional-information-15>"
    },    
    "deviceContext": {
        "deviceOS": "ANDROID"
    },
    "paymentFlow": {
        "type": "PG",    
        "paymentMode" : {                           
            "type" : "UPI_INTENT",
            "targetApp" : "com.phonepe.app" // Package name for UPI app selected by the user in Android
        }  
    } 
}

iOS

Sample Request

{
    "merchantOrderId": "TX123456",
    "amount": 1000,
    "expireAfter": 1200,
   "metaInfo": {
        "udf1": "<additional-information-1>",
        "udf2": "<additional-information-2>",
        "udf3": "<additional-information-3>",
        "udf4": "<additional-information-4>",
        "udf5": "<additional-information-5>",
        "udf6": "<additional-information-6>",
        "udf7": "<additional-information-7>",
        "udf8": "<additional-information-8>",
        "udf9": "<additional-information-9>",
        "udf10": "<additional-information-10>",
        "udf11": "<additional-information-11>",
        "udf12": "<additional-information-12>",
        "udf13": "<additional-information-13>",
        "udf14": "<additional-information-14>",
        "udf15": "<additional-information-15>"
    },    
    "deviceContext": {
        "deviceOS": "IOS",
        "merchantCallBackScheme": ""
    },
    "paymentFlow": {
        "type": "PG",    
        "paymentMode" : {                           
            "type" : "UPI_INTENT",
            "targetApp" : "PHONEPE" // Static Values: PHONEPE, GPAY, PAYTM, CRED, BHIM, AMAZON or null.
        }  
    } 
}

Response

Sample Response

{
    "orderId": "OMO123456789",
    "state": "PENDING",
    "expireAt": 1703756259307,      
    "intentUrl" : "ppe://url"
}

Field Name	Data Type	Description
`orderId`	String	PG generated internal order id.
`state`	String	State of the order created, Expected value is CREATED.
`expiryAt`	Long	Order expiry date in epoch (in milliseconds).
`intentUrl`	String	Intent url (Present in case of UPI_INTENT or UPI_QR).

merchantCallBackScheme for iOS UPI Intent

The merchantCallBackScheme field is mandatory only for iOS devices when using the UPI Intent flow. It allows PhonePe to redirect the user back to your app after the transaction is completed via the UPI app.

To enable redirection back to your iOS app, you must define a URL Type (DeepLink) in your app’s Info.plist.

Ensure your custom scheme follows the guidelines below to prevent redirection failures:

Only alphabets (lower and upper case) and numbers are allowed.
Special characters allowed: dot (.) and hyphen (-) only.
The name should always start with alphabets.
The schema should be correct to redirect the app; otherwise, it will not redirect back to the merchant app.

Try it yourself!

Android

headers

body params

iOS

headers

body params

What’s Next?

In the next section, you will learn how to validate whether the UPI address (VPA) or UPI number provided by the customer is valid and capable of accepting payments. This process uses the VPA Validation API to ensure that payment requests are sent only to an active and correct UPI account.