Initiate and Verify Refunds

Initiate Refund

Payment Link Refund allows you to return funds to customers for payments made through a payment link. You can easily initiate the refund and track its status through the API.

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>

⚠️ For Partner Integrations!

It is mandatory to include the X-MERCHANT-ID header with the MerchantID of the end merchant.

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 = 100

Initiate a Sample Refund!

headers

body params

⚠️ 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

Response for 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.

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>

Fetch Refund Status!

headers

url params

Refund Status Response

Case 1: Response for 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"
            }
        }
    ]
}

Case 2: Response for 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

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.