eZacto powered by CONFLICT

Staff payments

Administrators open Payments (/payments) from the main navigation or Team. Reports → Payments report opens /payments/report. It is available on the Worker and container, independently of payment-provider configuration.

Monthly review

The register lists active people and archived people with records for the selected month. Use Review payroll costs to inspect the existing cost report before setting an amount owed. A computed cost is a proposal; an administrator records the agreed obligation, currency, optional due date and note.

Amounts remain separate by currency. Unspecified obligations and historical settlement amounts are excluded from monetary totals and explicitly counted. Destination readiness is checked separately for Wise and Deel. A ready destination means an attached account for that provider has been verified; it does not prove a transfer was sent or received.

Provider settings

Expand Payment provider settings to choose an organization default: Wise or Deel. Wise is the initial default. Select a person to choose their Preferred payment provider: Wise, Deel, or Use organization default. Changing the organization default affects only people who inherit it. These preferences apply across months.

The preferred provider preselects the source when recording a payment. Each receipt keeps the provider actually used. One person can receive partial payments through both providers in the same month; balances remain per person, month and currency. Changing preferences never rewrites prior receipts.

Setting changes require an administrator session and a reason. They have immutable history, actor, timestamp, request ID, idempotency and version checks. Provider settings history shows changes across all dates. Monthly exports include current preferences and both providers’ readiness; audit exports include all provider-setting changes alongside the selected month's payment events.

The existing optional Deel adapter remains available for people/contract matching, timesheet submission and transfer-log deduplication. See packages/integrations. Selecting Deel here does not configure credentials or confirm a payout. Once an organization sets DEEL_TOKEN and DEEL_SYNC_START_DATE (see Integrations), the daily sync submits one Deel timesheet per person-day of approved time for people whose provider is Deel, never twice for the same entry; an entry edited after it was sent is reported, not resent.

Sorting tables

Click a column heading to sort ascending; click it again to sort descending. The monthly register, payment history and provider settings history each retain their own selection when refreshed or filtered. Sorting leaves open payment forms intact. Comments, notes and reasons are not sortable.

Dates sort chronologically, numbers numerically, and text naturally (including identifiers). Money sorts by currency and then the exact amount; unspecified values remain last in either direction. Arrow indicators and accessible header state identify the current ordering. CSV exports continue to include the complete selected month in their standard order.

Recording confirmed payments

After confirming a payment in Wise or Deel, select the person and Record confirmed payment, choose the provider actually used, enter its actual date and transfer reference, and save. Partial payments are supported. This action records a confirmed payment; it does not initiate a transfer. The existing payout_transfers store and Wise webhook log remain provider evidence, and are not automatically interpreted as a recipient receiving money by this register.

For a mistaken payment record, Void an incorrect payment record, give a reason, then record the correct receipt. A void corrects this register; it does not reverse money at either provider. The original entry and correction remain in history.

Opening history, including earlier Deel payments

Choose a completed month, expand Record historical settlement through this month, select the people whose earlier periods are confirmed settled, and enter the source and explanation. Choose a different cutoff for anyone with an unpaid exception. Each selected person's record is version checked and saved individually; if a batch stops, the screen reports how many saved and reloads before continuing.

An opening settlement covers earlier months without fabricating transaction amounts or payment dates. Explicit obligations and payments in an earlier month retain their balances. Reopen historical settlement overrides a cutoff for an individual month.

Exact historical transactions require evidence from the previous provider, such as a Deel export. To enter those receipts, reopen the applicable month's historical settlement, set the documented amount owed, and record each receipt with its actual provider (Deel or Wise), or Other historical payment, its original reference/date and source in the note. Existing historical entries remain unchanged. No historical receipts are fetched automatically.

Reports and audit

Export monthly report exports the full selected month, including status, due date, currency, recorded amount, payments, balance, historical cutoff, Wise readiness and report date. Export audit log includes every monthly action and applicable opening cutoff, actor, timestamp, request ID, command ID, source, reference, note and void target. Display filters do not narrow these month-wide exports.

