Customer finance and wallet

The finance client API at /client/finance/* is the customer-facing slice of the Finance module. It serves marketplace sellers, affiliates, content creators, and any principal that earns money on the platform — letting them check their balance, manage payout destinations, and request payouts. Staff-side endpoints (approval, batch processing) live under /finance/* instead.

Wallet

Returns the customer's wallet — current balance, pending balance (earnings not yet released), held funds, currency, and the wallet's transaction summary.

const wallet = await fetch('/api/client/finance/wallet', {
  headers: { orgid: ORG_ID, Authorization: `Bearer ${customerJwt}` },
}).then(r => r.json());

// {
//   walletId: 'wall-cust-abc',
//   ownerType: 'customer',
//   ownerId: 'cust-abc',
//   balance: 1250.50,
//   pending: 200.00,
//   held: 0,
//   currency: 'USD',
//   lifetimeEarnings: 4870.30,
//   nextPayoutDate: '2026-05-01'
// }

If the customer has no wallet yet (never earned), the response is empty — the wallet is created lazily on first credit.

Payout history

Paginated payout history. Each payout record carries:

• amount, currency
• status: pending → approved → processing → completed (or failed, cancelled)
• methodId (which payout destination)
• requestedAt, processedAt, completedAt
• failureReason if applicable

Wallet transactions (per-credit detail) come from /client-data/transactions — see Customer account.

Request a payout

Customer triggers a payout from their wallet to a saved destination.

await fetch('/api/client/finance/payouts/request', {
  method: 'POST',
  headers: { orgid: ORG_ID, Authorization: `Bearer ${customerJwt}` },
  body: JSON.stringify({
    amount: 500.00,
    methodId: 'pm-bank-chase',
    notes: 'April earnings',
  }),
});

Validation:

• Amount cannot exceed wallet.balance (pending and held funds are excluded).
• Method must belong to the customer.
• Org-level minimum payout (e.g. $50) and maximum-per-request rules apply.

The payout enters status: pending; staff approval (or the org's auto-approval rule) moves it forward.

Payout-method management

Add, edit, remove, and pick a default destination. Supported destination types depend on configured providers in the integrations module:

• Bank account (ACH) — routing + account number, validated via vendor
• PayPal — email address, validated via PayPal API
• Venmo — phone or username
• Cash App — $cashtag
• Debit card (push-to-card) — tokenised via Stripe
• Crypto wallet — address + chain, validated via on-chain check

await fetch('/api/client/finance/payout-methods', {
  method: 'POST',
  headers: { orgid: ORG_ID, Authorization: `Bearer ${customerJwt}` },
  body: JSON.stringify({
    type: 'bank',
    label: 'Chase Checking',
    routingNumber: '021000021',
    accountNumber: '...',
    accountHolderName: 'Alice Smith',
    accountType: 'checking',
  }),
});

The platform tokenises sensitive details before storage — the raw account number is never persisted in plaintext on the customer record.

Payout settings

Per-customer payout preferences:

• autoPayoutEnabled — automatically request a payout once balance crosses a threshold
• autoPayoutThreshold — the trigger amount
• payoutSchedule — manual, weekly, monthly
• taxIdProvided — required in some jurisdictions before payouts can run

await fetch('/api/client/finance/payout-settings', {
  method: 'PUT',
  headers: { orgid: ORG_ID, Authorization: `Bearer ${customerJwt}` },
  body: JSON.stringify({
    autoPayoutEnabled: true,
    autoPayoutThreshold: 100,
    payoutSchedule: 'weekly',
  }),
});

Failed payouts

A payout can fail at the provider step (closed bank account, invalid PayPal email). The platform records the failure reason on the payout record and notifies the customer via the broadcast module. The funds return to wallet balance. The customer must update or delete the failing method before retrying.

Currency

The wallet is denominated in one currency (the org's default). Mixed-currency earning flows aren't supported in the customer wallet — for those, use the Banking module which handles multi-currency accounts properly.