#Contractor payments and payouts

Module id: MOD-PAYMENTS
Doc profile: capability

Contractor-facing payment schedules and history on /contractor/payments: This week totals, Previous / Upcoming tabs over sent and company-approved time entries, a shift details popup, and a bounded Stripe account affordance. Programme fence MON-MARKETPLACE blocks Connect onboarding, KYC, live balance fetch, and payouts until answered. Admin payment-schedule editors and paid-status writes stay MOD-ADMIN; this module owns the contractor read surface and the Upcoming payment cycle PostMark outbound contract.

#Purpose

Give signed-in contractors one place to see what they are owed and what was already paid for shifts they tracked, open a row’s shift details, and (when an account id exists) open the Stripe dashboard. An upcoming-cycle email can land them on the Upcoming tab. Money writes and Connect account creation are out of scope here — schedules are read models under RLS; Stripe Connect plugins on the source page are fenced, not ported.

#Scope boundaries

#Actors

#Capability composition

One contractor cabinet route hosts overview cards, schedule tabs, and the repeating payment list. Stripe control and balance label sit in the title/overview row but Connect and live balance stay fenced. Cycle email is an edge outbound that deep-links back into the same route’s Upcoming tab.

Bubble evidence for page, workflows, option sets, and connector is under Traceability / IR evidence.

#Primary journeys

Journeys are reconstructed from contractor_payment PageLoaded and ButtonClicked workflows, RG search states, and the PostMark call Upcoming payment cycle (for contractor). Connect plugin workflows exist on the Stripe control but are not delivered until MON-MARKETPLACE is answered.

#J1 — Contractor reviews payment schedules

1. A signed-in contractor opens /contractor/payments (optionally with ?tab=previous_payments or ?tab=upcoming_payment).
2. Signed-out visitors redirect to /; signed-in admin redirects to admin; signed-in company redirects to company shifts — only contractors remain on the page.
3. The page shows heading “Payments”, overview “This week” with a $ sum of paid_amount for the contractor’s sent rows whose related shift date falls in the current ISO week, and tabs defaulting to Previous payments.
4. Previous tab lists sent + company-approved rows with payment_status = paid; Upcoming lists the same filters with payment_status not equal to paid; empty filter shows “No result found”.
5. Each row shows Company, Payment ($ × logged hours including minutes/60 × shift hours required), Shift date, and Status (“Paid” or “Unpaid” when Upcoming is selected).
6. Details opens the shift details popup (Company Name, Job position, Shift date, Total of payment via skill-matched company contractor rate × hours, Hours worked, Job location, feedback or “No feedback”); Close hides and resets the popup.
7. Load failures show a user-visible error — not a blank success state. No contractor money writes on this surface.

#J2 — Contractor uses evidenced Stripe account fields

1. On /contractor/payments, the Stripe control shows “View stripe account” when profiles.stripe_account_id is non-empty, and “Connect Stripe account” when empty.
2. When an id is present, click opens https://dashboard.stripe.com/dashboard in a new tab.
3. When empty, click must not run Connect plugin actions or persist new stripe fields — show a pending/unavailable affordance until MON-MARKETPLACE is answered.
4. “Your balance” label may render; live Stripe balance via connected-account header is out of scope — use empty formatting $0 until the programme unblocks it.

#J3 — Upcoming payment cycle email lands on Upcoming tab

1. An authorized admin/service caller invokes the upcoming-payment-cycle edge (source admin workflows mark paid then call PostMark; admin UI remains MOD-ADMIN).
2. The edge POSTs PostMark email/withTemplate with server-only secrets, TemplateAlias evidenced as user-invitation-3, To = contractor email, and empty TemplateModel as exported — timeout and idempotency enforced.
3. Product landing contract: the contractor opens /contractor/payments?tab=upcoming_payment and sees the Upcoming schedule from J1 (whether that URL is already inside the PostMark template body is HQ-1).
4. Missing secrets or PostMark failures fail closed with a mapped error; no token leaks to the client.

#Vertical slices (decompose)

#Key UI states

#Style and fidelity

