Payment webhook events

Handle PAYMENT_INTENT_NOTIFICATION to reconcile a payment outcome on the merchant backend. This page owns the payment-event trigger and payload guidance; use the shared webhook guide for signature verification.

Before you begin#

Configure and secure the endpoint according to Integrate XPay webhooks. Verify x-signature before reading or storing any payment result.

Event type#

XPay sends payment notifications with this case-sensitive type:

PAYMENT_INTENT_NOTIFICATION

When XPay sends the notification#

For a standard payment that requires 3D Secure, XPay sends the notification after the customer completes the required 3D Secure action and the payment flow finishes. XPay sends the notification regardless of whether the resulting payment succeeds or fails.

For a tokenized payment, XPay sends the notification after request validation reaches gateway processing. This includes outcomes where the gateway returns an error or required gateway response data is missing.

Representative payload#

The following payload is shortened. The complete payload varies with the payment method and outcome.

{
  "type": "PAYMENT_INTENT_NOTIFICATION",
  "payment_intent_id": "xpay_pi_example",
  "refund_id": null,
  "amount": 500,
  "currency": "PKR",
  "status": "succeeded",
  "customer": {
    "name": "Ayesha Khan",
    "email": "ayesha@example.com",
    "phone": "{{customer_phone}}"
  },
  "payment_method_types": "card",
  "transaction_details": {
    "status": "CAPTURED",
    "activity": []
  },
  "metadata": {
    "order_reference": "order-1001"
  },
  "mode": "test",
  "account_id": "{{account_id}}"
}

Conditional fields#

• The contents of transaction_details.activity change according to the payment result.
• XPay adds the token object when the flow creates a reusable token. Read its identifier from token.id.
• XPay includes metadata when metadata was supplied for the PaymentIntent.
• Other payment-method or gateway fields can vary with the result.

Do not require a conditional field before accepting and storing the core payment notification.

Process the event#

1. Verify x-signature.
2. Confirm that type is PAYMENT_INTENT_NOTIFICATION.
3. Match payment_intent_id to the merchant order or token request.
4. Store the received payment status and relevant identifiers.
5. Process token.id only when the token object is present.
6. Apply the merchant action for the received result.

Next steps#

• PaymentIntent lifecycle and statuses.
• Collect a payment token with XPay Element.
• Use the XPay API reference for the complete payment-notification schema.