Webhook Handling

PhonePe Payment Gateway uses Webhooks (S2S Callbacks) to notify your server about key events, such as payment completion or refund statuses. By providing a specific Webhook URL on your server, PhonePe can push real-time updates directly to your system.

Webhook Setup & Configuration

You can configure your webhook using one of two authentication methods. Both methods follow the same initial setup but require slightly different details on the configuration form.

Using HMAC Authentication: A secure approach that allows the receiver to verify both the authenticity and integrity of the payload using a shared secret key.
Using Basic Authentication (SHA): A method where a configured username and password are hashed (SHA-256) and sent in the authorization header.

Configuration Steps

Follow these steps to set up your webhook:

Log in to your PhonePe Business Dashboard.
Set the Environment Mode using the Test Mode toggle on the dashboard:
- Sandbox (Testing): Switch the toggle ON.
- Production (Live): Switch the toggle OFF.
Navigate to Developer Settings from the side menu.
Select the Webhook tab and click the Create Webhook button.
Fill in the Configuration Details based on your preferred authentication type:
- Option A: HMAC
  - Select Authentication Type as HMAC.
  - Provide your Webhook URL (your server’s endpoint), select the Events you wish to subscribe to, and add a brief Description.
  - Secret Key Generation: Once you click create, a Secret Key will be automatically generated. You can view and access this key at any time by clicking on the created webhook in your dashboard.
  - Editing the Webhook: You can edit an existing webhook at a later time; however, you will only be able to update the Webhook URL, selected Events, and Description.
- Option B: SHA (Username & Password)
  - Select Authentication Type as SHA.
  - Provide your Webhook URL, Username, Password, and a brief Description.
  - Select Active Events.
Click Create to save. Your webhook is now active!

Authorization & Verification

How you verify incoming webhooks depends on the method you chose:

If you chose HMAC:

Credentials: Upon creation of the HMAC webhook, a Checksum Secret Key and a Webhook ID will be generated. You must save these securely on your end.
Authorization: During the transactional flow, PhonePe encrypts the plain text payload using the secret key and transmits two specific parameters in the headers:
- The generated checksum X-phonepe-checksum-key-id
- The phonepe-checksum-signature value.

Verification:

When your server receives the plain text payload, extract the x-phonepe-checksum-key-id and x-phonepe-checksum-signature headers.
Use the x-phonepe-checksum-key-id to identify and retrieve the specific Checksum Secret Key you saved earlier.
Generate your own checksum by encrypting the received plain text payload with that Secret Key.
Compare your generated checksum against the x-phonepe-checksum-signature header. If they match, the payload is valid and authentic. If they do not match, you must reject the payload.

If you chose SHA:

Authorization: PhonePe will use your configured credentials to create an Authorization header in the webhook response using the SHA256(username:password) method.
Verification: For incoming requests, extract the Authorization header. Generate your own hash using the username and password you configured and compare it. If the hashes match, the update is valid. If they do not match, the response should be ignored.

Supported Events

Select only the specific events you need to reduce unnecessary server load and processing “Events.”

Event Name	Trigger Condition
`pg.order.completed`	Sent when an order is successfully completed.
`pg.order.failed`	Sent when an order fails (authorization failed, capture failed, or cancelled).
`pg.transaction.failed`	A transaction attempt fails while order is still `PENDING` (e.g., authorization failure with retries remaining).

Response

Event: pg.transaction.authorized

{
  "type": "PG_TRANSACTION_ATTEMPT_AUTHORIZED",
  "event": "pg.transaction.authorized",
  "payload": {
    "merchantId": "M_001",
    "merchantOrderId": "ORDER_123456",
    "orderId": "OMO2506...",
    "state": "PENDING",
    "currency": "INR",
    "amount": 10000,
    "expireAt": 1750000000000,
    "paymentDetails": [
      {
        "transactionId": "OMT2506...",
        "paymentMode": "UPI_INTENT",
        "state": "AUTHORIZED",
        "amount": 0,
        "currency": "INR",
        "authAmount": 10000,
        "authCurrency": "INR",
        "payableCurrency": "INR",
        "payableAmount": 0,
        "feeCurrency": "INR",
        "feeAmount": 0,
        "timestamp": 1749999000000,
        "instrument": {
          "type": "ACCOUNT",
          "processingRail": "UPI"
        },
        "rail": {
          "type": "UPI"
        }
      }
    ]
  }
}

Event: pg.order.completed

{
    "type": "PG_ORDER_COMPLETED",
    "event": "pg.order.completed",
    "payload": {
        "merchantId": "M_001",
        "merchantOrderId": "ORDER01",
        "orderId": "OMO2607171048305486053103V",
        "state": "COMPLETED",
        "currency": "INR",
        "amount": 100,
        "payableCurrency": "INR",
        "payableAmount": 100,
        "feeCurrency": "INR",
        "feeAmount": 0,
        "expireAt": 1784265990538,
        "paymentDetails": [
            {
                "transactionId": "OM2607171048305656053482V",
                "paymentMode": "UPI_QR",
                "timestamp": 1784265510598,
                "currency": "INR",
                "amount": 100,
                "authAmount": 100,
                "authCurrency": "INR",
                "payableCurrency": "INR",
                "payableAmount": 100,
                "feeCurrency": "INR",
                "feeAmount": 0,
                "state": "COMPLETED",
                "instrument": {
                    "type": "ACCOUNT",
                    "accountType": "SAVINGS",
                    "bankId": "SBIN"
                },
                "rail": {
                    "type": "UPI",
                    "utr": "619821250213",
                    "upiTransactionId": "YBL90bb442e0b7249139237a8cc8b6d7a08"
                },
                "splitInstruments": [
                    {
                        "instrument": {
                            "type": "ACCOUNT",
                            "accountType": "SAVINGS",
                            "bankId": "SBIN"
                        },
                        "rail": {
                            "type": "UPI",
                            "utr": "619821250213",
                            "upiTransactionId": "YBL90bb442e0b7249139237a8cc8b6d7a08"
                        },
                        "currency": "INR",
                        "amount": 100
                    }
                ]
            }
        ]
    }
}

Event: pg.order.failed

{
    "type": "PG_ORDER_FAILED",
    "event": "pg.order.failed",
    "payload": {
        "merchantId": "M_001",
        "merchantOrderId": "ORDER012",
        "orderId": "OMO2607171050501339612835V",
        "state": "FAILED",
        "currency": "INR",
        "amount": 100,
        "expireAt": 1784266130117,
        "errorCode": "INVALID_MPIN",
        "detailedErrorCode": "ZM",
        "paymentDetails": [
            {
                "transactionId": "OM2607171050501509612164V",
                "paymentMode": "UPI_QR",
                "timestamp": 1784265650199,
                "currency": "INR",
                "amount": 0,
                "authAmount": 100,
                "authCurrency": "INR",
                "payableCurrency": "INR",
                "payableAmount": 0,
                "feeCurrency": "INR",
                "feeAmount": 0,
                "state": "FAILED",
                "errorCode": "INVALID_MPIN",
                "detailedErrorCode": "ZM"
            }
        ]
    }
}