Refund APIs

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

Try it yourself!

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.

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

Refund Status API

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

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

Refund Status Request

Request Headers

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

Try it yourself!

headers

url params

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