Setting up Stripe Connect

The simplest Stripe shape is Charges: customers pay a single Stripe account, you settle later. That works for one-operator setups but collapses for multi-tenant SaaS — and LiteHQ is multi-tenant by definition.

Three reasons we picked Connect

1. Direct settlement. Tenant payments land in your bank — not ours. We never custody your money. This is a legal + tax simplification.
2. Per-operator dispute handling.Chargebacks, refunds, and disputes go to your Connect dashboard. You don't need to wait for us to triage.
3. Multi-currency without a per-currency platform account.Each operator picks their settlement currency at onboarding. We don't need to be in every market they are.

Onboarding happens at signup time (or later if you skipped it). You're redirected to a Stripe-hosted page, fill in business + verification details, and come back to your LiteHQ dashboard with a connected account.

The full sequence

1. In Settings → Payments, click Connect Stripe. We create a Stripe account in your jurisdiction and generate an AccountLink.
2. The AccountLink redirects to Stripe's hosted onboarding. Fill in: business name, tax id (ABN / NZBN / EIN / VAT), bank account, owner ID verification.
3. Stripe returns to our callback at /v2/preview/onboarding (see step 7 of the onboarding flow).
4. We auto-create two webhook secrets and register both endpoints with Stripe. You see them surfaced in Settings → Webhooks.
5. We mark your operator account stripe_status='active'. From this point your public booking URL accepts paid bookings.

LiteHQ's Stripe webhook endpoint accepts events from both your platform account and your connected account. The endpoint verifies the signature against both secrets — whichever matches wins, neither matching fails the request.

The two secrets

• STRIPE_WEBHOOK_SECRET. Platform-level events. Things like account.updated on your Connect account.
• STRIPE_WEBHOOK_SECRET_CONNECT. Connected-account events. charge.succeeded, payment_intent.succeeded, refunds.

// Both secrets are tried — the first that verifies wins.
// We never reveal which one matched to the caller (timing leak).

async function POST(req: Request): Promise<Response> {
  const sig = req.headers.get('stripe-signature') ?? ''
  const body = await req.text()

  let event: Stripe.Event | null = null

  for (const secret of [
    process.env.STRIPE_WEBHOOK_SECRET!,
    process.env.STRIPE_WEBHOOK_SECRET_CONNECT!,
  ]) {
    try {
      event = stripe.webhooks.constructEvent(body, sig, secret)
      break
    } catch {
      // try the next secret
    }
  }

  if (!event) return new Response('invalid signature', { status: 400 })
  await processEvent(event)
  return new Response('ok')
}

Stripe sweeps funds from your connected account to your linked bank on a schedule you choose. We default to daily for operators with steady volume and weekly for smaller operators (fewer wire fees on the receiving bank).

Setting the schedule

1. In your Stripe dashboard → Settings → Payouts, choose Daily / Weekly / Monthly. Stripe applies a rolling 2-business-day hold for cards (configurable).
2. Link a bank account. Stripe requires a 1-cent test deposit + confirmation for ACH accounts; instant for AU/NZ via PayTo/POLi.
3. Multi-currency operators can add additional payout currencies — each currency gets its own bank.

Reconciling payouts in Xero

Stripe payouts arrive in your bank as a single batched line. We map each payout to its underlying invoices via the cron-xero-syncedge function, which writes a Bank Transaction in Xero and matches it against the payout's individual charges.

These five errors are the most common Stripe Connect issues we see in support. Each includes the underlying cause and the exact resolution.