Refund

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	Merchant transaction Id of forward transaction which needs to be reversed.	`Yes`
amount	LONG	Reversal amount in paise. Upto a max of amount of original payment transaction.	`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.