∧pex

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 project

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.

Coupon code integration

When a program uses coupon tracking (couponSyncMode: "stripe"), Apex creates Stripe Promotion Codes tied to each partner's membership. The flow:

  1. Partner is assigned a coupon code (e.g. SARAH20) via the dashboard or API
  2. Apex calls stripe.promotionCodes.create to create a matching Promotion Code under your Stripe account
  3. When a customer uses the Promotion Code at checkout, Stripe attaches it to the invoice or checkout.session
  4. Apex ingests the event and attributes the conversion to the partner who owns the code

This works alongside link-based attribution — a partner can drive conversions through both their link and their coupon code.

For non-Stripe sync modes (webhook / manual), see Coupon tracking.

1099 tax reporting

Stripe handles 1099-NEC issuance for US partners automatically:

  • W-9/W-8BEN collection: happens during Stripe Express onboarding — partners submit tax forms before they can receive payouts
  • 1099-NEC filing: Stripe auto-files for every US partner earning $600+ in a calendar year
  • Partner access: partners view and download their 1099 forms from their Stripe Express dashboard

Merchants do not need to issue their own 1099s for payouts facilitated through Apex + Stripe Connect. See Tax compliance for the full flow.

What happens under the hood

Apex stores four fields on your ProjectConfig 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 ProjectConfig)
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

PreviousFacilitated payoutsNextInviting partners