Request a Payout

POST /api/v1/payouts/request — 🔑 Bearer

Initiates a payout from the authenticated creator's wallet. The endpoint runs a long chain of pre-conditions before writing — KYC + tax form must be approved, the chosen payout method must be ready, the wallet must have enough headroom (balance minus any outstanding requests), and the per-creator cooldown must have elapsed. All checks happen on the request path — by the time 201 returns, the row is in the DB at PENDING.

Request

Body — RequestPayoutDto

Headers

Response

201 Created — ApiResponseOf<RequestPayoutResponseDto>

{
  "success": true,
  "data": {
    "payoutId": "po-uuid-..."
  }
}

After 201:

• A PayoutRequest row exists at PENDING. It will move to APPROVED → PROCESSING → PROCESSED (or FAILED / REJECTED) via admin action.
• A fire-and-forget payout_requested notification is queued for the creator. Failures are logged, not surfaced.
• The creator's available balance for subsequent requests is reduced by this amount (still in their wallet — but counted against future requests).

Errors

Side effects

In order — first failing check throws, no later check runs, no DB write happens until step 13:

1. KillSwitchGuard reads kill_switch.PAYOUT from admin config; engaged → 503.
2. JwtAuthGuard (global). userId = req.user.id.
3. VelocityCheckGuard: count non-REJECTED payouts in the last fraud.payout_window_days; if ≥ fraud.max_weekly_payouts, create a FraudFlag row and throw 400 error.guard.payout_limit.
4. Resolve CreatorProfile by userId → 404 profile_not_found.
5. KYC check: kycStatus === APPROVED → else 400 kyc_required.
6. Tax form check: at least one TaxForm with status = APPROVED for this creator → else 400 tax_form_required.
7. Method-specific readiness:
   • STRIPE_CONNECT: stripeAccountId set, stripeAccountStatus = ACTIVE, stripePayoutsEnabled = true (3 separate checks, distinct error codes).
   • BANK_TRANSFER: iban set, accountHolderName set, bankAccountVerified = true (3 separate checks).
8. Resolve CREATOR-type wallet by userId → 404 wallet_not_found.
9. Wallet status: frozen === false → else 400 wallet_frozen. balance >= 0 → else 400 wallet_in_debt.
10. Minimum balance: balance >= payout.min_amount (admin config, default 10) → else 400 minimum_amount.
11. Minimum amount: amount >= 1 → else 400 minimum_amount.
12. Available balance: aggregate sum(amount) of this creator's payouts in [PENDING, APPROVED] (NOT PROCESSING); compute available = balance - outstanding; require amount <= available → else 400 insufficient_balance.
13. Cooldown: read most recent non-REJECTED payout; if (createdAt + cooldown_days) > now → 400 frequency_limit.
14. Write: prisma.payoutRequest.create({ data: { id: randomUUID(), creatorId, amount: Decimal(amount), method, status: 'PENDING' } }).
15. Fire-and-forget notification: notificationService.send({ eventKey: 'payout_requested', userId, variables: { amount, method } }) — failures logged.
16. Increment payoutRequestedTotal Prometheus counter.
17. Return { payoutId }.

Code samples

curl -X POST https://api.bio.re/api/v1/payouts/request \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": "50.00",
    "method": "STRIPE_CONNECT"
  }'

curl -X POST https://api.bio.re/api/v1/payouts/request \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": "100.00",
    "method": "BANK_TRANSFER"
  }'

type PayoutMethod = 'STRIPE_CONNECT' | 'BANK_TRANSFER';

async function requestPayout(
  accessToken: string,
  amount: string,                  // e.g. "50.00"
  method: PayoutMethod,
): Promise<{ payoutId: string }> {
  const res = await fetch('https://api.bio.re/api/v1/payouts/request', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ amount, method }),
  });
  const json = await res.json();
  if (!res.ok || !json.success) {
    // Discriminate per i18nKey for correct user-facing copy.
    throw Object.assign(new Error(json?.error?.message ?? 'Payout failed'), {
      code: json?.error?.code,
      i18nKey: json?.error?.i18nKey,
      status: res.status,
    });
  }
  return json.data;
}

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

export function useRequestPayout() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: async (input: { amount: string; method: PayoutMethod }) => {
      const res = await fetch('/api/v1/payouts/request', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Payout failed'), {
          i18nKey: json?.error?.i18nKey,
          status: res.status,
        });
      }
      return json.data as { payoutId: string };
    },
    onSuccess: () => {
      // The new PENDING payout shifts the available-balance math —
      // refetch the wallet view AND the report so both reflect reality.
      qc.invalidateQueries({ queryKey: ['payout', 'report'] });
      qc.invalidateQueries({ queryKey: ['wallet'] });
    },
    // Don't auto-retry — the user needs to see the rejection reason.
    retry: false,
  });
}

Try it

curl -X POST "https://loading/api/v1/payouts/request" \  -H "Content-Type: application/json" \  -d '{    "amount": "50.00",    "method": "STRIPE_CONNECT"  }'

{
  "success": true,
  "data": {
    "payoutId": "c3d65312-6575-43de-b8ae-728d8d0a9371"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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