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/v3/credit/backToSource/

Prod Endpoints:
POST https://mercury-t2.phonepe.com/v3/credit/backToSource/

Request Headers

Header Name	Header Value
`Content-Type`	application/json
`X-VERIFY`	SHA256(base64 encoded payload +”/v3/credit/backToSource” + salt key) + ### + salt index

Sample Payload for Base64

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

Sample Request

{
  "request": "ewogICAgIm1lcmNoYW50SWQiOiAiRGVtb01lcmNoYW50IiwKICAgICJ0cmFuc2FjdGlvbklkIjogIlRYMTIzNDU2Nzg5IiwKICAgICJwcm92aWRlclJlZmVyZW5jZUlkIjogIlQyWFhYWFhYWFhYWFgiLAogICAgImFtb3VudCI6IDEwMCwKICAgICJtZXNzYWdlIjogInJlZnVuZCBmb3IgY2FuY2VsbGVkIG9yZGVyIgp9"
}

Request Parameters

Parameter Name	Type	Description	Mandatory
`merchantId`	String	Unique Merchant ID assigned to the merchant by PhonePe	Yes
`transactionId`	String	Unique Transaction ID created by merchant to track the refund request to PhonePe. This should be different from transaction ID of forward transaction.	Yes
`originalTransactionId`	String	Transaction Id of forward transaction which needs to be reversed/refunded. You will get the details in the payload of Callback or Transaction_List API.	Yes
`providerReferenceId`	String	PhonePe transaction Id of the original or forward payment. Note : You can use either the originalTransactionId or providerReferenceId.	Yes
`amount`	Long	Reversal amount in paise. Upto a max of amount of original payment transaction.	Yes
`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
`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. Possibly the transaction ID is incorrect or the forward payment was not successful.
`INTERNAL_SERVER_ERROR`	Something went wrong. Refund might get initiated (need to do 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.