Fixed-price subscription webhooks

Subscription webhooks notify the merchant about billing outcomes and lifecycle changes that occur after or as a result of an API request.

Use Integrate XPay webhooks for signature verification and delivery handling. Use the XPay API reference for the canonical payload schema.

Subscription events#

Invoice event#

Payment outcome fields#

Subscription payment notifications can include:

• subscription_id
• invoice_id or related invoice data
• Subscription state
• Payment status and message
• PaymentIntent identifier
• attempts_left
• Retry count

Treat the XPay API reference schema as canonical because fields can vary by event and payment outcome.

Example subscription-created event#

The payload contains the event name and the created subscription fields:

{
  "event": "subscription_created",
  "retry_count": 0,
  "subscription_id": "xpay_subs_{{subscription_id}}",
  "plan_id": "xpay_plan_{{plan_id}}",
  "state": "draft",
  "active": true,
  "collect_advance": false,
  "billing_cycle": {
    "interval": "month",
    "every": 1
  },
  "scheduled_invoices": [
    {
      "invoice_id": "xpay_invoice_{{invoice_id}}",
      "date": "2026-08-01T00:00:00.000Z"
    }
  ]
}

Example payment events#

subscription_payment includes the payment outcome and the updated subscription:

{
  "event": "subscription_payment",
  "status": "PAYMENT_CAPTURED",
  "message": "Payment has been captured successfully",
  "error": false,
  "payment_intent": "xpay_pi_{{payment_intent_id}}",
  "retry_count": 1,
  "subscription_id": "xpay_subs_{{subscription_id}}",
  "plan_id": "xpay_plan_{{plan_id}}",
  "state": "paid"
}

invoice_payment includes the invoice and payment-attempt fields:

{
  "event": "invoice_payment",
  "invoice_id": "xpay_invoice_{{invoice_id}}",
  "subscription_id": "xpay_subs_{{subscription_id}}",
  "plan_id": "xpay_plan_{{plan_id}}",
  "state": "paid",
  "amount": 5000,
  "currency": "PKR",
  "payment_date": "2026-08-01T00:00:02.000Z",
  "payment_attempts": [
    {
      "number": 1,
      "date": "2026-08-01T00:00:02.000Z",
      "payment_method": "{{payment_token}}",
      "payment_intent": "xpay_pi_{{payment_intent_id}}",
      "pi_status": "succeeded"
    }
  ]
}

These examples are shortened to the fields most merchants need for reconciliation. Read the actual attempts_left value from each received event; it depends on the payment outcome and configured retry behavior.

Refund event#

After a successful full or partial refund, XPay sends REFUND_NOTIFICATION. Refunding a subscription payment doesn't change the subscription state; it remains paid. See Invoices and recurring payments.

Stage environment delivery#

XPay sends subscription and payment webhooks automatically in the stage environment. To resend a notification for testing, use the manual webhook action on the relevant subscription or transaction in the merchant portal.

Deferred cancellation webhook#

For a future or end-of-invoice cancellation, XPay changes the subscription to cancelled immediately and stops future billing. The subscription_cancel webhook is sent at the requested time or when the next invoice would otherwise have become due.

The delayed webhook doesn't change when cancellation takes effect. See Manage a fixed-price subscription for the canonical cancellation behavior.

Keep subscription and invoice states separate when processing these billing events. Retrieve the current API object when an event doesn't contain all the information required by the merchant.