feat: subscription based events for web

[aritro2002]

Type of Change

• Bugfix
• New feature
• Enhancement
• Refactoring
• Dependency updates
• Documentation
• CI/CD

Description

This PR implements subscription-based events for the Web SDK, allowing merchants to receive real-time updates about payment form status changes and other payment-related events.

Key Changes:

• New Event Types: Added comprehensive subscription event types (SubscriptionEventTypes.res) to support form status changes, payment method selection, validation states, and more
• Event Hooks: Introduced SubscriptionEventHooks.res to manage event subscription lifecycle and handle event dispatching to merchant callbacks
• Payment Method Integration: Integrated event emission across all payment methods (Card, Apple Pay, Google Pay, PayPal, Klarna, Samsung Pay, SEPA, ACH, BACS, BECS, Boleto, Paze, and more)
• Form Status Tracking: Added FORM_STATUS event that notifies when the payment form is complete/incomplete, allowing merchants to enable/disable pay buttons dynamically
• Saved Methods Support: Extended event support to saved payment methods and card items
• Loader Integration: Updated payment element loader to initialize event subscription system

Supported Event Names:

• FORM_STATUS - Notifies when payment form completeness changes (COMPLETE/INCOMPLETE)
• PAYMENT_METHOD_STATUS - Emitted when payment method status changes
• PAYMENT_METHOD_INFO_CARD - Card payment method information updates (card number, expiry, CVV)
• PAYMENT_METHOD_INFO_BILLING_ADDRESS - Billing address field changes

Configuration:

Merchants can configure which events to receive using the subscriptionEvents option in paymentElementOptions:

const paymentElementOptions = {
  displayDefaultSavedPaymentIcon: false,
  subscriptionEvents: ["PAYMENT_METHOD_INFO_CARD"],
  layout: {
    savedMethodCustomization: {
      groupingBehavior: "groupByPaymentMethods",
    },
  },
  wallets: {
    walletReturnUrl: window.location.origin,
    applePay: "auto",
    googlePay: "auto",
    style: {
      theme: "dark",
      type: "default",
      height: 55,
    },
  },
};

Backward Compatibility:

The implementation maintains full backward compatibility. If subscriptionEvents option is not passed in the payment element options, all events are emitted by default to existing integrations. When subscriptionEvents array is explicitly provided, only the specified events are dispatched, giving merchants fine-grained control over event handling.

Architecture:

• Events are emitted from individual payment components through the new hooks system
• Merchants can subscribe via the onChange callback on PaymentElement
• Events follow a consistent structure with eventName and payload fields
• Event filtering logic: subscriptionEvents undefined → all events emitted; subscriptionEvents defined → only listed events emitted

How did you test it?

Tested manually using the following React component integration:

<PaymentElement
  id="payment-element"
  options={paymentElementOptions}
  onChange={(event) => {
    console.log(
      "PaymentElement changed:",
      JSON.stringify(event, null, 2),
    );
    if (
      event.eventName !== undefined &&
      event.eventName === "FORM_STATUS"
    ) {
      setComplete(() => event.payload.status === "COMPLETE");
    }
  }}
/>

Test Scenarios:

• Verified FORM_STATUS events fire when form completeness changes
• Tested with multiple payment methods (Cards, Wallets, Bank Transfers)
• Confirmed events emit correctly for saved payment methods
• Validated event payload structure matches expected types

Checklist

• I ran npm run re:build
• I reviewed submitted code
• I added unit tests for my changes where possible

[semanticdiff-com]

Review changes with  

[github-actions]

🚫 Missing Linked Issue

Hi 👋 This pull request does not appear to be linked to any open issue yet.

Linking your PR to an issue helps keep the project tidy and ensures the issue is closed automatically.

✔️ How to fix this

• Add a keyword like Fixes #123 or Closes #456 to your PR description or a commit message.
• Or link it manually using the "Linked issues" panel in the PR sidebar.

✅ Tip: You can link multiple issues.
🚫 Note: If only one issue is linked, it must be open for this check to pass.

Once linked, this check will pass automatically on your next push or when you re-run the workflow.

Thanks for helping maintainers! 🙌