Check Status API

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

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](ref:server-to-server-callback-4) 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

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 (20 mins).

Request Headers

Header Name	Header Value
`Content-Type`	application/json
`X-VERIFY`	SHA256(“/pg/v1/status/{merchantId}/{merchantTransactionId}” + saltKey) + “###” + saltIndex
`X-MERCHANT-ID`	Unique Merchant ID assigned to the merchant by PhonePe

Path Parameters

Parameter Name	Type	Description	Mandatory
`merchantId`	`STRING`	Unique Merchant ID assigned to the merchant by PhonePe	`Yes`
`merchantTransactionId`	`STRING`	Merchant transaction Id for which status is to be fetched	`Yes`

Sample Response

Note: Not to have strict deserialization in the Check Status or Webhook response. If any unknown fields are received within the response, merchants should ignore.

{
  "success": true,
  "code": "PAYMENT_SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "PGTESTPAYUAT",
    "merchantTransactionId": "MT7850590068188104",
    "transactionId": "T2111221437456190170379",
    "amount": 100,
    "state": "COMPLETED",
    "responseCode": "SUCCESS",
    "paymentInstrument": {
      "type": "UPI",
      "utr": "206378866112"
    }
  }
}

{
  "success": true,
  "code": "PAYMENT_SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "PGTESTPAYUAT",
    "merchantTransactionId": "MT7850590068188104",
    "transactionId": "T2111221437456190170379",
    "amount": 100,
    "state": "COMPLETED",
    "responseCode": "SUCCESS",
    "paymentInstrument": {
      "type": "CARD",
      "cardType": "DEBIT_CARD",
      "pgTransactionId": "pay_NL1BzXXXXXXX",
      "bankTransactionId": "d66n586eXXXXXXX",
      "pgAuthorizationCode": "62XXXXX",
      "arn": "78637687302027XXXXXXX",
      "bankId": "SBIN",
      "brn": "400523XXXXXXX"
    }
  }
}

{
  "success": true,
  "code": "PAYMENT_SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "PGTESTPAYUAT",
    "merchantTransactionId": "MT7850590068188104",
    "transactionId": "T2206202020325589144911",
    "amount": 100,
    "state": "COMPLETED",
    "responseCode": "SUCCESS",
    "paymentInstrument": {
      "type": "NETBANKING",
      "pgTransactionId": "1856982900",
      "pgServiceTransactionId": "PG2207281811271263274380",
      "bankTransactionId": null,
      "bankId": "SBIN"
    }
  }
}

{
  "success": false,
  "code": "PAYMENT_ERROR",
  "message": "Payment Failed",
  "data": {
    "merchantId": "PGTESTPAYUAT",
    "merchantTransactionId": "MT7850590068188104",
    "transactionId": "T2111221437456190170379",
    "amount": 100,
    "state": "FAILED",
    "responseCode": "ZM",
    "responseCodeDescription": "Invalid m-pin entered",
    "paymentInstrument": null
  }
}

