Stripe Connect API

Onboarding and state-recovery flows for Stripe Connect Standard accounts.

reference • updated 2026-03-15

Goal

Run Connect Standard onboarding with strong organization context and deterministic callback handling.

Primary endpoints

Endpoint	Purpose	Expected outcome
`POST /v1/connect/accounts/onboarding-links`	start or resume onboarding	short-lived Stripe onboarding URL
`GET /v1/connect/accounts/return`	success callback	account state refreshed in Beacon
`GET /v1/connect/accounts/refresh`	requirements-pending callback	new onboarding session preserving context

Recommended operational flow

11) Request onboarding link
Call onboarding-links with organization and mode (test|live).
22) Redirect to Stripe
User completes legal and payout requirements in Connect.
33) Handle callbacks
Process return and refresh after validating signed state.
44) Update dashboard
Expose final status and pending requirements per organization.

Mandatory callback validation

Signed state is valid and unexpired.
Callback organization matches session organization.
charges_enabled and details_submitted are true before considering onboarding complete.

Onboarding-link request example

bash

curl -X POST https://api.beacon.pt/v1/connect/accounts/onboarding-links \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<organization_id>",
    "mode": "test",
    "returnUrl": "https://app.beacon.pt/dashboard/connect/return",
    "refreshUrl": "https://app.beacon.pt/dashboard/connect/refresh"
  }'

json

{
  "onboardingUrl": "https://connect.stripe.com/setup/c/acct_123/...",
  "expiresAt": "2026-03-15T11:00:00Z"
}

Common failures and mitigation

Signal	Likely cause	Mitigation
repeated `refresh` loop	pending legal requirements in Connect	show requirement checklist before retry
callback without context	invalid/expired `state`	restart onboarding from Beacon
connected but not operational	missing capabilities	block go-live until capabilities are enabled