UPI QR
The UPI QR flow lets you generate a QR code that the customer can scan using any UPI app to complete the payment. The request includes order details, optional metadata, and split settlement info. The response returns an orderId, PENDING status, a qrData for generating the QR, and an intentUrl for app redirection.
Environment
| Environment | Http Method | API |
|---|---|---|
| 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>"
},
"paymentFlow": {
"type": "PG",
"paymentMode" : {
"type" : "UPI_QR"
}
},
"splitSettlementInfo":
{
"type": "PERCENT", // Values: PERCENT or ABSOLUTE
"accountsSplit":
[
{
"value": 10.5, // Floor upto 2 decimal
"accountId": "B12345678"
},
{
"value": 20.5, // Floor
"accountId": "B9101112"
}
]
}
}| Parameter Name | Data Type | Description | Mandatory (Yes/No) | Constraints |
details | Object | Object that holds the UPI collect payment details. | Yes | |
details.type | String | Specifies the type of UPI collect request. Supported values: • VPA• UPI_NUMBER | Yes | |
details.vpa | String | The Virtual Payment Address to which the collect request should be sent. Required when type is set to VPA. | Yes | |
details.upiNumber | String | The UPI number to which the collect request should be sent. Required when type is set to UPI_NUMBER. | Yes | |
message | String | Custom message to be displayed in the customer’s collect prompt. | Yes | |
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",
"qrData": ""
}{
"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 |