Handle Webhooks with Python SDK

Use callback verification to confirm that the callback you received from PhonePe is authentic.

The validateCallback() method is used to validate webhook or callback responses. You can use this method by passing all the necessary parameters.

Request

Request Parameters

Parameter Name	Data Type	Mandatory (Yes/NO)	Description
`username`	String	Yes	Your unique username configured for the callback URL
`password`	String	Yes	Your unique password configured for the callback URL
`authorization`	String	Yes	Value of the Authorization header under the callback response.
`responseBody`	String	Yes	The response body received in the callback as a string

Sample Request

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)
 
authorization_header_data = "ef4c914c591698b268db3c64163eafda7209a630f236ebf0eebf045460df723a"  # header value under `Authorization` key
phonepe_s2s_callback_response_body_string = """{"event": "pg.refund.completed","payload": {}}"""  # callback body as string
 
username_configured = "MERCHANT_USERNAME"
password_configured = "MERCHANT_PASSWORD"
 
callback_response = client.validate_callback(username=username_configured,
                                                              password=password_configured,
                                                              callback_header_data=authorization_header_data,
                                                              callback_response_data=phonepe_s2s_callback_response_body_string)
callback_event = callback_response.event
merchant_refund_id = callback_response.payload.merchant_refund_id
state = callback_response.payload.state

Response

The function returns a CallbackResponse object containing two main parameters: type, which indicates the event type, and payload, which holds all the event-specific details.

Parameter Name	Data Type	Description
type	CallbackType	Tells you what type of event happened (e.g., order completed, refund failed, etc.)
payload	CallbackData	Contains all the details related to that event

The events are explained below:

Event	Description
`checkout.order.completed`	The payment was successfully completed
`checkout.order.failed`	The payment failed
`pg.refund.completed`	A refund was successfully processed
`pg.refund.failed`	A refund request failed

The payload details are explained below:

Parameter Name	Data Type	Description
`merchantId`	String	Merchant ID from which the request was initiated
`orderId`	String	Order ID generated by PhonePe Payment Gateway (only for order callbacks)
`originalMerchantOrderId`	String	Order ID generated by you (only for order callbacks)
`refundId`	String	Refund ID generated by PhonePe PG (only for refund callbacks)
merchantRefundId	String	Refund ID generated by you (only for refund callbacks)
`state`	String	The current state of the order or refund.
`amount`	Long	The amount processed in paisa.
`expireAt`	Long	The expiry timestamp in epoch format
`errorCode`	String	The error code (only for failed transactions)
`detailedErrorCode`	String	A more detailed error code (only for failures)
`metaInfo`	MetaInfo	Metadata passed during order initialization
`paymentDetails`	List<PaymentDetail>	The Payment details of the transaction

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.

Attribute	Data Type	Description
`transactionId`	String	PhonePe Reference ID from which the request was initiated
`paymentMode`	String	Mode of payment; Expected Values: • UPI_INTENT • UPI_COLLECT • UPI_QR • CARD • NET_BANKING
`timestamp`	Long	Transaction attempt timestamp in epoch
`state`	String	Attempted transaction state. It can be any one of the following states: • COMPLETED • FAILED • PENDING
`errorCode`	String	Error code (only present when the state is failed)
`detailedErrorCode`	String	A more specific error code (only present when the state is failed)

InstrumentCombo
- Represents a combination of the payment instrument and the payment rail used to complete a transaction.

Property Parameters

Property	Type
`instrument`	PaymentInstrumentV2	Instrument used for the payment.
`rails`	PaymentRail	Rail used for the payment.
`amount`	long	Amount transferred using the above instrument and rail.

PaymentRail
- Defines the type of rail used to initiate payment.

UPI RAIL

Property	Type
`type`	PaymentRailType
`utr`	String
`upi_transaction_id`	String
`vpa`	String

PG RAIL

Property	Type
`type`	PaymentRailType
`transaction_id`	String
`authorization_code`	String
`service_transaction_id`	String

PaymentInstrumentV2
- Represents the instrument used to initiate a payment. Various instrument types are listed below:

ACCOUNT

Property	Type
`type`	PaymentInstrumentType
`ifsc`	String
`account_type`	String
`masked_account_number`	String
`account_holder_name`	String

CREDIT_CARD

Property	Type
`type`	PaymentInstrumentType
`bank_transaction_id`	String
`bank_id`	String
`arn`	String
`brn`	String

DEBIT_CARD

Property	Type
`type`	PaymentInstrumentType
`bank_transaction_id`	String
`bank_id`	String
`arn`	String
`brn`	String

NET_BANKING

Property	Type
`type`	PaymentInstrumentType
`bank_transaction_id`	String
`bank_id`	String
`arn`	String
`brn`	String

Exception Handling

Exception handling in the PhonePe SDK is managed through the PhonePeException, which captures errors related to PhonePe APIs. It provides detailed information such as HTTP status code, error code, message, and additional error data to help identify and resolve issues effectively.

PhonePeException

Exception raised for errors related to PhonePe APIs.

Attribute	Type	Description
`message`	String	The http error message.
`http_status_code`	Integer	The status code of the http response.

Sample Request

from phonepe.sdk.pg.common.exceptions import PhonePeException
 
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)

try:
    callback_valid = client.validate_callback(username="username_configured",
                                                               password="password_configured",
                                                               callback_header_data="ef4c914c591698b268db3c64163eafda7209a630f236ebf0eebf045460df723a",
                                                               callback_response_data="phonepe_s2s_callback_response_body_string")
except PhonePeException as exception:
    print(exception.http_status_code)
    print(exception.message)

What’s Next?

Now that you have learned how to verify the payment and what happens when the webhook fails, this concludes your website integration. The next step is to complete UAT testing and understand the process to go live.