Refund

This API is used for initiating the refund

Request Headers

Header Name

Header Value

Content-Type

application/json

X-VERIFY

SHA256(base64 encoded payload + "/pg/v1/refund" + salt key) + ### + salt index

{
    "merchantId": "MERCHANTUAT",
    "merchantUserId": "User123",
    "originalTransactionId": "OD620471739210623",
    "merchantTransactionId": "ROD620471739210623",
    "amount": 1000,
    "callbackUrl": "https://webhook.site/callback-url"
}
{
  "request": "ewogICAgIm1lcmNoYW50SWQiOiAiTUVSQ0hBTlRVQVQiLAogICAgIm1lcmNoYW50VXNlcklkIjogIlVzZXIxMjMiLAogICAgIm9yaWdpbmFsVHJhbnNhY3Rpb25JZCI6ICJPRDYyMDQ3MTczOTIxMDYyMyIsCiAgICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIlJPRDYyMDQ3MTczOTIxMDYyMyIsCiAgICAiYW1vdW50IjogMTAwMCwKICAgICJjYWxsYmFja1VybCI6ICJodHRwczovL3dlYmhvb2suc2l0ZS9jYWxsYmFjay11cmwiCn0="
}

Request Parameters

Parameter Name

Type

Description

Mandatory

merchantId

STRING

Unique Merchant ID assigned to the merchant by PhonePe

Yes

merchantUserId

STRING

User Id passed in the debit request

Yes

merchantTransactionId

STRING

Unique Refund Transaction ID generated by the merchant.
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

amount

LONG

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

Yes

callbackUrl

STRING

The url where server to server callback will be posted. Always POST

This callback will be of POST type and will contain the same payload as the Status API Response of Refund transaction. The callback will contain an X-VERIFY header which the merchant should verify.

Sample Response

{
  "success": true,
  "code": "PAYMENT_PENDING",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "ROD620471739210623",
    "transactionId": "TR620471739210623",
    "amount": 10000,
    "state": "PENDING",
    "responseCode": "PAYMENT_PENDING"
  }
}

🚧

Refund API Response

  • Merchants should rely on the "code" parameter for the status of the Refund API.

  • Merchants should validate the status of the Refund API either using Check Status API or the S2S Callback Response.

{
  "success": true,
  "code": "PAYMENT_SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "ROD620471739210623",
    "transactionId": "TR620471739210623",
    "amount": 10000,
    "state": "COMPLETED",
    "responseCode": "SUCCESS"
  }
}
{
    "success": false,
    "code": "INTERNAL_SERVER_ERROR",
    "message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}

Response Parameters

Parameter Name

Type

Description

success

BOOLEAN

Success status of the request

code

STRING

Response code explaining reason for status.
For status SUCCESS, only one possible response code is present - PAYMENT_SUCCESS
For status FAILURE, following response codes are possible:
INTERNAL_SERVER_ERROR
BAD_REQUEST
AUTHORIZATION_FAILED
TRANSACTION_NOT_FOUND
PAYMENT_ERROR
PAYMENT_PENDING
PAYMENT_DECLINED
REVERSAL_WINDOW_EXCEEDED

message

STRING

Message giving more information about the code.

merchantId

STRING

Unique Merchant ID assigned to the merchant by PhonePe

merchantTransactionId

STRING

Transaction id generated by the merchant

transactionId

STRING

Transaction Id generated by the Phonepe

amount

LONG

Refunded amount against the forwarded transaction in paise

state

STRING

Transaction State

responseCode

STRING

Response code

Error Codes

Code

Description

BAD_REQUEST

Invalid request

AUTHORIZATION_FAILED

X-VERIFY header is incorrect

INTERNAL_SERVER_ERROR

Something went wrong

PAYMENT_SUCCESS

Payment is successful

PAYMENT_ERROR

Payment failed
Note: Merchants can retry initiating the Refund.

TRANSACTION_NOT_FOUND

The original Transaction id is incorrect.

PAYMENT_PENDING

Payment is pending. It does not indicate failed payment.
Note: Merchants shouldn't retry initiating the Refund while the status is PAYMENT_PENDING. Instead, merchants need to call Check Transaction Status to verify the transaction status till the terminal Success/Failure status is reached.

REVERSAL_WINDOW_EXCEEDED

The time window for refunding the transaction has been breached. Please process the refund manually

Sample Refund S2S Response

Callback headers
Following are the response headers sent with the callback.

Header Name

Header Value

Content-Type

application/json

X-VERIFY

SHA256(base64response + salt key) + ### + salt index

{
    "response": "eyJzdWNjZXNzIjp0cnVlLCJjb2RlIjoiUEFZTUVOVF9TVUNDRVNTIiwibWVzc2FnZSI6IllvdXIgcGF5bWVudCBpcyBzdWNjZXNzZnVsLiIsImRhdGEiOnsibWVyY2hhbnRJZCI6Ik1FUkNIQU5UVUFUIiwibWVyY2hhbnRUcmFuc2FjdGlvbklkIjoiZDliODY5MTMtZjhlZS00NGM3LThhYjctM2IzNjYwZDY1YzAzIiwidHJhbnNhY3Rpb25JZCI6IlAyMjA2MjQxMDQyMTkwOTUyNzAxMjEzIiwiYW1vdW50IjoxMDAsInN0YXRlIjoiQ09NUExFVEVEIiwicmVzcG9uc2VDb2RlIjoiUEFZTUVOVF9TVUNDRVNTIiwicGF5bWVudEluc3RydW1lbnQiOm51bGx9fQ=="
}
{
    "success": true,
    "code": "PAYMENT_SUCCESS",
    "message": "Your payment is successful.",
    "data":
    {
        "merchantId": "MERCHANTUAT",
        "merchantTransactionId": "d9b86913-f8ee-44c7-8ab7-3b3660d65c03",
        "transactionId": "P2206241042190952701213",
        "amount": 100,
        "state": "COMPLETED",
        "responseCode": "PAYMENT_SUCCESS",
        "paymentInstrument": null
    }
}

🚧

S2S Refund Response

  • This callback will be of POST type and will contain the same payload as the Status API Response of Refund transaction.

  • The callback will contain a checksum in the "X-VERIFY" header which the merchant should validate for the checksum.

  • Once the checksum is verified, validate the amount parameter.

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