How Payvy works
A bill in Payvy follows the workflow set for its vendor. Agents prepare each step; a person authorizes the ones that matter. Payvy never holds or moves money — it instructs your own bank.
The lifecycle
Section titled “The lifecycle”- A document arrives — by upload or by email — and lands in the document inbox on your S3-compatible storage. The same file arriving twice is caught.
- A model reads it (optional): vendor, invoice number, dates, lines, tax and total. Payvy checks the arithmetic, matches the vendor, flags duplicates, and keeps a draft. Nothing becomes a bill until someone calls
bill.create. - The bill follows its vendor’s workflow: approve steps, holds, waits for external signals, then payment. A bill pins the workflow version it arrived under — editing a workflow never changes a bill already in flight.
- A person releases payment. Release previews the exact payment (bank, account, recipient, last four, method, amount) and commits with a single-use token tied to that preview.
- Your bank pays; Payvy watches. Only the bank’s answer marks a bill paid. Failures and ACH returns bring the bill back with the reason.
- Every change is on the record. Each write appends an event in the same database transaction, and organizations are isolated by Postgres row-level security. Where a bill stands is derived from approvals, signals and the release every time — never a stored status that can drift.
Who does what
Section titled “Who does what”| Agents (API/MCP keys) | People | |
|---|---|---|
| Read bills, enter bills, file documents | ✓ | ✓ |
| Signal events, propose workflows and payees | ✓ | ✓ |
| Approve, reject, release payment, void | — (tools not even listed) | ✓ |
| Accept a workflow or a payee change | — | ✓ |
See Agents & authority for the command tiers, and Commands: REST & MCP for the interface.
What is not built yet
Section titled “What is not built yet”Approving and releasing inside the web app, the invoice viewer, the visual workflow builder, accounting sync (VisiBooks, QuickBooks Online, Xero), purchase-order matching, and banks beyond Mercury are planned. The API, MCP server and CLI cover the workflow today; see Integrations for current status.