Inspiration

Weekly contractor payouts look simple until finance has to reconcile scanned invoices, contract clauses, payment history, and last-minute email requests. A repeated invoice can look new. A changed payee address can look routine. A legitimate surcharge can look unsupported until the contractor supplies the missing approval.

I built PayoutGuard for finance and operations teams at agencies and marketplaces that use PayPal Payouts. The goal is to make each payment decision explainable before money leaves, while giving contractors a fair way to provide additional evidence.

What it does

PayoutGuard turns a messy inbox into an auditable payment run. It reads PDF invoices and phone photos, compares them with contract terms, the vendor master, payout history, and relevant emails, then produces a verdict, a clause reference, quoted evidence, and a contractor-facing remittance note. A human approves the initial payout batch.

The fictional agency, Brightloom Studio, has eight invoices totaling $25,580. Five pass in full. Three need attention.

  • Priya Nair — short pay. Her $4,850 invoice includes a $650 rush surcharge without the written pre-approval required by clause 4.3. PayoutGuard approves the supported $4,200.
  • Diego Ramos — duplicate hold. A $1,440 invoice repeats work already paid. Adding a zero to the invoice number does not change the underlying work, period, and amount.
  • Tom Okafor — payee quarantine. A $9,400 invoice requests a new payment address through an email from a look-alike domain. PayoutGuard holds the payment for independent verification under clause 5.

After approval, six payable items totaling $14,090 go into one PayPal Payouts sandbox batch, with a remittance note on each item. Batch IDs and item statuses are visible in the interface. The initial audit stops $11,490.

Then Priya supplies a forwarded email from her engagement PM approving the flat $650 surcharge before the work. PayoutGuard checks the new evidence against clause 4.3 and releases a separate $650 top-up, capped at the amount withheld. Priya is paid in full, and $10,840 remains protected through the duplicate and payee holds.

How it's built

The frontend uses React, TypeScript, Vite, and Tailwind CSS. It presents the source documents, audit decisions, and payout tray together, with a side-by-side document and evidence drawer.

The Python/FastAPI backend uses OpenAI's Responses API for multimodal invoice analysis and structured outputs validated with Pydantic. Deterministic checks cover payee mismatches, duplicate evidence, and invoice arithmetic. These checks can raise the severity of a decision. They cannot silently turn a flagged payment into an approval.

The PayPal integration uses OAuth, the Payouts API, per-item remittance notes, and payout-status retrieval. A webhook endpoint verifies PayPal event signatures, while background polling provides a fallback for status updates. The appeal flow creates a second, single-item batch and prevents a completed top-up from being repeated.

Run state is persisted in JSON. Audit caching makes the fixed demonstration repeatable, with a force-live audit option for fresh analysis. Docker packages the frontend and backend for deployment on Render.

Challenges faced

The hardest decisions depended on context. A matching amount alone is not enough to establish a duplicate. Ordinary weekend hours and a separate rush premium have different approval requirements. A suspicious payee email requires verification, while the person named on the invoice may be legitimate.

Payment execution had to be kept separate from the audit decision, reconcile asynchronous payment statuses, and ensure that an appeal could release only the supported amount still withheld. Making all of that understandable in a short demonstration drove the evidence drawer, explicit verdicts, and visible batch IDs.

Accomplishments and lessons

Connected document interpretation, contract evidence, human approval, PayPal payout execution, and an appeal into one flow. The seeded dataset covers all eight expected verdicts and the $650 appeal decision. The strongest lesson was that useful financial automation needs both an understandable reason to hold a payment and a clear path to release it when the evidence changes.

What's next

I'd add authenticated workspaces, durable multi-tenant storage, role-based approval policies, stronger payee-change verification, and a contractor portal for submitting appeal evidence. We would also expand evaluation across varied invoice formats and ambiguous contract language before considering production use.

Demo and development disclosure

All contractors, invoices, contracts, emails, and amounts in the scenario are synthetic. Payments use the PayPal sandbox. The hosted demo uses cached audit results for repeatability, and the code also supports live AI audits. The local frontend mock mode simulates payment statuses separately.

AI coding assistants, including Codex and Claude Code, assisted development. Generated artwork was used for submission visuals. The displayed dollar amounts describe this synthetic scenario.

Built With

Share this project:

Updates

Submission history