Refund Status

This API is used to check the refund status.

Host Details

Environment	Http Method	Value
`UAT`	GET	https://api-preprod.phonepe.com/apis/pg-sandbox
`PROD`	GET	https://api.phonepe.com/apis/pg

Endpoint

/payments/v2/refund/{merchantRefundId}/status – Endpoint is common for UAT and Production.

Complete Host Details

Environment	Http Method	Value
`UAT`	GET	https://api-preprod.phonepe.com/apis/pg-sandbox/payments/v2/refund/{merchantRefundId}/status
`PROD`	GET	https://api.phonepe.com/apis/pg/payments/v2/refund/{merchantRefundId}/status

Request Details

Copied !

Request Headers

Header Name	Header Value
`Content-Type`	application/json
`Authorization`	O-Bearer <access_token>

Header details :

Content-Type – Its value should be always application/json, meaning this API responds to only when content is in format of application/json
Authorization – This should be the auth token that you have received from the Auth API.

Response Details

Copied !

Response Headers:

Header Name	Header Value
`Content-Type`	application/json

Response Payload:

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": "abc@ybl"
            },
            "instrument": {
                "type": "ACCOUNT",
                "maskedAccountNumber": "XXXXXXXXXXX7728",
                "accountType": "SAVINGS"
            }
        }
    ]
}

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": "abc@ybl"
            },
            "instrument": {
                "type": "ACCOUNT",
                "maskedAccountNumber": "XXXXXXXXXXX7728",
                "accountType": "SAVINGS"
            },
            "amount": 400
        },
        {
            "rail": {
                "type": "WALLET"
            },
            "instrument": {
                "type": "WALLET"
            },
            "amount": 100
        }
    ]
}

Response Field Details:

Header Name	Data Type	Description
`originalMerchantOrderId`	String	original merchant order id against which refund is initiated
`amount`	String	Amount in paisa to refund
`state`	String	refund state, Expected values = [PENDING, CONFIRMED, COMPLETED, FAILED]
`timestamp`	Long	Transaction attempt timestamp in epoch (in milliseconds)
`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]

NOTE: Order status and refund api are common for SDK and Direct integration