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>

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.

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

Initiate a Sample Refund!

headers

body params

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

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