Initiate and Verify Refunds with Python SDK

This section explains how to initiate a refund for a successful transaction using 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 RefundRequest.build_refund_request() 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.build_refund_request() to create the refund request and the following are the attributes that merchant can pass.

Parameter Name	Data Type	Mandatory (Yes/No)	Description
`merchant_refund_id`	String	Yes	Unique refund ID assigned by you
`original_merchant_order_id`	String	Yes	The original order ID against which the refund is requested
`amount`	Integer	Yes	Refund amount in paisa. Must be at least 100 paisa and not exceed the order amount

Sample Request

from uuid import uuid4
from phonepe.sdk.pg.payments.v2.standard_checkout_client import StandardCheckoutClient
from phonepe.sdk.pg.common.models.request.refund_request import RefundRequest
from phonepe.sdk.pg.env import Env
 
client_id = "<YOUR_CLIENT_ID>"
client_secret = "<YOUR_CLIENT_SECRET>"
client_version = <CLIENT_VERSION>  # Insert your client version here
env = Env.SANDBOX  # Change to Env.PRODUCTION when you go live
should_publish_events = False
 
client = StandardCheckoutClient.get_instance(client_id=client_id,
                                                              client_secret=client_secret,
                                                              client_version=client_version,
                                                              env=env,
                                                              should_publish_events=should_publish_events)

unique_merchant_refund_id = str(uuid4())
original_merchant_order_id = "<YOUR_ORDER_ID_TO_REFUND>"
amount = 100
refund_request = RefundRequest.build_refund_request(merchant_refund_id=unique_merchant_refund_id,
                                                    original_merchant_order_id=original_merchant_order_id,
                                                    amount=amount)
refund_response = client.refund(refund_request=refund_request)
refund_state = refund_response.state

⚠️ 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
`refund_id`	String	Refund ID generated by PhonePe PG.
`state`	String	The status of the refund.
`amount`	Integer	The refunded 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. 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

Request Parameters

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

Sample Request

from uuid import uuid4
from phonepe.sdk.pg.payments.v2.standard_checkout_client import StandardCheckoutClient
from phonepe.sdk.pg.env import Env
 
client_id = "<YOUR_CLIENT_ID>"
client_secret = "<YOUR_CLIENT_SECRET>"
client_version = <CLIENT_VERSION>  # Insert your client version here
env = Env.SANDBOX  # Change to Env.PRODUCTION when you go live
should_publish_events = False
 
client = StandardCheckoutClient.get_instance(client_id=client_id,
                                                              client_secret=client_secret,
                                                              client_version=client_version,
                                                              env=env,
                                                              should_publish_events=should_publish_events)

unqiue_merchant_refund_id = "<INSERT_YOUR_REFUND_ID>"  # replace with your refund id
refund_response = client.get_refund_status(merchant_refund_id=unqiue_merchant_refund_id)
refund_state = refund_response.state

Refund Status Response

It returns a RefundStatusResponse Object.

RefundStatusResponse

Parameter Name	Data Type	Description
`merchant_id`	String	Your merchant ID
`merchant_refund_id`	String	The refund ID assigned by you
`original_merchant_order_id`	String	The order ID for which the refund was initiated
`amount`	Integer	Refund amount (in paisa)
`state`	String	The current status of the refund
`payment_details`	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:

Parameter Name	Data Type	Description
`transaction_id`	String	The transaction ID generated by PhonePe PG.
`payment_mode`	String	The payment method used: • UPI_INTENT • UPI_COLLECT • UPI_QR • CARD • TOKEN • NET_BANKING
`timestamp`	Integer	The timestamp of the transaction attempt in epoch.
`state`	String	Status of the transaction: • PENDING • COMPLETED • FAILED
`error_code`	String	Error code(only if the transaction failed)
`detailed_error_code`	String	A more detailed error code(only if the transaction failed)
`split_instruments`	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.