Process a payout run
Take sellers' earned balances out to the bank — through the hold, the KYC gate and the ACH result.
Owned by Admin · 10 steps · about 25 minutes
Why this exists
A payout is the only route by which money leaves this platform to a person's bank, so it is the most gated thing in it. Three gates sit in a row, and each one exists for a different reason.
The hold. Resale proceeds are spendable inside the club immediately but are not cashable until a hold expires — by default a day after the event finishes. The reason is that an event can still be cancelled after it sells, and a cancellation claws proceeds back from sellers. Money that has left for a bank account cannot be clawed back, and the ledger will not let an earned balance go negative, so the venue would absorb it as a write-off. The hold is what keeps that window small.
The KYC gate. Over the reporting threshold of gross secondary sales in a calendar year, a cash-out requires a verified tax identity. The check is on external cash-outs only — spending your earned balance inside the club is never gated, because that is not reportable income leaving the platform. The identity itself is stored as a hash plus the last four digits; the raw number is never persisted anywhere, and the user row keeps only a masked marker. The gate is re-checked at processing time, not just at request time, so revoking someone's verification actually stops a payout that is already in the queue.
The clearing account. Requesting a payout does not pay anybody. It moves the amount out of the seller's earned balance into a payout clearing account, which is where it sits while the transfer is in flight. It leaves clearing only when the bank tells us what happened: settled posts a release, failed posts a reversal and gives the seller their balance back as an immediately available lot. The clearing account balance should always equal the money genuinely in flight, and the integrity report checks exactly that.
Worth knowing what the platform does not do: it holds the KYC record and computes year-to-date gross secondary sales, but it does not generate a 1099-K document. The tax module's filing package produces federal, state and municipal returns, not information returns for sellers.
Before you start
- An admin session for the processing half; a member session for the requesting half.
- A seller with an earned balance (sam.seller@demo.club has one, plus a completed payout to read).
- Debug endpoints enabled if you want to skip the hold or simulate the bank result.
Practise with
| Persona | Password | Note | |
|---|---|---|---|
| admin | admin@club.test | admin123 | processes payouts and can revoke a KYC verification |
| member | sam.seller@demo.club | sam-pass-1234 | $46.75 earned and one already-paid payout to inspect |
Steps 1–3 — Member
their manual →It is their money leaving the platform: they request it and they are the one the identity gate applies to.
-
1As the seller, open your payouts page. Read the eligible amount, which is not the same as your earned balance.Expected result Your earned balance, the portion that has cleared its hold, any pending requests with a countdown, and a KYC panel if you are over the threshold.Watch out for Earned and payout-eligible are different numbers on purpose. Money from an event that has not finished yet is spendable in the club and not yet cashable.
-
2Submit your legal name and tax id if the page asks for them.Expected result A verified record. Only a hash and the last four digits are stored.Watch out for Formats are checked strictly and a bad one is 422 TAX_ID_INVALID. Under the threshold this step does not exist at all — the platform does not collect identity it does not need.
-
3Request the payout: an amount and your bank details.Expected result A request that is either held with a countdown or immediately eligible, and a ledger posting that moves the amount from your earned balance into payout clearing.Watch out for 409 for more than your earned balance, 422 for malformed bank details, 403 KYC_REQUIRED if you are over the threshold without verification. Only the last four digits of the account number are ever stored.
Steps 4–10 — Admin
their manual →-
4As an admin, open the payout queue and filter by status. The lifecycle is held, eligible, processing, paid — or failed or cancelled.Expected result Requests with amounts, users, hold expiry and status.Watch out for Only eligible requests can be processed. A held one is not yours to hurry along by hand — the scheduler promotes it when the hold expires.
-
5In training, promote matured holds immediately instead of waiting, so you can see the rest of the workflow today.Expected result The ids that moved from held to eligible.Watch out for This runs the same promotion the scheduler runs; it does not skip an unexpired hold. To skip a hold in a demo, make the lot available first — do not edit the row.
-
6Process an eligible payout. This is the call that hands the transfer to the bank rail.Expected result The request moves to processing and a transfer record is created with the processor's transfer id.Watch out for 409 PAYOUT_NOT_ELIGIBLE for anything not in eligible status. And the KYC gate is re-checked HERE, so a verification revoked after the request was made stops the payout at this point with 403 KYC_REQUIRED.
-
7Simulate the bank's answer both ways: settle one payout and fail another with a failure code.Expected result Settled posts the release out of payout clearing and marks the request paid. Failed reverses it and restores the seller's earned balance as an immediately available lot.Watch out for In production this arrives as a webhook, and both handlers are idempotent — replaying a settlement does not pay twice. Rehearse the failure path too: a seller whose transfer bounced gets their balance back, not an apology.
-
8Trace the whole life of one payout through the ledger: the hold, then the release or the reversal.Expected result Two transactions per completed payout, both balanced, both referencing the payout.Watch out for The payout clearing account should net to exactly the money in flight. If it does not, the integrity report will say so before anyone else notices.
-
9Learn the revocation path: an admin can revoke a verification when something about it turns out to be wrong.Expected result The record moves out of verified status.Watch out for Revoking does not claw back payouts already paid. It stops the next one, at processing time. Treat it as a stop, not as an undo.
-
10Finish by running the payout gate invariant and reading its answer.Expected result Confirmation that paid payouts carry a release posting, that none was processed before its hold expired, and that none over the threshold was processed without verified identity.Watch out for This invariant is the reason the gates above are worth obeying rather than working around. If you find a way past a gate, this check is what will find it too.