## Antes de empezar

- La app Stripe de Beacon debe estar registrada como **Extension**.
- `STRIPE_EXTENSION_ENABLED=true` en el entorno.
- La cuenta Stripe ya existe y debe ser autorizada por un `OWNER` o `ADMIN` en Beacon.
- Usa el runtime correcto: `https://test.beacon.pt` para `mode=test` y `https://app.beacon.pt` para `mode=live`.

<Note title="Requisito duro">Beacon exige `scope=read_only` en el callback OAuth. Si Stripe no devuelve `read_only`, la conexión se aborta y se registra el error operativo `stripe_oauth_extension_required`.</Note>

## Flujo recomendado

<Steps>
  <Step title="1) Iniciar OAuth">En el Dashboard Beacon, abre `Integraciones` y lanza `POST /api/stripe/oauth/start?org=<slug>&mode=<mode>`.</Step>
  <Step title="2) Autorizar cuenta existente">Stripe muestra el consentimiento OAuth para la cuenta existente. Beacon no crea cuentas nuevas.</Step>
  <Step title="3) Validar callback">Stripe vuelve a `GET /api/stripe/oauth/callback?code=...&state=...`. Beacon valida `state`, intercambia el `code` por token y confirma que el scope devuelto incluye `read_only`.</Step>
  <Step title="4) Confirmar ingestión">La conexión queda `ACTIVE` y Beacon empieza a ingerir solo los pagos y movimientos visibles en esa cuenta Stripe.</Step>
</Steps>

## Qué implica este modelo

- Beacon **no** controla pagos y **no** crea cuentas Stripe.
- Beacon solo ingiere lo que es **visible** en la cuenta conectada.
- Si el cargo original permanece en la cuenta de una plataforma third-party, la visibilidad puede ser parcial.
- En esos casos, la `Sale` fiscal completa solo aparece cuando llega **Beacon Connect** o datos equivalentes.

## Después de conectar

1. Confirmar que el dashboard muestra la cuenta como Stripe existente conectada por OAuth.
2. Verificar ingestión de `charge.succeeded`, refunds, disputes y, cuando aplique, `transfer` / `payout`.
3. Validar que los casos `destination charge` quedan parciales hasta recibir enriquecimiento suficiente.

## Errores frecuentes

| Señal | Causa probable | Acción |
| --- | --- | --- |
| OAuth bloqueado al inicio | `STRIPE_EXTENSION_ENABLED=false` | activar la flag y confirmar que la app Stripe está registrada como Extension |
| Callback falla con error operativo | Stripe no devolvió `read_only` | corregir la configuración Extension en Stripe; Beacon no trata `read_write` como fallback funcional |
| Pago ingerido sin `Sale` completa | visibilidad parcial en la cuenta conectada | enviar Beacon Connect con buyer, seller y líneas fiscales |
| `transfer` / `payout` sin charge visible | destination charge o flujo controlado por plataforma | tratarlo como parcial y enriquecer por Beacon Connect |

## Beacon Connect en el mismo flujo

- `POST /api/platform-connect/verify-mapping`
- `POST /api/platform-connect/payments`
- `POST /api/platform-connect/refunds`
- `POST /api/platform-connect/disputes`

Cada plataforma usa su propio secreto y un mapping `externalOrgRef -> organizationId` gestionado en la consola admin de Beacon.