Each command is an immutable event. Repeating an identical command ID is idempotent; changing its payload is refused. Concurrent writes use an atomic per-person/month version check in SQLite and D1. Payments cannot exceed the balance, and a currency cannot change while recorded payments remain. Correction events replace deletion.

All register API routes require an administrator session; API tokens and other roles are refused, matching the payroll cost report's confidentiality boundary. API server failures follow the existing Worker log and Sentry request-ID reporting path when Sentry is configured.

Payment runs and the Payments page

Payments (/payments) combines the existing obligation ledger with Wise payment runs. Administrators select people and amounts from the chosen work month, then Review selected payments. Partial payments are allowed up to the unreserved balance. Only people whose preferred provider is Wise and who have a verified Wise destination can be selected; existing manual Wise/Deel receipts remain available in the ledger.

Review shows the work period, Wise's recipient name and resolved destination, recipient amount, estimated fee, estimated source cost, estimated arrival, and an editable maximum source cost per payment. Funding uses the organization's Wise balance in the selected source currency. Send or Schedule on this separate confirmation screen authorizes the payments. Viewing a quote alone never authorizes a transfer. Reviews expire after 30 minutes. The schedule is saved as a UTC instant alongside the browser's IANA timezone; the screen labels its local timezone. The scheduled instant is the start of processing, not a guaranteed arrival time.

Approval atomically reserves each recipient amount against its person/month obligation. A competing run, manual payment, currency change, or reduction in the amount owed cannot consume those reservations. If any selected balance or destination changed, the entire approval rolls back. A run may contain up to 100 payments. Source costs and fees are additional company expenses and do not reduce the agreed recipient amount.

The Worker checks due payments every minute; the container processes them on its existing scheduler tick. Each tick advances up to ten due payments, at most three durable stages apiece. Runs are processed individually through Wise's quote, transfer and balance-funding APIs. This implementation does not use Wise batch groups; scheduling and the common run history belong to ezacto. Individual outcomes are retained when part of a run succeeds.

Execution refreshes the quote, checks the source profile, recipient and approved cost ceiling, and pauses a payment that no longer matches. It saves the execution quote and stable transaction UUID before creating a transfer. Retries of an uncertain creation reuse the same payload and UUID. Funding is marked before the request: a lost response causes status reconciliation, never an automatic second funding attempt. Authentication, insufficient funds and other unresolved funding failures retain their reservations and direct the operator to the existing transfer in Wise. HTTP 429 delays subsequent attempts using Retry-After and bounded backoff. Creation recovery is bounded; Check status can request another reconciliation with the original transaction identity.

Cancel unsent payments releases only items that have never entered transfer creation. Payments already creating, funding or processing must be reconciled/cancelled at Wise. Changing a destination does not redirect an approved payment. The original destination remains in the run's review and audit history.

Wise's outgoing_payment_sent status records a payment in the immutable register exactly once and releases its reservation. This means Wise confirmed dispatch; it is not an assertion of final bank receipt. Where a verified webhook supplies the event time, its UTC date is used; otherwise the observed confirmation date is recorded and identified in the note. Confirmed refunds append a void event and restore the outstanding balance. Paid transfers are polled for 90 days; later verified webhook deliveries can request reconciliation too. Operators cannot manually void these provider-created receipts. The original receipt and any refund remain visible in the ledger audit.

Run approvals, cancellation requests, reconciliation requests and processing transitions have a durable audit in payment_run_audit. No test or migration initiates a transfer. API funding availability depends on the Wise account and currency route; a route must offer balance funding before it can be reviewed.

Payments report

Reports → Payments report, or /payments/report, shows up to twelve work months. It includes balances by person/month, individual transfer progress, and recorded receipts with actual provider/reference and payment or confirmation date. Filter by person, currency and status; Export filtered CSV exports those same filtered rows. Amounts owed, paid, reserved, and available to pay are summed separately by currency. Unspecified historical amounts are counted but excluded from monetary totals. Transfer costs are labelled as review estimates or execution quotes, not bank-statement expenses.

The report describes the current ledger for the selected work months, not a historical “as of” snapshot. Its receipt section includes manual payments from Wise, Deel and historical providers as well as new automatic Wise payments, excluding voided receipts.

