Inspiration

Autonomous AI agents are rapidly moving from answering questions to executing multi-vendor B2B procurement—leasing cloud GPUs, purchasing API quotas, and licensing datasets. However, giving an LLM direct access to intent: "CAPTURE" payment tools creates three critical enterprise risks:

  1. Prompt Injection & Spend Drain: An untrusted vendor memo or Base64-obfuscated prompt can trick an agent into draining treasury funds.
  2. Pre-Delivery Settlement Risk: Standard CAPTURE checkout transfers money immediately before multi-vendor deliverables or SLAs are verified.
  3. Blind Timeout Retries: Network timeouts on financial POST calls cause naive retry loops to double-charge or double-payout.

I built Payegis Studio v3.5—the Financial Control Plane for Autonomous Commerce on PayPal—guided by one core principle:

AI agents can propose. Deterministic policies can validate. Humans can authorize. PayPal can execute. Payegis verifies and reconciles.

What it does

Instead of acting as an unregulated third-party escrow bank or allowing autonomous agents to fire blind CAPTURE requests, Payegis Studio orchestrates a complete, deterministic 6-Stage Financial Lifecycle directly on the PayPal Developer Platform:

  1. Neuro-Symbolic Intake & Channel3 Merchant Verification: Evaluates multi-vendor bundles ($1,168.00 across 3 vendors: NebulaCompute $420.00, VectorIndex $248.00, and LexCorpus $500.00) against a 20-rule prompt-injection decoder (NFKC Unicode normalization, URL decoding, and Base64 payload inspection) and verifies merchant trust scores ($\ge 85.0$). Orders $\ge \$250.00$ are automatically halted at a durable PENDING_HUMAN_GATE checkpoint.
  2. Step 1 — 2-Phase Buyer Approval & Orders v2 AUTHORIZE Hold: Requires a cryptographically bound HMAC-SHA256 human approvalRecord, creates a PayPal Order with intent: "AUTHORIZE" (POST /v2/checkout/orders), verifies buyer approval via authoritative witness (GET /v2/checkout/orders/{id}), and executes POST /v2/checkout/orders/{id}/authorize to place a $1,168.00 USD authorization hold.
  3. Step 2 — 72-Hour Honor Period Gate & Day +4 Reauthorization: Enforces PayPal's 3-day (72h) honor period vs. 29-day validity window server-side. Premature reauthorization at T+0h is rejected with HTTP 409 REAUTHORIZE_HONOR_PERIOD_STILL_ACTIVE. Once the 72h honor window elapses (Day +4), Payegis executes POST /v2/payments/authorizations/{id}/reauthorize to issue a fresh authorization ID and renew the honor period.
  4. Step 3 — SHA-256 Fulfillment Verification & Partial Capture (final_capture: false): Computes 64-hex RFC 6234 SHA-256 digests of vendor delivery artifacts. For the 2 verified vendors (CH3-GPU-NODE-01 and CH3-SERP-API-02), Payegis executes POST /v2/payments/authorizations/{id}/capture for $668.00 USD with final_capture: false, keeping the remaining $500.00 USD hold active while isolating any PENDING capture status in CAPTURE_PENDING until verified via GET /v2/payments/captures/{id}.
  5. Step 4 — SLA Breach Uncaptured Hold Release (VOID): When the third vendor (LexCorpus, $500.00) breaches its delivery SLA, Payegis executes POST /v2/payments/authorizations/{id}/void (HTTP 204 No Content), releasing the uncaptured $500.00 USD hold back to the buyer ($0.00 active hold remaining).
  6. Step 5 & Step 6 — Multi-Vendor Split Payouts v1, Disputes v1 Defense & ISO-18004 Invoice QR: Disburses $420.00 + $248.00 ($668.00) via POST /v1/payments/payouts, immediately verifies batch and item-level settlement via GET /v1/payments/payouts/{batch_id}, submits carrier tracking proof via POST /v1/customer/disputes/{id}/provide-evidence using PayPal's official evidences[] array schema, and encodes untruncated PayPal Invoices v2 URLs into an ISO/IEC 18004 Reed-Solomon QR code.

