Inspiration
When autonomous AI agents book trips, events, or multi-vendor services today, they suffer from a dangerous flaw: they treat complex, interdependent supply chains as a collection of isolated transactions.
Consider organizing an outdoor dessert pop-up: you need a venue stall, refrigerated display rental, and early-morning refrigerated delivery.
If the stall's electricity is unavailable, the refrigerator cannot run. If the refrigerator cannot run, the perishable inventory spoils. If one vendor drops out after your card has already been charged, you are left holding non-refundable receipts for an event that cannot happen. Worse still, giving an autonomous LLM an unrestricted credit card to "fix the problem" frequently leads to unauthorized spending, hallucinated items, and budget overruns.
We asked ourselves: How do we enable AI-driven multi-party commerce without surrendering financial sovereignty?
Our answer is PlanLock: an agentic commerce platform that synchronizes multi-vendor logistics with two-phase PayPal authorizations, atomic inventory reservations, and an ironclad human-in-the-loop consent boundary.
What It Does
PlanLock acts as an intelligent, financially guarded coordinator for multi-supplier events:
Intelligent Constraint Validation: Validates physical, temporal, and budgetary constraints before any money moves. It verifies that Total Supplier Cost <= Max Budget and checks schedule feasibility so that Delivery Time + Setup Buffer <= Event Start Time.
Atomic Inventory Hold: Places a 15-minute time-to-live (TTL = 900 seconds) reservation lock across all chosen vendors simultaneously, preventing race conditions.
Two-Phase Linked Checkout: Instead of directly charging the customer, PlanLock creates separate supplier orders on PayPal using intent: "AUTHORIZE". Funds are reserved on hold, but zero dollars are captured until all suppliers are locked in.
Instant Failure Isolation & Paused Captures: If a supplier cancels or fails a dependency check (e.g., power failure), PlanLock's transactional outbox triggers an immediate circuit breaker (CAPTURES_PAUSED_FOR_RECOVERY), preventing cascade billing.
AI "What-If" Analysis with Zero-Autonomous-Spending: PlanLock's AI analyst simulates viable alternatives and generates recovery proposals. However, it operates in a strictly read-only sandbox: no replacement purchases, voids, or refunds can execute without the customer's explicit, signed approval.
How We Built It
We built PlanLock with a resilience-first architecture spanning the browser, an Express/TypeScript backend, and PayPal's REST APIs:
Frontend: React 19, Vite, TypeScript, Tailwind CSS, Lucide icons, and AG Studio for rich analytics visualization.
Backend: Node.js, Express, TypeScript, and a unified storage engine supporting SQLite for rapid local demos and PostgreSQL with advisory locks for production.
Payments: Native PayPal REST API v2 (/v2/checkout/orders with intent: 'AUTHORIZE', /v2/payments/authorizations/{id}/capture, /v2/payments/authorizations/{id}/void, and /v2/payments/captures/{id}/refund).
Webhooks & Idempotency: Raw-body cryptographic signature verification via /v1/notifications/verify-webhook-signature with strict replay prevention.
AI Core: Constrained LLM reasoning with allowlisted parameter schemas (Gemini / Groq) that reject invented catalog items and prevent financial prompt injections.
Challenges We Ran Into
- Two-Phase Distributed Consensus Over HTTP
In distributed systems, synchronizing state between local databases and an external payment gateway is notoriously difficult. A network drop during capture could leave an order in an unknown state.
Solution: We designed an operation lease pattern (claimFinancialOperation('CAPTURE')). If an ambiguous timeout occurs (AmbiguousPayPalError), the payment is transitioned to reconciliationRequired: true and the booking is gated into RECOVERY_REQUIRED. Blind retries are blocked until PayPal's actual order state is verified via /v2/checkout/orders/{id} or a signed webhook .
- Preventing Buyer Popup Cancellation Deadlocks
In early testing, if a user opened the PayPal modal and closed it without completing approval, the payment record was marked CANCELLED, permanently deadlocking the checkout flow.
Solution: We decoupled the local checkout attempt from the PayPal order lifecycle. Closing the popup sets the payment status to CANCELLED and clears the stale paypal_order_id. Clicking Retry Payment resets the item to AWAITING_APPROVAL and dispatches a fresh request with a deterministic, attempt-specific idempotency key: Key = hash(payment_id + attempt_count) This guarantees that stale or cancelled PayPal orders are never reused and no duplicate captures can occur.
- Taming the Autonomous Agent (The Human Consent Boundary)
Large Language Models are eager to please and will happily "fix" an itinerary by hallucinating replacement vendors or auto-charging cards.
Solution: We implemented an air-gapped tool boundary. The AI has read-only access to the catalog and state facts (FINANCIALS, DEPENDENCIES, ALTERNATIVES). It can simulate alternatives: Cost Difference = Replacement Cost - Original Cost However, voiding an authorization, issuing a refund, or swapping a vendor requires a cryptographically validated CustomerApproval token submitted from the UI.
What We Learned
Authorization Holds Beat Immediate Captures for Multi-Vendor Apps: Authorizing funds rather than capturing them immediately simplifies failure recovery. Voiding an active authorization is instantaneous and free of merchant transaction fees, whereas refunding a captured payment incurs processing delays and processing costs.
Idempotency Must Be Multi-Layered: Network retries, browser reloads, and webhook replays happen constantly. Implementing idempotency at the API route, the database row lease, and the PayPal PayPal-Request-Id header is essential for true financial integrity.
Grounding AI in Strict Schemas: Allowing an LLM to freely format actions leads to edge-case bugs. Forcing the AI to reason strictly over structured dependency graphs guarantees that every generated recovery proposal is realistic and executable.
Accomplishments That We're Proud Of
Zero-Unapproved-Spend Guarantee: Formally proven across our failure injection test suite. When simulated disasters occur (e.g., venue power loss), 100% of captures are halted, and exactly 0 unauthorized voids or charges occur until the customer clicks approve.
Live PayPal Sandbox E2E Verification: Successfully executed automated end-to-end runs against live PayPal Sandbox endpoints, validating real order generation, popup retry handling, capture idempotency, and cryptographic webhook verification.
Production-Ready Blueprints: 27 unit tests, 4 comprehensive scenario audits (Scenarios A through D), automated migrations, and zero TypeScript compilation errors.
What's Next for PlanLock
Live PayPal Merchant Onboarding: Transitioning from PayPal Sandbox to live production onboarding using PayPal Complete Payments (PPCP) for direct vendor split-payouts.
Dynamic Multi-Party Escrow: Expanding the authorization window with milestone-based release schedules (e.g., 50% hold release upon delivery check-in).
Public Cloud Launch: Deploying the combined Render web service and hosted PostgreSQL worker cluster with automated background outbox processing.
Built With
- express.js
- gemini-api
- groq
- idempotency
- node.js
- paypal
- paypal-sandbox
- postgresql
- react
- rest-api
- sql
- sqlite
- state-machine
- tailwindcss
- typescript
- vite
- vitest
- webhooks
