UPI Intent
To start a payment through PhonePe, you need to first create a payment request using the Initiate Payment API. PhonePe supports various payment instruments, and in this section, we’ll focus on UPI Intent as the payment method.
This flow is supported on both Android and iOS platforms, enabling a seamless payment experience through the respective UPI apps installed on the customer’s device.
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 |
📘 Pre-requisite for UAT Testing
Before initiating the payment, ensure that the PhonePe Test App is installed and the template is configured. Failing to do so will result in an HTTP 500 error.
Request
| Header Name | Header Value |
| Content-Type | application/json |
| Authorization | O-Bearer <partner-auth-token> |
| X-MERCHANT-ID | MID |
{
"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>"
},
"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
}
},
"splitSettlementInfo":
{
"type": "PERCENT", // Values: PERCENT or ABSOLUTE
"accountsSplit":
[
{
"value": 10.5, // Floor upto 2 decimal
"accountId": "B12345678"
},
{
"value": 20.5, // Floor
"accountId": "B9101112"
}
]
}
}{
"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>"
},
"deviceContext": {
"deviceOS": "IOS",
"merchantCallBackScheme": "merchantApp"
},
"paymentFlow": {
"type": "PG",
"paymentMode" : {
"type" : "UPI_INTENT",
"targetApp" : "PHONEPE" // Static Values: PHONEPE, GPAY, PAYTM, CRED, BHIM, AMAZON or null.
}
},
"splitSettlementInfo":
{
"type": "PERCENT", // Values: PERCENT or ABSOLUTE
"accountsSplit":
[
{
"value": 10.5, // Floor upto 2 decimal
"accountId": "B12345678"
},
{
"value": 20.5, // Floor
"accountId": "B9101112"
}
]
}
}Note: Refer here for the common Request Parameters.
Extra parameters for UPI INTENT
| Parameter Name | Data Type | Description | Mandatory (Yes/No) | Constraints |
targetApp | application/json | Target app used for the transaction: • For Android: Provide the package name of the UPI app selected by the user. • For iOS: Allowed values are PHONEPE, GPAY, PAYTM, CRED, BHIM, or AMAZON. | ||
merchantOrderId | String | Unique order ID created by the merchant to identify the transaction. | Yes | Max Length = 63 charactersNo Special characters allowed except underscore “_” and hyphen “-“ |
amount | Long | Total amount of the order specified in paisa. | Yes | Min Value = 100 (In paise) |
expireAfter | Long | Time after which the order will expire, specified in seconds. If not provided, a default value will be applied. | No | 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 | Merchant defined meta information used to store additional data related to the order. The same data will be returned in the status and callback response. | No | |
metaInfo.udf1-5 | String | Additional information provided by the merchant, usually used to store custom data related to the order. | No | Max length = 256 characters |
deviceContext.deviceOS | String | Device operating system is required only when the payment mode is UPI_INTENT. | Yes | Values Allowed: • iOS • ANDROID |
deviceContext.merchantCallBackScheme | String | Merchant callback scheme is required only when the target app is PhonePe and the device operating system is IOS. | Yes | |
paymentFlow | Object | Additional information required to complete this payment flow. | Yes | |
paymentFlow.type | String | Specifies the type of payment flow used. | Yes | Valued Allowed: PG |
paymentMode | Object | Contains information related to available payment modes. | Yes | |
paymentMode.type | String | Specifies the type of the payment method | Yes | Values Allowed: • UPI_INTENT • UPI_COLLECT • UPI_QR • NET_BANKING • TOKEN • CARD |
merchantUrls.redirectUrl | String | URL to which the user is redirected after completing the payment. Required only for NET BANKING, TOKEN, and CARD payment modes. | Yes | Valid Http url. |
splitSettlementInfo | Object | Accounts where the merchant wants the amount to be distributed. Applicable only if split is enabled for the merchant. | No | The total split amount must not exceed the order amount provided. |
The splitSettlementInfo field contains two key components which are explained below.
| Field Name | Data Type | Mandatory | Description |
|---|---|---|---|
splitSettlementInfo.type | String | Yes | Type of split. i.e if the amount in split is in percent or absolute. |
splitSettlementInfo.accountsSplit | List | Yes | Information of the account into which the split should be done |
If splitInfo.type is set to “PERCENT”, the splitInfo.accounts field should contain details of each account along with the percentage of the total amount to be allocated.
| Field Name | Data Type | Mandatory | Description |
|---|---|---|---|
value | Double | Yes | Percentage of the amount to be split, allowing up to two decimal places. |
accountId | String | Yes | Name assigned by the merchant when adding the beneficiary, used for the merchant’s reference. |
If splitInfo.type is set to ABSOLUTE, then accountsSplit must include the following details.
| Field Name | Data Type | Mandatory | Description |
|---|---|---|---|
value | Double | Yes | Amount to be split, specified in Paisa. |
accountId | String | Yes | Name assigned by the merchant while adding the beneficiary. This acts as a reference for the merchant. |
Response Details
| Header Name | Header Value |
|---|---|
Content-Type | application/json |
{
"orderId": "OMO123456789",
"state": "PENDING",
"expireAt": 1703756259307,
"intentUrl" : "ppe://url"
}{
"code": SPLIT_SETTLEMENT_NOT_ENABLED/ INVALID_SPLIT_DETAILS / BAD_REQUEST
"message": Split settlement not enabled/ invalid split details
}{
"code": "INTERNAL_SERVER_ERROR",
"message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}| Field Name | Data Type | Description |
|---|---|---|
orderId | String | Internal order ID generated by the PG. |
state | String | Current state of the created order. The expected value is CREATED. |
expiryAt | Long | The timestamp when the order will expire, represented in epoch (milliseconds). |
redirectUrl | String | The URL to which the merchant should redirect the user to complete the payment. |
intentUrl | String | The intent URL used to trigger the UPI app flow. Present only in case of UPI_INTENT or UPI_QR payment modes. |
| Field Name | Data Type | Description |
|---|---|---|
code | String | Error Code |
message | String | Error Message |
merchantCallBackScheme
📘 This is applicable only for the iOS UPI Intent flow.
Create DeepLink Schema
To enable deep linking, create a URLType for your app if it does not already exist.
For example, in our case, we have used iOSIntentIntegration. You can define your own unique name for your app.
URLScheme Guidelines
Make sure the URLScheme follows these rules:
- Use only alphabets (both uppercase and lowercase) and numbers.
- Special characters allowed: dot and hyphen.
- It must always start with an alphabet.
- The scheme should be valid to ensure the app redirects back properly. An incorrect scheme will result in failed redirection to the merchant app.