Stripe & Beacon Connect API

Read-only OAuth for existing Stripe accounts and Beacon Connect endpoints for platforms.

reference • updated 2026-03-18

Objective

Connect existing Stripe accounts through read-only OAuth and accept direct platform push when the linked Stripe account does not expose the full sale.

Stripe OAuth endpoints

Endpoint	Purpose	Expected outcome
`POST /api/stripe/oauth/start?org={slug}&mode={test\|live}&lang={locale}`	prepare OAuth connection	temporary Stripe consent `redirectUrl`
`GET /api/stripe/oauth/start?org={slug}&mode={test\|live}&lang={locale}`	immediate redirect helper	`302/307` redirect to Stripe
`GET /api/stripe/oauth/callback?code=...&state=...`	internal OAuth callback	dashboard redirect with validated connection

Beacon Connect endpoints

Endpoint	Purpose	Expected outcome
`POST /api/platform-connect/verify-mapping`	validate `externalOrgRef`	resolved Beacon organization
`POST /api/platform-connect/payments`	ingest payment	create/enrich `Payment` and, if sufficient, `Sale`
`POST /api/platform-connect/refunds`	ingest refund	create `PaymentRefund` and update status
`POST /api/platform-connect/disputes`	ingest dispute	create `PaymentDispute` and update status

Recommended operational flow

11) Start OAuth
Call oauth/start with organization and mode (test|live).
22) Validate callback
Beacon validates state, exchanges code for a token, and fails if the returned scope does not include read_only.
33) Ingest visible Stripe data
The linked account starts feeding Payment.kind=CHARGE|TRANSFER|PAYOUT, plus financial enrichment from balance_transactions.
44) Enrich missing sale context
If the linked account only shows a partial money movement, the platform sends Beacon Connect to complete Sale and fiscal context.

Mandatory validations

STRIPE_EXTENSION_ENABLED=true.
The OAuth callback must include read_only; Beacon does not treat read_write as a functionally equivalent fallback.
providerEventId is required for Beacon Connect.
Payment reconciliation priority is: stripeChargeId -> stripePaymentIntentId -> providerEventId -> (platformIntegrationId, externalPaymentId).

OAuth start example

bash

curl -X POST "https://test.beacon.pt/api/stripe/oauth/start?org=acme&mode=test&lang=en" \
  -H "Authorization: Bearer <beacon_session_token>"

json

{
  "ok": true,
  "redirectUrl": "https://connect.stripe.com/oauth/authorize?...",
  "expiresAt": "2026-03-18T11:00:00.000Z"
}

Beacon Connect verify-mapping example

bash

curl -X POST "https://app.beacon.pt/api/platform-connect/verify-mapping" \
  -H "Authorization: Bearer <platform_secret>" \
  -H "Content-Type: application/json" \
  -d '{"externalOrgRef":"seller_org_123"}'

Common failures and mitigation

Signal	Likely cause	Mitigation
OAuth callback fails	Stripe app is not configured as an Extension or does not return `read_only`	fix Stripe configuration and restart the flow
partial payment without `Sale`	limited visibility in the linked account	enrich via Beacon Connect
`429` from Beacon Connect	integration quota exceeded	respect `retryAfterSec` and use exponential backoff with jitter