Members and held funds

Access

• Owners and admins in the space (a member, or an organization key acting On-Behalf-Of a member → 403). An organization API key works (SDK). The held-funds routes under /members/…/held-funds are documented in Held funds.
• :userUuid is the member's user uuid (Member.userUuid; it was the numeric :userId), a member of the request's organization in the request's mode: a user of another organization, an unknown uuid, a removed member, a member of the other mode only, an owner or an admin → 404; a malformed uuid → 400 validation_failed on userUuid. Only exception: the held-funds routes (Held funds) also reach a member removed from this mode, so what was held when they left can still be paid out.

Read

• GET /members → 200 a page of the mode's members, newest first by when they joined in this mode (joinedAt, then userUuid; limit default 20, at most 100; cursor = the previous page's nextCursor, absent on the last page; a cursor that isn't one → 400 validation_failed on cursor). Never the team.
• Member: userUuid, firstName, lastName (absent when the account has none), email, test, organizationFeePercent (this mode's, a string, "0" when none), trustedAt (absent while the organization holds their funds), joinedAt (in this mode), acceptedCurrencies (the currency objects a checkout of theirs can be paid in now, [] when none), spaceUuid (their personal space in this mode: an owner or admin acts as them with POST /auth/switch-space { "spaceUuid" }, Account and credential § Sessions). member.joined / member.removed carry the same Member.

Update — PATCH /members/:userUuid

• organizationFeePercent (required, a string, "0" to "50"; re-authentication) → 200 Member. Per mode: the other mode keeps its own fee. Missing or above 50 → 400 validation_failed on organizationFeePercent.
• Which payments the new fee applies to (today's rule). A checkout session already created keeps the fee it was created with. A running subscription's next bills take the new fee: a bill reads the member's fee when it is charged (the rate isn't part of what the subscriber signed, only the organization's address is; contracts SPEC §4.1). Exception: a subscription created while the fee was 0 (or without an organization wallet on its chain) never pays one. Nothing tells the member of the change today (no event, no email): tell them yourself. This rule is under review; the CHANGELOG will flag any change.

Remove — DELETE /members/:userUuid

• Refused with 409 held_funds_pending while the organization holds live funds for the member: release them first (POST /members/:userUuid/held-funds/release/…, Held funds). Nothing changes then. Test-mode funds never block (test money isn't owed): they stay in the removed member's test ledger, which the team can still read and release.
• Otherwise removes the member from the request's mode (re-authentication) → 204 with no body, answered once the removal is done:
  • Their sessions in this mode and their API keys of this mode stop working at once (401). Signing in lands in the mode they still have. Removed from their last mode, they leave the organization: only their membership ends (soft: kept, with a removal date). Their account stays theirs: signing in with the right password gives a session without an organization (a wrong one 401 invalid_credentials, as ever; Account and credential § Sessions), from which they create their own organization or accept an invitation; an invitation brings them back (their personal space reopens with the new invitation's terms, their data still there).
  • Their checkouts take no more payments, a permanent link or an open session included (410 merchant_closed).
  • Their data stays with the organization; their referral code too.
  • The organization's endpoints receive member.removed once (Webhook events).
• Then, within moments:
  • their products are hidden;
  • their subscriptions in this mode created before the removal are cancelled on-chain (off-chain for a trial), each with subscription.statusChanged to cancelled;
  • about 10 minutes after the cancellations, their webhook endpoints are disabled (the cancellations' events are sent to them first). It used to leave their subscriptions billing.
• A member invited back while that cleanup runs stops it: what they kept stays theirs, the subscriptions they create afterwards are never touched. Removed again, it's a new removal (its own member.removed, its own cleanup).
• A payment already sent when the member was removed may still confirm and be held for them: the team releases it the usual way (Held funds), the member being removed.
• A seller can't leave on their own: the organization removes them (this route, from the dashboard or with an organization key). Their subscriptions (created once trusted) are cancelled like the others; what they were owed must be released first (the 409 above).

The organization fee on held funds

While the organization holds a member's funds (their trustedAt absent), their payments go to the organization's wallet. The organization's fee (organizationFeePercent) is still taken, without going on-chain:

• On-chain, the payment pays QBitFlow's fee as usual, and the member's whole share to the organization's wallet, without an organization fee (the contracts refuse a fee paid to the payment's own recipient).
• The payment records the split a direct payment would have had: settlement.organizationFee (the rate, and the organization's wallet address), settlement.split.organization (the fee, computed as the contracts do: on what remains after QBitFlow's fee, rounded down) and settlement.split.merchant (the member's net). The fee is the organization's like any other: its fee record, GET /metrics and GET /accounting/export count it as earned (it stays in the organization's wallet, where it belongs).
• The organization owes the member the net (settlement.split.merchant, the line's owed / owedUsd in the member's held funds), and a release pays exactly that (Held funds). A refund of a held payment still pays the customer back their share of everything they paid (Refunds), from the organization's wallet, and the member bears it: what they are owed drops by what the refund sent back (Held funds § Refunds of held payments).
• The rate is the one the payment would have paid directly (§ Update says which), read when it is paid and recorded with it: a later change of the member's fee never changes what an entry owes.
• Held members sell one-time payments only. A subscription's receiver is fixed on-chain when it is created, for its whole life: one created while the organization holds the member's funds would pay the organization's wallet forever, the organization forwarding every bill by hand. So a held member's subscription checkout is refused (409 merchant_not_ready, details.reason: "fundsHeld", Checkout sessions), and so is their subscription product's link. Once trusted, they sell subscriptions, paid to their own wallet with the organization's fee taken on-chain. Held funds are only ever payments (and refunds of them).
• The fee needs an organization wallet on the chain. It is paid to the organization's wallet of the payment's chain, so members sell only where the organization has one: a member accepts only its organization's currencies, and removing the organization's wallet of a chain removes that chain's currencies from every member at once (Wallets; a checkout already open then refuses them at the payer's intent: 409 currency_not_accepted, pick another currency). Behind it, the fee is never silently dropped from a new payment: should a member's payment or subscription still reach a chain without an organization wallet, its intent answers 409 merchant_not_ready (details.reason: "organizationFeeNoWallet"), nothing prepared (a guard, not a flow to expect). A subscription signed before the organization removed that wallet keeps billing, without the organization's fee (its subscriber signed for it; a removed address may no longer be the organization's). Held funds need that wallet anyway: it is the one that receives them.

Trust and held funds

• POST /members/:userUuid/trust → 200 Member with trustedAt: their new payments in this mode go to their own wallets. What is already held stays held until released. Per mode.
• Trust is one-way: there is no untrust. It narrows what the member accepts to their own wallets' currencies (within the organization's): the answer's acceptedCurrencies is what their checkouts take from now on.
• A member whose own wallets accept none of the organization's currencies isn't trusted: 409 member_has_no_wallet, nothing changes (they stay held, their checkouts keep working). Trusted, every checkout of theirs would answer 409 merchant_not_ready (noWallet). Trust them once they've added a wallet (their acceptedCurrencies while held are the organization's, so read their wallets in the dashboard, or retry the trust). Trusting a trusted member answers 200 and changes nothing.
• QBitFlow emails the member when the trust changes them (not on a repeat): their sales are paid directly to their wallet now, on their terms (the commission and what it is taken on, as the invitation words it), and what the organization still holds for them from before, in USD, paid out separately. Each release confirmed on-chain emails them too: what they received, for how many sales, and whether their next sales are still held. Both are sent in test mode as well, marked "Test mode", in QBitFlow's name, with no setting to turn them off (they are about the member's own money). Nothing to do on your side.
• From then on they sell subscriptions too (refused while held: § The organization fee on held funds).
• Reading what is held (GET /members/held-funds, GET /members/:userUuid/held-funds, the member's own GET /held-funds), releasing it (POST /members/:userUuid/held-funds/release/intent, then …/release) and closing it (POST /members/:userUuid/held-funds/close): Held funds.