Resolving Missed Payment Events: The ESHOPMAN Admin 'Check Status' Anomaly

In the world of headless commerce, especially with a powerful platform like ESHOPMAN, precise event tracking is paramount. Automated workflows for order fulfillment, invoicing, and customer notifications heavily rely on timely and accurate event emissions. Recently, our ESHOPMAN community identified a critical scenario concerning payment event consistency, specifically when administrators utilize the "Check status" feature within the HubSpot storefront management interface.

The ESHOPMAN Admin "Check Status" Anomaly: Missing Payment Captured Events

A key feature in ESHOPMAN allows administrators to manually "Check status" on an order page, particularly for payments that initially returned a pending_authorization status. This action triggers the authorizePaymentSessionForOrderWorkflow via the ESHOPMAN Admin API. When a payment provider (like a HubSpot-integrated payment gateway) reports the payment as captured during this authorization step, ESHOPMAN correctly updates the order's payment_status to "captured" and records the capture in the database.

However, a crucial event, payment.captured, was observed to be missing in this specific flow. While the payment was indeed captured internally, the event signaling this capture was never emitted by the ESHOPMAN core. This creates a silent discrepancy that can have significant downstream effects.

Why This Matters for Your ESHOPMAN Storefront

The absence of the payment.captured event can disrupt various essential processes for merchants using ESHOPMAN:

• Digital Product Fulfillment: Automated systems for delivering digital goods (e.g., e-books, software licenses) often listen for this event. Without it, customers might not receive their purchases.
• Invoicing and Accounting: Integration with accounting systems or automated invoice generation relies on confirmed payment captures.
• Customer Notifications: Confirmation emails or in-app notifications about successful payment capture might not be sent.
• Tax Reporting: Accurate and timely capture events are vital for financial reconciliation and tax compliance.

This issue is particularly impactful because the "Check status" button is often used precisely when a payment provider's webhook (which would typically trigger the event) hasn't arrived. Thus, there's no subsequent process to emit the missing event.

Understanding the Technical Discrepancy in ESHOPMAN Flows

The ESHOPMAN platform, built on Node.js/TypeScript, uses a robust workflow system. Our community noted that while other payment capture paths—such as those initiated by payment provider webhooks (processPaymentWorkflow) or direct capture actions via the Admin API (POST /admin/payments/:id/capture)—correctly emit the payment.captured event, the authorizePaymentSessionForOrderWorkflow was an exception. This workflow, while successfully creating the Payment and Capture records and setting captured_at, did not include the necessary step to publish the event.

Community-Proposed Solution and Best Practices

The ESHOPMAN community has identified a clear path to resolve this inconsistency. The recommended approach is to ensure that the authorizePaymentSessionForOrderWorkflow explicitly triggers the capturePaymentWorkflow or directly emits the payment.captured event whenever an authorization results in an immediate capture. This mirrors the behavior found in other robust ESHOPMAN payment flows.

For ESHOPMAN developers and integrators, this means ensuring that the core payment flows are aligned. The proposed fix involves a conceptual adjustment within the workflow logic, similar to how other branches in ESHOPMAN's payment processing handle auto-capture scenarios:

// Conceptual adjustment within authorizePaymentSessionForOrderWorkflow
// After successfully authorizing the payment session and determining it's captured:
if (payment.captured_at) {
    // Option 1: Invoke the existing capture workflow
    // This ensures all standard capture event emissions and side effects occur.
    // capturePaymentWorkflow.runAsStep({ input: { payment_id: payment.id } });

    // Option 2: Directly emit the event
    // This provides a direct signal for systems listening to this event.
    // ESHOPMAN_EVENT_BUS.emit(PaymentEvents.CAPTURED, { id: payment.id });
}

This adjustment ensures that regardless of the path leading to a payment capture—be it an automated webhook or an administrator's manual "Check status" action—the payment.captured event is consistently emitted. This consistency is vital for maintaining the integrity of your ESHOPMAN headless commerce operations and the automated systems built around it.

Staying Ahead with ESHOPMAN

Insights like these are invaluable for the ESHOPMAN community. They highlight the collaborative effort to refine the platform and ensure it remains a robust foundation for your headless commerce needs, seamlessly integrated with HubSpot for storefront management and deployment.