Refund Status

This API is used to check the refund status.

Host Details

EnvironmentHttp MethodValue
UATGEThttps://api-preprod.phonepe.com/apis/pg-sandbox
PRODGEThttps://api.phonepe.com/apis/pg

Endpoint

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

Complete Host Details

EnvironmentHttp MethodValue
UATGEThttps://api-preprod.phonepe.com/apis/pg-sandbox/payments/v2/refund/{merchantRefundId}/status
PRODGEThttps://api.phonepe.com/apis/pg/payments/v2/refund/{merchantRefundId}/status
anchor image
Copied !

Request Headers

Header NameHeader Value
Content-Typeapplication/json
AuthorizationO-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.
anchor image
Copied !

Response Headers:

Header NameHeader Value
Content-Typeapplication/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 NameData TypeDescription
originalMerchantOrderIdStringoriginal merchant order id against which refund is initiated
amountStringAmount in paisa to refund
stateStringrefund state, Expected values = [PENDING, CONFIRMED, COMPLETED, FAILED]
timestampLongTransaction attempt timestamp in epoch (in milliseconds)
refundIdStringRefund Id generated by PhonePe
errorCodeStringError code (Only present when transaction state is failed)
detailedErrorCodeStringDetailed Error Code (Only present when transaction state is failed)
splitInstruments.railStringContains processing rail details under which payment attempt is made.
splitInstruments.rail.typeStringType of rail. Expected values = [UPI, PG]
splitInstruments.instrumentStringContains instrument details
splitInstruments.instrument.typeStringType 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