Beacon

Connect existing Stripe

View as Markdown

Connect existing Stripe

Connect an existing Stripe account via read-only OAuth and understand real visibility limits.

howto • updated 2026-03-18

Before you start

  • Beacon's Stripe app must be registered as an Extension.
  • STRIPE_EXTENSION_ENABLED=true in the environment.
  • The Stripe account already exists and must be authorized by an OWNER or ADMIN in Beacon.
  • Use the correct runtime: https://test.beacon.pt for mode=test and https://app.beacon.pt for mode=live.

Recommended flow

  1. 11) Start OAuth

    In the Beacon Dashboard, open Integrations and call POST /api/stripe/oauth/start?org=<slug>&mode=<mode>.

  2. 22) Authorize an existing account

    Stripe shows OAuth consent for the existing account. Beacon does not create new accounts.

  3. 33) Validate callback

    Stripe returns to GET /api/stripe/oauth/callback?code=...&state=.... Beacon validates state, exchanges the code for a token, and confirms the returned scope includes read_only.

  4. 44) Confirm ingestion

    The connection becomes ACTIVE and Beacon starts ingesting only the payments and movements visible in that Stripe account.

What this model means

  • Beacon does not control payments and does not create Stripe accounts.
  • Beacon only ingests what is visible in the connected account.
  • If the original charge stays in a third-party platform account, visibility can be partial.
  • In those cases, the full fiscal Sale only appears when Beacon Connect or equivalent data arrives.

After connecting

  1. Confirm the dashboard shows the account as an existing Stripe account connected through OAuth.
  2. Verify ingestion of charge.succeeded, refunds, disputes and, when applicable, transfer / payout.
  3. Validate that destination-charge cases stay partial until sufficient enrichment arrives.

Common errors

SignalLikely causeAction
OAuth blocked at startSTRIPE_EXTENSION_ENABLED=falseenable the flag and confirm the Stripe app is registered as an Extension
Callback fails with operational errorStripe did not return read_onlyfix the Extension setup in Stripe; Beacon does not treat read_write as a functional fallback
Payment ingested without full Salepartial visibility in the connected accountsend Beacon Connect with fiscal buyer, seller and lines
transfer / payout without visible chargedestination charge or platform-controlled flowtreat as partial and enrich through Beacon Connect

Beacon Connect in the same flow

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

Each platform uses its own secret and an externalOrgRef -> organizationId mapping managed in Beacon's admin console.