Order Status with SplitInfo
The Order Status API lets you fetch the status of a payment using the merchant order ID. It confirms whether a payment is pending, completed, or failed.
You will receive key details like transaction info, settlement state, and split settlement data. If the order fails, error codes and context are included for better debugging. Use the state field in the response to determine the final payment status. This helps you handle success, failure, and settlement scenarios effectively.
Environment
| Environment | Http Method | Value |
|---|---|---|
Sandbox | GET | https://api-preprod.phonepe.com/apis/pg-sandbox/checkout/v2/order/{merchantOrderId}/status |
Production | GET | https://api.phonepe.com/apis/pg/checkout/v2/order/{merchantOrderId}/status |
Request
Request Headers
| Header Name | Header Value |
| Content-Type | application/json |
| Authorization | O-Bearer <partner-auth-token> |
| X-MERCHANT-ID | MID |
Path Parameters
| Header Name | Description |
|---|---|
merchantOrderId | The merchant generated Order Id |
Query Parameters for Order Status API
API with query parameter
/checkout/v2/order/{merchantOrderId}/status?details=false&errorContext=true| 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. |
Response
Response Headers:
| Header Name | Header Value |
|---|---|
Content-Type | application/json |
Case 1: The order is completed, but the settlement to the merchant and the associated split is still pending.
{
"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
}
]
}
],
// below splitSettlementInfo block will only come if order split information is given.
"splitSettlementInfo":
{
"type": "ABSOLUTE",
"accountSplit":
[
{
"value": 400,
"accountId": "ACC12345"
},
{
"value": 510,
"accountId": "ACC6789"
}
],
"state": "PENDING"
},
"settlementDetails":
{
"state": "NOT_INITIATED"
},
// below errorContext block will only come if order is in failed state and queryParam is passed as "errorContext=true"
"errorContext":
{
"errorCode": "INVALID_MPIN",
"detailedErrorCode": "ZM",
"source": "CUSTOMER",
"stage": "AUTHENTICATION",
"description": "Wrong MPIN was entered"
}
Case 2: The order is completed, and the settlement to the merchant along with the split settlement information is accepted.
{
"orderId": "OMO2506191600147346181268",
"state": "COMPLETED",
"amount": 47900,
"payableAmount": 47900,
"feeAmount": 0,
"expireAt": 1750329614682,
"metaInfo": {
"udf1": "<additional-information-1>",
"udf2": "<additional-information-2>",
"udf3": "<additional-information-3>",
"udf4": "<additional-information-4>"
},
"paymentDetails": [
{
"transactionId": "OM2506191600148276181057",
"paymentMode": "UPI_INTENT",
"timestamp": 1750329014929,
"amount": 47900,
"payableAmount": 47900,
"feeAmount": 0,
"state": "COMPLETED",
"instrument": {
"type": "ACCOUNT",
"maskedAccountNumber": "XXXXXXX20000",
"ifsc": "AABC0876543",
"accountHolderName": "Venkat",
"accountType": "SAVINGS"
},
"rail": {
"type": "UPI",
"utr": "517045000220",
"upiTransactionId": "YBL5d23003235214cfa9550c8ecbd7aecdb"
},
"splitInstruments": [
{
"instrument": {
"type": "ACCOUNT",
"maskedAccountNumber": "XXXXXXX20000",
"ifsc": "AABC0876543",
"accountHolderName": "Venkat",
"accountType": "SAVINGS"
},
"rail": {
"type": "UPI",
"utr": "517045000220",
"upiTransactionId": "YBL5d23003235214cfa9550c8ecbd7aecdb"
},
"amount": 47900
}
]
}
],
"splitSettlementInfo": {
"type": "ABSOLUTE",
"accountsSplit": [
{
"accountId": "A2506101204484257980786",
"value": 19160.00
},
{
"accountId": "A2506101203231037980769",
"value": 19160.00
}
],
"state": "ACCEPTED"
},
"settlementDetails": {
"state": "PROCESSED",
"splitSettlementDetails": [
{
"type": "UPI",
"settlementId": "3630e239-1f1b-4bed-bf02-e1015868c092",
"utr": "string",
"timestamp": 1750354845203,
"amountBreakup": {
"transactionAmount": 47900,
"settlementAmount": 47150,
"settlementDeduction": {
"sgst": -57,
"cgst": -57,
"igst": 0,
"fee": -635,
"commission": 0
}
}
}
],
"accountsSettlementDetails": [
{
"accountType": "PRIMARY",
"settlementId": "3630e239-1f1b-4bed-bf02-e1015868c092",
"utr": "string",
"timestamp": 1750354845203,
"amountBreakup": {
"totalAmount": 9580,
"settlementAmount": 8830,
"transactionFee": {
"sgst": -57,
"cgst": -57,
"igst": 0,
"fee": -635,
"commission": 0
},
"splitSettlementFee": {
"sgst": 0,
"cgst": 0,
"igst": 0,
"fee": 0,
"commission": 0
},
"totalFee": {
"sgst": -57,
"cgst": -57,
"igst": 0,
"fee": -635,
"commission": 0
}
}
},
{
"accountType": "SELF",
"accountId": "A2506101204484257980786",
"settlementId": "7ca097b1-0443-4fa7-bbae-edd2ff313d10",
"utr": "string",
"timestamp": 1750356504764,
"amountBreakup": {
"totalAmount": 19160,
"settlementAmount": 19160,
"transactionFee": {
"sgst": 0,
"cgst": 0,
"igst": 0,
"fee": 0,
"commission": 0
},
"splitSettlementFee": {
"sgst": 0,
"cgst": 0,
"igst": 0,
"fee": 0,
"commission": 0
},
"totalFee": {
"sgst": 0,
"cgst": 0,
"igst": 0,
"fee": 0,
"commission": 0
}
}
},
{
"accountType": "SELF",
"accountId": "A2506101203231037980769",
"settlementId": "6b329fbf-7f37-4510-9f1b-76532745fd00",
"utr": "string",
"timestamp": 1750356422911,
"amountBreakup": {
"totalAmount": 19160,
"settlementAmount": 19160,
"transactionFee": {
"sgst": 0,
"cgst": 0,
"igst": 0,
"fee": 0,
"commission": 0
},
"splitSettlementFee": {
"sgst": 0,
"cgst": 0,
"igst": 0,
"fee": 0,
"commission": 0
},
"totalFee": {
"sgst": 0,
"cgst": 0,
"igst": 0,
"fee": 0,
"commission": 0
}
}
}
]
}
}Case 3: Order is completed, merchant settlement is successful, but split settlement has failed.
{
"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
}
]
}
],
// below splitSettlementInfo block will only come if order split information is given.
"splitSettlementInfo":
{
"type": "ABSOLUTE",
"accountSplit":
[
{
"value": 400,
"accountId": "ACC12345"
},
{
"value": 510,
"accountId": "ACC6789"
}
],
"state": "FAILED"
},
"settlementDetails":
{
"state": "PROCESSED",
"splitSettlementDetails":
[
{
"type": "UPI",
"settlementId": "93de5fff-fb18-4be6-ac8a-df5da3b55596",
"utr": "UTR100298",
"timestamp": 1723050625221,
"amountBreakup":
{
"transactionAmount": 10000,
"settlementAmount": 9998,
"settlementDeduction":
{
"sgst": 0,
"cgst": 0,
"igst": 0,
"fee": -2,
"commission": 0
}
}
}
]
},
// below errorContext block will only come if order is in failed state and queryParam is passed as "errorContext=true"
"errorContext":
{
"errorCode": "INVALID_MPIN",
"detailedErrorCode": "ZM",
"source": "CUSTOMER",
"stage": "AUTHENTICATION",
"description": "Wrong MPIN was entered"
}
}Response Field Details:
| Header Name | Data Type | Description |
|---|---|---|
orderId | String | PG generated internal order ID |
state | String | Indicates the current status of the order. Possible values: • PENDING • FAILED • COMPLETED Note: Always rely on the state field to determine the final status of the payment. |
amount | String | Order amount specified in paisa. |
expireAt | Long | Order expiry time represented in epoch (in milliseconds). |
metaInfo | Object | metadata provided by the merchant during order creation. |
paymentDetails | List | Contains a list of details for each payment attempt made for the order. |
paymentDetails.paymentMode | String | Specifies the mode of payment used. Expected values include: • UPI_INTENT • UPI_COLLECT • UPI_QR • CARD • TOKEN • NET_BANKING. |
paymentDetails.timestamp | Long | The time at which the transaction attempt was made, represented in epoch (in milliseconds). |
paymentDetails.amount | Long | The amount, in paisa, associated with the specific payment attempt. |
paymentDetails.transactionId | String | The internal transaction ID associated with the specific payment attempt. |
paymentDetails.state | String | The current state of the payment attempt. Expected values: • PENDING • COMPLETED • FAILED. |
paymentDetails.errorCode | String | Code that indicates the reason for failure. Available only if the transaction state is FAILED. |
paymentDetails.detailedErrorCode | String | Provides additional information about the failure reason. This is available only when the transaction state is FAILED. |
paymentDetails.rail | String | Includes details of the processing rail used for the payment attempt. |
paymentDetails.rail.type | String | Specifies the type of processing rail used for the transaction. Expected values: • UP • PG |
paymentDetails.instrument | String | Includes details of the payment instrument used for the transaction. |
paymentDetails.instrument.type | String | Specifies the type of payment instrument used. Expected values include: • ACCOUNT • CREDIT_CARD • DEBIT_CARD • NET_BANKING |
| Object | Provides details about how the order amount is divided between different accounts. |
| String | Defines how the amount should be split between accounts. Expected values: • PERCENT • ABSOLUTE |
| String | Account ID provided by the merchant for reference during split settlement. |
| String | Status of the split, indicating whether it is accepted or failed. |