PayPal ScopeGuard

Inspiration

Autonomous agents can describe purchases, but probabilistic model output should not directly control irreversible financial actions. ScopeGuard enforces a simpler boundary: AI can propose; deterministic policy and the buyer decide.

What it does

ScopeGuard sits between untrusted purchase-intent extraction and PayPal Orders v2. It validates a narrow schema, enforces integer minor-unit transaction and rolling-window caps, checks merchant-category allowlists, and reserves budget before network I/O. Capture remains an explicit post-approval action.

Version 0.3 also treats payment outcomes as distributed-systems state. Stable request IDs make retries idempotent; atomic local snapshots preserve pending reservations across restart; ambiguous create or capture responses keep budget reserved until an explicit reconciliation reads the authoritative order state. Signed PayPal webhooks are verified against the exact raw body with PayPal-only certificate URLs and replay deduplication. CHECKOUT.ORDER.APPROVED never auto-captures.

How we built it

The prototype uses Node.js ESM, a PayPal Orders v2 client, a strict structured-intent adapter, an atomic JSON state store, an order-level operation queue, a raw-body RSA webhook verifier, and a loopback CSP-protected browser UI. GitHub Actions runs the suite on Node 22 and 24.

Challenges we ran into

The hardest cases were preventing concurrent overspend, distinguishing definitive API rejection from response loss after remote success, preserving reservations across restart and time-window rollover, and ensuring an approval notification can never capture funds.

Accomplishments that we're proud of

The repository has 25 passing tests covering policy enforcement, concurrency, restart recovery, idempotent retries, webhook tampering and replay, lost create/capture responses, and the no-auto-capture invariant. The 94-second demo clearly labels its in-memory PayPal simulator and shows a lost capture response recovering through reconciliation without a second capture. No real PayPal sandbox transaction is claimed in the recording.

What's next

Run a real PayPal sandbox end-to-end flow with a registered HTTPS webhook endpoint, then replace local snapshots with managed durable storage and add authenticated remote ingress before any non-demo deployment.

Built With

• javascript
• node.js
• paypal
• rest-api