Flows

Payouts & Connect

Onboard a trader as a Stripe Connect payee, then pay out the trading profit they've earned. The payout amount is computed by the validator — it's an estimate you read, not an arbitrary amount the user requests.

How it works

Create a Connect account → send the user to the Stripe onboarding link.
Stripe returns them to the return URL registered on your app row — in this app, /dashboard/payouts?onboarding=return.
The API learns the account is payout-enabled from Stripe's account.updated webhook. In local dev only, it also self-heals from Stripe on the next list call, since webhooks don't reach localhost.
Read the estimated payout owed. Disbursement is run by the platform, not by your app — there is no partner-callable endpoint to move money.

Create a Connect account

POST/v2/connect/accounts

User session

Request body

{ "country": "US" }

200 OK

{
  "id": "con_...",
  "stripe_account_id": "acct_...",
  "onboarding_url": "https://connect.stripe.com/setup/...",
  "status": "pending",
  "payouts_enabled": false,
  "charges_enabled": false,
  "details_submitted": false
}

Resuming onboarding

If a link expires, get a fresh one from POST /v2/connect/accounts/{stripe_account_id}/onboarding-link.

List Connect accounts

GET/v2/connect/accounts

User session

200 OK

[
  {
    "id": "con_...",
    "stripe_account_id": "acct_...",
    "status": "active",
    "payouts_enabled": true,
    "charges_enabled": false,
    "details_submitted": true,
    "bank_name": "STRIPE TEST BANK",
    "last4": "6789",
    "country": "US"
  }
]

GET

/v2/connect/accounts

Runs live against your environment using the app's server-side credentials and your session. Sign in to the dashboard first for authenticated reads.

charges_enabled stays false — that's correct

These are payout-only Express accounts: the platform requests the transfers capability and nothing else, because the platform takes the payments, not the trader. Watch payouts_enabled — that is the flag that governs whether money can move, and status reads active once it flips.

Estimated payout (read-only)

The amount owed is computed from realized trading profit via the validator's high-water-mark. Read it; don't invent it.

GET/v2/payouts/estimate

User session

curl

curl http://localhost:8000/v2/payouts/estimate \
  -H "Authorization: Bearer <app_access_token>" \
  -H "X-Session-Token: <user_session_token>" \
  -H "X-Prop-Account: prop_..."

200 OK

{ "amount_usd": 412.50, "amount_cents": 41250, "currency": "usd", "available": true }

GET

/v2/payouts/estimate

Runs live against your environment using the app's server-side credentials and your session. Sign in to the dashboard first for authenticated reads.

Payout history

GET/v2/payouts

User session

status is one of pending (row created), submitted (transfer cut), completed (Stripe confirmed transfer.created) or failed (transfer.reversed). There is no paid state.

200 OK

[
  {
    "id": "po_...",
    "amount_cents": 41250,
    "currency": "usd",
    "status": "completed",
    "stripe_transfer_id": "tr_...",
    "failure_reason": null,
    "requested_at": "2026-06-20T00:00:00Z",
    "completed_at": "2026-06-20T00:00:05Z"
  }
]

GET

/v2/payouts

Runs live against your environment using the app's server-side credentials and your session. Sign in to the dashboard first for authenticated reads.