Work months and actuals review

The work month is the period the earnings belong to. August work paid in September stays in the August ledger; its receipt separately records the real September payment date. Payments and the payment report default to the previous completed month. September earnings can be confirmed from October 1 in the organization's timezone. Manual entries remain available for reasoned overrides.

In Payments → Review actuals, load the selected work month and choose a contractor. The review uses the contractor report's captured rounded seconds and captured cost rates, priced per entry with the same rounding. It includes tracked time regardless of timesheet approval. Select projects or change included hours on individual entries. Missing selected rates must be resolved before confirmation.

Confirm earnings saves an immutable snapshot and sets the month's total owed; it never adds the total twice and never transfers money. Revisions show the existing balance and cannot reduce earnings below paid or reserved funds. Changed source entries or concurrent ledger edits require a fresh review. Excluded hours are not added to the balance; return to the review to include them later. To make a partial payment against the whole month's earnings, confirm all hours and change the payment amount at the separate Pay now → review → send/schedule step.

Historical settlements block actuals imports until explicitly reopened. Contractor invoices and advance credits have their own audit tabs; importing actuals does not generate invoices or record deposits.

Correcting a work-month allocation

A completed register can be reassigned to an empty work month through a targeted operator insert into staff_payment_period_moves. This is an operational data correction, never deployment seed data. Verify the person, source and destination, latest source version, receipts and all payment-run states before writing. The insert must specify its actor, request ID, timestamp and reason. The database rejects a changed source, an occupied destination or active payment runs.

Original event rows and receipt dates remain immutable. The effective ledger projects those entries into the corrected period and leaves correction notes in the original period; payment-run items and audit history record the new work month. Future refunds reconcile against that corrected month. After the correction, verify balances, receipt reference and date, run history, and both monthly reports. Historical settlement entries should be recorded separately after those checks.

Historical amounts from contractor costs

A settled month without an exact ledger amount displays the selected work month's current contractor cost, using the same captured rounded seconds, captured cost rates, and per-entry rounding as the contractor cost report. The API identifies this amount with amount_basis: contractor_cost; exact ledger amounts use amount_basis: ledger and always take precedence. Missing rates, absent entries, and non-contractors remain unspecified. This is a live report valuation, not a frozen historical receipt: editing the source time entries changes the displayed cost. The settlement cutoff and original audit records remain unchanged.

Balances, the payments report, and CSV label the amount basis. Historical costs have a separate total from recorded payments; they do not create payable balances, receipts, dates, or transfers. Reopening a month removes this fallback so its exact earnings can be reviewed normally. This reporting change requires no data repair or schema migration.

Hide empty people

Payments and the payments report default to people with hours or payment activity in the selected work month. Enable Show people with no hours or payments to include everyone. Nonzero captured hours remain visible even without rates or confirmed earnings; amounts, reservations and payment history also keep a person visible. A blanket historical settlement by itself does not count as activity. Monthly and filtered report exports follow this checkbox; the full audit export keeps all records. The filter changes visibility only, not ledger records.

Payment allocations

An allocation links part of one payment to the earnings it pays. It is an additive layer: monthly totals, payments and payment runs are unchanged, and existing monthly payments stay unallocated until an administrator allocates them explicitly. Hour splits are never inferred.

People see only their own figures, read-only, at /my-payments (GET /api/v1/me/payments) when the own_money setting is on; see contractor-payments.md. These administrator routes are unchanged.

