Inspiration

A customer pays with PayPal. PayPal captures the money and sends a webhook. The merchant's handler fails, so the order stays "payment pending". Now three systems tell three different stories: PayPal says completed, the store says unpaid, and the customer is left guessing whether to pay again.

This happens because a webhook is only a message, and messages get lost, retried, delayed and mishandled. We wanted one place where the customer and the merchant look at the same case, backed by the same verified evidence.

We also wanted to answer a harder question: what does it take to let AI work near money safely?

What it does

FRACTAL is a shared payment-exception resolution platform.

  • One shared case ID for the customer and the merchant, with a separate view for each.
  • Evidence from the source: PayPal's current transaction state, the merchant's order state, verified webhook history, and the merchant's logs and traces.
  • AI investigation: a LangGraph agent reads that evidence and explains what probably went wrong in plain language, citing the evidence it used.
  • Independent verification: our backend re-fetches the key facts itself. The AI's claims are treated as advice, never as facts.
  • Policy decisions with OPA: a deterministic policy engine returns one of four answers: allow, require approval, wait for more evidence, or block. Every answer comes with rule IDs and a policy version.
  • Safe execution: actions run under a per-case lock with idempotency keys and a final fresh-state check. Sensitive actions such as refunds need a human approval.
  • A reconciliation loop that finds problems nobody reported. If a payment completed at PayPal but the merchant's order never updated, FRACTAL notices, opens the case, and tells both sides.
  • An audit trail of every decision and action.

AI investigates. Backend verifies. Policy governs. Backend executes. Everything is audited.

How we built it

PayPal is central to the project. We use:

  • PayPal REST APIs for orders, captures and transaction retrieval [confirm: and refunds]
  • PayPal webhooks, verified through PayPal's verify-webhook-signature endpoint
  • The PayPal Sandbox for a real checkout in the demo

AI is used in the investigation step. A single LangGraph agent has read-only tools (case evidence, webhook history, log and trace search) and returns structured findings with evidence references. It has no payment credentials and no way to write. [Name the model/provider you used]

Architecture

  • Go backend (modular monolith) calls PayPal's REST API directly. It receives webhooks, verifies them, deduplicates them with a database unique constraint, replies quickly, and processes them asynchronously.
  • Python service runs the LangGraph agent.
  • Open Policy Agent (Rego) makes the decisions. Rules use one standard input and output format, and behavior such as thresholds and action requirements lives in data, so adding an action doesn't need new policy code.
  • PostgreSQL stores cases, evidence, decisions, approvals and the audit log. Evidence and audit rows are append-only.
  • Elastic with OpenTelemetry gives case-scoped logs and traces that the agent and the merchant can read. [Confirm this is working before you claim it.]
  • React and TypeScript web app for the customer and merchant views.
  • A mock merchant store with a switch that breaks its webhook handler on demand, so the failure in the demo is real.

The trust boundary

An AI agent can be confident and wrong. OPA can only judge the input it is given, so if an agent's claim goes into the policy engine, the policy engine will believe it. So in FRACTAL:

  1. The agent produces findings and a recommendation (advisory).
  2. The Go backend re-fetches the critical facts from PayPal and the merchant.
  3. Go builds the policy input from those verified facts. The agent output sits in a separate field that no allow rule is allowed to read (a check enforces this).
  4. OPA decides. Missing data, an unknown action, or a policy failure always results in a block.
  5. The executor takes a lock, checks the idempotency key, re-checks PayPal state, then acts.

Challenges we ran into

  • Webhooks are messier than they look. PayPal retries failed deliveries for days, so duplicates are normal. We made the unique event ID the guard, answered quickly, and moved processing to a worker. Verification needs the exact raw request body, and PayPal's simulator events can't be verified.
  • Local development. PayPal can't reach localhost, so we put a tunnel in front of the webhook receiver and registered it on the Sandbox app.
  • Knowing what counts as a mismatch. A payment that is still pending at PayPal, or one that PayPal denied, is not a webhook bug. We built a decision table so the reconciler only opens a case when PayPal says the payment is complete and the merchant's order disagrees, and it never acts on data it couldn't fetch.
  • Keeping AI advisory. The hardest design problem was making sure a wrong AI answer can't move money.
  • Scope. We cut features to protect the core flow instead of building everything halfway.

What we learned

  • A webhook is a hint, not the source of truth. The reliable design is to re-check the real state.
  • An AI system near money needs boundaries enforced outside the model: verified inputs, deterministic policy, idempotent execution and an audit trail.
  • Good policy engines make decisions explainable, and explainability is what makes a human willing to approve an action.

What's next for FRACTAL

  • More providers behind the same interface, such as PhonePe and other payment platforms.
  • Jurisdiction-specific policy packs (for example US Regulation E and EU PSD2), enabled only after qualified legal review.
  • Operational anomaly detection that can only make decisions stricter, never looser.
  • Spotting recurring failures across a merchant's cases, so "five complaints" turns into "one root cause".

FRACTAL runs on PayPal Sandbox only. It is an engineering project, not legal advice or a compliance certification, and it makes no claim of regulatory compliance.

Built With

  • cloudflare
  • docker
  • docker-compose
  • elastic
  • fastapi
  • go
  • kibana
  • langgraph
  • open-policy-agent
  • open-telemetry
  • paypal-restapi
  • paypal-sandbox
  • paypal-webhook
  • postgresql
  • react
  • rego
  • type-script
  • vite
Share this project:

Updates

Submission history