💳 How We Integrated PayPal
PayPal Shield AI integrates PayPal's payment infrastructure directly into its fraud prevention workflow. We use the PayPal JavaScript SDK to provide checkout functionality through our demo store, connected to PayPal Sandbox for secure testing with simulated transactions.
Using Orders API v2 with intent=AUTHORIZE, the system creates an order and authorizes the payment without immediately capturing the funds. This creates a critical checkpoint where our Frequency, Time and Geo Agents evaluate transaction behaviour before the payment proceeds.
Based on the risk assessment, our Deterministic Policy Engine controls the next payment action. Low-risk transactions proceed to Capture API, medium-risk transactions require OTP or WebAuthn Passkey verification, high-risk transactions remain pending for analyst review, and very high-risk transactions are stopped using the Authorization Void API.
We also implement PayPal-Request-Id for idempotency to prevent duplicate payment operations. For reliability testing, PayPal-Mock-Response allows us to simulate declined captures and validate negative payment scenarios in the Sandbox environment.
Why Authorization Before Capture?
The separation between Authorization and Capture allows PayPal Shield AI to introduce fraud checks before payment completion. Rather than automatically capturing every authorized transaction, our system evaluates risk first and executes the corresponding action through the PayPal payment lifecycle.
🤖 How AI Powers PayPal Shield AI
Our system uses a Multi-Agent Architecture in which each behavioural agent examines a different dimension of transaction risk. The Frequency Agent identifies unusual transaction velocity, multiple incoming senders and rapid movement of funds. The Time Agent detects unusual transaction hours and amounts compared with account behaviour. The Geo Agent evaluates country mismatches and impossible-travel patterns.
The AI Fraud Investigator analyses the agents' findings and generates a structured investigation summary, supporting evidence and an action recommendation. It is strictly advisory and cannot independently capture, void or modify a payment decision.
A Deterministic Policy Engine, implemented using explicit rules, retains complete control over payment actions. We also treat payer-supplied text as untrusted input and provide a template-based fallback when an AI API key is unavailable.
📊 Analyst Dashboard with AG Grid
We use AG Grid to build the analyst-facing transaction review interface. It organizes transaction records and risk information into a structured grid, helping analysts inspect suspicious cases, understand behavioural evidence and review transactions requiring manual intervention.
The dashboard connects the transaction details, agent explanations, risk assessment and investigation workflow, giving analysts a consolidated view instead of relying on isolated risk scores.
🏗️ Technology Stack
The backend is developed using FastAPI and Python, while the frontend uses Next.js, React, TypeScript and Tailwind CSS. MySQL stores transaction and investigation data, and Apache Kafka can optionally support background transaction streaming.
For authentication, we implement OTP and WebAuthn Passkeys as step-up verification mechanisms. AG Grid powers the analyst interface, while pytest and a mocked PayPal client support backend and payment-workflow testing.
We also provide a Lite Mode, allowing judges to run the application using only MySQL, FastAPI and the frontend, without requiring Kafka.
🧩 Challenges We Faced
One of our biggest challenges was ensuring that a payment could never be captured twice or captured without an explicit policy decision. We addressed this through idempotency and a risk-gated payment workflow.
Another major challenge was maintaining a strict boundary between AI recommendations and financial execution. We designed the investigator to explain and recommend actions while leaving all payment decisions to deterministic code.
We also addressed the limitations of the PaySim synthetic dataset. Since it does not contain real timestamps or geographical locations, our time and location signals are simulated and clearly labelled in the demo.
🏆 Accomplishments We're Proud Of
We built a complete multi-agent fraud assessment workflow around PayPal's authorization and capture model. Our system combines behavioural risk detection, explainable AI investigation, deterministic payment policies, step-up authentication and human-in-the-loop review.
One of our key accomplishments is ensuring that money movement remains controlled by explainable and testable rules rather than an LLM. The shop, analyst dashboard and investigation story share a common case-file structure, providing a consistent view of each transaction.
📚 What We Learned
We learned that effective fraud prevention requires more than accurate risk scores. It also requires explainability, auditability, reliable payment-state management and controlled decision-making.
PayPal's Authorization/Capture separation** provides a natural checkpoint for evaluating transaction risk, while AI adds value by converting complex behavioural signals into understandable investigation summaries.
🚀 What's Next?
We plan to integrate real device and IP signals, introduce merchant-configurable risk policies, and implement PayPal webhook-driven payment status updates. We also aim to develop a trained ML Risk Agent and evaluate its performance using a temporal train-test split. ⚠️ Honest Limitations
The current implementation operates in PayPal Sandbox only. Time and geographical signals are simulated, and the PaySim dataset is synthetic. We do not claim production-grade fraud detection performance or real-world financial deployment.
Built With
- apache
- api
- css
- fastapi
- kafka
- mysql
- next.js
- pytest
- python
- sdk
- tailwind
- typescript