ORCHESTRA AI: the trust layer between work and payment
From vague requests to verified work and PayPal settlement. AI advises. Humans approve. PayPal settles.
Inspiration
When a client hires a freelancer or an agency, the key facts live in different places: the request in a chat, the deliverables in a shared drive, the approval in an email, and the invoice in yet another tool. Nobody can say at a glance what was agreed, what was actually delivered, and whether it is time to pay.
I wanted to connect those three things in one traceable workflow, and to do it without handing control of money to an AI. The AI should help people understand and prepare. People should keep the authority over irreversible decisions, and PayPal should be the system that settles the payment.
What it does
ORCHESTRA AI has two separate workspaces, one for the client who pays and one for the provider who delivers.
- Define. The client writes a plain-language request. The Intent Agent turns it into a structured agreement with milestones, amounts and acceptance criteria. It flags missing information (like a deadline) and rewrites vague or circular criteria ("Design approved by client") into ones that can be verified.
- Prove. The provider accepts, works milestone by milestone, and submits evidence: a description, links, and image files.
- Verify. The Evidence Agent compares the evidence with each criterion and explains what is verified, what is missing and why. Deterministic checks verify links (HTTPS only, with SSRF protections), and a vision model looks at image evidence. Everything is clearly labeled as advisory.
- Approve. Only the client can approve, and the decision is recorded with identity and time. If the AI is not satisfied, the client can still approve, but must explicitly acknowledge it. The AI never blocks the human and never decides for them.
- Pay. After a recorded approval, the platform creates and sends a PayPal invoice for that specific milestone. When PayPal's webhook confirms the payment, the milestone is paid and the next one unlocks.
A Payment readiness panel explains, for each milestone, why payment is blocked or ready, and an activity timeline shows who did what (client, provider, AI, PayPal).
How I built it
- Backend: FastAPI, PostgreSQL, SQLAlchemy and Alembic.
- Frontend: React, TypeScript and Vite, with AG Grid Community for the data tables.
- AI: GPT-OSS and Qwen models served by Groq's free tier, through a swappable provider layer, with strict JSON schemas, validation and retries.
- Payments: PayPal Sandbox, using the Invoicing API and webhooks.
- Everything runs with Docker Compose. A mock mode starts without any API key so anyone can try the whole flow.
The architecture separates intelligence from authority. All status changes go through deterministic state machines in plain code. A permission matrix, enforced on the server and covered by tests, defines who can do what: the AI cannot approve work, create invoices or confirm payments. Invoice creation is a server step that requires a recorded client approval, and payment is only confirmed by PayPal.
How PayPal is used:
- The Invoicing API creates and sends one invoice per approved milestone, with idempotent request IDs so retries never create duplicates.
- Webhooks are verified with PayPal's signature verification, deduplicated and processed once. Each event is stored and linked to its milestone.
- A manual sync endpoint exists as a fallback, and the interface states honestly whether a payment was confirmed by the webhook or by a manual sync.
- A PayPal panel shows the invoice timeline, the events received, and whether the signature was verified.
The project has more than 170 automated tests covering the state machines, permissions, PayPal handling, AI validation and the interface.
Challenges
- Getting PayPal right. A Sandbox app token without the invoicing scope returned 403 errors. Creating an invoice only returns its ID when the request asks for the full representation. The webhook payload keeps the invoice ID in a nested field, and verified events that are not relevant must still be answered with a success code.
- Webhooks need a public URL. I used a tunnel during development. When the tunnel was down, payments were still found through the sync fallback, which taught me to label the source of every confirmation.
- Honest AI under real limits. The free tier allows a small number of tokens per minute, and the models cannot read arbitrary files or open linked pages. Instead of pretending otherwise, I added deterministic link checks, vision analysis for PNG and JPEG evidence, and wording that never overstates what the AI saw. Evidence text is treated as untrusted data, with prompt-injection tests.
- Letting the human decide. My first version blocked approval whenever the AI could not verify a criterion. That contradicted the whole idea, and it made some criteria impossible to satisfy. The final design lets the client approve with an explicit, recorded acknowledgement.
- Design. The product went through several passes, from a technical dashboard to two clearly separated workspaces with a landing page and a Proof-to-Pay timeline.
Accomplishments I'm proud of
- A complete loop proven with a real PayPal Sandbox payment confirmed by a signed webhook.
- Permission boundaries that are visible to the user and tested in code.
- A project that anyone can run from the README, with or without API keys.
What I learned
- Put LLMs between deterministic guardrails: validate their output, never give them authority, and always say what they could not check.
- Payments need idempotency and provenance from the start: every confirmation should say where it came from.
- Trust comes from showing the reasoning and the audit trail, not from a confident answer.
What's next
Scope-creep detection and versioned agreements, a dispute and review flow, a provider copilot, notifications, real authentication, and multi-project analytics. ORCHESTRA AI is a Sandbox prototype that uses standard PayPal invoicing. It is not an escrow service and does not create legally binding contracts.
Try it
- Code (MIT license): https://github.com/Wiameelhernoussi/Orchestra-AI
- The README explains setup in mock mode (no keys) and real mode (Groq and PayPal Sandbox keys, plus a public tunnel for webhooks).
- Demo files for the evidence step are in
demo-assets/.
Built With
- ag-grid
- alembic
- docker
- docker-compose
- fastapi
- gpt-oss
- groq
- paypal
- paypal-invoicing-api
- paypal-sandbox
- paypal-webhooks
- pillow
- postgresql
- pydantic
- pytest
- python
- qwen
- react
- sqlalchemy
- typescript
- vite