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
orPending
. WhenPending
, merchants should retry until the status changes toSuccess
orFailed
.
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 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
{
"success": true,
"code": "PAYMENT_SUCCESS",
"message": "Your request has been successfully completed.",
"data": {
"merchantId": "FKRT",
"merchantTransactionId": "MT7850590068188104",
"transactionId": "T2111221437456190170379",
"amount": 100,
"state": "COMPLETED",
"responseCode": "SUCCESS",
"paymentInstrument": {
"type": "UPI",
"utr": "206378866112",
"unmaskedAccountNumber" : "123123123123" //Optional. Will be shared only for TPV Flow.
}
}
}
{
"success": true,
"code": "PAYMENT_SUCCESS",
"message": "Your request has been successfully completed.",
"data": {
"merchantId": "FKRT",
"merchantTransactionId": "MT7850590068188104",
"transactionId": "T2111221437456190170379",
"amount": 100,
"state": "COMPLETED",
"responseCode": "SUCCESS",
"paymentInstrument": {
"type": "CARD",
"cardType": "DEBIT_CARD",
"pgTransactionId": "b9090242ac120002",
"bankTransactionId": "e57a658e9e1011ec",
"pgAuthorizationCode": "9cf3ef4932bf9e05",
"arn": "339482773927",
"bankId": "SBIN",
"brn": "Dummy_Bank_Ref_Number"
}
}
}
{
"success": true,
"code": "PAYMENT_SUCCESS",
"message": "Your request has been successfully completed.",
"data": {
"merchantId": "FKRT",
"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": "FKRT",
"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 to indicate the success/failure of the request. | 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 |
paymentInstrument.unmaskedAccountNumber | STRING | ● Will be present for only UPI. ● Optional Parameter as this will be present only for TPV Flow. | 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. |