Order Status

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]