Refund Check Transaction Status

This API is used to check the status of the transaction using transaction id.

It is mandatory for the merchant to check the status of a transaction post callback from workflows.

Once the customer is redirected back to the merchant website, merchants should check with their server if they have received the [Server-to-Server Callback](ref:server-to-server-callback-3) 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, merchants should check with their server if they have received the 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).

<html-block html=”

Request Headers

“>

Header Name	Header Value
`Content-Type`	application/json
`X-VERIFY`	SHA256(“/v3/transaction/{merchantId}/{transactionId}/status” + saltKey) + “###” + saltIndex

<html-block html=”

Path Parameters

“>

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

<html-block html=”

Response Parameters

“>

Parameter Name	Type	Description
success	BOOLEAN	A boolean to indicate the success/failure of the request.
`code`	`ENUM`	Please see the list of Transaction Status Response Codes below. You should base your decision on this parameter.
`message`	`STRING`	Short message about status of transaction
`transactionId`	`STRING`	Unique Transaction ID generated by the merchant to track this request to PhonePe
`merchantId`	`STRING`	Unique Merchant ID assigned to the merchant by PhonePe
`amount`	`LONG`	Transaction amount in paise
`merchantOrderId`	`STRING`	Merchant Order Id Note: The merchantOrderId would be returned only when the merchantOrderId passed in API request is different from the transactionId.
`providerReferenceId`	`STRING`	PhonePe transaction Id
`paymentState`	`STRING`	Please ignore this. Use “code” parameter to get latest status of transaction.
`payResponseCode`	`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 marshalling/unmarshalling into an enum for this at your side). This is an informative value.

<html-block html=”

Transaction Status Response Codes

“>

Code	Description
`TRANSACTION_NOT_FOUND`	Payment not initiated inside PhonePe
`BAD_REQUEST`	Invalid request
`AUTHORIZATION_FAILED`	X-VERIFY header is incorrect
`INTERNAL_SERVER_ERROR`	Something went wrong. Merchant needs to call Check Transaction Status to verify the transaction status.
`PAYMENT_SUCCESS`	Payment is successful or In case of refund – Refund is successful.
`PAYMENT_ERROR`	Payment failed
`PAYMENT_PENDING`	Payment is pending. It does not indicate failed payment. Merchant needs to call Check Transaction Status to verify the transaction status.
`PAYMENT_DECLINED`	Payment declined by user.

Cross-check the amount which has been passed in forward payment path(Accept payment API) and in the response of Check Transaction Status API.

{“method”:”get”,”url”:”/v3/transaction/{merchantId}/{transactionId}/status (Refund)”,”auth”:”never”,”apiSetting”:”5a1563aec32b6d002a16fb67″,”examples”:{“codes”:[]},”results”:{“codes”:[{“status”:200,”language”:”json”,”code”:”{\n \”success\”: true,/* Rely on success flag and\n code parameter as PAYMENT_SUCCESS for \n successful transaction */\n \n \”code\”: \”PAYMENT_SUCCESS\”,\n \”message\”: \”Your payment is successful.\”,\n \”data\”: {\n \”transactionId\”: \”TX123456789\”,\n \”merchantId\”: \”U123456789\”,\n \”amount\”: 100,\n \”merchantOrderId\”: \”OD162763132055338\”,\n \”providerReferenceId\”: \”PPXXXXXX\”,\n \”payResponseCode\”: \”SUCCESS\”,\n \”paymentState\”: \”COMPLETED\”/* This is an\n informative field. For making decisions\n rely on code field */\n }\n}”,”name”:”Success Response”},{“status”:200,”language”:”json”,”code”:”{\n \”success\”: false,\n \”code\”: \”TRANSACTION_NOT_FOUND\”,\n \”message\”: \”No Transaction found with the given details.\”,\n \”data\”: {}\n}”,”name”:”Error Response”}]},”params”:[{“name”:”merchantId”,”type”:”string”,”enumValues”:””,”default”:”M2306160483220675579140″,”desc”:”Unique Merchant ID assigned to the merchant by PhonePe”,”required”:false,”in”:”path”,”ref”:””,”_id”:”5a16aa3038e7e00012818373″},{“name”:”transactionId”,”type”:”string”,”enumValues”:””,”default”:”1511522079″,”desc”:”Merchant transaction id for which status is to be fetched”,”required”:false,”in”:”path”,”ref”:””,”_id”:”5a16aa3038e7e00012818372″},{“name”:”Content-Type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”5a16aa3038e7e00012818371″},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:”6ab24e24ae92646c82e0450f029478117d8a1a0a00390e266ea1178a0c68e419###1″,”desc”:”SHA256(\”/v3/transaction/{merchantId}/{transactionId}/status\” + saltKey) + \”###\” + saltIndex”,”required”:true,”in”:”header”,”ref”:””,”_id”:”5a16aa3038e7e00012818370″}]}

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

Updated on May 05, 2023