Cabinet workspace outlet on /contractor/payments. Transcribe visible copy (“Payments”, “This week”, “Previous payments”, “Upcoming payment schedule”, column headers, “Details”, “No result found”, popup labels, Stripe control strings). Stamp data-bubble-id on page and payment-region roots. Preserve RG column hierarchy — do not restyle into a marketing card grid. Shared tokens come from the app-level stylesheet that SHELL-LAYOUT (MOD-SHELL) delivers out of IR styles (ir/slices/styles____part_all.json — 49 styles, 8 color tokens, 1 font token); this cycle's module map has no separate design-system module, so do not defer a token to one. Responsive element conditions at narrow widths stay structural tweaks, not a different product layout.

#Failure modes

#Needs human clarification

#Traceability

#IR evidence

#Module evidence roots

• bTIzV0 — page contractor_payment (/pages/bTIzW0); sole module evidence root.

Supporting segments: ir/slices/bTIzW0____root.json, user, rates (dead), status_paid, external_ns:bTNMZ.

#Path-key ↔ inventory id aliases

#PageLoaded gates (chased)

• bTNMB2 / bTNMD2: CurrentUser not_logged_in → ChangePage index (bTGYf).
• bTNMH2: logged in and role ≠ contractor → bTNMJ2 admin when role = admin (bTHun0); bTNMO2 company when role = company (bTITd).

#Schedule filters (chased)

• Default RG search (bTJCQ0): contractor_user = CurrentUser, send_boolean true, approve_company_boolean true, status_option_status_paid equals paid.
• When G-sort tab_ equals upcoming_payment: same three constraints with status not equal paid.
• Custom state tab_ default previous_payments (custom_state:bTJBr0:tab_); clicks set Previous (bTMOK) or Upcoming (bTMOR).

#This week sum (chased)

• Group bTJAp0 Search time_tracking1 where contractor = CurrentUser and send_boolean true; filter shift.date week equals current week; sum paid___number.

#Row payment amount (chased)

• Number group behind payment cell (export path under RG content; display text bTJCW0): logged__hours__number + (logged__minuts__number / 60).
• Display text bTJCW0: that number × related shift hours_required_number (via RG content bTJCR0), prefixed $.

#Stripe control (chased)

• Default copy “View stripe account”; state when stripe_account_id_text is empty → “Connect Stripe account” (bTJAS0 state 1).
• bTMLD/bTMLL: when id not empty → OpenURL https://dashboard.stripe.com/dashboard new tab.
• bTMFn: id empty and approve1_boolean false → Connect plugin action (fenced).
• bTNJn0: id empty and approve1_boolean true → Connect login / MakeChangeCurrentUser / OpenURL chain (fenced).
• Balance group bTJBb0: GetDataFromAPI Stripe with Stripe-Account header = current user’s account id — do not port under MON-MARKETPLACE; keep label + $0 empty formatting from source.

#PostMark upcoming cycle (chased)

• Connector name “Upcoming payment cycle (for contractor)”; POST https://api.postmarkapp.com/email/withTemplate.
• Admin actions bTNNo / bTNNp: body From fixed, To = parent row contractor_user.email, TemplateAlias user-invitation-3, TemplateModel {}.
• No TemplateModel deep-link fields in export — see HQ-1.

#Residual dispositions

• rates — every field deleted; payment math uses logged hours × hours_required (list) and company-user skill rate fields (popup), not the rates type.
• Style / public_key / settings tokens — answered structurally; not journey items.

#Privacy & authorization (time_tracking1 → time_entries)

• privacy_role:time_tracking1:contractor_ — view/search when CurrentUser is the contractor on the row.
• privacy_role:time_tracking1:company_ — view/search via shift ownership chain (company role).
• privacy_role:time_tracking1:admin_ — view/search for admin role.
• privacy_role:time_tracking1:everyone — no view/search.

This module’s SPA only needs contractor-scoped reads on /contractor/payments. Target: RLS so authenticated contractors read only own contractor_id rows; no contractor update of money fields here. Company/admin writers stay on other modules with server authority (MON-CLIENT-WRITES).