Refund API
post https://mercury-uat.phonepe.com/enterprise-sandbox/v3/credit/backToSource

API flow to refund against a payment transaction made through PhonePe. A full or partial refund is possible against a transaction.
  • 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

PROD
Base Url: https://mercury-t2.phonepe.com
Refund Endpoint: https://mercury-t2.phonepe.com/v3/credit/backToSource

Request Headers

Header NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256(base64 encoded payload +”/v3/credit/backToSource” + salt key) + ### + salt index
X-PROVIDER-IDUsed for the cases where the merchants are getting onboarded via their Providers
X-CALLBACK-URLMerchants 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 NameDescription
merchantId
String
Mandatory
Unique Merchant ID assigned to the merchant by PhonePe
transactionId
String
Mandatory
Unique Transaction ID generated by the merchant to track this request to PhonePe.
This should be different from transaction ID of debit transaction.
originalTransactionId
String
Mandatory
Merchant transaction Id of forward transaction which needs to be reversed.
providerReferenceId*
String
Mandatory
PhonePe transaction id of the original forward payment.
Note : use only one of originalTransactionId, providerReferenceId only
amount
Long
Mandatory
Reversal amount in paise. Upto a max of amount of original payment transaction.
merchantOrderId
String
Mandatory
Order ID for the merchant transaction
subMerchant
String
Optional
Tag to categorize merchant transaction
message
String
Mandatory
Short message

Response Parameters

Parameter NameDescription
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

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)
DUPLICATE_TXN_REQUESTIf 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.
{“method”:”post”,”url”:”/v3/credit/backToSource”,”auth”:”required”,”results”:{“codes”:[{“name”:”Success Response”,”code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_SUCCESS\”,\n \”message\”: \”Your payment is successful.\”,\n \”data\”: {\n \”transactionId\”: \”TX123456789\”,\n \”merchantId\”: \”DemoMerchant\”,\n \”amount\”: 100,\n \”status\”: \”SUCCESS\”,\n \”mobileNumber\”: \”9xxxxxxxxxx\”,\n \”providerReferenceId\”: \”PPXXXXX\”,\n \”payResponseCode\”: \”SUCCESS\”\n }\n}”,”language”:”json”,”status”:200},{“name”:”Failure Response”,”code”:”{\n \”success\”: false,\n \”code\”: \”INVALID_TRANSACTION_ID\”,\n \”message\”: \”The transaction id you have entered seems to be invalid.\”,\n \”data\”: {}\n}”,”language”:”json”,”status”:400}]},”examples”:{“codes”:[]},”apiSetting”:”64c244096688b200429110a5″,”params”:[{“name”:”request”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”base64 encoded payload”,”required”:true,”in”:”body”,”ref”:””,”_id”:”5b71964460cf570003c05d98″},{“name”:”Content-type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”5b71964460cf570003c05d97″},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”SHA256(base64 encoded payload + \”/v3/credit/backToSource\” + salt key) + ### + salt index”,”required”:true,”in”:”header”,”ref”:””,”_id”:”5b71964460cf570003c05d96″}]}
https://mercury-uat.phonepe.com/enterprise-sandbox

HEADERS
Content-type string required
X-VERIFY string required
SHA256(base64 encoded payload + "/v3/credit/backToSource" + salt key) + ### + salt index

BODY PARAMS
request string required
base64 encoded payload

RESPONSES
Code 200
200
Code 400
400