- 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
Header Name | Header Value |
---|---|
Content-Type | application/json |
X-VERIFY | SHA256(base64 encoded payload +”/v3/credit/backToSource” + 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"
}
Parameter Name | Description | ||
---|---|---|---|
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 |
Parameter Name | 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 |
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. |
{“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