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 Name	Header Value
`Content-Type`	application/json
`X-VERIFY`	SHA256(base64 encoded payload +”/v3/credit/backToSource” + salt key) + ### + salt index

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

{
  "request": "ewogICAgIm1lcmNoYW50SWQiOiAiRGVtb01lcmNoYW50IiwKICAgICJ0cmFuc2FjdGlvbklkIjogIlRYMTIzNDU2Nzg5IiwKICAgICJwcm92aWRlclJlZmVyZW5jZUlkIjogIlQyWFhYWFhYWFhYWFgiLAogICAgImFtb3VudCI6IDEwMCwKICAgICJtZXNzYWdlIjogInJlZnVuZCBmb3IgY2FuY2VsbGVkIG9yZGVyIgp9"
}

<html-block html=”

Request Parameters

“>

Parameter Name		Description
`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 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
`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

“>

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.

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

Request Headers

Request Parameters

Response Parameters

Refund API Response Codes

Updated on Oct 11, 2023