# 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

1. **A document arrives** — by upload or [by email](https://docs.payvy.com/guide/email-intake/) — and lands in the document inbox on your S3-compatible storage. The same file arriving twice is caught.
2. **A model reads it** (optional): vendor, invoice number, dates, lines, tax and total. Payvy [checks the arithmetic](https://docs.payvy.com/guide/extraction/), matches the vendor, flags duplicates, and keeps a *draft*. Nothing becomes a bill until someone calls `bill.create`.
3. **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.
4. **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.
5. **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.
6. **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

| | 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](https://docs.payvy.com/guide/agents-and-authority/) for the command tiers, and [Commands: REST & MCP](https://docs.payvy.com/api/commands/) for the interface.

## 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](https://docs.payvy.com/guide/integrations/) for current status.