Beacon

Conectar Stripe existente

Ver como Markdown

Conectar Stripe existente

Conectar una cuenta Stripe existente por OAuth read-only y entender los límites reales de visibilidad.

howto • updated 2026-03-18

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.

Flujo recomendado

  1. 11) Iniciar OAuth

    En el Dashboard Beacon, abre Integraciones y lanza POST /api/stripe/oauth/start?org=<slug>&mode=<mode>.

  2. 22) Autorizar cuenta existente

    Stripe muestra el consentimiento OAuth para la cuenta existente. Beacon no crea cuentas nuevas.

  3. 33) 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.

  4. 44) Confirmar ingestión

    La conexión queda ACTIVE y Beacon empieza a ingerir solo los pagos y movimientos visibles en esa cuenta Stripe.

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ñalCausa probableAcción
OAuth bloqueado al inicioSTRIPE_EXTENSION_ENABLED=falseactivar la flag y confirmar que la app Stripe está registrada como Extension
Callback falla con error operativoStripe no devolvió read_onlycorregir la configuración Extension en Stripe; Beacon no trata read_write como fallback funcional
Pago ingerido sin Sale completavisibilidad parcial en la cuenta conectadaenviar Beacon Connect con buyer, seller y líneas fiscales
transfer / payout sin charge visibledestination charge o flujo controlado por plataformatratarlo 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.