Operational Integrations – Vertical Insurance Partner

This integration adds optional event insurance powered by Vertical Insure. After a successful checkout, the system clones the customer’s payment method to a connected Stripe account and processes insurance quote charges. If there’s nothing to charge, the handler exits gracefully.

Configuration 🔧

Ensure the following keys are set in config/services.php (or your environment):

Key Purpose
services.vertical_insurance.client_id Vertical Insure API Client ID
services.vertical_insurance.client_secret Vertical Insure API Client Secret
services.vertical_insurance.stripe_connected_account Stripe Connected Account ID

Define these via .env:

VERTICAL_INSURANCE_CLIENT_ID=your_client_id
VERTICAL_INSURANCE_CLIENT_SECRET=your_client_secret
STRIPE_CONNECTED_ACCOUNT_ID=acct_XXXXXXXXXXXX

Livewire Trait: VerticalInsureTrait 🛒

This trait keeps the cart in sync with iframe-driven quote selections, adding or removing vertical_insurance items with metadata.

  • Method: verticalQuoteUpdated($data)
    • Compares incoming quote IDs to cart metadata.
    • Adds new quotes, removes deselected ones.
    • Persists cart to session.
  • Helper: addQuote($quote)
    • Creates a CartItem with metadata keys: type, name, price, quote_id.
  • Helper: removeQuote($id)
    • Deletes matching CartItem and updates partners state.
public function verticalQuoteUpdated($data) { … }  // live update of cart items 

Partner Handler: VerticalInsurance 🛡️

The VerticalInsurance class executes post-payment insurance charges:

Constructor

  • Retrieves and validates:
    • client_id, client_secret (Vertical API).
    • stripe_connected_account (Stripe).
  • Throws if any are missing.
public function __construct(OrderRound $orderRound, $data) { … }  // config checks 

Method: handle()

  1. Compute Total
    Sums cart_content items of type vertical_insurance.
  2. No-Op
    Returns early if total ≤ 0.
  3. Retrieve Payment
    Fetches original PaymentIntent & Customer via StripeTrait.
  4. Collect Quotes
    Calls getQuote() for each ID; accumulates those needing charge.
  5. Clone Payment Method
    Duplicates customer’s method onto the connected account.
  6. Create Secondary Charge
    Uses StripeClient to confirm a new PaymentIntent under the connected account.
  7. POST to Vertical
    Calls /v2/purchase with quotes and Stripe token.
    Logs or reports failures without breaking the flow.
public function handle() { … }  // filters, clone PM, charge, API call 

Method: getQuote($productCode, $quoteId)

Fetches a single quote from Vertical’s v1 API; returns null on failure.

public function getQuote(string $productCode, string $quoteId): ?array { … }

Method: clonePaymentMethod($payment_intent_id, $connected_account_id)

Creates a new PaymentMethod in the connected account, referencing the original customer.

public function clonePaymentMethod(string $payment_intent_id, string $connected_account_id) { … }

Integration Flow

sequenceDiagram
    participant F as Frontend (iframe)
    participant L as Livewire Component
    participant C as Cart
    participant S as Stripe Checkout
    participant Save as SaveOrderService
    participant O as OrderRound
    participant VI as VerticalInsurance
    participant SA as Stripe Connected Account
    participant API as Vertical API

    F->>L: offer-state-change(quotes)
    L->>L: verticalQuoteUpdated(data)
    L->>C: add/remove CartItem(s)
    F->>S: Submit Checkout
    S->>Save: processSessionId(session_id)
    Save->>O: create OrderRound
    Save->>VI: (new) VerticalInsurance.handle()
    VI->>SA: clonePaymentMethod(...)
    VI->>SA: paymentIntents.create(...)
    VI->>API: POST /v2/purchase(quotes, token)

{
    "title": "Graceful No-Op",
    "content": "If no vertical_insurance items exist, the handler returns early without error."
}

Key Relationships

  • Livewire Frontend uses embedded Vertical Insure scripts to emit quote events.
  • VerticalInsureTrait syncs those quote events with the cart.
  • Checkout & Webhook via SaveOrderService drive creation of an OrderRound.
  • VerticalInsurance runs as a post-order handler, charging and purchasing insurance.

This integration ensures seamless insurance addition without impacting core registration flows.