Initiate Refund and Check Refund Status

Initiate Refund

The Refund API allows you to initiate refunds for specific transactions, returning funds to customers for reasons like order cancellations, returns, or payment adjustments. This ensures smooth and direct refund processing through the payment gateway.

Environment

Environment	HTTP Method	API
Sandbox	POST	https://api-preprod.phonepe.com/apis/pg-sandbox/payments/v2/refund
Production	POST	https://api.phonepe.com/apis/pg/payments/v2/refund

Initiating Refund Request

Request Headers

Header Name	Header Value
Content-Type	application/json
Authorization	O-Bearer <merchant-auth-token>

Request Parameters

Field Name	Data Type	Mandatory(Y/N)	Description	Constraints
merchantRefundId	String	Yes	A unique refund ID that you create to identify the refund request.	Max Length = 63 characters
originalMerchantOrderId	String	Yes	The merchant OrderId for which you want to initiate the refund.
amount	Long	Yes	The amount to be refunded, specified in paisa.	Min Value = 1 paisa

Sample Request

{
    "merchantRefundId": "Refund-id-12345",
    "originalMerchantOrderId": "Order-12345",
    "amount": 1234
}

⚠️ Invalid Refund Amount!

The refund amount cannot exceed the initiated amount. It must always be less than or equal to the amount originally initiated.

Refund Initiation Response

Sample Response for Case 1: Refund initiated successfully

{
    "refundId": "OMRxxxxx"
    "amount": 1234,
    "state": "PENDING"
}

Response Parameters

Field Name	Data Type	Description
`refundId`	String	Payment Gateway generated internal order ID.
`amount`	Long	Refund amount specified in paisa.
`state`	String	Indicates the current state of the refund process. Expected value: PENDING.

Try it yourself!

headers

body params

Check Refund Status

Refund status provides information about the current progress of a refund request. It helps track whether the refund is still pending, completed, or failed, ensuring that merchants can monitor and manage the refund process effectively.

Environment	HTTP Method	API
Sandbox	`GET`	https://api-preprod.phonepe.com/apis/pg-sandbox/payments/v2/refund/{merchantRefundId}/status
Production	`GET`	https://api.phonepe.com/apis/pg/payments/v2/refund/{merchantRefundId}/status

Refund Status Request

Request Headers

Header Name	Header Value
Content-Type	application/json
Authorization	O-Bearer <merchant-auth-token>

Refund Status Response

Sample Response for Case 1: Original source of transaction = UPI

{
    "originalMerchantOrderId": "Order123",
    "amount": 100,
    "state": "COMPLETED",
    "timestamp": 1730869961754,
    "refundId": "OMR7878098045517540996",
    "errorCode": "", // Only present in case of ERROR
    "detailedErrorCode": "",   // Only present in case of ERROR
    "splitInstruments": [
        {
            "amount": 100,
            "rail": {
                "type": "UPI",
                "utr": "586756785",
                "upiTransactionId": "YBL5bc011fa9f8644763b52b96a29a9655",
                "vpa": "12****78@ybl"
            },
            "instrument": {
                "type": "ACCOUNT",
                "maskedAccountNumber": "******1234",
                "accountType": "SAVINGS"
            }
        }
    ]
}

Sample Response for Case 2: Original source of transaction = PPE_INTENT

{
    "originalMerchantOrderId": "Order123",
    "amount": 500,
    "state": "COMPLETED",
    "timestamp": 1730869961754,
    "refundId": "OMR7878098045517540996",
    "errorCode": "", // Only present in case of ERROR
    "detailedErrorCode": "",   // Only present in case of ERROR
    "splitInstruments": [
        {
            "rail": {
                "type": "UPI",
                "utr": "586756785",
                "upiTransactionId": "YBL5bc011fa9f8644763b52b96a29a9655",
                "vpa": "12****78@ybl"
            },
            "instrument": {
                "type": "ACCOUNT",
                "maskedAccountNumber": "******1234",
                "accountType": "SAVINGS"
            },
            "amount": 400
        },
        {
            "rail": {
                "type": "WALLET"
            },
            "instrument": {
                "type": "WALLET"
            },
            "amount": 100
        }
    ]
}

Response Parameters

Field Name	Data Type	Description
originalMerchantOrderId	String	The original merchant order ID is used to identify the transaction for which the refund is being processed.
amount	String	The amount to be refunded, specified in paisa.
`state`	String	Refund state, Expected values: • PENDING • CONFIRMED • COMPLETED • FAILED
`timestamp`	Long	Timestamp of the transaction attempt in epoch (in milliseconds).
`refundId`	String	Refund Id generated by PhonePe.
`errorCode`	String	Error code returned only if the transaction state is FAILED.
`detailedErrorCode`	String	Detailed error code returned only when the transaction state is FAILED.
`splitInstruments.rail`	String	Includes details of the processing rail used for the payment attempt.
`splitInstruments.rail.type`	String	Specifies the type of processing rail used. Expected values: • UPI • PG
`splitInstruments.instrument`	String	Includes the details of the payment instrument used for the transaction.
`splitInstruments.instrument.type`	String	Specifies the type of payment instrument used. Expected values: • ACCOUNT • CREDIT_CARD • DEBIT_CARD • NET_BANKING

Try it yourself!

headers

url params

You can also test this API request directly in Postman for a quick and easy integration check.

What’s Next?

In this section, you’ve learned how to initiate a refund and check its status. In the next section, you’ll understand how payment verification is handled using webhooks, and how to manually verify the payment in case the webhook callback fails.