Beacon

Ligar Stripe existente

Ver como Markdown

Ligar Stripe existente

Ligar uma conta Stripe existente por OAuth read_only e perceber os limites reais de visibilidade.

howto • updated 2026-03-18

Antes de começar

  • A app Stripe do Beacon tem de estar registada como Extension.
  • STRIPE_EXTENSION_ENABLED=true no ambiente.
  • A conta Stripe já existe e deve ser autorizada por um OWNER ou ADMIN da organização Beacon.
  • O runtime correcto deve estar seleccionado: https://test.beacon.pt para mode=test e https://app.beacon.pt para mode=live.

Fluxo recomendado

  1. 11) Iniciar OAuth

    No Dashboard Beacon, abre Integrações e dispara POST /api/stripe/oauth/start?org=<slug>&mode=<modo>.

  2. 22) Autorizar conta existente

    A Stripe apresenta o consentimento OAuth da conta existente. O Beacon não cria contas novas.

  3. 33) Validar callback

    A Stripe regressa a GET /api/stripe/oauth/callback?code=...&state=.... O Beacon valida state, troca o code por token e confirma que o scope inclui read_only.

  4. 44) Confirmar ingestão

    A ligação passa a ACTIVE e o Beacon começa a ingerir apenas os pagamentos e movimentos visíveis nessa conta Stripe.

O que fica claro neste modelo

  • O Beacon não controla pagamentos e não cria contas Stripe.
  • O Beacon só ingere o que é visível na conta ligada.
  • Se a charge original estiver na conta Stripe de uma plataforma third-party, a visibilidade pode ser apenas parcial.
  • Nesses casos, a Sale fiscal completa só sobe quando chega Beacon Connect ou dados equivalentes.

Depois da ligação

  1. Confirmar que o dashboard mostra a conta ligada como Stripe existente via OAuth.
  2. Verificar ingestão de charge.succeeded, refunds, disputes e, quando aplicável, transfer / payout.
  3. Validar se os casos destination charge aparecem como parciais até chegar enriquecimento suficiente.

Erros comuns

SinalCausa provávelAção
OAuth bloqueado no arranqueSTRIPE_EXTENSION_ENABLED=falseactivar a flag e confirmar que a app Stripe está registada como Extension
Callback falha com erro operativoa Stripe não devolveu read_onlycorrigir registo Extension na Stripe; o Beacon não faz fallback funcional por read_write
Pagamento entra mas sem Sale completavisibilidade parcial da conta ligadaenviar Beacon Connect com linhas, buyer e seller fiscais
transfer / payout sem charge visíveldestination charge ou fluxo controlado por plataformatratar como parcial e enriquecer por Beacon Connect

Beacon Connect no mesmo fluxo

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

Cada plataforma usa um segredo próprio e um mapping externalOrgRef -> organizationId criado na consola admin do Beacon.