Check Status API

This API is used for checking the status of an existing transaction.

šŸ‘

S2S and Check Status API Handling

  • Once the customer is redirected back to the merchant website/app, merchants should check with their server if they have received the Server-to-Server Callback response. If not, it is mandatory to make a Transaction Status API check with PhonePe backend systems to know the actual status of the payment and, then accordingly process the result.

  • The payment status can be Success, Failed or Pending. When Pending, merchants should retry until the status changes to Success or Failed.

šŸ“˜

Check Status API - Reconciliation [MANDATORY]

If the payment status is Pending, then Check Status API should be called in the following interval:
The first status check at 20-25 seconds post transaction start, then
Every 3 seconds once for the next 30 seconds,
Every 6 seconds once for the next 60 seconds,
Every 10 seconds for the next 60 seconds,
Every 30 seconds for the next 60 seconds, and then
Every 1 min until timeout (15 mins).

Request Headers

Header NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256("/pg/v1/status/{merchantId}/{transactionId}" + saltKey) + "###" + saltIndex
X-MERCHANT-IDUnique Merchant ID assigned to the merchant by PhonePe

Path Parameters

Parameter NameTypeDescriptionMandatory
merchantIdSTRINGUnique Merchant ID assigned to the merchant by PhonePeYes
transactionIdSTRINGMerchant transactionID for which status is to be fetchedYes

Sample Response

{
  "success": true,
  "code": "PAYMENT_SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "FKRT",
    "merchantTransactionId": "MT7850590068188104",
    "transactionId": "T2111221437456190170379",
    "amount": 100,
    "paymentState": "COMPLETED",
    "payResponseCode": "PAYMENT_SUCCESS",
    "paymentInstrument": {
      "type": "UPI",
      "utr": "206378866112"
    }
  }
}
{
  "success": true,
  "code": "PAYMENT_SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "FKRT",
    "merchantTransactionId": "MT7850590068188104",
    "transactionId": "T2111221437456190170379",
    "amount": 100,
    "paymentState": "COMPLETED",
    "payResponseCode": "PAYMENT_SUCCESS",
    "paymentInstrument": {
      "type": "CARD",
      "cardType": "DEBIT_CARD",
      "pgTransactionId": "b9090242ac120002",
      "bankTransactionId": "e57a658e9e1011ec",
      "pgAuthorizationCode": "9cf3ef4932bf9e05",
      "arn": "339482773927",
      "bankId": "SBIN"
    }
  }
}
{
  "success": true,
  "code": "PAYMENT_SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "FKRT",
    "merchantTransactionId": "MT7850590068188104",
    "transactionId": "T2206202020325589144911",
    "amount": 100,
    "state": "COMPLETED",
    "responseCode": "PAYMENT_SUCCESS",
    "paymentInstrument": {
      "type": "NET_BANKING",
      "pgTransactionId": "1856982900",
      "pgServiceTransactionId": "PG2207281811271263274380",
      "bankTransactionId": null,
      "bankId": "SBIN"
    }
  }
}
{
    "success": false,
    "code": "INTERNAL_SERVER_ERROR",
    "message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}

Response Parameters

Parameter NameTypeDescriptionMandatory
successBOOLEANA boolean to indicate the success/failure of the request.Yes
codeENUMResponse code explaining reason for status.
For status SUCCESS, only one possible response code is present - PAYMENT_SUCCESS
For status FAILURE, following response codes are possible:
ā— BAD_REQUEST
ā— AUTHORIZATION_FAILED
ā— INTERNAL_SERVER_ERROR
ā— TRANSACTION_NOT_FOUND
ā— PAYMENT_ERROR
ā— PAYMENT_PENDING
ā— PAYMENT_DECLINED
ā— TIMED_OUT
Yes
messageSTRINGMessage giving more information about the code.Yes
merchantIdSTRINGUnique Merchant ID assigned to the merchant by PhonePeYes
merchantTransactionIdSTRINGUnique Transaction ID generated by the merchant to track this request to PhonePeYes
transactionIdSTRINGTransaction id generated by PhonePe

Note: The Value will be present only if the actual transaction happened.
No
amountLONGTransaction amount in paiseYes
stateSTRINGCurrent state of the transactionYes
responseCodeSTRINGMeta data of state. This is an informative value.

Note: The Value will be present only if the actual transaction happened.
No
paymentInstrumentOBJECTPayment instrument with which payment was done

Note: The Value will be present only if the actual transaction happened.
No

Error Codes

CodeDescription
BAD_REQUESTInvalid request
AUTHORIZATION_FAILEDX-VERIFY header is incorrect
INTERNAL_SERVER_ERRORSomething went wrong. It does not indicate failed payment. The merchant needs to call Check Status API to verify the transaction status.
PAYMENT_SUCCESSPayment is successful
PAYMENT_ERRORPayment failed
TRANSACTION_NOT_FOUNDThe transaction id is incorrect
PAYMENT_PENDINGPayment is pending. It does not indicate success/failed payment. The merchant needs to call Check Status API to verify the transaction status.
PAYMENT_DECLINEDPayment declined by user
TIMED_OUTThe payment failed due to the timeout.
Language
Click Try It! to start a request and see the response here!