This API elaborates on how you can check the Order Status of the payment.
Note : It is recommended to rely on Server to server callback response, if not received then you can start calling the Order status API
Order Status API
This API is used to check the payment status:
Host Details
Environment | Http Method | Value |
---|---|---|
UAT | GET | https://api-preprod.phonepe.com/apis/pg-sandbox |
PROD | GET | https://api.phonepe.com/apis/pg |
Endpoint
/checkout/v2/order/{merchantOrderId}/status – Endpoint is common for UAT and Production.
Complete Host Details
Environment | Http Method | Value |
---|---|---|
UAT | GET | https://api-preprod.phonepe.com/apis/pg-sandbox/checkout/v2/order/{merchantOrderId}/status |
PROD | GET | https://api.phonepe.com/apis/pg/checkout/v2/order/{merchantOrderId}/status |
Request Details
Request Headers
Header Name | Header Value |
---|---|
Content-Type | application/json |
Authorization | O-Bearer <access_token> |
Header details :
- Content-Type – Its value should be always application/json, meaning this API responds to only when content is in format of application/json
- Authorization – This should be the auth token that you have received from the Auth API.
Query Parameters
Sample EndPoint Detials with Query Parameters:
/checkout/v2/order/{merchantOrderId}/status?details=false&errorContext=true
- Endpoint is common for UAT and Production.
- These query parameters are Optional.
- default value for details and errorContext is False.
Name | Description |
---|---|
details | true → return all attempt details under paymentDetails list false → return only latest attempt details under paymentDetails list |
errorContext | true → To receive the errorContext block with error details if the state is FAILED. false → If the errorContext block is not required. |
Query the API with above details using HTTP GET method, below is the sample CURL for the same:
curl --location 'https://api-preprod.phonepe.com/apis/pg-sandbox/checkout/v2/order/TX123rrty34432456/status?details=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: O-Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHBpcmVzT24iOjE3MTIyNTM2MjU2NDQsIm1lcmNoYW50SWQiOiJWMlNVQlVBVCJ9.7aVzYI_f_77-bBicEcRNuYx093b2wCsgl_WFNkKqAPY'
Sample response of the above CURL :
Note: Merchants should rely only on the highlighted “state” parameter for the payment status confirmation.
{
"orderId": "OMO2403282020198641071317",
"state": "COMPLETED",
"amount": 1000,
"expireAt": 1711867462542,
"paymentDetails": [
{
"paymentMode": "UPI_QR",
"transactionId": "OM2403282020198651071949",
"timestamp": 1711694662542,
"amount": 1000,
"state": "COMPLETED",
"rail": {
"type": "UPI",
"utr": "<utr>",
"upiTransactionId": "<upiTransactionId>",
"vpa": "<vpa>"
},
"instrument": {
"type": "ACCOUNT",
"maskedAccountNumber": "<maskedAccountNumber>",
"accountType": "SAVINGS",
"accountHolderName": "<accountHolderName>"
}
}
]
}
Response Details
Response Headers:
Header Name | Header Value |
---|---|
Content-Type | application/json |
Response Payload:
Case 1: Order is completed and details = true
Http Response Code: 200
Note: Merchants should rely only on the highlighted “state” parameter for the Payment status confirmation.
{
"orderId": "OMO2407021511185686967711",
"state": "COMPLETED",
"amount": 1000,
"payableAmount": 1000,
"feeAmount": 0,
"expireAt": 1719913878566,
"metaInfo": {
"udf1": "",
"udf2": "",
"udf3": "",
"udf4": "",
"udf5": ""
},
"paymentDetails": [
{
"transactionId": "OM2407021515097451914211",
"paymentMode": "UPI_INTENT",
"timestamp": 1719913509762,
"amount": 1000,
"payableAmount": 1000,
"feeAmount": 0,
"state": "COMPLETED",
"rail": {
"type": "UPI",
"upiTransactionId": "upi12313",
"vpa": "abcd@ybl"
},
"instrument": {
"type": "ACCOUNT",
"maskedAccountNumber": "XXXXXX5533",
"accountType": "SAVINGS"
},
"splitInstruments": [
{
"instrument": {
"type": "ACCOUNT",
"maskedAccountNumber": "XXXXXX5533",
"accountType": "SAVINGS"
},
"rail": {
"type": "UPI",
"utr": "455069731511",
"upiTransactionId": "YBL369f6d962de74c2680789bff8c11aec9",
"vpa": "abcd@ybl"
},
"amount": 1000
}
]
}
]
}
Case : PPE_INTENT split payment case.
Note: Merchants should rely only on the highlighted “state” parameter for the Payment status confirmation.
{
"orderId": "OMO2407111823257502858511",
"state": "COMPLETED",
"amount": 200,
"payableAmount": 200,
"feeAmount": 0,
"expireAt": 1720703005748,
"metaInfo": {
"udf1": "",
"udf2": "",
"udf3": "",
"udf4": "",
"udf5": ""
},
"paymentDetails": [
{
"transactionId": "OM2407111823340281302812",
"paymentMode": "UPI_INTENT",
"timestamp": 1720702414053,
"amount": 200,
"payableAmount": 200,
"feeAmount": 0,
"state": "COMPLETED",
"splitInstruments": [
{
"instrument": {
"type": "ACCOUNT",
"maskedAccountNumber": "XXXXXX6862",
"accountType": "SAVINGS"
},
"rail": {
"type": "UPI",
"utr": "455948340054",
"upiTransactionId": "YBLec33d3d277264fd8ac5deeabfece2494",
"vpa": "abcd@ybl"
},
"amount": 100
},
{
"instrument": {
"type": "WALLET"
},
"rail": {
"type": "PPI_WALLET"
},
"amount": 100
}
]
}
]
}
Case 2: No payment attempt is made for order
Note: Merchants should rely only on the highlighted “state” parameter for the Payment status confirmation.
{
"orderId": "OMO2407111821482103732111",
"state": "PENDING",
"amount": 100,
"expireAt": 1720702908208,
"metaInfo": {
"udf1": "<additional-information-1>",
"udf2": "<additional-information-2>",
"udf3": "<additional-information-3>",
"udf4": "<additional-information-4>",
"udf5": "<additional-information-5>"
},
"paymentDetails": []
}
Case 3: Order is Failed
Note: Merchants should rely only on the highlighted “state” parameter for the Payment status confirmation.
{
"orderId": "OMO2407121214395503786511",
"state": "FAILED",
"amount": 200,
"expireAt": 1720767279548,
"errorCode": "INVALID_MPIN",
"detailedErrorCode": "ZM",
"metaInfo": {
"udf1": "<additional-information-1>",
"udf2": "<additional-information-2>",
"udf3": "<additional-information-3>",
"udf4": "<additional-information-4>",
"udf5": "<additional-information-5>"
},
"paymentDetails": [
{
"transactionId": "OM2407121214579231302711",
"paymentMode": "UPI_COLLECT",
"timestamp": 1720766697944,
"amount": 200,
"payableAmount": 200,
"feeAmount": 0,
"state": "FAILED",
"errorCode": "INVALID_MPIN",
"detailedErrorCode": "ZM"
}
],
"errorContext": {
"errorCode" : "INVALID_MPIN",
"detailedErrorCode" : "ZM",
"source" : "CUSTOMER",
"stage" : "AUTHENTICATION",
"description" : "Wrong MPIN was entered"
}
}
Case 4: Invalid order ID
{
"success": false,
"code": "MERCHANT_ORDER_MAPPING_NOT_FOUND",
"message": "No entry found for <Merchant Order Id>",
"data": {}
}
Response Field Details:
Header Name | Data Type | Description |
---|---|---|
orderId | String | PG generated internal order id |
state | String | State of order, Expected Values = [PENDING, FAILED, COMPLETED] Note: Merchants should rely only on the “state” parameter for the Payment status confirmation. |
amount | String | Order amount in paisa |
expireAt | Long | order expiry time in epoch (in milliseconds) |
metaInfo | Object | Merchant defined meta info passed at the time of order creation |
paymentDetails | List | Contain list of details of each payment attempt made corresponding to this order. |
paymentDetails.paymentMode | String | Mode of payment. Expected Values = [UPI_INTENT, UPI_COLLECT, UPI_QR, CARD, TOKEN, NET_BANKING] |
paymentDetails.timestamp | Long | Transaction attempt timestamp in epoch (in milliseconds) |
paymentDetails.amount | Long | Amount in paisa, corresponding to payment attempt |
paymentDetails.transactionId | String | internal transaction id for given payment attempt |
paymentDetails.state | String | Transaction attempt state. Expected Values = [PENDING, COMPLETED, FAILED] |
paymentDetails.errorCode | String | Error code (Only present when transaction state is failed) |
paymentDetails.detailedErrorCode | String | Detailed Error Code (Only present when transaction state is failed) |
paymentDetails.rail | String | Contains processing rail details under which payment attempt is made. |
paymentDetails.rail.type | String | Type of rail. Expected values = [UPI, PG] |
paymentDetails.instrument | String | Contains instrument details |
paymentDetails.instrument.type | String | Type of payment instrument. Expected values = [ACCOUNT,CREDIT_CARD, DEBIT_CARD,NET_BANKING] |