Apex

Stripe Connect

Apex uses Stripe Connect Standard for facilitated payouts: your merchant account authorises Apex with read_write scope, and Apex issues transfers under your account context. Money flows merchant's Stripe balance → partner's Stripe Express account + Apex's platform fee. Apex never advances funds.

Prerequisites

  • Active Stripe account (test or live mode)
  • Admin access to your Apex workspace

One-time setup (merchants)

1. Connect Stripe

  1. Open /dashboard/partners/stripe-connect in the Apex dashboard
  2. Click Connect with Stripe
  3. You'll be redirected to connect.stripe.com/oauth/authorize — log in with your Stripe credentials
  4. Review the authorisation prompt (Apex requests read_write scope) + approve
  5. Stripe redirects back with ?stripe=connected. The card updates to show:
    • Your Stripe account id
    • Granted scope (read_write)
    • Date connected

2. Set your payout policy

Still on /dashboard/partners/stripe-connect (or via SDK):

await apex.updateProgram(programId, {
  autoPayoutPolicy: "auto_under_cap",
  autoPayoutCapUsd: 1000,
});

See Facilitated payouts for the three policy options.

Tax reporting

Stripe takes care of partner tax paperwork:

  • Tax details: partners give Stripe their identity and tax information when they set up their Stripe Express account, before they can receive payouts
  • Year-end forms: any year-end tax forms that apply to a partner are sent through Stripe
  • Partner access: partners find and download their tax forms in their Stripe Express dashboard

You don't need to collect tax forms from partners paid through Apex and Stripe Connect. See Tax compliance for more.

What happens under the hood

Apex stores four fields on your WorkspaceConfig after OAuth:

  • stripeAccountId — your acct_* id (what we transfer from)
  • stripeAccountStatus — connected / restricted / revoked / disabled / pending
  • stripeOauthGrantedAt — ISO timestamp
  • stripeOauthScope — read_write

Every payout transfer uses these.

Revocation

If you revoke Apex's access from your Stripe dashboard:

  1. Stripe fires the account.application.deauthorized webhook to Apex
  2. Your stripeAccountStatus flips to revoked
  3. merchantProbationUntil is set to +7 days — automatic payouts pause
  4. Affected partners get a partner_merchant_oauth_revoked notification
  5. You have 7 days to re-authorise. Past that window, the program moves to archived.

Re-auth within the window clears probation immediately — pending payouts resume on the next scheduled cycle.

Revenue integration vs. Connect — what's different?

Apex has two separate Stripe integrations:

ConnectorPurposeAuth
Stripe revenue integrationIngests charges, refunds, subscriptions for attribution + analyticsAPI key (secret key in your WorkspaceConfig)
Stripe Connect (this doc)Facilitates partner payoutsOAuth with read_write scope

The same underlying Stripe account supports both — but they're independent authorisations. Connecting Stripe for revenue does NOT grant payout authorisation, and vice versa.

Troubleshooting

Banner says "Access revoked"

Re-click Connect with Stripe. You have 7 days from revocation before programs archive automatically.

Transfer fails with account_inactive

Your Stripe account is in review or has limitations. Resolve the Stripe-side issue first (visit your Stripe dashboard).

Transfer fails with insufficient_balance

Your Stripe balance was short when the scheduled transfer fired. Apex retries in 24 hours. See Facilitated payouts → Insufficient balance for the full escalation ladder.

OAuth callback returns to ?stripe=error&reason=state_expired

The OAuth state token is valid for 10 minutes. Click Connect again — it regenerates a fresh state.

Related

PreviousTax complianceNextInviting partners