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

Language
Click Try It! to start a request and see the response here!