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 |
⚠️ Before initiating a payment, install the PhonePe Test App and configure the payment template. Skipping this step may result in HTTP 500 errors.
Request
| Header Name | Header Value | Description |
| Content-Type | application/json | |
Authorization | O-Bearer <access_token> | Pass access_token received in Authorization call |
| Parameter Name | Data Type | Mandatory | Description | Constraints |
| application/json | Yes | Target app to use. • Android – Package name for UPI app selected by the user. • iOS – Allowed Values:[PHONEPE, GPAY, PAYTM, CRED, BHIM, AMAZON] | |
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. | |
metaInfo.udf1-5 | String | No | Merchant defined additional information | Max length = 256 characters |
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. | |
paymentMode.type | String | Yes | Type of payment mode | Values Allowed: • UPI_INTENT • UPI_COLLECT • UPI_QR • NET_BANKING • TOKEN • CARD |
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. |
Try it yourself!
Android
iOS
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.
