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, confirmed, failed, or completed, enabling you to keep your records up to date and provide accurate information to your customers.

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

Request

Request Headers

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

Response

Sample Response for Refund Pending

{
    "originalMerchantOrderId": "Refund-12345",
    "amount": 50000,
    "state": "PENDING",
    "timestamp": 1706629419799,
    "refundId": "OMR7896789"
}

Sample Response for Refund Accepted

{
    "originalMerchantOrderId": "Refund-12345",
    "amount": 50000,
    "state": "CONFIRMED",
    "timestamp": 1706629419799,
    "refundId": "OMR7896789"
}

Sample Response for Refund Completed

{
    "originalMerchantOrderId": "Refund-12345",
    "amount": 50000,
    "state": "COMPLETED",
    "timestamp": 1706629419799,
    "refundId": "OMR7896789",
    "errorCode": "", // Only present in case of ERROR
    "detailedErrorCode": "", // Only present in case of ERROR
    "splitInstruments": [
        {
            "rail": {
                "type": "UPI",
                "upiTransactionId": "upi12313",
                "vpa": "12****78@ybl"
            },
            "instrument": {
                "type": "ACCOUNT",
                "accountType": "SAVINGS",
                "maskedAccountNumber": "******1234"
            },
            "amount": 50000
        }
    ]
}

Sample Response for Refund Failed

{
    "originalMerchantOrderId": "Refund-12345",
    "amount": 50000,
    "state": "FAILED",
    "timestamp": 1706629419799,
    "refundId": "OMR7896789",
    "errorCode": "UPI_BACKBONE_ERROR", // Only present in case of ERROR
    "detailedErrorCode": "UPI_1231",   // Only present in case of ERROR
    "splitInstruments": [              // In case of failure this is optional. It may or may not be present.
        {
            "rail": {
                "type": "UPI",
                "upiTransactionId": "upi12313",
                "vpa": "12****78@ybl"
            },
            "instrument": {
                "type": "ACCOUNT",
                "accountType": "SAVINGS",
                "maskedAccountNumber": "******1234"
            },
            "amount": 50000
        }
    ]
}

What’s Next?

The implementation of the refund status completes the development phase of the integration. The next step is to validate the integration’s functionality by conducting testing in the provided UAT environment before proceeding to the Production environment.