Check Payment Link Status
The Payment Link Status API allows you to track the real-time status of a payment link you previously created. By passing the merchantOrderId, you can find out whether the payment is completed, pending, failed, expired, or still active with no attempts made.
Use this API to stay updated on your customer’s payment progress by providing details like the merchantOrderId
Environment
| Environment | HTTP Method | API |
| Sandbox | GET | https://api-preprod.phonepe.com/apis/pg-sandbox/paylinks/v1/{merchantOrderId}/status?details=[false or true] |
| Production | GET | https://api.phonepe.com/apis/pg/paylinks/v1/{merchantOrderId}/status?details=[false or true] |
Path Parameters
| Parameter Name | Description |
details | • details = true → Returns all payment attempt details in the paymentDetails list.• details = false → Returns only the most recent payment attempt in the paymentDetails list. |
Request
Request Headers
| Header Name | Header Value |
| Content-Type | application/json |
| Authorization | O-Bearer <merchant-auth-token> |
⚠️ For Partner Integrations!
It is mandatory to include the X-MERCHANT-ID header with the MerchantID of the end merchant.
Response
Response Header
| Header Name | Header value |
| Content-Type | application/json |
Case 1: Response for Order is completed
{
"orderId": "OMOxx",
"state": "COMPLETED",
"amount": 10000,
"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>"
},
"expireAt": 1291391291,
"paymentFlow": {
"type": "PAYLINK",
"paylinkUrl": "https://phon.pe/abc"
},
"paymentDetails": [
{
"paymentMode": "UPI_COLLECT",
"timestamp": 12121212,
"amount": 10000,
"transactionId": "OM12333",
"state": "FAILED",
"errorCode": "AUTHORIZATION_ERROR",
"detailedErrorCode": "ZM",
"rail": {
"type": "UPI",
"upiTransactionId": "upi12313",
"vpa": "12****78@ybl"
},
"instrument": {
"type": "ACCOUNT",
"accountType": "SAVINGS",
"accountNumber": "******1234"
}
},
{
"paymentMode": "UPI_QR",
"transactionId": "OM12334",
"timestamp": 12121212,
"amount": 10000,
"state": "COMPLETED",
"rail": {
"type": "UPI",
"upiTransactionId": "upi12313",
"vpa": "12****78@ybl"
},
"instrument": {
"type": "ACCOUNT",
"accountType": "SAVINGS",
"accountNumber": "******1234"
}
}
]
}Case 2: Response for No payment attempt has been made for the Payment Link.
{
"orderId": "OMOxx",
"state": "ACTIVE",
"amount": 10000,
"expireAt": 1291391291,
"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>"
}
}Case 3: Response for Invalid order id.
{
"code": "INVALID_MERCHANT_ORDER_ID",
"message": "No entry found for given merchant order id"
}Response Parameters
| Parameter Name | Data Type | Description |
OrderId | String | Payment Gateway generated internal order ID. |
state | String | Represents the current status of the payment link. Possible values: • ACTIVE • FAILED • EXPIRED • COMPLETED • CANCELLED. Note: Always refer to the state parameter to confirm the payment status. |
amount | String | Order amount specified in paisa. |
| Long | Order expiry time in epoch. |
| Object | Meta information means extra details you want to add for your own use. This information will be sent back to you in the status and callback responses. |
| List | Contains a list of details for each payment attempt made for the corresponding order. |
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 |
The paymentDetails object contains additional parameters, which are explained in the table below.
Request Parameters of paymentDetails Object:
| Parameter Name | Data Type | Description |
| String | The payment method used. Expected values include: • UPI_INTENT • UPI_COLLECT • UPI_QR, CARD • TOKEN • NET_BANKING |
| Long | The timestamp of the transaction attempt, in epoch. |
| Long | The amount in paisa for the payment attempt. |
| String | The internal transaction ID associated with the given payment attempt. |
| String | The state of the transaction attempt. Expected values are: • PENDING • COMPLETED • FAILED |
| String | The error code, which is provided only when the transaction state is “FAILED.” |
paymentDetails.detailedErrorCode | String | The detailed error code, which is provided only when the transaction state is “FAILED.” It gives more specific information about why the transaction failed. |
paymentDetails.rail | String | Contains details about the processing rail used for the payment attempt. |
paymentDetails.rail.type | String | Indicates the type of payment rail used for the transaction. Expected values are: • UPI • PG |
paymentDetails.instrument | String | Contains details of the payment instrument used for the transaction. |
paymentDetails.instrument.type | String | Specifies the type of payment instrument used for the transaction. Expected values include: • ACCOUNT • CREDIT_CARD • DEBIT_CARD • NET_BANKING |
Rail and Instrument Values for Each Payment Mode
Rail = “UPI”, When Payment Mode = [UPI_INTENT, UPI_COLLECT, UPI_QR]
"rail": {
"type": "UPI",
"utr": "<utr>",
"upiTransactionId": "upi12313",
"vpa": "12****78@ybl"
}Rail = “PG”, When payment Mode = [CARD, TOKEN, NET_BANKING]
"rail": {
"type": "PG",
"transactionId": "<transactionId>",
"authorizationCode": "<authorizationCode>",
"serviceTransactionId": "<serviceTransactionId>"
}Instrument = “ACCOUNT”, When payment Mode = [UPI_INTENT, UPI_COLLECT, UPI_QR]
"instrument": {
"type": "ACCOUNT",
"accountType": "SAVINGS",
"maskedAccountNumber": "<maskedAccountNumber>",
"accountHolderName": "<accountHolderName>"
}Instrument = “CREDIT_CARD”, When payment Mode = [CARD, UPI_INTENT, UPI_COLLECT, UPI_QR]
"instrument": {
"type": "CREDIT_CARD",
"bankTransactionId": "<bankTransactionId>",
"bankId": "<bankId>",
"arn": "<arn>",
"brn": "<brn>"
}Instrument = “DEBIT_CARD”, When payment Mode = [CARD]
"instrument": {
"type": "DEBIT_CARD",
"bankTransactionId": "<bankTransactionId>",
"bankId": "<bankId>",
"arn": "<arn>",
"brn": "<brn>"
}Instrument = “NET_BANKING”, When payment Mode = [NET_BANKING]
"instrument": {
"type": "NET_BANKING",
"bankTransactionId": "<bankTransactionId>",
"bankId": "<bankId>",
"arn": "<arn>",
"brn": "<brn>"
}Try it yourself!
headers
url params
What’s Next?
After checking the status of an order, you may need to handle post-payment actions like issuing a refund for failed, cancelled, or customer-returned transactions.
Head over to the next section to learn how to process cancel.
