# Stripe Connect

Organisers must connect a Stripe account before publishing paid events.

## Stored Data

Store only Stripe identifiers and onboarding status:

- `stripe_connected_accounts.stripe_account_id`
- charges/payouts enabled flags
- onboarding status

Do not store card numbers or bank account data.

## Onboarding

The production onboarding flow should create connected accounts using Stripe's Accounts v2 API and explicit controller/responsibility settings. Account links should be generated server-side and expire naturally.

For the MVP, the reviewed checkout charge model is `direct_charge`. The Checkout Session is created on the connected organiser account, and Zavvion collects its customer-paid platform service fee through `application_fee_amount`. Destination charges remain a supported code path only for a separately reviewed merchant-of-record, liability, Stripe fee-payer, and reporting decision.

## Webhooks

Configure a local or test webhook endpoint:

```bash
stripe listen --forward-to http://localhost/zavvion-events/public/api/v1/webhooks/stripe
```

Set `STRIPE_WEBHOOK_SECRET` in `.env`. Webhook signature verification is required before any payment state changes.

## Local test readiness

The MVP is already prepared for your Stripe account. Until real test credentials are added, checkout safely creates pending checkout drafts but does not issue paid tickets. Local mock completion is available only when `PAYMENT_MOCK_ENABLED=true` outside production; keep it disabled for production-like rehearsals unless the launch owner explicitly approves a mock-only walkthrough.

When you are ready to test Stripe:

1. Put test keys into `.env`:

```env
STRIPE_MODE=test
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_CONNECT_CHARGE_MODEL=direct_charge
PAYMENT_MOCK_ENABLED=false
```

2. Log in as admin and open:

```text
http://localhost/zavvion-events/public/admin.html#health
```

3. Confirm the Stripe readiness panel is OK.
   You can also run:

```powershell
php bin/check-stripe-readiness
```

4. Add a Stripe connected account ID to the organiser Stripe account screen if testing Connect transfers. For readiness to pass, mark onboarding complete and charges/payouts enabled only after the account is actually ready in Stripe test mode.
5. Create a customer checkout; if keys are valid, the API returns a Stripe Checkout URL instead of only local mock checkout.
6. Complete the payment with a Stripe test card.
7. Let the Stripe webhook mark the checkout paid. Browser redirects alone must not issue tickets.

Expected direct-charge evidence in Stripe test mode:

- The Checkout Session request is sent with the connected account in the Stripe request options.
- The PaymentIntent contains `application_fee_amount` for the Zavvion platform fee.
- The connected organiser account receives the charge, net of Stripe fees and the Zavvion application fee.
- The platform receives an Application Fee object for the configured fee amount.
- Public online checkout remains Stripe card payment only; cash and external-card recording are organiser box-office workflows, not public checkout options.

The full production decision on liability, dashboard access, fee payer, requirement collection, and controller responsibilities should be confirmed before launch, but the MVP test configuration should not mix direct and destination charge models.