Refund and Refund Status 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

Request

Request Headers

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

Request Parameters

Parameter Name	Data Type	Description
`merchantRefundId`	String	Unique merchant refund ID generated by the merchant
`originalMerchantOrderId`	String	Original merchant order ID against which refund is required
`amount`	Long	Amount in paisa to refund

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.

Response

Sample Response

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

Try to refund!

headers

body params

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

Path Parameters

Parameter Name	Description
`merchantRefundId`	The Merchant Refund ID for which the status is to be retrieved

Refund Status Response

Sample Response

{
  "originalMerchantOrderId": "",
  "refundId": "OMRxxxxx",
  "amount": 1234,
  "state": "FAILED",
  "errorCode": "INTERNAL_SERVER_ERROR",
  "detailedErrorCode": "",
  "rail": {
    "type": "UPI",
    "upiTransactionId": "upi12313",
    "vpa": "12****78@ybl"
  },
  "instrument": {
    "type": "ACCOUNT",
    "accountType": "SAVINGS",
    "accountNumber": "******1234"
  }
}

Check the Refund Status!

headers

url params

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.