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 stripeCheckout to 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:
    1. Retrieve stored session metadata via Cart::restoreData.
    2. Re-instantiate cart context with cartInstance.
    3. Populate items using restore.
    4. Clean up stored data with deleteStoredCart.
  • 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:
    The StripeWebhookController listens for checkout.session.expired and invokes checkoutSessionExpired, seamlessly restoring cart state for the user .

  • Checkout Flow:
    In stripeCheckout, the StripeTrait first calls expireExistingSession, then saves metadata, invokes SaveOrderService::processCart, and finally redirects to Stripe’s hosted page .

  • Order Processing:
    Upon payment completion, SaveOrderService’s processPayments finalizes orders, updates statuses, and removes the cart record .

Dependencies & Relationships

  • Models: Cart, Order, OrderRound, Payment
  • Services: SaveOrderService, StripeService
  • Trait: StripeTrait for shared Stripe logic
  • Webhooks: StripeWebhookController for event-driven restores
  • Configurations: services.stripe credentials in config/services.php

This documentation encapsulates how Stripe sessions are managed, expired, and how carts recover lost data, while categorizing revenue effectively.