Payee Onboarding Process
How managers onboard a payee through the guided fork — manager-completes or send-to-payee.
After you create a payee, a manager guides them through onboarding before that payee can be paid: any representatives, engagement and pay details, allowances and deductions, and finally tax ID, payment method, and signed documents (I-9, startwork packet). Onboarding isn't a single linear form — it's a shared scroll that ends at an explicit fork, where the manager chooses whether to finish the record themselves or hand the rest to the payee.
The onboarding scroll and fork
Onboarding is one continuous scroll on the payee detail page, not a numbered wizard. A manager (or the payee, on their own portal) fills in, in order:
- Basics — legal name (business name for a loan-out or vendor), email, phone. Before the payee is approved, this section deliberately collects only name and contact info — no date of birth, tax ID, or address yet.
- Representation — optional; set up an agent, manager, business manager, or attorney if the payee has one, and their payment-direction authorization. Positioned here, right after Basics and before any pay or engagement details, because who (if anyone) directs the payee's money is treated as a wiring choice rather than a payroll detail.
- Engagement & Union — classification (employee/loan-out/contractor/vendor), union affiliation if applicable, job start date.
- Pay & wages — production role, compensation structure, and pay rate(s), priced weekly, hourly, or by an 8/10/12-hour day. This is also the section a payee needs at least one rate in before Path B, below, can send — unless the payee is invoice-based (see the callout below).
- Allowances and Deductions — per diem, housing, wardrobe, taxable earnings, and any deduction lines.
Right after Deductions, the scroll reaches a Startwork card — pick which signed-document packet this payee works through, or leave it on the company's automatic default — and then an explicit "Complete onboarding" card. The product deliberately stops here and asks the manager to choose the next step, rather than assuming the manager will fill in everything themselves.
Two paths, one flow
The fork card lays out both options side by side:
Finish setup yourself. The button takes the manager to a dedicated Finish payee setup page (/payees/[code]/setup) — the same shared setup flow the payee uses on their own portal, mounted here for a manager acting on the payee's behalf: the payee's tax ID (SSN or EIN — encrypted at rest, replace-only once set), the I-9 work-eligibility module, and any outstanding startwork documents. A wet-signed, uploaded Form I-9 satisfies work eligibility — the payee doesn't have to e-sign anything for this path to be complete. Each signed document can still be individually handed off for the payee to e-sign instead of uploading a paper copy, so "finish it yourself" doesn't have to mean paper for every single step.
Employees need a separate Section 2 from the manager — this is a federal requirement, not optional
For employees specifically, uploading the payee's I-9 Section 1 and documents isn't enough on its own. A manager must separately examine the documents the payee uploaded and complete Section 2 — a distinct certification card on the payee record where the examiner records each document's title, issuing authority, document number, and expiration, then certifies under penalty of perjury (the exact federal 8 CFR 274a.2 attestation text) that they examined the originals. Federal law requires this within 3 business days of the employee's start date. Work-authorization status doesn't move from pending to complete for an employee until Section 2 is certified — manager approval of the rest of onboarding does not, by itself, complete work authorization for employees the way it does for loan-outs, contractors, and vendors. Loan-outs, contractors, and vendors don't owe an electronic Section 2 and aren't affected by this gate.
The W-4 is optional and skippable on the payee's behalf. Greenroom never requires it to finish setup, and a skipped W-4 never gets pushed to Check — follow up with the payee directly if you skip it.
Send it to the payee. The manager sends an account-aware link instead. If the payee's email already has a Greenroom account — because they work with another production on the platform — the link reads as an invitation to join this company rather than create a new account; the send mechanism is identical, only the wording changes. The payee then completes the remaining tax, payment, I-9, and signature steps themselves, from any device, without further help from the manager. The link expires after 14 days; if the payee doesn't act in time, re-sending (see Following up with a payee, below) revokes it and issues a fresh one.
First sends are rate-gated
Until the payee has at least one pay rate, the send-to-payee button is disabled, with an inline note explaining that sending becomes available once the payee has a pay rate — with a link back up to Pay & wages. Vendors are exempt (they bill per invoice, not a standing rate, so there's never a rate to wait for), and so is a non-union contractor or loan-out who's been switched to invoice-based pay (see Pay & Compensation) — same reasoning, no standing rate to wait for. The gate applies only to the very first send — once an invite has gone out, or the payee has an account, resending and password resets are always available. "Finish setup yourself" is never gated.
Startwork packet
A separate Startwork card, right before the fork, lets a manager pick which signed-document packet the payee (or the manager, on Path A) works through, or leave it on "Automatic (Production Default)." Either path ends in the same set of signed documents, so this choice applies no matter which way the manager sends. Changing the packet after the payee has already started signing doesn't retroactively change what they see — Greenroom saves the new choice but tells the manager the payee already started, so the in-progress packet stays as issued.
Payment details are separate from the fork
Bank and payment information doesn't live inside either onboarding path — it's a standalone Payment card on the payee detail page, right after the fork. But it isn't usable there until the payee is fully approved: while onboarding is still in progress, the card shows as locked ("Payment is collected during finish setup") with a link back into whichever finish-setup flow is running, rather than any payment details. Bank/check information is actually entered as part of that finish-setup flow itself (Path A, or the payee's own steps on Path B) — it's just not shown or editable as its own summary card on this page until approval.
Once the payee is approved, the card becomes the full summary: payment method (direct deposit or paper check), bank name, account type, and the routing/account numbers masked to their last 4 digits, with an audited "reveal" action for the full value. An Edit payment method button opens a drawer to make changes.
The edit drawer requires double-entry confirmation (you type the account number twice) and validates the routing number against the standard ABA checksum before saving — a routing number that fails the checksum is rejected with an explanation rather than silently accepted. Payment edits are never blocked by review status, so a manager can fix a bank-detail typo mid-review without waiting for approval to reopen.
Replacing an already-approved payee's bank details isn't silent: Greenroom emails the payee a notice when their bank numbers change post-approval, as an anti-fraud measure. The save itself still goes through — this is a notification, not a block.
Saving progress
While a manager is filling out Path A, entries save automatically to the browser — not the server — so the manager can navigate away and come back without losing work, or recover after a crash or an accidental back-button press. These local drafts never include the tax ID, date of birth, or bank numbers; they expire after 24 hours; and they're cleared on sign-out. Restoring a draft is always an explicit choice — Greenroom offers it in a banner ("Restore" / "Discard draft") rather than silently reapplying it, since this is a payroll record, not a low-stakes form.
Onboarding status
Greenroom tracks three separate signals, shown as three separate badges — there's no single unified "onboarding status" value.
Onboarding status — the pill next to the payee's name at the top of the page. Tracks where the payee's own setup stands:
| Status | Indicator | Meaning |
|---|---|---|
| Not started | Nothing submitted yet — covers a brand-new payee and one with an outstanding invite who hasn't acted on it | |
| Review submission | The payee (or manager, on Path A) submitted their setup — waiting on the manager to approve or request changes | |
| Changes requested | A manager bounced the submission with a note; the payee needs to fix it and resubmit | |
| Complete | The manager approved — payroll-eligible (work authorization permitting) |
Manager approval — a second, more specific pill on the Complete onboarding fork card itself:
| Status | Indicator | Meaning |
|---|---|---|
| Setup in progress | Provisioned, nothing submitted yet | |
| Pending Manager Approval | Submitted, awaiting the manager's decision | |
| Changes requested | Bounced back to the payee with a note | |
| Approved | Signed off — the payment portal and payroll eligibility ungate |
Login status — a third, independent badge in the header (and the payee list's Login column): whether the payee has claimed a Greenroom portal account (Active), has an account-creation link or invitation outstanding (Invited), or has neither (no badge). A payee can be mid-onboarding with no login at all if a manager is filling in their setup for them on Path A — login status and onboarding status move independently.
Managing Onboarding
Following up with a payee
There's no separate "reminder" button. You follow up the same way you sent the original link: on the payee's detail page, the Send it to the payee control now offers a re-send, which revokes the outstanding link and issues a fresh one — only the newest link works. This is available any time an invite is outstanding, with no rate-gate to worry about; the gate only ever applies to the first send.
Tracking progress
The payee detail page is a single continuous scroll, not a set of tabs — there's no per-tab badge system to check. Instead:
- A status pill at the top of the page, next to the payee's name, shows where they stand overall.
- A second, more specific pill on the Complete onboarding fork card reflects the manager-approval state.
- Once setup is under way, the fork card also shows a plain-language progress line — "N of M setup steps complete" — with a link straight back to whichever step is unfinished.
See Onboarding status above for what each status value means.
Navigating Payee Details
The payee details page includes breadcrumb navigation at the top — "Payees" followed by the payee's name — for easy navigation back to the payee list.
Assisting Payees
Provide support to payees who encounter difficulties during onboarding. This may include answering questions about required information, helping with document uploads, or guiding them through specific steps in the process.
Required Documents by Payee Type
This table was previously inaccurate — it invented documents that don't exist in the product ("contract agreement," "payment authorization," "corporate agreements") and omitted vendors entirely. The real, company-wide document set below comes from Greenroom's document_requirements table (data-driven, not hardcoded per type) and is checked directly against it:
| Payee Type | Required | Optional (available via the Startwork packet) |
|---|---|---|
| Employee | Work-eligibility document (I-9 List A, or B + C) | — |
| Loan-out | Signed W-9 (loan-out entity) | I-9 work-eligibility document; Articles of incorporation / LLC certificate |
| Contractor | Signed W-9 | I-9 work-eligibility document |
| Vendor | Signed W-9 | Certificate of insurance |
Every payee type also signs whatever your company's Startwork packet includes beyond these system defaults — the packet's exact document set is configurable per company and is separate from this required/optional baseline. See Payment Details for how payment method itself is collected.
Onboarding Validation
Information
The finish-setup form marks every required field with an asterisk and, when you try to continue with something missing, shows a Still needed to finish personal details summary at the top listing each gap as a link straight to that field. Nothing is guessed and nothing is skipped silently.
What's actually checked: email format, a ten-digit US phone (or a valid international one), a date of birth that is a real date, not before 1900, and not in the future, and a routing number that passes the standard ABA checksum with the account number typed twice to confirm. See Form Validation for the exact messages.
A tax ID's format is checked; the number itself isn't
Greenroom checks that an SSN or EIN has the right shape and stores it encrypted. It doesn't verify the number against the IRS. If a tax ID is wrong, that surfaces later as a Check tax-setup failure on the payee — see Tax Information.
Documents
Uploads are checked for type (PDF, JPG, PNG, or WEBP), size (10 MB per file), and count (20 files per payee). The check happens before the upload starts, so an unusable file — an iPhone HEIC, for instance — is refused immediately rather than after a slow transfer.
Greenroom does not read what's inside a document. Whether an uploaded passport is the right passport, legible, or unexpired is a human judgement — which is exactly what the employer's own I-9 Section 2 certification is for. See Document Validation.
Best Practices
- Follow up with payees who haven't completed onboarding after 3-5 days
- Provide proactive support to help payees through the process
- Monitor onboarding completion regularly, especially before payroll deadlines
- Review submitted information thoroughly before approving
- Keep onboarding requirements updated as regulations or company policies change
Tip: Set a calendar reminder to check onboarding status a few days before each payroll run to ensure all necessary payees have completed the process.
Next Steps
Continue with Managing Payee Information to learn about updating payee details, see Payment Details to understand payment configuration, or see Representatives & Payment Direction to set up an agent or manager for a payee.