Initiate and Verify Refunds with PHP 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 StandardCheckoutRefundRequestBuilder::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.

Sample Request

<?php

use PhonePe\payments\v2\models\request\builders\StandardCheckoutRefundRequestBuilder;

$merchantRefundId = "REFUND_" . time(); // Unique refund ID from your system
$originalMerchantOrderId = "YOUR_ORIGINAL_MERCHANT_ORDER_ID"; // The order ID you are refunding
$amount = 500; // Amount to refund in paisa (e.g., 500 = ₹5.00)

$refundRequest = StandardCheckoutRefundRequestBuilder::builder()
    ->merchantRefundId($merchantRefundId)
    ->originalMerchantOrderId($originalMerchantOrderId)
    ->amount($amount)
    ->build();
?>

Call the refund() Method

<?php

require_once "vendor/autoload.php"; // Include Composer autoloader

use PhonePe\payments\v2\standardCheckout\StandardCheckoutClient;
use PhonePe\Env;

$clientId = "YOUR_CLIENT_ID"; // Replace with your Client ID
$clientVersion = CLIENT_VERSION; // Replace with your Client Version
$clientSecret = "YOUR_CLIENT_SECRET"; // Replace with your Client Secret
$env = Env::PRODUCTION;

$standardCheckoutClient = StandardCheckoutClient::getInstance(
    $clientId,
    $clientVersion,
    $clientSecret,
    $env
);

try {
    $refundResponse = $standardCheckoutClient->refund($refundRequest);

    // Handle the response
    echo "Refund ID: " . $refundResponse->getRefundId() . "\n";
    echo "Refund Amount: " . $refundResponse->getAmount() . "\n";
    echo "Refund State: " . $refundResponse->getState() . "\n";
} catch (\PhonePe\common\exceptions\PhonePeException $e) {
    // Handle exceptions (e.g., log the error)
    echo "Error initiating refund: " . $e->getMessage();
}
?>

⚠️ 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 StandardCheckoutRefundResponse Object.

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

Pass the refundId parameter to getRefundStatus() :

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

Sample Request

<?php

require_once "vendor/autoload.php"; // Include Composer autoloader

use PhonePe\payments\v2\standardCheckout\StandardCheckoutClient;
use PhonePe\Env;

$clientId = "YOUR_CLIENT_ID"; // Replace with your Client ID
$clientVersion = CLIENT_VERSION; // Replace with your Client Version
$clientSecret = "YOUR_CLIENT_SECRET"; // Replace with your Client Secret
$env = Env::PRODUCTION;

$client = StandardCheckoutClient::getInstance(
    $clientId,
    $clientVersion,
    $clientSecret,
    $env
);

$merchantRefundId = "YOUR_MERCHANT_REFUND_ID"; // Replace with the refund ID you want to check

try {
    $refundStatusCheckResponse = $client->getRefundStatus(
        $merchantRefundId
    );

    // Process the refund status check response
    echo "Refund ID: " . $refundStatusCheckResponse->getRefundId() . "\n";
    echo "State: " . $refundStatusCheckResponse->getState() . "\n";
    echo "Amount: " . $refundStatusCheckResponse->getAmount() . "\n";
} catch (\PhonePe\common\exceptions\PhonePeException $e) {
    // Handle exceptions (e.g., log the error)
    echo "Error checking refund status: " . $e->getMessage();
}
?>

Refund Status Response

It returns a RefundStatusCheckResponse Object:

Property	Data Type	Description
`originalMerchantOrderId`	String	Order ID for which refund has initiated. Created at the time of order creation.
`merchantRefundId`	String	The refund ID created at the time of refund initiation.
`state`	String	The status of the refund.
`amount`	Long	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.