Initiate Stripe Connect

POST /api/v1/creators/stripe-connect/initiate — 🔑 Bearer · Rate limit: 10 req / hour

Creates a Stripe Connect Express account for the calling creator and returns a fresh onboarding link. KYC must be APPROVED before this endpoint will work — the platform requires identity verification before opening up payouts. Idempotent: if the creator already has a Stripe account, a new onboarding link is generated against it (no duplicate account creation).

Request

No body, no params. Identity comes from the bearer token.

Response

201 Created — ApiResponseOf<StripeConnectInitiateResponseDto>

{
  "success": true,
  "data": {
    "accountId": "acct_...",
    "onboardingUrl": "https://connect.stripe.com/express/onboarding/..."
  }
}

Errors

Side effects

1. Lookup CreatorProfile (with user.email); throw not_creator if missing.
2. KYC gate: assert kycStatus === APPROVED; otherwise kyc_required.
3. Idempotent path — if stripeAccountId already set: skip account creation, just call createAccountLink(stripeAccountId) and return.
4. Atomic claim — updateMany({ where: { userId, stripeAccountId: null }, data: { stripeAccountStatus: PENDING } }). Zero rows touched → another concurrent request beat us; re-read and either return its result or throw connect_in_progress.
5. Stripe SDK creates the Express account — accounts.create({ type: 'express', country: <stripe.connect_country admin-managed, default 'US'>, email: user.email, metadata: { creatorId, userId, platform: 'biore' }, capabilities: { transfers: { requested: true } } }).
6. Persist stripeAccountId (update({ stripeAccountId })).
7. Audit log: [stripe-connect] Account created: {accountId} for creator {creatorId}.
8. Generate the onboarding URL via createAccountLink(accountId) (Stripe accountLinks.create).
9. Return { accountId, onboardingUrl }.
10. Webhook updates status fields — Stripe's account.updated webhook flips stripeChargesEnabled / stripePayoutsEnabled / stripeAccountStatus server-side as the creator completes onboarding (handled by an internal webhook controller, not this portal).

Code samples

curl -X POST https://api.bio.re/api/v1/creators/stripe-connect/initiate \
  -H "Authorization: Bearer $ACCESS_TOKEN"

type StripeConnectInitiate = {
  accountId: string;
  onboardingUrl: string;
};

async function initiateStripeConnect(accessToken: string): Promise<StripeConnectInitiate> {
  const res = await fetch('https://api.bio.re/api/v1/creators/stripe-connect/initiate', {
    method: 'POST',
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  const json = await res.json();
  if (!res.ok || !json.success) {
    throw Object.assign(new Error(json?.error?.message ?? 'Stripe Connect initiate failed'), {
      code: json?.error?.code,
    });
  }
  return json.data;
}

// Usage: redirect to onboardingUrl in a new tab
function openOnboarding(onboardingUrl: string) {
  window.location.assign(onboardingUrl);
}

import { useMutation, useQueryClient } from '@tanstack/react-query';

export function useInitiateStripeConnect() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: async () => {
      const res = await fetch('/api/v1/creators/stripe-connect/initiate', { method: 'POST' });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Stripe Connect initiate failed'), {
          code: json?.error?.code,
          i18nKey: json?.error?.i18nKey,
        });
      }
      return json.data as StripeConnectInitiate;
    },
    onSuccess: () => {
      // Status flipped to PENDING server-side
      qc.invalidateQueries({ queryKey: ['creators', 'stripe-connect', 'status'] });
      qc.invalidateQueries({ queryKey: ['creators', 'payout-settings'] });
      qc.invalidateQueries({ queryKey: ['creators', 'profile'] });
    },
  });
}

Try it

curl -X POST "https://loading/api/v1/creators/stripe-connect/initiate"

{
  "success": true,
  "data": {
    "accountId": "acct_1234567890",
    "onboardingUrl": "string"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Invalid credentials",
    "i18nKey": "auth.login.invalid_credentials",
    "i18nVars": {
      "field": "email"
    },
    "details": [
      {
        "message": "email must be an email"
      }
    ],
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Source