Contractor advances (#900)

The Advances tab prepares an advance/deposit before work or an invoice exists. Only administrators with a session may prepare/approve transfers or manage credit; API tokens and other profiles cannot use these routes. Choose an active contractor, Wise destination, recipient/source currencies, amount, intended work month and a reason. Review the verified recipient and maximum source cost including fees, then explicitly confirm the transfer. The normal payment-run processor handles retries, scheduling and reconciliation. Advances are labeled in History and transfer reports. The preview API also accepts an optional intended advance_project_id.

Pending transfers reserve advance funds, not a work month's payable balance. Only confirmed settlement creates credit. No future hours automatically consume it. Existing payments and monthly balances are not migrated or reinterpreted.

Load credit by activity dates to see settled, applied, returned and unapplied amounts, plus opening + settlements − net applications − returns = closing credit for each advance/currency. Current pending and available amounts are separate from historical statement dates. Reversals are negative applications in their activity period.

To apply credit, choose a reviewed earning month and an eligible month, project or entry; enter the partial amount and a reason, review the remaining earnings, and confirm. One atomic database command consumes credit and projects its settlement onto the monthly register/allocation ledger with source advance_credit, referencing the original advance. It creates no new earning, payment run or provider transfer. A payee sees Advance credit applied (no new transfer), rather than another paycheck. Month/project allocations never invent a split across time entries.

Reversing an application requires a reason and restores both credit and the payable balance; the application, allocation and reversal history remain. Recording a return requires the amount, bank reference and confirmation that the money was already returned; this action sends no funds. Duplicate return references on one advance are refused. Credit still applied must be reversed before it can be returned. A confirmed provider refund reverses outstanding applications and returns the remaining credit atomically. Cancellation before settlement releases pending funds without credit.

Routes (administrator sessions only):

Advance selections use purpose: "advance", explicit currency, advance_reason and optional advance_project_id on the existing payment-run preview command. An application's id is its retry key; changing the content under that ID is refused. Person/currency, settled capacity, reviewed earnings, reservations and allocation limits are checked inside the database transaction on SQLite and D1. Source-hour changes retain the captured allocation and are reviewed through the Allocations tab. No customer-specific correction or live transfer is part of the migration or fixtures.

Contractor payable invoices (#901)

Contractor invoices on Payments documents existing earning obligations. These are payable documents, separate from customer receivable invoices, numbering and tax. Recording, correcting, receiving or voiding one never changes earnings, payments, advances or allocations. A contractor reference is unique across all periods/currencies for that contractor (trimmed, ASCII case-insensitive). A retry with the same command replays; a different document using that reference is refused. Correct the existing document through a new optimistic-versioned command.

Draft from a confirmed actuals review, including signed correction hours, or record received lines explicitly. Lines may reference an entry or a project. Project summaries match only a single captured rate; mixed rates require entry references. Partial quantities are supported. Missing references, wrong rates, excess hours/rounded cents and overlapping received claims are flagged for review. Project-level and entry-level claims on the same project are conservatively flagged instead of inventing a split. Drafts do not consume invoiced capacity; voided documents release it. A monthly amount that differs from the reviewed earning snapshot also requires review before matching.

The report separates earned, actual received-document totals, matched invoice amounts, paid for the work month, and earnings without a matched invoice. The last figure is earned minus matched received lines, not a new payable balance. Unmatched invoice lines remain visible without becoming earnings. Currency rows never net. There is no historical invoice inferred from an old payment or settlement cutoff.

Every correction preserves earlier versions, lines, earning-review IDs, documents, reasons and actors. Work-period and currency corrections change the document only; earlier payment allocations stay in their original period. Existing or historically recorded payments require explicit acknowledgement before a correction. Contractor identity and reference stay fixed; void an erroneous identity/reference and record the correct document. A received invoice cannot silently become a draft again.

A PDF or other file can be uploaded after the invoice has an identity, then included in a new version. Uploads use the shared multipart/file validation, a 25 MiB file limit and content-addressed storage. Staged files remain administrator-only until a received version explicitly includes them. Download ownership is checked each time; files download as attachments with no-store and nosniff. The public demo refuses uploads before parsing or object writes. File objects participate in the existing backup/export machinery, and document/version metadata is immutable.

Administrators use session-authenticated GET/POST /api/v1/staff-invoices and the /staff-invoices/:invoiceId/documents upload/content routes. API tokens and other profiles cannot record or correct documents. A person with own-money viewing enabled can read their received/voided documents at GET /api/v1/me/staff-invoices?month=… and on My payments. The subject comes only from their session; drafts, other people's documents, and unpublished uploads are excluded. Reasons entered on a received invoice are shared with that contractor.

Combined contractor review (#902)

GET /api/v1/staff-payments/contractor-review?month=YYYY-MM is an administrator-session-only, uncached read available on Worker and container. It joins captured-hours proposals, the latest immutable actuals review (actor, reason and version), recorded obligations and receipts, contractor invoice versions, allocation evidence, advance credit and payment-run item states. Currency rows are independent. The credit_period states the date range of the credit statement; payable balances and transfer states describe current records.

version identifies the exact financial/source review content deterministically. Repeated reads do not create earnings, invoices, allocations, credit applications or payments. It changes when those sources change, not merely when the request clock advances. Entry-rate/source changes and unfinished work months block monetary proposals; historical settlements stay settled, and explicit amount or selection overrides retain their evidence.

Monthly allocation proposals link existing unassigned payments to reviewed monthly earnings without inferring a project/entry split. Those payments take capacity before a proposed credit application; both consume one shared reviewed-earnings capacity. Credit proposals use only settled available credit in the same currency and respect intended work month. Project-specific or differently intended advances remain visible for explicit target review. The remaining-to-pay figure never assumes that a proposal has already executed. Unknown balances remain unknown.

On Payments → Reconcile, load the selected work month to review one row per person/currency. The sortable summary separates recorded earnings, hours-based earnings, paid/reserved amounts, current payable and the projected balance after proposed credits. Expand a person for review reasons, captured hours, invoice versions/documents, receipts, recorded allocations, advance intent and payment attempts. Confirm the selected monthly receipt allocations and settled credit applications here with a reason, or use the related-section buttons for actuals and invoice changes. Payment progress links to History, whose existing Check status only reconciles an already prepared provider operation; it never resets it to a new transfer. Cancellation is limited to unsent items. The existing processor still handles at most ten due items and three durable stages per tick. Refreshes and month changes clear prior figures before loading, stale responses are discarded and session end clears the evidence.

Explicit acceptance and recovery

POST /api/v1/staff-payments/contractor-review/acceptances accepts the displayed person/currency, its review_version and source_revision, selected allocation and/or credit changes, an identifier and a reason. Only an administrator session can confirm. The server derives exact monthly commands from the fresh review; callers cannot supply amounts, provider commands or another actor. Changed hours, missing rates, unsettled months and blocked proposals require review first.

Migration 0138 tracks source revisions for shared configuration, each contractor and each work month. A consistent read retries at most three times if sources move while it loads. Unrelated contractors' hours do not invalidate a person's confirmation. The insertion rechecks the person's revision inside the database, then existing allocation/advance triggers execute all selected changes in the same SQLite statement on both runtimes. If any check fails, every change and the acceptance roll back. No partial application needs a second executor.

GET .../contractor-review/acceptances?month=… returns completed immutable confirmations, with actor/reason/time and links to their allocation/application identities. After a lost response, retrying the same identifier and exact intent returns the original confirmation, even after later refunds. Changing the identifier/intent cannot spend an old review twice. The screen retains the original intent for a manual retry; reload obtains current balances and history. Confirming these links never creates an invoice, replaces an earnings override, creates/funds a transfer or approves a payment run.

The synthetic SQLite/D1 lifecycle in packages/db/test/contractor-review.test.ts covers an advance before hours, reviewed earnings, a received invoice, partial receipt, accepted credit, final receipt, settlement and confirmed provider refund, with payment-report totals before/after the refund. It also covers concurrent same/different-identifier retries, stale-read-to-write rejection, missing rates, independent contractors and full rollback after a later step fails. Chromium covers the explicit confirmation and same-identifier retry after a lost response.

Scheduled-action seam

Reconciliation is a proposal producer, currently triggered by the authenticated read. General scheduled actions (#61/#62/#63) can use the same reader to prepare a manifest keyed by person, work month and source version. Their notification or confirmation never becomes authority to create/fund a payout. Accepted monetary work continues through the immutable ledger commands and existing payment-run preview/approval, with processDue on the existing Worker cron/container timer. This slice adds no job type, scheduler, transfer executor or automatic application of credit. A later scheduler integration must retain that single execution seam.

The scheduled-action integration itself remains owned by #61/#62/#63. This contractor flow reuses the current payout execution and recovery seam.