Check Order Status

Use this API to poll or verify the current, comprehensive status of an OTM order by passing your merchantOrderId. This will return order-level details as well as the underlying transaction states.

API Endpoint

Environment	HTTP Method	API
`Sandbox`	`GET`	https://api-preprod.phonepe.com/apis/pg-sandbox/payments/v2/order/{merchantOrderId}/status
`Production`	`GET`	https://api.phonepe.com/apis/pg/payments/v2/order/{merchantOrderId}/status

Request

Request Header

Header Name	Header Value
`Content-Type`	application/x-www-form-urlencoded
`Authorization`	O-Bearer <merchant-auth-token>

Path Parameter

Parameter	`Type`	`Required`	Description
`merchantOrderId`	String	Yes	The merchant order ID used in the pay call

Query Parameter

Parameter	`Type`	`Default`	Description
`details`	boolean	false	If `true`, returns all transaction-level payment details
`settlementDetails`	boolean	false	If `true`, includes settlement information
`errorContext`	boolean	false	If `true`, includes detailed error context

Response

Sample Response

{
  "merchantId": "M_001",
  "merchantOrderId": "ORDER_123456",
  "orderId": "OMO2506...",
  "state": "PENDING",
  "currency": "INR",
  "amount": 10000,
  "expireAt": 1750000000000,
  "paymentDetails": [
    {
      "transactionId": "OMT2506...",
      "paymentMode": "UPI_INTENT",
      "state": "AUTHORIZED",
      "amount": 0,
      "currency": "INR",
      "authAmount": 10000,
      "authCurrency": "INR",
      "timestamp": 1749999000000,
      "instrument": {
        "type": "ACCOUNT",
        "processingRail": "UPI"
      },
      "rail": {
        "type": "UPI"
      }
    }
  ]
}

Sample Status Response Payloads by OTM State

When Transaction is `AUTHORIZATION_IN_PROGRESS`

Pay API has been called, user has not yet authorized on UPI app.

{
  "merchantId": "M_001",
  "merchantOrderId": "ORDER_123456",
  "orderId": "OMO2506...",
  "state": "PENDING",
  "currency": "INR",
  "amount": 10000,
  "expireAt": 1750000000000,
  "paymentDetails": [
    {
      "transactionId": "OMT2506...",
      "paymentMode": "UPI_INTENT",
      "state": "AUTHORIZATION_IN_PROGRESS",
      "amount": 0,
      "currency": "INR",
      "authAmount": 10000,
      "authCurrency": "INR",
      "payableCurrency": "INR",
      "payableAmount": 0,
      "feeCurrency": "INR",
      "feeAmount": 0,
      "timestamp": 1749999000000,
      "instrument": {
        "type": "ACCOUNT",
        "processingRail": "UPI"
      },
      "rail": {
        "type": "UPI"
      }
    }
  ]
}

When Transaction is `AUTHORIZED`

User has authorized the mandate on UPI app. Capture or Cancel can now be called.

{
  "merchantId": "M_001",
  "merchantOrderId": "ORDER_123456",
  "orderId": "OMO2506...",
  "state": "PENDING",
  "currency": "INR",
  "amount": 10000,
  "expireAt": 1750000000000,
  "paymentDetails": [
    {
      "transactionId": "OMT2506...",
      "paymentMode": "UPI_INTENT",
      "state": "AUTHORIZED",
      "amount": 0,
      "currency": "INR",
      "authAmount": 10000,
      "authCurrency": "INR",
      "payableCurrency": "INR",
      "payableAmount": 0,
      "feeCurrency": "INR",
      "feeAmount": 0,
      "timestamp": 1749999000000,
      "instrument": {
        "type": "ACCOUNT",
        "processingRail": "UPI"
      },
      "rail": {
        "type": "UPI"
      }
    }
  ]
}

When Transaction is `CAPTURE_IN_PROGRESS`

Capture API has been called, capture is being processed.

{
  "merchantId": "M_001",
  "merchantOrderId": "ORDER_123456",
  "orderId": "OMO2506...",
  "state": "PENDING",
  "currency": "INR",
  "amount": 10000,
  "expireAt": 1750000000000,
  "paymentDetails": [
    {
      "transactionId": "OMT2506...",
      "paymentMode": "UPI_INTENT",
      "state": "CAPTURE_IN_PROGRESS",
      "amount": 8000,
      "currency": "INR",
      "authAmount": 10000,
      "authCurrency": "INR",
      "payableCurrency": "INR",
      "payableAmount": 8000,
      "feeCurrency": "INR",
      "feeAmount": 0,
      "timestamp": 1749999000000,
      "instrument": {
        "type": "ACCOUNT",
        "processingRail": "UPI"
      },
      "rail": {
        "type": "UPI"
      }
    }
  ]
}

Note: In this example, the merchant authorized 10000 paise but captured only 8000 paise (partial capture).

When Transaction is `COMPLETED`

Capture was successful. Payment is complete.

