Initiate Refund and Check Refund Status

Refunds can be initiated using the SDK by building a refund request and calling the refund() method.
To check the status of a refund, use the getRefundStatus() function with the refund ID. Responses include details like refund ID, amount, and current status.
This enables smooth and trackable refund handling within the application.

Initiate Refund

The refund() method is used to start the refund process by passing parameters through the RefundRequest.builder() function.

Initiating Refund Request

Attribute	Data Type	Mandatory	Description	Constraints
`merchantOrderId`	String	Yes	Unique order ID generated by the merchant.	Max Length = 63 characters
`originalMerchantOrderId`	String	Yes	Original merchant order ID for which the refund is requested.
`amount`	Long	Yes	Refund amount in paisa.	Min value = 100 (in paise), Max value = order amount.

Code Reference

import com.phonepe.sdk.pg.Env;
import com.phonepe.sdk.pg.common.models.request.RefundRequest;
import com.phonepe.sdk.pg.common.models.response.RefundResponse;
import com.phonepe.sdk.pg.subscription.v2.SubscriptionClient;
 
String clientId = "<clientId>";
String clientSecret = "<clientSecret>";
Integer clientVersion = <clientVersion>;  //insert your client version here
Env env = Env.SANDBOX;      //change to Env.PRODUCTION when you go live
 
SubscriptionClient subscriptionClient = SubscriptionClient.getInstance(clientId, clientSecret,
        clientVersion, env);
 
String merchantRefundId = UUID.randomUUID()
        .toString();
String originalMerchantOrderId = "<merchantOrderId>";
long amount = 100;
 
RefundRequest refundRequest = RefundRequest.Builder()
        .merchantRefundId(merchantRefundId)
        .originalMerchantOrderId(merchantOrderId)
        .amount(amount)
        .build();
 
RefundResponse refundResponse = subscriptionClient.refund(refundRequest);
String state = refundResponse.getState();

Refund Initiation Response

The function returns a RefundResponse object with the following properties:

Parameter Name	Data Type	Description
`refundId`	String	PhonePe generated internal refund id.
`state`	String	The status of the initiated refund. It will initially be “PENDING”
`amount`	Long	The amount, in paisa, that will be refunded.

Check Refund Status

The getRefundStatus() method is used to check the current status of the initiated refund.

Refund Status Request

Attribute	Data Type	Mandatory	Description
`refundId`	String	Yes	Refund ID created by the merchant when initiating the refund request.

Code Reference

import com.phonepe.sdk.pg.Env;
import com.phonepe.sdk.pg.common.models.response.RefundStatusResponse;
import com.phonepe.sdk.pg.subscription.v2.SubscriptionClient;
 
String clientId = "<clientId>";
String clientSecret = "<clientSecret>";
Integer clientVersion = <clientVersion>;  //insert your client version here
Env env = Env.SANDBOX;      //change to Env.PRODUCTION when you go live
 
SubscriptionClient subscriptionClient = SubscriptionClient.getInstance(clientId, clientSecret,
        clientVersion, env);
 
String refundId = "<REFUND_ID>";
 
RefundStatusResponse refundStatusResponse = subscriptionClient.getRefundStatus(refundId);
String state = refundStatusResponse.getState();

Refund Status Response

The function returns a RefundStatusResponse object with the following properties:

Parameter Name	Data Type	Description
`merchantId`	String	The ID of the merchant who initiated the refund.
`merchantRefundId`	String	Refund ID created by the merchant when initiating the refund.
`originalMerchantOrderId`	String	Order ID for which the refund was initiated, created by the merchant during order creation.
`amount`	Long	The amount to be refunded.
`state`	String	The current state of the refund process.
`paymentDetails`	List<PaymentRefundDetail>	A list containing details of each transaction attempt made for this specific refund order.

The PaymentRefundDetail property contains a list of payment details for each payment attempt made against an order. The details of each payment are explained in the table below.

Parameter Name	Data Type	Description
`transactionId`	String	Unique transaction ID generated by PhonePe.
`paymentMode`	String	The mode of payment used for the transaction. It can be one of the following: • UPI_INTENT • UPI_COLLECT • UPI_QR • CARD • TOKEN • NET_BANKING
`timestamp`	Long	The timestamp of the transaction attempt, provided in epoch (in milliseconds)
`state`	String	The state of the attempted transaction. Possible values include: • COMPLETED • FAILED • PENDING
`errorCode`	String	The error code present only when the transaction state is “FAILED.”
`detailedErrorCode`	String	A detailed error code present when the transaction state is “FAILED.”
`rail`	PaymentRail	Contains the processing rail details under which the transaction attempt was made.
`instrument`	PaymentInstrumentV2	Contains the instrument details for that particular transaction.
`splitInstruments`	List<InstrumentCombo>	Types of transaction instruments involved. It can be one of the following: • ACCOUNT • CREDIT_CARD • DEBIT_CARD • NET_BANKING

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.