Commerce: Checkout & Order Processing π
This section details Stripe session lifecycle management and cart restoration utilities. These core components ensure users seamlessly create, expire, and recover checkout sessions while categorizing revenue by item type.
Stripe Session Lifecycle Utilities
Stripe sessions enable secure, hosted payment flows. Two mechanisms handle session expiration:
Expire Existing Session
Before starting a new checkout, any open session is invalidated to avoid stale data.
// app/Traits/StripeTrait.php
private function expireExistingSession(): void
{
if (! session()->has('stripe_session_id')) {
return;
}
$stripeSession = Session::retrieve(session('stripe_session_id'));
if ($stripeSession && $stripeSession->status === 'open') {
$stripeSession->expire();
}
session()->forget('stripe_session_id');
}
- Purpose: Called in
stripeCheckoutto guarantee a fresh session per attempt. - Location: StripeTrait
Explicit Stripe Session Expiration
When needed outside the checkout flow (e.g., custom scripts), sessions can be expired manually:
// in StripeService (app/Services/...)
public function expireStripeSession(): void
{
if (session()->has('stripe_session_id')) {
Stripe::setApiKey(config('services.stripe.secret'));
try {
$session = Session::retrieve(session('stripe_session_id'));
$session->expire();
} catch (Exception $e) {
Log::error($e);
}
session()->forget('stripe_session_id');
}
}
- Use Case: CLI commands or admin tools expiring orphaned sessions.
- Reference: expireStripeSession
Cart Restore Workflow
Upon session expiration, cart data must be rehydrated so users can retry checkout.
checkoutSessionExpired
// in StripeService (app/Services/...)
public function checkoutSessionExpired(string $session_id): void
{
try {
$cart = app(Cart::class);
$sessionData = $cart->restoreData($session_id);
$event_id = $sessionData['event_id'];
$cart->cartInstance($event_id);
$cart->restore($session_id);
$cart->deleteStoredCart($session_id);
} catch (\Exception $e) {
app()->environment('production')
? report($e)
: Log::error($e);
}
}
- Flow:
- Retrieve stored session metadata via
Cart::restoreData. - Re-instantiate cart context with
cartInstance. - Populate items using
restore. - Clean up stored data with
deleteStoredCart.
- Retrieve stored session metadata via
- Citation: checkoutSessionExpired
Sequence Diagram
sequenceDiagram
participant Stripe as Stripe Webhook
participant Webhook as StripeWebhookController
participant Service as StripeService
participant Cart as Cart Model
Stripe ->> Webhook: checkout.session.expired(event.id)
Webhook ->> Service: checkoutSessionExpired(session_id)
Service ->> Cart: restoreData(session_id)
Cart -->> Service: sessionData
Service ->> Cart: cartInstance(event_id)
Service ->> Cart: restore(session_id)
Service ->> Cart: deleteStoredCart(session_id)
Service -->> Webhook: OK
Webhook ->> Stripe: 200 OK
Revenue Categorization Utilities
Line items are analyzed to assign revenue types for reporting.
| Function | Returns | Criteria |
|---|---|---|
| lineItemsContainsGateTicket | bool |
Checks names containing βPassβ |
| getRevenueType | `'Gate' | 'RSVP' |
// app/Services/StripeService.php
public function lineItemsContainsGateTicket(array $items): bool
{
foreach ($items as $item) {
if (isset($item['price_data']['product_data']['name'])
&& str_contains($item['price_data']['product_data']['name'], 'Pass')
) {
return true;
}
}
return false;
}
- Citation:
public function getRevenueType(array $items): string
{
foreach ($items as $item) {
$name = $item['price_data']['product_data']['name'] ?? '';
if (str_contains($name, 'Pass')) {
return 'Gate';
}
if (str_contains($name, 'RSVP')) {
return 'RSVP';
}
}
return 'Registration';
}
- Citation:
Integration Points & Flow
-
Stripe Webhook:
TheStripeWebhookControllerlistens forcheckout.session.expiredand invokescheckoutSessionExpired, seamlessly restoring cart state for the user . -
Checkout Flow:
InstripeCheckout, theStripeTraitfirst callsexpireExistingSession, then saves metadata, invokesSaveOrderService::processCart, and finally redirects to Stripeβs hosted page . -
Order Processing:
Upon payment completion,SaveOrderServiceβsprocessPaymentsfinalizes orders, updates statuses, and removes the cart record .
Dependencies & Relationships
- Models:
Cart,Order,OrderRound,Payment - Services:
SaveOrderService,StripeService - Trait:
StripeTraitfor shared Stripe logic - Webhooks:
StripeWebhookControllerfor event-driven restores - Configurations:
services.stripecredentials inconfig/services.php
This documentation encapsulates how Stripe sessions are managed, expired, and how carts recover lost data, while categorizing revenue effectively.