UPI Collect
Use this flow to initiate a UPI collect request to the customer’s UPI Number. Before creating a collect request, you must validate the VPA or UPI number.
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 | Accepts Json Payload. |
Authorization | 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 |
| Object | Yes | Object containing collect payment details. | |
message | String | Yes | Message to show in collect request. | |
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. | |
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. |
The details object contains additional parameters, which are explained in the table below.
Request Parameters of details Object:
| Parameter Name | Data Type | Mandatory | Description | Constraints |
details.type | String | Yes | Type of collect payment details. Allowed Values: • VPA • UPI_NUMBER | |
details.vpa | String | Yes | VPA against which collect request need to be raised (Use when type = VPA) | |
details.upiNumber | String | Yes | UPI Number against which collect request need to be raised (Use when type = UPI_NUMBER) |
The metaInfo object contains additional parameters, which are explained in the table below.
Request Parameters of metoInfo Object:
| Parameter Name | Data Type | Description | Mandatory (Yes/No) | Constraints |
metaInfo.udf1-15 | String | Optional details you can add for more information | No | • Maximum length for Udf1-10 = 256 characters • Maximum length for Udf11-15 = 50 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.
Sample Request UPI Collect With VPA
{
"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>"
},
"paymentFlow": {
"type": "PG",
"paymentMode" : {
"type" : "UPI_COLLECT",
"details" : {
"type" : "VPA",
"vpa" : "success@ybl"
},
"message" : "some message from merchant to populate"
}
}
}Sample Request for UPI Collect With UPI Number
{
"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>"
},
"paymentFlow": {
"type": "PG",
"paymentMode" : {
"type" : "UPI_COLLECT",
"details" : {
"type" : "UPI_NUMBER",
"upiNumber" : "XXXXXXXXXX"
},
"message" : "some message from merchant to populate"
}
}
}Response
Sample Response
{
"orderId": "OMO123456789",
"state": "PENDING",
"expireAt": 1703756259307
}| 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). |
Try it yourself!
UPI Collect With VPA
headers
body params
UPI Collect With UPI Number
body params
What’s Next?
In the next section, you will learn about the flow that generates a QR code, which the customer can scan using any UPI enabled app to complete the payment.
