Inspiration
Peer-to-peer marketplaces, high-value freelance milestones, and local classified exchanges suffer from a persistent trust deficit: the vulnerability gap between payment authorization and physical/digital settlement.
In traditional checkouts, single-click approvals execute an instant payment capture without verifying whether both parties are genuinely present, attentive, and consenting in real time. This opens the door to:
- Account Takeovers & Stolen Credentials: Attackers with compromised credentials execute unauthorized one-click checkouts.
- Non-Delivery & Identity Spoofing: Sellers or buyers claim they never authorized the handoff or claim the counter-party was an automated bot.
- Static Replay Attacks: Fraudulent actors using static photographs or deepfake loops to bypass basic photo verification.
We set out to create a zero-trust, privacy-first payment protocol: What if a PayPal transaction was held in escrow and captured only when both the buyer and seller independently prove live, physical human presence through client-side AI biometric liveness verification?
What it does
PayVerify transforms standard PayPal checkouts into a secure, AI-gated dual-party verification protocol:
- Buyer Checkout & Approval: The buyer starts a checkout on the web platform, creates an order via PayPal Orders v2, and approves the transaction via the PayPal JS SDK v6 modal.
- Payment Gate Activation: Rather than immediately capturing funds, the application intercepts the flow and creates an ephemeral, cryptographically isolated dual-device verification session.
- QR Code Handshake: The buyer is presented with a dynamically generated QR code. The seller scans the QR code on their smartphone or secondary device to enter the shared verification room.
- Independent Edge AI Liveness Check: Both buyer and seller independently complete a real-time, interactive biometric liveness test (dynamic Eye Aspect Ratio blink detection) on their respective webcams/cameras. All facial processing runs 100% locally in browser memory—no biometric images or facial landmarks ever leave the user's device.
- Conditional Gated Capture: Once both parties pass liveness and the buyer's PayPal approval is confirmed, the backend automatically triggers
POST /v2/checkout/orders/{id}/capture, transferring funds and displaying verified transaction proofs to both screens in real time. - AI Fraud & Risk Triage Engine: Includes a TypeSafe Decision Model (Jev) pipeline to analyze transaction notes, customer messages, and dispute texts for fraud signals, coercion, and scam indicators.
- Agentic Commerce via PayPal MCP Server: Integrates local and remote Model Context Protocol (MCP) endpoints (
@paypal/mcpandmcp.sandbox.paypal.com), allowing AI agents to generate invoices, check order statuses, and review dispute records via natural language.
How we built it
flowchart TD
subgraph BuyerClient ["Buyer Device (Browser)"]
B_SDK[PayPal JS SDK v6 Modal]
B_AI[Edge AI Ocular Liveness Check]
B_UI[Checkout & QR Generator]
end
subgraph SellerClient ["Seller Device (Mobile / Browser)"]
S_QR[QR Code Session Join]
S_AI[Edge AI Ocular Liveness Check]
end
subgraph NextServer ["Next.js 16 Full-Stack App Router"]
API_Create[API: /api/paypal/create-order]
API_Capture[API: /api/paypal/capture-order]
API_Session[API: /api/session/:id]
API_Token[API: /api/paypal/token]
API_Eval[API: /api/evaluate]
PusherServer[Pusher Real-Time Dispatcher]
TokenCache[OAuth2 Token Engine with Clock-Skew Buffer]
end
subgraph ExternalServices ["External Services & APIs"]
PP_API[PayPal Sandbox Orders v2 REST API]
PP_MCP[PayPal MCP Server Local / Remote SSE & HTTP]
PP_Hooks[PayPal Webhook Simulator]
Pusher_Cloud[Pusher Channels Cloud]
TypeSafe_AI[TypeSafe Jev Decision Model]
end
B_SDK -->|1. Create Order| API_Create --> PP_API
B_SDK -->|2. Authorize| API_Session
B_UI -->|3. Display QR| S_QR
B_AI -->|4a. Buyer Verified| API_Session
S_AI -->|4b. Seller Verified| API_Session
API_Session <--> PusherServer <--> Pusher_Cloud
Pusher_Cloud -.->|Sync State| BuyerClient
Pusher_Cloud -.->|Sync State| SellerClient
API_Session -->|5. Condition Met: Both Verified + Approved| API_Capture
API_Capture -->|POST /v2/checkout/orders/id/capture| PP_API
API_Capture -->|Broadcast Result| PusherServer
API_Token -->|Fresh Bearer Auth| PP_MCP
API_Eval -->|Fraud Risk Analysis| TypeSafe_AI
PP_Hooks -->|Order Events| NextServer
- Frontend & Architecture: Next.js 16 (App Router, TypeScript, Turbopack) styled with Tailwind CSS.
- PayPal Integration:
- Orders v2 REST API: Endpoints for OAuth2 token retrieval (
/v1/oauth2/token), order creation (/v2/checkout/orders), order verification, and capture (/v2/checkout/orders/{id}/capture). - PayPal JS SDK v6: Secure client-side smart buttons managing delegated approval without premature capture.
- PayPal Token Management:
payverify/lib/paypal.tsimplements an in-memory OAuth2 token cache withPAYPAL_O_AUTH_CLOCK_SKEWsafety buffering, request timeouts, and structured logging with authorization header masking. - PayPal MCP Server: Full
payverify/mcp.jsonconfiguration supporting local@paypal/mcpand remotemcp.sandbox.paypal.com(SSE and Streamable HTTP transports). - Negative Testing & Webhooks: Support for
PayPal-Mock-Responseheaders (INSTRUMENT_DECLINED,INSUFFICIENT_FUNDS) and webhook listeners forCHECKOUT.ORDER.APPROVEDandCHECKOUT.ORDER.COMPLETED.
- Orders v2 REST API: Endpoints for OAuth2 token retrieval (
- Edge AI Computer Vision: Real-time canvas frame differential and Eye Aspect Ratio (EAR) algorithm running in browser memory at 60 FPS, calculating palpebral fissure landmark deltas to detect natural blinks within a 15-second challenge window.
- Real-Time Cross-Device Communication: Pusher Channels (
pusher/pusher-js) with automatic polling fallback to synchronize verification state across desktop and mobile devices without latency. - Decision AI:
@typesafe-ai/sdkwith the Jev model (jev-1.14.0) to compute multi-signal noisy-OR fraud risk scores and support triage weights.
Challenges we ran into
Zero-Trust Liveness Without Compromising Biometric Privacy: Transmitting live webcam feeds or face imagery to a server creates massive privacy vulnerabilities and GDPR/CCPA compliance overhead. We solved this by executing the entire facial landmark and blink detection pipeline on the client's device using HTML5 Canvas pixel differentials and WebGL acceleration. Only an encrypted verification handshake flag is emitted upon successful completion.
Decoupling Approval from Capture in the PayPal SDK Flow: Most standard PayPal SDK integrations capture payments immediately inside
onApprove. We re-architected the flow to treatonApproveas a permission grant that pauses the transaction state, holding the order in an approved status until our backend verifies that both counter-parties have satisfied their biometric requirements.Dual-Device Concurrency & Race Conditions: Coordinating events when a buyer is on a desktop and a seller is on a mobile browser required robust state handling. If both parties pass liveness simultaneously, duplicate capture requests could be triggered. We implemented single-flight server-side session locks and centralized the capture dispatch to the buyer's client orchestrator backed by real-time Pusher state updates and fallback interval syncs.
SSR & Bundling with Next.js Turbopack: Browser-centric vision algorithms and canvas operations can cause hydration mismatches or crash server-side builds. We encapsulated the computer vision components using Next.js dynamic client imports (
ssr: false) with graceful loading fallbacks.
Accomplishments that we're proud of
- Complete End-to-End Dual-Party Flow: Built a seamless UX where a buyer approves a PayPal transaction on desktop, presents a dynamic QR code, and a seller joins on mobile to complete a simultaneous verification handshake in under 15 seconds.
- Privacy-Preserving Biometrics: Zero biometric data, video frames, or facial geometry ever touch our servers—protecting user privacy while delivering high-assurance anti-spoofing protection.
- Full-Spectrum PayPal Ecosystem Integration: Went beyond basic button rendering to implement the full PayPal developer suite: Orders v2 REST API, JS SDK v6, Token Caching with clock-skew protection, Webhooks, Negative Mock Testing, and Model Context Protocol (MCP) server endpoints.
- Resilient Negative Testing & Error Handling: Gracefully surfaces and maps capture-level decline codes (
INSTRUMENT_DECLINED,INSUFFICIENT_FUNDS) to clear, actionable UI states with sandbox card hints.
What we learned
- The Flexibility of PayPal's Two-Phase Commit: PayPal's decoupled create $\rightarrow$ approve $\rightarrow$ capture lifecycle provides an ideal foundation for custom multi-party authorization gates, escrow triggers, and AI-driven compliance checks.
- Power of the Model Context Protocol (MCP): Implementing PayPal's MCP server demonstrated how natural language AI agents (in Claude Desktop, Bob, or Cursor) can securely orchestrate multi-step financial operations like automated invoice generation, payment tracking, and dispute management.
- Edge AI is Ready for Production Web Apps: High-precision computer vision and biometric liveness checks can run smoothly at 60 FPS in modern browsers using client-side canvas analysis, eliminating cloud GPU costs and privacy liabilities.
What's next for PayVerify: Face-Verified PayPal Checkout
- 3D Passive Liveness & Depth Estimation: Integrate WebGL-based photogrammetric depth checks and micro-texture reflection analysis to defend against advanced high-resolution video replay and silicon mask attacks.
- Smart Escrow Release Conditions: Extend the dual-party gate into physical delivery verification, where GPS geolocation proximity and carrier delivery API events trigger the liveness challenge.
- Autonomous MCP Agent Dispute Arbitrator: Build an automated AI dispute agent using PayPal's MCP tools that gathers liveness audit certificates, delivery signatures, and order logs to resolve open disputes instantly via
accept_dispute_claimor evidence submission. - Native Mobile Biometrics & WebAuthn / Passkeys: Combine browser face liveness with device-native Passkeys / TouchID / FaceID for instant multi-factor transaction signing.
Built With
- artificial-intelligence
- biometrics
- computer-vision
- edge-ai
- fintech
- liveness-detection
- machine-learning
- mcp
- nextjs
- node.js
- oauth2
- opencv
- paypal
- paypal-sandbox
- paypal-sdk
- pusher
- react
- rest-api
- security
- tailwindcss
- turbopack
- typesafe-ai
- typescript
- webhooks