Webhook Handling

In a subscription-based system, it’s essential to confirm the outcome of every payment event. Once a payment or recurring debit is initiated, your system should quickly identify whether it was successful, failed, or is still pending. This real-time verification helps you take timely actions like activating services, updating customer access, retrying failed payments, or sending notifications.

To support this, PhonePe sends two types of webhook callbacks that your system should listen to:

• Subscription Callbacks: These indicate the result of the first payment made when a subscription is created.
• Redemption Callbacks: These provide the status of automated payments for ongoing subscriptions.

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.”

Response for Subscription Setup

{
    "type": "SUBSCRIPTION_SETUP_ORDER_COMPLETED",
    "event": "subscription.setup.order.completed",
    "payload": {
        "merchantId": "TX12345",
        "merchantOrderId": "MO1774243061089",
        "orderId": "OMO2603231047412984235557BW",
        "state": "PENDING",
        "currency": "INR",
        "amount": 200,
        "expireAt": 1774243961270,
        "metaInfo": {
            "udf1": "udf1",
            "udf2": "udf2"
        },
        "paymentFlow": {
            "type": "SUBSCRIPTION_SETUP",
            "merchantSubscriptionId": "MS1774243061089",
            "authWorkflowType": "ZERO",
            "amountType": "FIXED",
            "maxAmount": 20000000,
            "frequency": "MONTHLY",
            "expireAt": 1774643045000,
            "subscriptionId": "OMS2603231047412704235838BW",
            "productType": "ENACH_MANDATE",
            "authInstrumentType": "NET_BANKING"
        },
        "paymentDetails": []
    }
}

Responses for Redemption

{
    "type": "SUBSCRIPTION_REDEMPTION_ORDER_COMPLETED",
    "event": "subscription.redemption.order.completed",
    "payload": {
    "merchantId": "TX12345",
    "merchantOrderId": "MO1722319560997",
    "orderId": "OMO2601282154473535900531",
    "state": "COMPLETED",
    "currency": "INR",
    "amount": 200,
    "expireAt": 1769618686824,
    "paymentFlow": {
        "type": "SUBSCRIPTION_REDEMPTION",
        "merchantSubscriptionId": "MS1769569283073",
        "redemptionRetryStrategy": null,
        "autoDebit": false,
        "validAfter": null,
        "validUpto": null,
        "notifiedAt": null
    },
    "paymentDetails": [
        {
            "transactionId": "OM2601282154486455900694",
            "paymentMode": "ENACH_ACCOUNT",
            "timestamp": 1769617488702,
            "currency": "INR",
            "amount": 200,
            "payableCurrency": "INR",
            "payableAmount": 200,
            "feeCurrency": "INR",
            "feeAmount": 0,
            "state": "COMPLETED",
            "instrument": {
                "type": "ACCOUNT",
                "accountType": "SAVINGS",
                "bankId": "HDFC"
            },
            "rail": {
                "type": "NACH",
                "utr": "ddf5d315-93cd-4019-9137-7bb2ad2ec702"
            },
            "splitInstruments": [
                {
                    "instrument": {
                        "type": "ACCOUNT",
                        "accountType": "SAVINGS",
                        "bankId": "HDFC"
                    },
                    "rail": {
                        "type": "NACH",
                        "utr": "ddf5d315-93cd-4019-9137-7bb2ad2ec702"
                    },
                    "currency": "INR",
                    "amount": 200
                }
            ]
        }
    ]
}
}

{
    "type": "SUBSCRIPTION_REDEMPTION_ORDER_CANCELLED",
    "event": "subscription.redemption.order.cancelled",
    "payload": {
        "merchantId": "TX12345",
        "merchantOrderId": "MO1774751396248",
        "orderId": "OMO2603290759596486953861BW",
        "state": "FAILED",
        "currency": "INR",
        "amount": 20000000,
        "expireAt": 1774917000000,
        "paymentFlow": {
            "type": "SUBSCRIPTION_REDEMPTION",
            "merchantSubscriptionId": "MS1773646960613",
            "autoDebit": false
        },
        "paymentDetails": [
            {
                "transactionId": "OM2603290800005236953538BW",
                "paymentMode": "ENACH_ACCOUNT",
                "timestamp": 1774751400561,
                "currency": "INR",
                "amount": 20000000,
                "payableCurrency": "INR",
                "payableAmount": 20000000,
                "feeCurrency": "INR",
                "feeAmount": 0,
                "state": "FAILED",
                "errorCode": "TXN_CANCELLED",
                "detailedErrorCode": "REQUEST_CANCEL_BY_REQUESTER"
            }
        ]
    }
}