Feature: Payment resolver, Payment Provider, Completing Stripe Webhooks, Wiring Payments to checkout service

src/Checkout/Events/OrderPlaced.php

@@ -5,13 +5,17 @@ namespace Modules\Core\Checkout\Events;
 use Lunar\Models\Order;
 
 /**
- * Dispatched by CheckoutService::placeOrder() the moment an Order exists —
- * the handoff point between Checkout and Order (see docs/checkout.md's
- * "Three-stage lifecycle"). Checkout has no opinion about what happens
- * after this fires; Order's own listeners (not built yet — Order is a
- * named-but-unscoped concern, same status Recovery had before it existed)
- * would be what reacts to it — e.g. a confirmation email, initializing
- * order status tracking.
+ * Dispatched once an Order's placed_at is set — the handoff point between
+ * Checkout/Payment and Order (see docs/checkout.md's "Three-stage
+ * lifecycle"). Fired by Modules\Core\Order\Listeners\
+ * ApplyResolvedPaymentStatus once it resolves a PaymentCaptured/
+ * PaymentAuthorized event into an actual order status change, not by
+ * CheckoutService directly — a draft Order can exist (via
+ * CheckoutService::initiatePayment()) well before this fires, if payment
+ * resolves asynchronously (e.g. a redirect-based gateway). Checkout has no
+ * opinion about what happens after this fires; Order's own listeners are
+ * what react to it — e.g. a confirmation email, initializing order status
+ * tracking.
  */
 class OrderPlaced
 {