Refund

Request Headers

Header NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256(base64 encoded payload + “/v4/credit/backToSource” + salt key) + ### + salt index
X-CALLBACK-URLDynamic callback URI for server-to-server callback
X-CALLBACK-MODEHTTP mode to be used for server-to-server callback

Sample Request

{
    "merchantId": "UATMERCHANT",
    "transactionId": "TXTEST1294",
    "providerReferenceId": "PPXXXXX",
    "amount": 100,
    "merchantOrderId": "OD1234",
    "subMerchantId": "DemoMerchant",
    "message": "refund for cancelled order"
}
{
  "request": "ewogICAgIm1lcmNoYW50SWQiOiAiVUFUTUVSQ0hBTlQiLAogICAgInRyYW5zYWN0aW9uSWQiOiAiVFhURVNUMTI5NCIsCiAgICAicHJvdmlkZXJSZWZlcmVuY2VJZCI6ICJQUFhYWFhYIiwKICAgICJhbW91bnQiOiAxMDAsCiAgICAibWVyY2hhbnRPcmRlcklkIjogIk9EMTIzNCIsCiAgICAic3ViTWVyY2hhbnRJZCI6ICJEZW1vTWVyY2hhbnQiLAogICAgIm1lc3NhZ2UiOiAicmVmdW5kIGZvciBjYW5jZWxsZWQgb3JkZXIiCn0="
}
{
    "merchantId": "UATMERCHANT",
    "transactionId": "TXTEST1294",
    "originalTransactionId": "TXTEST9891",    
    "amount": 100,
    "merchantOrderId": "OD1234",
    "subMerchantId": "DemoMerchant",
    "message": "refund for cancelled order"
}
{
  "request": "ewogICAgIm1lcmNoYW50SWQiOiAiVUFUTUVSQ0hBTlQiLAogICAgInRyYW5zYWN0aW9uSWQiOiAiVFhURVNUMTI5NCIsCiAgICAib3JpZ2luYWxUcmFuc2FjdGlvbklkIjogIlRYVEVTVDk4OTEiLCAgICAKICAgICJhbW91bnQiOiAxMDAsCiAgICAibWVyY2hhbnRPcmRlcklkIjogIk9EMTIzNCIsCiAgICAic3ViTWVyY2hhbnRJZCI6ICJEZW1vTWVyY2hhbnQiLAogICAgIm1lc3NhZ2UiOiAicmVmdW5kIGZvciBjYW5jZWxsZWQgb3JkZXIiCn0="
}

Request Parameters

Parameter NameTypeDescriptionMandatory
merchantIdSTRINGUnique Merchant ID assigned to the merchant by PhonePeYes
transactionIdSTRINGUnique Transaction ID generated by the merchant to track this request to PhonePe.
This should be different from transaction ID of debit transaction.
Yes
originalTransactionIdSTRINGMerchant transaction Id of forward transaction which needs to be reversed.Yes
providerReferenceIdSTRINGPhonePe transaction id of the original forward payment.
Note : use only one of originalTransactionId, providerReferenceId only
Yes
amountLONGReversal amount in paise. Upto a max of amount of original payment transaction.Yes
merchantOrderIdSTRINGOrder ID for the merchant transactionYes
subMerchantIdSTRINGTag to categorize merchant transactionNo
messageSTRINGShort messageYes

Sample Response

{
   "success": true,
   "code": "PAYMENT_PENDING",
   "message": "Your request is in pending state.",
   "data": {
       "merchantId": "UATMERCHANT",
       "amount": 100,
       "providerReferenceId": "P2204061257259693373320",
       "status": "PENDING",
       "transactionId": "TXREFUND1045"
   }
}
{
    "success": false,
    "code": "PAYMENT_ERROR",
    "message": "Payment Failed",
    "data": {
        "merchantId": "UATMERCHANT",
        "amount": 10000,
        "providerReferenceId": "",
        "payResponseCode": "EXCESS_REFUND_AMOUNT",
        "status": "FAILED",
        "transactionId": "TXREFUND1046"
    }
}

S2S Callback Response

