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

EnvironmentHttp MethodValue
UATGEThttps://api-preprod.phonepe.com/apis/pg-sandbox
PRODGEThttps://api.phonepe.com/apis/pg

Endpoint

/checkout/v2/order/{merchantOrderId}/status – Endpoint is common for UAT and Production.

Complete Host Details

EnvironmentHttp MethodValue
UATGEThttps://api-preprod.phonepe.com/apis/pg-sandbox/checkout/v2/order/{merchantOrderId}/status
PRODGEThttps://api.phonepe.com/apis/pg/checkout/v2/order/{merchantOrderId}/status

Request Details

Request Headers

Header NameHeader Value
Content-Typeapplication/json
AuthorizationO-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.
NameDescription
detailstrue → return all attempt details under paymentDetails list
false → return only latest attempt details under paymentDetails list
errorContexttrue → 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 NameHeader Value
Content-Typeapplication/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 NameData TypeDescription
orderIdStringPG generated internal order id
stateStringState of order, Expected Values = [PENDING, FAILED, COMPLETED]
Note: Merchants should rely only on the “state” parameter for the Payment status confirmation.
amountStringOrder amount in paisa
expireAtLongorder expiry time in epoch (in milliseconds)
metaInfoObjectMerchant defined meta info passed at the time of order creation
paymentDetailsListContain list of details of each payment attempt made corresponding to this order.
paymentDetails.paymentModeStringMode of payment. Expected Values = [UPI_INTENT, UPI_COLLECT, UPI_QR, CARD, TOKEN, NET_BANKING]
paymentDetails.timestampLongTransaction attempt timestamp in epoch (in milliseconds)
paymentDetails.amountLongAmount in paisa, corresponding to payment attempt
paymentDetails.transactionIdStringinternal transaction id for given payment attempt
paymentDetails.stateStringTransaction attempt state. Expected Values = [PENDING, COMPLETED, FAILED]
paymentDetails.errorCodeStringError code (Only present when transaction state is failed)
paymentDetails.detailedErrorCodeStringDetailed Error Code (Only present when transaction state is failed)
paymentDetails.railStringContains processing rail details under which payment attempt is made.
paymentDetails.rail.typeStringType of rail. Expected values = [UPI, PG]
paymentDetails.instrumentStringContains instrument details
paymentDetails.instrument.typeStringType of payment instrument. Expected values = [ACCOUNT,CREDIT_CARD, DEBIT_CARD,NET_BANKING]