Webhook Handling

PhonePe Payment Gateway uses Webhook (S2S Callbacks) to notify you about key events like payment completion or refund status. Here’s how it works:

You need to provide a Webhook URL (a specific endpoint on your server) where these updates will be sent.
To ensure secure communication, you should set up a username and password for authentication.

Webhook Setup

Configure Webhook: Follow these steps to set up a new webhook for receiving event notifications.
- Log in to your PhonePe Business Dashboard.
- Set the environment mode using the Test Mode toggle located on the dashboard.
  - For Sandbox (Testing): Ensure the toggle is switched ON.
  - For Production (Live): Ensure the toggle is switched OFF.
- Navigate to Developer Settings from the side menu.
- Select the Webhook tab and click the Create Webhook button.
- In the configuration form, fill in the following details:
  - Webhook URL: Your server’s endpoint URL to receive notifications.
  - Username: Your authentication username.
  - Password: Your authentication password.
  - Description: A brief description for your reference.
- From the list of active events, choose:
  - payment.dispute.created
  - payment.dispute.won
  - payment.dispute.lost
  - payment.dispute.under_review
  - payment.dispute.action_required
- Click Create to save and complete the configuration.
- Your webhook is now active.
Authorization.
- Once configured, PhonePe Payment Gateway will send updates to your server using the provided username and password.
- These credentials will be used to create an Authorization header in the webhook response using SHA256 (username:password) method.
Verification.
- For the incoming request, extract the header Authorization, verify it with the one which you have shared with us and accept the response if the Username and password match.
- If the hash matches the one sent by PhonePe Payment Gateway, the update is valid, and the response payload can be consumed.
- If it doesn’t match, the response should be ignored.

ℹ️ Authorization Header!

PhonePe Payment Gateway includes the Authorization header in the following format:
Authorization: SHA256(username:password)

📘 Accessing Your Credentials

When the payment.dispute.created callback is sent, the status will be UNDER_REVIEW. The system will then verify whether the dispute is valid.
If the dispute is valid, another callback payment.dispute.action_required will be sent with the status ACTION_REQUIRED.
If the dispute is not valid, no further callback will be sent.

Webhook Response

Sample Response

{
  "event": "payment.dispute.under_review",
  "payload": {      
        "merchantId": "MId",
        "disputeId": "D1234",
        "merchantOrderId": "MO2329",
        "orderId": "OMO241",
        "transactionId": "OM4564",
        "transactionCompletedAt": <epoch-timestamp>,
        "transactionAmount": 1000,
        "disputeAmount": 1000,
        "refundAmount": 1000,
        "contestAmount": 0,
        "status": "LOST",   
        "stage": "CHARGEBACK",
        "dueDate": <epoch-timestamp>,
        "createdAt": <epoch-timestamp>,
        "updatedAt": <epoch-timestamp>,   
        "evidences": {
            "explanationLetter": [{
                "evidenceId": "D1",
                "label" : "dummmy"
            }]
        }
    }
}

Response Parameters

Parameter Name	Type	Description
`merchantId`	String	Unique `MerchantID` assigned to the merchant by PhonePe Note: merchantId length will be less than 38 characters.
`disputeId`	String	Unique DisputeId assigned to a dispute
`merchantOrderId`	String	Unique merchant order id generated by merchant
`orderId`	String	PhonePe generated order Id
`transactionId`	String	Unique transaction id generated by phonepe
`transactionCompletedAt`	Long	Epoch timestamp of the transaction completion time (in milliseconds)
`transactionAmount`	Long	Amount of the transaction
`disputeAmount`	Long	Amount for which dispute is raised, will be lesser than or equal to transactionAmount
`refundAmount`	Long	After the status of dispute moved to LOST or WON, The amount that is given back to the customer
`contestAmount`	Long	Amount for which merchant does the contest
`status`	Enum	Status of the dispute Note: The value could be “ACTION_REQUIRED”, “UNDER_REVIEW”, “WON” or “LOST”
`stage`	Enum	Stage of the dispute Note: The value could be “CHARGEBACK” or “PRE_ARBITRATION”
`dueDate`	Long	Epoch timestamp the last date to respond for a dispute for merchant (in milliseconds)
`createdAt`	Long	Epoch timestamp, Creation date of the dispute (in milliseconds)
`updatedAt`	Long	Epoch timestamp, Last updated date of a dispute (in milliseconds)
`evidences`	Object	Map of String and List containing the type as key and List of evidence object as value that merchant uploaded by upload evidence api