{
    "success": true,
    "code": "PAYMENT_SUCCESS",
    "message": "Your payment is successful.",
    "data":
    {
        "merchantId": "HOTSTARONLINE",
        "transactionId": "TXREFUND1047",
        "providerReferenceId": "P2204061317483647785587",
        "amount": 100,
        "paymentState": "COMPLETED",
        "payResponseCode": "SUCCESS",
        "paymentModes":
        [
            {
                "mode": "WALLET",
                "amount": 100
            }
        ],
        "transactionContext":
        {
            "qrCodeId": null,
            "posDeviceId": null,
            "storeId": null,
            "terminalId": null
        }
    }
}

Response Parameters

Parameter NameTypeDescription
successBOOLEANSuccess status of the request
codeENUMSee list of response codes below
messageSTRINGShort message about code
transactionIdSTRINGUnique Transaction ID generated by the merchant to track this request to PhonePe
merchantIdSTRINGUnique Merchant ID assigned to the merchant by PhonePe
amountLONGTransaction amount in paise
statusSTRINGStatus of the request
mobileNumberSTRINGMobile number of the user
providerReferenceIdSTRINGPhonePe payment transaction id against which the reversal is to be done
payResponseCodeSTRINGPhonePe internal status code

Refund API Response Codes

CodeDescription
BAD_REQUESTInvalid request
AUTHORIZATION_FAILEDX-VERIFY header is incorrect
TRANSACTION_NOT_FOUNDOriginal transaction not found
INTERNAL_SERVER_ERRORSomething went wrong. Refund might get initiated (need to check status with check transaction status API before retrying the refund)
PAYMENT_SUCCESSPayment is successful
PAYMENT_ERRORPayment failed
PAYMENT_PENDINGPayment is pending. It does not indicate failed payment. Refund might get initiated (need to check status with check transaction status API before retrying the refund)
TIMED_OUTRefund timed out. Refund might get initiated (need to check status with check transaction status API before retrying the refund)
REVERSAL_WINDOW_EXCEEDEDThe time window for refunding the transaction has been breached. Please process the refund manually
{“method”:”post”,”url”:”/v4/credit/backToSource “,”auth”:”required”,”results”:{“codes”:[{“name”:””,”code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_PENDING\”,\n \”message\”: \”Your request is in pending state.\”,\n \”data\”: {\n \”merchantId\”: \”UATMERCHANT\”,\n \”amount\”: 100,\n \”providerReferenceId\”: \”P2204061257259693373320\”,\n \”status\”: \”PENDING\”,\n \”transactionId\”: \”TXREFUND1045\”\n }\n}”,”language”:”json”,”status”:200},{“name”:””,”code”:”{ \n \”success\”:false,\n \”code\”:\”BAD_REQUEST\”,\n \”message\”:\”Please check the inputs you have provided.\”,\n \”data\”:{}\n}”,”language”:”json”,”status”:400}]},”params”:[{“name”:”request”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”base64 encoded payload”,”required”:true,”in”:”body”,”ref”:””,”_id”:”62b185fdf7565b0023b7837e”},{“name”:”Content-type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”62b185fdf7565b0023b7837d”},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”SHA256(base64 encoded payload + \”/v4/credit/backToSource\” + salt key) + ### + salt index”,”required”:true,”in”:”header”,”ref”:””,”_id”:”62b185fdf7565b0023b7837c”},{“name”:”X-CALLBACK-URL”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”Dynamic callback URI for server to server callback”,”required”:false,”in”:”header”,”ref”:””,”_id”:”62b185fdf7565b0023b7837b”},{“name”:”X-CALLBACK-MODE”,”type”:”string”,”enumValues”:””,”default”:”POST”,”desc”:”HTTP mode to be used for server to server callback. Default Values are POST/PUT”,”required”:false,”in”:”header”,”ref”:””,”_id”:”62b185fdf7565b0023b7837a”}],”apiSetting”:”5a1563aec32b6d002a16fb67″,”examples”:{“codes”:[]}}
https://api-preprod.phonepe.com/apis/pg-sandbox