Refund

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.CustomCheckoutClient;
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
 
CustomCheckoutClient customCheckoutClient = CustomCheckoutClient.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 = customCheckoutClient.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.

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.

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.CustomCheckoutClient;
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
CustomCheckoutClient customCheckoutClient = CustomCheckoutClient.getInstance(clientId, clientSecret,
        clientVersion, env);
 
String refundId = "<refundId>";
 
RefundStatusResponse refundStatusResponse = customCheckoutClient.getRefundStatus(refundId);
String state = refundStatusResponse.getState();

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