{
    "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 Name	Type	Description	Mandatory
`success`	`BOOLEAN`	A boolean value. Note: Irrespective of the value, the merchant should rely on the code parameter to update the status of the payment.	`Yes`
`code`	`ENUM`	Response 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`
`message`	`STRING`	Message giving more information about the code.	`Yes`
`merchantId`	`STRING`	Unique Merchant ID assigned to the merchant by PhonePe	`Yes`
`merchantTransactionId`	`STRING`	Unique Transaction ID generated by the merchant to track this request to PhonePe	`Yes`
`transactionId`	`STRING`	Transaction id generated by PhonePe Note: The Value will be present only if the actual transaction happened.	`No`
`amount`	`LONG`	Transaction amount in paise	`Yes`
`state`	`STRING`	Current state of the transaction	`Yes`
`responseCode`	`STRING`	PhonePe internal status code. Please note this is a string value and new codes are likely to be added in the future. (Please don’t do the marshaling/unmarshalling into an enum for this at your side). This is an informative value. Note: The Value will be present only if the actual transaction happened.	`Yes`
`responseCodeDescription`	`STRING`	Description of the responseCode ● Max Length – 256 ● Optional Parameter	`No`
`paymentInstrument`	`OBJECT`	Payment instrument with which payment was done Note: The Value will be present only if the actual transaction happened.	`No`

Error Codes

Code	Description
BAD_REQUEST	Invalid request
AUTHORIZATION_FAILED	X-VERIFY header is incorrect
INTERNAL_SERVER_ERROR	Something went wrong. It does not indicate failed payment. The merchant needs to call Check Status API to verify the transaction status.
PAYMENT_SUCCESS	Payment is successful
PAYMENT_ERROR	Payment failed
TRANSACTION_NOT_FOUND	The transaction id is incorrect
PAYMENT_PENDING	Payment is pending. It does not indicate success/failed payment. The merchant needs to call Check Status API to verify the transaction status.
PAYMENT_DECLINED	Payment declined by user
TIMED_OUT	The payment failed due to the timeout.

{“method”:”get”,”url”:”/pg/v1/status/{merchantId}/{merchantTransactionId}”,”auth”:”required”,”results”:{“codes”:[{“name”:”Sample Response – UPI”,”code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_SUCCESS\”,\n \”message\”: \”Your request has been successfully completed.\”,\n \”data\”: {\n \”merchantId\”: \”FKRT\”,\n \”merchantTransactionId\”: \”MT7850590068188104\”,\n \”transactionId\”: \”T2111221437456190170379\”,\n \”amount\”: 100,\n \”paymentState\”: \”COMPLETED\”,\n \”responseCode\”: \”PAYMENT_SUCCESS\”,\n \”paymentInstrument\”: {\n \”type\”: \”UPI\”,\n \”utr\”: \”206378866112\”\n }\n }\n}”,”language”:”json”,”status”:200},{“name”:””,”code”:”{\n \”success\”: false,\n \”code\”: \”INTERNAL_SERVER_ERROR\”,\n \”message\”: \”There is an error trying to process your transaction at the moment. Please try again in a while.\”\n}\n”,”language”:”json”,”status”:500},{“code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_SUCCESS\”,\n \”message\”: \”Your request has been successfully completed.\”,\n \”data\”: {\n \”merchantId\”: \”FKRT\”,\n \”merchantTransactionId\”: \”MT7850590068188104\”,\n \”transactionId\”: \”T2111221437456190170379\”,\n \”amount\”: 100,\n \”paymentState\”: \”COMPLETED\”,\n \”responseCode\”: \”PAYMENT_SUCCESS\”,\n \”paymentInstrument\”: {\n \”type\”: \”CARD\”,\n \”cardType\”: \”DEBIT_CARD\”,\n \”pgTransactionId\”: \”b9090242ac120002\”,\n \”bankTransactionId\”: \”e57a658e9e1011ec\”,\n \”pgAuthorizationCode\”: \”9cf3ef4932bf9e05\”,\n \”arn\”: \”339482773927\”,\n \”bankId\”: \”SBIN\”\n }\n }\n}”,”language”:”json”,”status”:200,”name”:”Sample Response – Card”},{“code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_SUCCESS\”,\n \”message\”: \”Your request has been successfully completed.\”,\n \”data\”: {\n \”merchantId\”: \”FKRT\”,\n \”merchantTransactionId\”: \”MT7850590068188104\”,\n \”transactionId\”: \”T2206202020325589144911\”,\n \”amount\”: 100,\n \”state\”: \”COMPLETED\”,\n \”responseCode\”: \”PAYMENT_SUCCESS\”,\n \”paymentInstrument\”: {\n \”type\”: \”NETBANKING\”,\n \”pgTransactionId\”: \”1856982900\”,\n \”pgServiceTransactionId\”: \”PG2207281811271263274380\”,\n \”bankTransactionId\”: null,\n \”bankId\”: \”SBIN\”\n }\n }\n}”,”language”:”json”,”status”:200,”name”:”Sample Response – NetBanking”}]},”params”:[{“name”:”merchantId”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”Unique Merchant ID assigned to the merchant by PhonePe”,”required”:false,”in”:”path”,”ref”:””,”_id”:”6203d352da832a0045a1183b”},{“name”:”merchantTransactionId”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”Merchant transaction id for which status is to be fetched”,”required”:false,”in”:”path”,”ref”:””,”_id”:”6203d352da832a0045a1183a”},{“name”:”Content-Type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”6203d352da832a0045a11839″},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”SHA256(\”/pg/v1/status/{merchantId}/{merchantTransactionId}\” + saltKey) + \”###\” + saltIndex”,”required”:true,”in”:”header”,”ref”:””,”_id”:”6203d352da832a0045a11838″},{“name”:”X-MERCHANT-ID”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”Unique Merchant ID assigned to the merchant by PhonePe”,”required”:true,”in”:”header”,”ref”:””,”_id”:”622853e1afa6ab004035d8b7″}],”apiSetting”:”63bb01b11abcf7046d98754c”,”examples”:{“codes”:[]}}

https://api-preprod.phonepe.com/apis/pg-sandbox

Request Headers

Path Parameters

Sample Response

Response Parameters

Error Codes

Updated on Oct 19, 2023