Handling Webhooks

Merchants can configure the Webhook/S2S Callback URLs along with username & password.

PROD – Merchants can configure URL, Username and Password on the PhonePe dashboard.

URL – Merchant’s Webhook URL
Username – Merchant configure their own username
Password – Merchant configure their own password
Note: Merchants should ensure the configured username and password is being used in the code to validate the Authorization header.

UAT – Merchants can reach out to the Integration Team.

Once the username and password is configured, PhonePe will pass the same SHA256 (username:password) as the “Authorization” header in s2s response.
Merchants should calculate using the same logic and match with the one passed by PhonePe. If both are matching, then the response payload can be consumed by the merchant. Otherwise, merchants should ignore the response.

Callback Event Types

Copied !

checkout.order.completed
checkout.order.failed
pg.refund.accepted
pg.refund.completed
pg.refund.failed

PhonePe will pass the authorization header as :

Authorization : SHA256(username:password)

Callback Validation/Verification flow for merchants

For the incoming request, extract the basic authorization header “Authorization”, verify it with the one which you have shared with us and accept the response if Username and password matches.

Key Notes

Merchants should rely only on the root level “payload.state” parameter for the payment status confirmation.
Avoid Strict Deserialization
Don’t rely on “type” parameter in the webhook response (This will be deprecated) instead rely on the “event” parameter only for the webhook event name.
expireAt and timestamp parameters will be a epoch timestamp ( in milliseconds)

Sample S2S Responses

Copied !

PG Standard Checkout Order Completed

Copied !

Note: Merchants should rely only on the highlighted “payload.state” parameter for the payment status confirmation.


{
    "event": "checkout.order.completed",
    "payload": {
        "orderId": "OMO2403282020198641071317",
        "merchantId": "merchantId",
        "merchantOrderId": "merchantOrderId",
        "state": "COMPLETED",
        "amount": 10000,
        "expireAt": 1724866793837,
        "metaInfo": {
            "udf1": "",
            "udf2": "",
            "udf3": "",
            "udf4": ""
        },
        "paymentDetails": [
            {
                "paymentMode": "UPI_QR",
                "transactionId": "OM12334",
                "timestamp": 1724866793837,
                "amount": 10000,
                "state": "COMPLETED",
                "splitInstruments": [
                    {
                        "amount": 10000,
                        "rail": {
                            "type": "UPI",
                            "upiTransactionId": "upi12313",
                            "vpa": "abcd@ybl"
                        },
                        "instrument": {
                            "type": "ACCOUNT",
                            "accountType": "SAVINGS",
                            "accountNumber": "121212121212"
                        }
                    }
                ]
            }
        ]
    }
}

PG Standard Checkout Order Failed

Copied !

Note: Merchants should rely only on the highlighted “payload.state” parameter for the payment status confirmation.


{
    "event": "checkout.order.failed",
    "payload": {
        "orderId": "OMO2403282020198641071311",
        "merchantId": "merchantId",
        "merchantOrderId": "merchantOrderId",
        "state": "FAILED",
        "amount": 10000,
        "expireAt": 1724866793837,
        "metaInfo": {
            "udf1": "",
            "udf2": "",
            "udf3": "",
            "udf4": ""
        },
        "paymentDetails": [
            {
                "paymentMode": "UPI_COLLECT",
                "timestamp": 1724866793837,
                "amount": 10000,
                "transactionId": "OM12333",
                "state": "FAILED",
                "errorCode": "AUTHORIZATION_ERROR",
                "detailedErrorCode": "ZM",
                "splitInstruments": [
                    {
                        "amount": 10000,
                        "rail": {
                            "type": "UPI",
                            "upiTransactionId": "upi12313",
                            "vpa": "abcd@ybl"
                        },
                        "instrument": {
                            "type": "ACCOUNT",
                            "accountType": "SAVINGS",
                            "accountNumber": "121212121212"
                        }
                    }
                ]
            }
        ]
    }
}

PG Refund Accepted:

Copied !


{
  "event": "pg.refund.accepted",
  "payload": {
    "merchantId": "merchantId",
    "merchantRefundId": "merchantRefundId_2",
    "originalMerchantOrderId": "MO950606fb",
    "amount": 1000,
    "state": "CONFIRMED",
    "paymentDetails": [
      {
        "transactionId": "OMR2408282309538075378400",
        "paymentMode": "UPI_QR",
        "timestamp": 1724866793837,
        "amount": 1000,
        "payableAmount": 1600,
        "feeAmount": 600,
        "state": "CONFIRMED"
      }
    ]
  }
}