How I built it

  • PayPal Platform & SDKs: Built on @paypal/[email protected] and @paypal/[email protected] in Node.js ES modules (paypal-core.mjs, server.mjs, fsm-and-policy.mjs, ai-procurement-agent.mjs, persistence-store.mjs).
  • Zero-Retry Mutation Safety (APIMatic Core Config): Configured the PayPal Server SDK client with retryConfig: { maxNumberOfRetries: 0, retryOnTimeout: false, httpMethodsToRetry: [HttpMethod.Get] } alongside pre-flight and post-flight operation journaling so network timeouts transition to UNKNOWN_TIMEOUT and reconcile via GET witnesses rather than double-capturing.
  • Distributed Concurrency & Tamper-Evident Persistence: Implemented PostgreSQL transactional advisory locks (pg_try_advisory_lock(int4, int4)), cross-process atomic OS kernel lockfiles, optimistic version control (409 STALE_SESSION_VERSION_CONFLICT), and a 64-character SHA-256 hash-chained audit ledger (prevHash -> entryHash).
  • Interactive Control Plane UI: Built a responsive, zero-clipping dark dashboard (index.html) featuring AG Grid Community v32.3.3 (with multi-line cell wrapping, CSV export, and an interactive SHA-256 Fulfillment Artifact Verifier), Chart.js v4.4.1 settlement waterfall charts, a multi-step reversible Sandbox Clock Simulator, a 10-tool Guarded Agent Toolkit sandbox, and 4 one-click Judge Verification Tours.

Challenges I ran into

  • Separating Order Creation from Order Authorization: Creating a PayPal order with intent: "AUTHORIZE" does not lock funds until the buyer approves the order and POST /v2/checkout/orders/{id}/authorize is called. I engineered an explicit ORDER_CREATED_AWAITING_BUYER state and GET witness verification before transitioning to AUTHORIZED.
  • Handling Asynchronous PENDING Captures and Payout Batches: A 201 Created response from POST /v1/payments/payouts or a PENDING capture status does not mean money has settled. I added strict CAPTURE_PENDING and PAYOUT_PENDING isolation that keeps settled totals at $0.00 and locks downstream steps until GET /v2/payments/captures/{id} and GET /v1/payments/payouts/{id} confirm COMPLETED/SUCCESS.
  • Preventing AI Tool Bypass: To ensure an LLM can never hallucinate or spoof human approval, I replaced boolean flags (humanApproved: true) with HMAC-SHA256 signed approvalRecord tokens bound to the exact session ID, operation name, dollar amount (in integer cents), and currency.

Accomplishments that I'm proud of

  • 56/56 Automated Test Suites & 20/20 Live Security Benchmark (0 Fail): Verified every state guard, integer-cent invariant, Base64/Unicode prompt injection, ISO/IEC 18004 QR round-trip decode, webhook verification, and mocked PayPal API lifecycle via Node's native test runner (npm test & npm run benchmark).
  • Complete 7-Primitive PayPal Lifecycle: Unified Orders v2, Authorizations (Reauthorize / Capture / Void), Payouts v1, Customer Disputes v1, and Invoicing v2 QR into one cohesive control plane.
  • Transparent Dual-Mode Honesty: Built a fail-closed LIVE_PAYPAL_SANDBOX mode alongside a clearly labeled OFFLINE_SIMULATOR mode on GitHub Pages so judges can test all 4 guided tours in one click in the browser or run the full-stack server locally/on Render.

What I learned

  • Designing financial infrastructure for AI agents requires treating the LLM as an untrusted proposer and enforcing every monetary invariant, temporal window (72h honor period vs. 29d validity), and idempotency key in deterministic server-side code.
  • Combining APIMatic's typed SDK configuration (@paypal/paypal-server-sdk) with authoritative GET witness reconciliation eliminates duplicate financial mutations under network instability.

What's next for Payegis Studio

  • Expanding multi-currency treasury rules and PayPal Vault v3 recurring mandate tokens for pre-approved micro-procurement under $250.00.
  • Adding automated carrier webhook triggers (UPS/USPS/FedEx) that auto-submit PROOF_OF_FULFILLMENT evidence the moment a dispute is opened.

Built With

Share this project:

Updates

Submission history