Refund

This API is used for initiating the refund

Request Headers

Header NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256(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 NameTypeDescriptionMandatory
merchantIdSTRINGUnique Merchant ID assigned to the merchant by PhonePeYes
merchantUserIdSTRINGUser Id passed in the debit requestNo
merchantTransactionIdSTRINGUnique Refund Transaction ID generated by the merchant.
This should be different from transaction ID of debit transaction.
Yes
originalTransactionIdSTRING The actual merchantTransactionId used in the Pay API call generated by the merchant for accepting the forward payments.Yes
amountLONGReversal amount in paise. Upto a max of amount of original payment transaction.
Note: Amount should be greater than 100 (in Paise)
Yes
callbackUrlSTRINGThe url where server to server callback will be posted. Always POSTThis 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 NameTypeDescription
successBOOLEANSuccess status of the request
codeSTRINGResponse 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
messageSTRINGMessage giving more information about the code.
merchantIdSTRINGUnique Merchant ID assigned to the merchant by PhonePe
merchantTransactionIdSTRINGTransaction id generated by the merchant
transactionIdSTRINGTransaction Id generated by the Phonepe
amountLONGRefunded amount against the forwarded transaction in paise
stateSTRINGTransaction State
responseCodeSTRINGResponse code

Error Codes

CodeDescription
BAD_REQUESTInvalid request
AUTHORIZATION_FAILEDX-VERIFY header is incorrect
INTERNAL_SERVER_ERRORSomething went wrong
PAYMENT_SUCCESSPayment is successful
PAYMENT_ERRORPayment failed
Note: Merchants can retry initiating the Refund.
TRANSACTION_NOT_FOUNDThe original Transaction id is incorrect.
PAYMENT_PENDINGPayment 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_EXCEEDEDThe 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 NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256(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