Refund

Request Headers

Header Name	Header Value
`Content-Type`	application/json
`X-VERIFY`	SHA256(base64 encoded payload + "/v4/credit/backToSource" + salt key) + ### + salt index
`X-CALLBACK-URL`	Dynamic callback URI for server-to-server callback
`X-CALLBACK-MODE`	HTTP 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 Name	Type	Description	Mandatory
merchantId	STRING	Unique Merchant ID assigned to the merchant by PhonePe	`Yes`
transactionId	STRING	Unique Transaction ID generated by the merchant to track this request to PhonePe. 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`
providerReferenceId	STRING	PhonePe transaction id of the original forward payment. Note : use only one of originalTransactionId, providerReferenceId only	`Yes`
amount	LONG	Reversal amount in paise. Upto a max of amount of original payment transaction.	`Yes`
merchantOrderId	STRING	Order ID for the merchant transaction	`Yes`
subMerchantId	STRING	Tag to categorize merchant transaction	`No`
message	STRING	Short message	`Yes`

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 Name	Type	Description
success	BOOLEAN	Success status of the request
code	ENUM	See list of response codes below
message	STRING	Short message about code
transactionId	STRING	Unique Transaction ID generated by the merchant to track this request to PhonePe
merchantId	STRING	Unique Merchant ID assigned to the merchant by PhonePe
amount	LONG	Transaction amount in paise
status	STRING	Status of the request
mobileNumber	STRING	Mobile number of the user
providerReferenceId	STRING	PhonePe payment transaction id against which the reversal is to be done
payResponseCode	STRING	PhonePe internal status code

Refund API Response Codes

Code	Description
BAD_REQUEST	Invalid request
AUTHORIZATION_FAILED	X-VERIFY header is incorrect
TRANSACTION_NOT_FOUND	Original transaction not found
INTERNAL_SERVER_ERROR	Something went wrong. Refund might get initiated (need to check status with check transaction status API before retrying the refund)
PAYMENT_SUCCESS	Payment is successful
PAYMENT_ERROR	Payment failed
PAYMENT_PENDING	Payment 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_OUT	Refund timed out. Refund might get initiated (need to check status with check transaction status API before retrying the refund)
REVERSAL_WINDOW_EXCEEDED	The time window for refunding the transaction has been breached. Please process the refund manually