{
  "merchantId": "M_001",
  "merchantOrderId": "ORDER_123456",
  "orderId": "OMO2506...",
  "state": "COMPLETED",
  "currency": "INR",
  "amount": 10000,
  "payableCurrency": "INR",
  "payableAmount": 8000,
  "feeCurrency": "INR",
  "feeAmount": 0,
  "discountAmount": 0,
  "expireAt": 1750000000000,
  "paymentDetails": [
    {
      "transactionId": "OMT2506...",
      "paymentMode": "UPI_INTENT",
      "state": "COMPLETED",
      "amount": 8000,
      "currency": "INR",
      "authAmount": 10000,
      "authCurrency": "INR",
      "payableCurrency": "INR",
      "payableAmount": 8000,
      "feeCurrency": "INR",
      "feeAmount": 0,
      "discountAmount": 0,
      "timestamp": 1749999000000,
      "instrument": {
        "type": "ACCOUNT",
        "processingRail": "UPI"
      },
      "rail": {
        "type": "UPI"
      }
    }
  ]
}

When Transaction is `CANCEL_IN_PROGRESS`

Cancel API has been called, cancellation is being processed.

{
  "merchantId": "M_001",
  "merchantOrderId": "ORDER_123456",
  "orderId": "OMO2506...",
  "state": "PENDING",
  "currency": "INR",
  "amount": 10000,
  "expireAt": 1750000000000,
  "paymentDetails": [
    {
      "transactionId": "OMT2506...",
      "paymentMode": "UPI_INTENT",
      "state": "CANCEL_IN_PROGRESS",
      "amount": 0,
      "currency": "INR",
      "authAmount": 10000,
      "authCurrency": "INR",
      "payableCurrency": "INR",
      "payableAmount": 0,
      "feeCurrency": "INR",
      "feeAmount": 0,
      "timestamp": 1749999000000,
      "instrument": {
        "type": "ACCOUNT",
        "processingRail": "UPI"
      },
      "rail": {
        "type": "UPI"
      }
    }
  ]
}

After Cancellation Completes

Cancellation was successful. The transaction moves to FAILED and the order is CANCELLED (externally mapped to FAILED).

{
  "merchantId": "M_001",
  "merchantOrderId": "ORDER_123456",
  "orderId": "OMO2506...",
  "state": "FAILED",
  "currency": "INR",
  "amount": 10000,
  "expireAt": 1750000000000,
  "errorCode": "PAYMENT_CANCELLED",
  "detailedErrorCode": "REQUEST_CANCEL_BY_REQUESTER",
  "paymentDetails": [
    {
      "transactionId": "OMT2506...",
      "paymentMode": "UPI_INTENT",
      "state": "FAILED",
      "amount": 0,
      "currency": "INR",
      "authAmount": 10000,
      "authCurrency": "INR",
      "payableCurrency": "INR",
      "payableAmount": 0,
      "feeCurrency": "INR",
      "feeAmount": 0,
      "errorCode": "PAYMENT_CANCELLED",
      "detailedErrorCode": "REQUEST_CANCEL_BY_REQUESTER",
      "timestamp": 1749999000000,
      "instrument": {
        "type": "ACCOUNT",
        "processingRail": "UPI"
      },
      "rail": {
        "type": "UPI"
      }
    }
  ]
}

Note: A successful cancellation results in order state FAILED with error code PAYMENT_CANCELLED. This is the expected terminal state for cancelled OTM authorizations.

When Authorization Fails

User did not authorize, or authorization timed out.

{
  "merchantId": "M_001",
  "merchantOrderId": "ORDER_123456",
  "orderId": "OMO2506...",
  "state": "FAILED",
  "currency": "INR",
  "amount": 10000,
  "expireAt": 1750000000000,
  "errorCode": "TIMED_OUT",
  "detailedErrorCode": "MANDATE_EXPIRED",
  "paymentDetails": [
    {
      "transactionId": "OMT2506...",
      "paymentMode": "UPI_INTENT",
      "state": "FAILED",
      "amount": 0,
      "currency": "INR",
      "authAmount": 10000,
      "authCurrency": "INR",
      "payableCurrency": "INR",
      "payableAmount": 0,
      "feeCurrency": "INR",
      "feeAmount": 0,
      "errorCode": "TIMED_OUT",
      "detailedErrorCode": "MANDATE_EXPIRED",
      "timestamp": 1749999000000,
      "instrument": {
        "type": "ACCOUNT",
        "processingRail": "UPI"
      },
      "rail": {
        "type": "UPI"
      }
    }
  ]
}

When Capture Fails

Capture was initiated but failed at the UPI provider.

{
  "merchantId": "M_001",
  "merchantOrderId": "ORDER_123456",
  "orderId": "OMO2506...",
  "state": "FAILED",
  "currency": "INR",
  "amount": 10000,
  "expireAt": 1750000000000,
  "errorCode": "TIMED_OUT",
  "detailedErrorCode": "MANDATE_EXPIRED",
  "paymentDetails": [
    {
      "transactionId": "OMT2506...",
      "paymentMode": "UPI_INTENT",
      "state": "FAILED",
      "amount": 8000,
      "currency": "INR",
      "authAmount": 10000,
      "authCurrency": "INR",
      "payableCurrency": "INR",
      "payableAmount": 8000,
      "feeCurrency": "INR",
      "feeAmount": 0,
      "errorCode": "TIMED_OUT",
      "detailedErrorCode": "MANDATE_EXPIRED",
      "timestamp": 1749999000000,
      "instrument": {
        "type": "ACCOUNT",
        "processingRail": "UPI"
      },
      "rail": {
        "type": "UPI"
      }
    }
  ]