Intent Refund API

API flow to refund against a payment transaction made through PhonePe. A full or partial refund is possible against a transaction.

UAT Endpoints:
POST https://mercury-uat.phonepe.com/enterprise-sandbox/v1/intent/refund

Prod Endpoints:
POST https://mercury-t2.phonepe.com/v1/intent/refund

When you hit the Refund API, initially the Refund transaction status will be PAYMENT_PENDING, it will move from PENDING to either SUCCESS or FAILURE within 90 seconds.
Payment Pending is the status of the refund transaction and it does not indicate a Failure or Success. You need to do a Refund transaction Status Check using the StatusCheck API for these cases to confirm the status
We recommend not to hit the Refund API again in case the response is Payment_Pending as when you hit the API again, you get the response like PAYMENT_ERROR with “payResponseCode”:”EXCESS_REFUND_AMOUNT” because the initial refund request was successfully done. Before calling the Refund API again, you need to check the status of already initiated refund using StatusCheck API
To know about the Check Payment Status API, please refer to the link here

Request Headers

Header Name	Header Value
`Content-Type`	application/json
`X-VERIFY`	SHA256(base64 encoded payload +”/v1/intent/refund” + salt key) + ### + salt index
`X-PROVIDER-ID`	Used for the cases where the merchants are getting onboarded via their Providers
`X-CALLBACK-URL`	Merchants need to pass their Callback URL to receive automated callbacks/ webhooks from Phonepe post performing transactions

Python SampleCode

{
    "merchantId": "MERCHANTUAT",
    "transactionId": "TX123456789001",
    "originalTransactionId": "TX123456XXXXX00",
    "amount": 100,
    "merchantOrderId": "OD1234",
    "subMerchant": "DemoMerchant",
    "message": "refund for cancelled order"
}

Sample Request

{
  "request": "eyJtZXJjaGFudE9yZGVySWQiOiAiT0QxMjM0IiwgInN1Yk1lcmNoYW50IjogIkRlbW9NZXJjaGFudCIsICJhbW91bnQiOiAxMDAsICJtZXNzYWdlIjogInJlZnVuZCBmb3IgY2FuY2VsbGVkIG9yZGVyIiwgIm1vYmlsZU51bWJlciI6ICI5eHh4eHh4eHh4IiwgInNob3J0TmFtZSI6ICJBbWl0IiwgInRyYW5zYWN0aW9uSWQiOiAiVFgxMjM0NTY3ODkiLCAibWVyY2hhbnRVc2VySWQiOiAiVTEyMzQ1Njc4OSIsICJtZXJjaGFudElkIjogIkRlbW9NZXJjaGFudCIsICJlbWFpbCI6ICJhbWl0eHh4NzVAZ21haWwuY29tIn0"
}

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
`subMerchant`	String	Tag to categorize merchant transaction	No
`message`	String	Short message	Yes

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)
`DUPLICATE_TXN_REQUEST`	If the transaction id is used already for refund request.
`EXCESS_REFUND_AMOUNT`	If the amount requested for refund is more than forward payment or If refund is already done
`WALLLET_NOT_ACTIVATED`	If the user has disabled the wallet. Contact user to know the source for refund.