Initiate Refund and Check Refund Status

This section explains how to initiate a refund for a successful transaction using the Refund API. You need to provide details like the original transaction ID, refund amount, and refund ID. After initiating the refund, you can use the Refund Status API to check whether the refund was successful, pending, or failed. These APIs help you manage the full refund lifecycle efficiently. Use them to ensure timely and transparent customer experiences.

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>

⚠️ 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	Unique merchant refund ID generated by the merchant	Max Length = 63 characters
`originalMerchantOrderId`	String	Yes	Original merchant order ID against which refund is required
`amount`	Long	Yes	Amount in paisa to refund	Min Value = 100

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

Case 1: Response for Refund initiated successfully

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

Response Parameters

Field Name	Data Type	Description
`refundId`	String	PG generated internal refund ID
`amount`	Long	Amount in paisa to refund
`state`	String	Refund state; expected value = PENDING

Initiate a Sample Refund!

headers

body params

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

Check Refund Status

The Refund Status API allows you to check the current status of a refund request. It helps you track whether the refund is pending, processed, failed, or completed, enabling you to keep your records up to date and provide accurate information to your customers.

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>

⚠️ For Partner Integrations!

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

Refund Status Response

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"
            }
        }
    ]
}

Case 2: Original source of transaction = PPE_INTENT (Wallet)

{
    "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
        }
    ]
}

Case 3: Original source of transaction = NetBanking

{
    "originalMerchantOrderId": "TX1752742884088",
    "amount": 50,
    "state": "COMPLETED",
    "refundId": "OMR2507211657281836129569",
    "timestamp": 1753097248198,
    "splitInstruments": [
        {
            "instrument": {
                "type": "NET_BANKING",
                "bankId": "SBIN",
                "brn": "brn123"
            },
            "rail": {
                "type": "PG"
            },
            "amount": 50
        }
    ],
    "paymentDetails": [
        {
            "transactionId": "OMR2507211657281836129569",
            "paymentMode": "NET_BANKING",
            "timestamp": 1753097248198,
            "amount": 50,
            "state": "COMPLETED",
            "instrument": {
                "type": "NET_BANKING",
                "bankId": "SBIN"
            },
            "rail": {
                "type": "PG"
            },
            "splitInstruments": [
                {
                    "instrument": {
                        "type": "NET_BANKING",
                        "bankId": "SBIN"
                    },
                    "rail": {
                        "type": "PG"
                    },
                    "amount": 50
                }
            ]
        }
    ]
}

Response Parameters

Field Name	Data Type	Description
`originalMerchantOrderId`	String	Original merchant order ID against which refund is initiated
`amount`	Long	Amount in paisa to refund
`state`	String	Refund state; Expected values: • PENDING • CONFIRMED • COMPLETED • FAILED
`timestamp`	Long	Transaction attempt timestamp in epoch.
`refundId`	String	Refund Id generated by PhonePe.
`errorCode`	String	Error code (Only present when transaction state is failed).
`detailedErrorCode`	String	Detailed Error Code (Only present when transaction state is failed).
`splitInstruments.rail`	String	Contains processing rail details under which payment attempt is made.
`splitInstruments.rail.type`	String	Type of rail. Expected values • UPI • PG
`splitInstruments.instrument`	String	Contains instrument details.
`splitInstruments.instrument.type`	String	Type of payment instrument. Expected values : • ACCOUNT • CREDIT_CARD • DEBIT_CARD • NET_BANKING

Fetch Refund Status!

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.