Initiate and Verify Refunds with Java SDK

This section explains how to initiate a refund for a successful transaction using the Initiate Refund. You need to provide details like the original transaction ID, refund amount, and refund ID. After initiating the refund, you can use Refund Status 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

Use the refund() function to initiate a refund. This ensures the amount is returned to the customer’s original payment method.

Initiating Refund Request

You can use the RefundRequest Builder() to create the refund request and the following are the attributes that merchant can pass.

Parameter Name	Data Type	Mandatory (Yes/No)	Description	Constraints
`merchantRefundId`	String	Yes	Unique refund ID assigned by you	Max Length = 63 characters
`originalMerchantOrderId`	String	Yes	The original order ID against which the refund is requested
`amount`	Long	Yes	Refund amount in paisa.	Min value = 100 (in paise), Max value = order amount.

Sample Request

import com.phonepe.sdk.pg.Env;
import com.phonepe.sdk.pg.payments.v2.StandardCheckoutClient;
import com.phonepe.sdk.pg.common.models.request.RefundRequest;
import com.phonepe.sdk.pg.common.models.response.RefundResponse;
 
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
 
StandardCheckoutClient client = StandardCheckoutClient.getInstance(clientId, clientSecret,
        clientVersion, env);
 
String merchantRefundId = UUID.randomUUID()
        .toString();
String originalMerchantOrderId = "<merchantOrderId>";  //orderId for which refund should be initiated
long amount = 100;
 
RefundRequest refundRequest = RefundRequest.Builder()
        .merchantRefundId(merchantRefundId)
        .originalMerchantOrderId(merchantOrderId)
        .amount(amount)
        .build();
 
RefundResponse refundResponse = client.refund(refundRequest);
String state = refundResponse.getState();

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

The function returns a RefundResponse Object:

Parameter Name	Data Type	Description
`refundId`	String	Refund ID generated by PhonePe PG.
`state`	String	The state of the refund initiated. Initially it will be PENDING.
`amount`	Long	Refund amount in paisa.

Check Refund Status

Refund Status is used to retrieve the current status and details of a refund request made against a payment. By calling the getRefundStatus() function with the refund ID, you can track whether the refund is pending, successful, or failed, enabling you to manage and update refund workflows accordingly.

Refund Status Request

Pass the below parameter to get the refund status in getRefundStatus() :

Request Parameters

Parameter Name	Data Type	Mandatory	Description
`refundId`	String	Yes	Refund ID assigned by you at the time of refund initiation.

Sample Request

import com.phonepe.sdk.pg.Env;
import com.phonepe.sdk.pg.payments.v2.StandardCheckoutClient;
import com.phonepe.sdk.pg.common.models.response.RefundStatusResponse;
 
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
 
StandardCheckoutClient client = StandardCheckoutClient.getInstance(clientId, clientSecret,
        clientVersion, env);
 
String refundId = "<refundId>";    //refundId used at the time of initiating refund
 
RefundStatusResponse refundStatusResponse = client.getRefundStatus(refundId);
String state = refundStatusResponse.getState();

Refund Status Response

It returns a RefundStatusResponse Object:

Object Properties

Properties	Data Type	Description
`merchantId`	String	Merchant Id who initiated the refund.
`merchantRefundId`	String	Refund Id created by you at the time of refund initiation.
`originalMerchantOrderId`	String	The order ID for which the refund was initiated.
`amount`	Long	Refund amount (in paisa).
`state`	String	The status of the refund.
`paymentDetails`	List<PaymentRefundDetail>	List of transaction attempts related to the refund.

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:

Property	Data Type	Description
`transactionId`	String	The transaction ID generated by PhonePe PG.
`paymentMode`	String	The payment method used • UPI_INTENT • UPI_COLLECT • UPI_QR • CARD • TOKEN • NET_BANKING
timestamp	Long	Timestamp of the attempted transaction in epoch.
`state`	String	Attempted transaction state. It can be any one of the following states: • PENDING • COMPLETED • FAILED
`errorCode`	String	Error code (only if the transaction failed)
`detailedErrorCode`	String	A more detailed error code (only if the transaction failed)
`splitInstruments`	list<InstrumentCombo>	Payment instruments used: • 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.