Request Headers
Header Name | Header Value |
---|---|
Content-Type | application/json |
X-VERIFY | SHA256(base64 encoded payload + “/pg/v1/refund” + salt key) + ### + salt index |
{
"merchantId": "MERCHANTUAT",
"merchantUserId": "User123",
"originalTransactionId": "OD620471739210623",
"merchantTransactionId": "ROD620471739210623",
"amount": 1000,
"callbackUrl": "https://webhook.site/callback-url"
}
{
"request": "ewogICAgIm1lcmNoYW50SWQiOiAiTUVSQ0hBTlRVQVQiLAogICAgIm1lcmNoYW50VXNlcklkIjogIlVzZXIxMjMiLAogICAgIm9yaWdpbmFsVHJhbnNhY3Rpb25JZCI6ICJPRDYyMDQ3MTczOTIxMDYyMyIsCiAgICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIlJPRDYyMDQ3MTczOTIxMDYyMyIsCiAgICAiYW1vdW50IjogMTAwMCwKICAgICJjYWxsYmFja1VybCI6ICJodHRwczovL3dlYmhvb2suc2l0ZS9jYWxsYmFjay11cmwiCn0="
}
Request Parameters
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
merchantId | STRING | Unique Merchant ID assigned to the merchant by PhonePe | Yes |
merchantUserId | STRING | User Id passed in the debit request | No |
merchantTransactionId | STRING | Unique Refund Transaction ID generated by the merchant. This should be different from transaction ID of debit transaction. | Yes |
originalTransactionId | STRING | The actual merchantTransactionId used in the Pay API call generated by the merchant for accepting the forward payments. | Yes |
amount | LONG | Reversal amount in paise. Upto a max of amount of original payment transaction. Note: Amount should be greater than 100 (in Paise) | Yes |
callbackUrl | STRING | The url where server to server callback will be posted. Always POST | This callback will be of POST type and will contain the same payload as the Status API Response of Refund transaction. The callback will contain an X-VERIFY header which the merchant should verify. |
Sample Response
{
"success": true,
"code": "PAYMENT_PENDING",
"message": "Your request has been successfully completed.",
"data": {
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "ROD620471739210623",
"transactionId": "TR620471739210623",
"amount": 10000,
"state": "PENDING",
"responseCode": "PAYMENT_PENDING"
}
}
Refund API Response
- Merchants should rely on the “code” parameter for the status of the Refund API.
- Merchants should validate the status of the Refund API either using Check Status API or the S2S Callback Response.
{
"success": true,
"code": "PAYMENT_SUCCESS",
"message": "Your request has been successfully completed.",
"data": {
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "ROD620471739210623",
"transactionId": "TR620471739210623",
"amount": 10000,
"state": "COMPLETED",
"responseCode": "SUCCESS"
}
}
{
"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 |
---|---|---|
success | BOOLEAN | Success status of the request |
code | STRING | 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: ● INTERNAL_SERVER_ERROR ● BAD_REQUEST ● AUTHORIZATION_FAILED ● TRANSACTION_NOT_FOUND ● PAYMENT_ERROR ● PAYMENT_PENDING ● PAYMENT_DECLINED ● REVERSAL_WINDOW_EXCEEDED |
message | STRING | Message giving more information about the code. |
merchantId | STRING | Unique Merchant ID assigned to the merchant by PhonePe |
merchantTransactionId | STRING | Transaction id generated by the merchant |
transactionId | STRING | Transaction Id generated by the Phonepe |
amount | LONG | Refunded amount against the forwarded transaction in paise |
state | STRING | Transaction State |
responseCode | STRING | Response code |
Error Codes
Code | Description |
---|---|
BAD_REQUEST | Invalid request |
AUTHORIZATION_FAILED | X-VERIFY header is incorrect |
INTERNAL_SERVER_ERROR | Something went wrong |
PAYMENT_SUCCESS | Payment is successful |
PAYMENT_ERROR | Payment failed Note: Merchants can retry initiating the Refund. |
TRANSACTION_NOT_FOUND | The original Transaction id is incorrect. |
PAYMENT_PENDING | Payment is pending. It does not indicate failed payment. Note: Merchants shouldn’t retry initiating the Refund while the status is PAYMENT_PENDING. Instead, merchants need to call Check Transaction Status to verify the transaction status till the terminal Success/Failure status is reached. |
REVERSAL_WINDOW_EXCEEDED | The time window for refunding the transaction has been breached. Please process the refund manually |
Sample Refund S2S Response
Callback headers
Following are the response headers sent with the callback.
Header Name | Header Value |
---|---|
Content-Type | application/json |
X-VERIFY | SHA256(base64response + salt key) + ### + salt index |
{
"response": "eyJzdWNjZXNzIjp0cnVlLCJjb2RlIjoiUEFZTUVOVF9TVUNDRVNTIiwibWVzc2FnZSI6IllvdXIgcGF5bWVudCBpcyBzdWNjZXNzZnVsLiIsImRhdGEiOnsibWVyY2hhbnRJZCI6Ik1FUkNIQU5UVUFUIiwibWVyY2hhbnRUcmFuc2FjdGlvbklkIjoiZDliODY5MTMtZjhlZS00NGM3LThhYjctM2IzNjYwZDY1YzAzIiwidHJhbnNhY3Rpb25JZCI6IlAyMjA2MjQxMDQyMTkwOTUyNzAxMjEzIiwiYW1vdW50IjoxMDAsInN0YXRlIjoiQ09NUExFVEVEIiwicmVzcG9uc2VDb2RlIjoiUEFZTUVOVF9TVUNDRVNTIiwicGF5bWVudEluc3RydW1lbnQiOm51bGx9fQ=="
}
{
"success": true,
"code": "PAYMENT_SUCCESS",
"message": "Your payment is successful.",
"data":
{
"merchantId": "MERCHANTUAT",
"merchantTransactionId": "d9b86913-f8ee-44c7-8ab7-3b3660d65c03",
"transactionId": "P2206241042190952701213",
"amount": 100,
"state": "COMPLETED",
"responseCode": "PAYMENT_SUCCESS",
"paymentInstrument": null
}
}
S2S Refund Response
- This callback will be of POST type and will contain the same payload as the Status API Response of Refund transaction.
- The callback will contain a checksum in the “X-VERIFY” header which the merchant should validate for the checksum.
- Once the checksum is verified, validate the amount parameter.
{“method”:”post”,”url”:”/pg/v1/refund”,”auth”:”required”,”results”:{“codes”:[{“name”:””,”code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_SUCCESS\”,\n \”message\”: \”Your request has been successfully completed.\”,\n \”data\”: {\n \”merchantId\”: \”MERCHANTUAT\”,\n \”merchantTransactionId\”: \”ROD620471739210623\”,\n \”transactionId\”: \”TR620471739210623\”,\n \”amount\”: 10000,\n \”state\”: \”COMPLETED\”,\n \”responseCode\”: \”SUCCESS\”\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}]},”params”:[{“name”:”request”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”base64 encoded payload”,”required”:true,”in”:”body”,”ref”:””,”_id”:”6203d59f29c6050281cf230c”},{“name”:”Content-type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”6203d59f29c6050281cf230b”},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”SHA256(base64 encoded payload + \”/pg/v1/refund\” + salt key) + ### + salt index”,”required”:true,”in”:”header”,”ref”:””,”_id”:”6203d59f29c6050281cf230a”}],”apiSetting”:”63bb01b11abcf7046d98754c”,”examples”:{“codes”:[]}}
https://api-preprod.phonepe.com/apis/pg-sandbox