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 Name

Header Value

Content-Type

application/json

X-VERIFY

SHA256(base64 encoded payload + "/v3/credit/backToSource" + salt key) + ### + salt index

{
    "merchantId": "DemoMerchant",
    "transactionId": "TX123456789",
    "providerReferenceId": "PPXXXXX",
    "amount": 100,
    "merchantOrderId": "OD1234",
    "subMerchant": "DemoMerchant",
    "message": "refund for cancelled order"
}
{
  "request": "eyJtZXJjaGFudE9yZGVySWQiOiAiT0QxMjM0IiwgInN1Yk1lcmNoYW50IjogIkRlbW9NZXJjaGFudCIsICJhbW91bnQiOiAxMDAsICJtZXNzYWdlIjogInJlZnVuZCBmb3IgY2FuY2VsbGVkIG9yZGVyIiwgIm1vYmlsZU51bWJlciI6ICI5eHh4eHh4eHh4IiwgInNob3J0TmFtZSI6ICJBbWl0IiwgInRyYW5zYWN0aW9uSWQiOiAiVFgxMjM0NTY3ODkiLCAibWVyY2hhbnRVc2VySWQiOiAiVTEyMzQ1Njc4OSIsICJtZXJjaGFudElkIjogIkRlbW9NZXJjaGFudCIsICJlbWFpbCI6ICJhbWl0eHh4NzVAZ21haWwuY29tIn0"
}

Request Parameters

Parameter Name

Type

Description

Mandatory

merchantId

STRING

Unique Merchant ID assigned to the merchant by PhonePe

Yes

transactionId

STRING

Unique Transaction ID generated by the merchant to track this request to PhonePe.
This should be different from transaction ID of debit transaction.

Yes

originalTransactionId

STRING

Merchant transaction Id of forward transaction which needs to be reversed.

Yes

providerReferenceId

STRING

PhonePe transaction id of the original forward payment.
Note : use only one of originalTransactionId, providerReferenceId only

Yes

amount

LONG

Reversal amount in paise. Upto a max of amount of original payment transaction.

Yes

merchantOrderId

STRING

Order ID for the merchant transaction

Yes

subMerchant

STRING

Tag to categorize merchant transaction

No

message

STRING

Short message

Yes

Response Parameters

Parameter Name

Type

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

Refund API Response Codes

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.

Language
Click Try It! to start a request and see the response here!