Refund API

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

<html-block html=”

Request Headers

“>

Header NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256(base64 encoded payload +”/v3/credit/backToSource” + salt key) + ### + salt index
{
    "merchantId": "DemoMerchant",
    "transactionId": "TX123456789",
    "providerReferenceId": "T2XXXXXXXXXXX", //OR originalTransactionId
    "amount": 100,
    "message": "refund for cancelled order"
}
{
  "request": "ewogICAgIm1lcmNoYW50SWQiOiAiRGVtb01lcmNoYW50IiwKICAgICJ0cmFuc2FjdGlvbklkIjogIlRYMTIzNDU2Nzg5IiwKICAgICJwcm92aWRlclJlZmVyZW5jZUlkIjogIlQyWFhYWFhYWFhYWFgiLAogICAgImFtb3VudCI6IDEwMCwKICAgICJtZXNzYWdlIjogInJlZnVuZCBmb3IgY2FuY2VsbGVkIG9yZGVyIgp9"
}

<html-block html=”

Request Parameters

“>

Parameter NameDescription
merchantId
String
Mandatory
Unique Merchant ID assigned to the merchant by PhonePe
transactionId
String
Mandatory
Unique Transaction ID created by merchant to track the refund request to PhonePe.
This should be different from transaction ID of forward transaction.
originalTransactionId
String
Mandatory
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.
providerReferenceId
String
Mandatory
PhonePe transaction Id of the original or forward payment.
Note : You can use either the originalTransactionId or providerReferenceId.
amount
Long
Mandatory
Reversal amount in paise. Upto a max of amount of original payment transaction.
message_
String
Mandatory
Short message

<html-block html=”

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
providerReferenceId
String
PhonePe payment transaction id against which the reversal is to be done
payResponseCode
String
PhonePe internal status code

<html-block html=”

Refund API Response Codes

“>

CodeDescription
BAD_REQUESTInvalid request
AUTHORIZATION_FAILEDX-VERIFY header is incorrect
TRANSACTION_NOT_FOUNDOriginal transaction not found. Possibly the transaction ID is incorrect or the forward payment was not successful.
INTERNAL_SERVER_ERRORSomething went wrong. Refund might get initiated (need to do 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.

Note: Forward or Original Transaction is the Transaction done by the customer that you are trying to refund. For static QR, you will get the txn details in the Callback or Transaction_List API payload (which ever you are using).

{“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