Initiate and Verify Refunds with Node.js SDK

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

Initiate 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`	Integer	Yes	Refund amount in paisa. Must be at least 1 paisa and not exceed the order amount.	Min value = 100 (in Paise), Max value = order amount.

⚠️ Invalid Refund Amount!

The refund amount cannot exceed the initiated amount. It must always be less than or equal to the amount originally initiated.

Sample Request

import { StandardCheckoutClient, Env, RefundRequest } from 'pg-sdk-node';
import { randomUUID } from 'crypto';
 
const clientId = "<clientId>";
const clientSecret = "<clientSecret>";
const clientVersion = <clientVersion>;  //insert your client version here
const env = Env.SANDBOX;      //change to Env.PRODUCTION when you go live
 
const client = StandardCheckoutClient.getInstance(clientId, clientSecret, clientVersion, env);
 
const refundId = randomUUID();
const originalMerchantOrderId = '<MERCHANT_ORDER_ID>';    //merchantOrderId for which order has to be initiated
const amount = 100                                      //amount to be refund
 
const request = RefundRequest.builder()
    .amount(amount)
    .merchantRefundId(refundId)
    .originalMerchantOrderId(originalMerchantOrderId)
    .build();
 
client.refund(request).then((response) => {
    const state = response.state
})

Refund Initiation Response

The function returns a RefundResponse object with the following properties:

Property	Data Type	Description
`refundId`	String	Refund ID generated by PhonePe PG.
state	String	The status of the refund.
amount	Long	The refunded amount (in paisa).

Check Refund Status

It is used to retrieve the status of a refund using getRefundStatus() function.

Refund Status Request

Request Parameters

Parameter Name	Data Type	Mandatory (Yes/No)	Description
`refundId`	String	Yes	Refund ID assigned by you at the time of initiation

Sample Request

import {StandardCheckoutClient, Env} from 'pg-sdk-node';
 
const clientId = "<clientId>";
const clientSecret = "<clientSecret>";
const clientVersion = <clientVersion>;  //insert your client version here
const env = Env.SANDBOX;      //change to Env.PRODUCTION when you go live
 
const client = StandardCheckoutClient.getInstance(clientId, clientSecret, clientVersion, env);
 
const refundId = '<REFUND_ID>'; //refundId used to initiate the refund
 
client.getRefundStatus(refundId).then((response) => {
    const state = response.state
})

Refund Status Response

It returns a RefundStatusResponse Object.

Response Parameters

Property	Data Type	Description
`merchantId`	String	Order ID generated by PhonePe PG.
`merchantRefundId`	String	The refund ID created at the time of refund initiation.
`state`	String	The status of the refund.
`amount`	Integer	Amount to refund.
`paymentDetails`	List<PaymentRefundDetail>	List of payment attempt details corresponding to the 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.

Property	Data Type	Description
`transactionId`	Integer	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.
`amount`	Integer	Order amount in paisa.
`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>	Contains split instrument details of all the transactions made.

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.