Refund

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

Request Headers

Header NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256(base64 encoded payload + "/v3/credit/backToSource" + salt key) + ### + salt index
{
    "merchantId": "UATMERCHANT",
    "transactionId": "TX123456789",
    "providerReferenceId": "PPXXXXX",
    "amount": 100,
    "merchantOrderId": "OD1234",
    "subMerchantId": "DemoMerchant",
    "message": "refund for cancelled order"
}
{
  "request": "ewogICAgIm1lcmNoYW50SWQiOiAiVUFUTUVSQ0hBTlQiLAogICAgInRyYW5zYWN0aW9uSWQiOiAiVFgxMjM0NTY3ODkiLAogICAgInByb3ZpZGVyUmVmZXJlbmNlSWQiOiAiUFBYWFhYWCIsCiAgICAiYW1vdW50IjogMTAwLAogICAgIm1lcmNoYW50T3JkZXJJZCI6ICJPRDEyMzQiLAogICAgInN1Yk1lcmNoYW50SWQiOiAiRGVtb01lcmNoYW50IiwKICAgICJtZXNzYWdlIjogInJlZnVuZCBmb3IgY2FuY2VsbGVkIG9yZGVyIgp9"
}

Request Parameters

Parameter NameTypeDescriptionMandatory
merchantIdSTRINGUnique Merchant ID assigned to the merchant by PhonePeYes
transactionIdSTRINGUnique Transaction ID generated by the merchant to track this request to PhonePe.
This should be different from transaction ID of debit transaction.
Yes
originalTransactionIdSTRINGMerchant transaction Id of forward transaction which needs to be reversed.Yes
providerReferenceIdSTRINGPhonePe transaction id of the original forward payment.
Note : use only one of originalTransactionId, providerReferenceId only
Yes
amountLONGReversal amount in paise. Upto a max of amount of original payment transaction.Yes
merchantOrderIdSTRINGOrder ID for the merchant transactionYes
subMerchantIdSTRINGTag to categorize merchant transactionNo
messageSTRINGShort messageYes

Response Parameters

Parameter NameTypeDescription
successBOOLEANSuccess status of the request
codeENUMSee list of response codes below
messageSTRINGShort message about code
transactionIdSTRINGUnique Transaction ID generated by the merchant to track this request to PhonePe
merchantIdSTRINGUnique Merchant ID assigned to the merchant by PhonePe
amountLONGTransaction amount in paise
statusSTRINGStatus of the request
mobileNumberSTRINGMobile number of the user
providerReferenceIdSTRINGPhonePe payment transaction id against which the reversal is to be done
payResponseCodeSTRINGPhonePe 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)
REVERSAL_WINDOW_EXCEEDEDThe time window for refunding the transaction has been breached. Please process the refund manually

Refund API - Pay Response Codes

CodepayResponseCodeDescription
PAYMENT_ERRORDUPLICATE_TXN_REQUESTIf the transaction id is used already for refund request.
PAYMENT_ERROREXCESS_REFUND_AMOUNTIf the amount requested for refund is more than forward payment or If refund is already done
PAYMENT_ERRORWALLET_NOT_ACTIVATEDIf the user has disabled the wallet. Contact user to know the source for refund.
REVERSAL_WINDOW_EXCEEDEDEXTERNAL_WALLET_REVERSAL_WINDOW_BREACHEDMaximum time period for refunding the transaction is breached
REVERSAL_WINDOW_EXCEEDEDPG_REVERSAL_WINDOW_EXCEEDEDMaximum time period for refunding the transaction is breached
REVERSAL_WINDOW_EXCEEDEDACCOUNT_REVERSAL_WINDOW_EXCEEDEDMaximum time period for refunding the transaction is breached
Language
Click Try It! to start a request and see the response here!