Overview tab
Analytics tab
AI chatbot for human queries on how to tackle payment problems
Report generation for payment failure
Shelfswipe buyer interface
Shelfswipe seller interface
Seller approval tab in Shelfswipe
Live Store tab
Transaction Explorer tab
Sessions tab
investigating session
Payments tab
Incidents tab
Approval tab
Settings

About PayTrace

Why we built it

When a payment fails, the reason is rarely visible in one place. A buyer may get stuck in checkout, a browser request may time out, a merchant backend may lose a provider response, or a webhook may arrive late. Developers often have to compare payment records, logs, network activity, and browser behavior by hand. PayTrace brings those signals together so a team can move from “this payment failed” to a clearer, evidence-backed explanation.

What PayTrace does

PayTrace is a payment observability and investigation platform for PayPal integrations. It correlates orders and captures with backend lifecycle events, verified PayPal webhooks, browser sessions, network request metadata, and console activity. A payment detail view presents the related lifecycle as a timeline, with links to the customer session and its replay where available. Dashboards, a searchable payment ledger, incident views, and analytics help operators investigate one transaction or spot broader patterns.

The project also includes a sample shopping and checkout experience. It demonstrates product browsing, cart and checkout steps, and PayPal Sandbox order approval and capture. Without PayPal credentials, a clearly labelled local simulator can demonstrate the flow without contacting PayPal or moving money.

ShelfSwipe: from seller catalog to checkout

ShelfSwipe is PayTrace’s small multi-seller commerce demo. It gives sellers a way to bring products from an existing website into a shared storefront, and gives buyers a catalog to browse and purchase from. During seller onboarding, the backend can use the Channel3 catalog service to search a seller’s website domain or look up supplied product URLs. Channel3 returns product details such as titles, descriptions, variants, prices, and images; PayTrace normalizes those details and imports the products as drafts.

We also integrated an HTTP MCP client for ShelfSwipe’s catalog tools and demo-shop fixtures. The MCP integration provides a simple tool-based way to list sample shops and fetch their catalogs, while Channel3 handles catalog discovery for seller websites. This lets the demo show both a ready-made catalog path and a seller-site import path without manually entering every product.

Imported items go through seller review before publication. Sellers can correct product details and confirm stock, then approve products for the ShelfSwipe live store. Buyers can add live products to a cart and check out through PayTrace’s PayPal order and capture flow. That connects the storefront purchase to the same payment lifecycle, session activity, and investigation tools used elsewhere in PayTrace. Channel3-sourced availability is treated as unknown until the seller confirms it; imported listings are not silently assumed to have verified stock.

Why it is useful

Less context switching: inspect payment state, timeline events, webhooks, and browser activity in one investigation workspace.
Faster failure diagnosis: compare a failed journey with similar failures or successful payments, and see where latency or state changes occurred.
Safer handling of uncertain captures: when the provider may have captured a payment but the merchant response was lost, PayTrace marks the result as uncertain and advises reconciliation before retrying, helping avoid duplicate charges.
Earlier awareness of patterns: deterministic incident rules group issues such as capture timeouts, decline spikes, and webhook delays; related metrics estimate potential revenue at risk.
Privacy-aware debugging: session recording masks sensitive inputs, while request and console capture is limited to sanitized metadata rather than request bodies, credentials, or cookies.

APIs and tools

The backend is a FastAPI service with versioned REST endpoints under /api/v1. Its APIs cover payment creation and lookup, checkout order approval and capture, payment timelines, browser session and event ingestion, replay, analytics, incidents, and AI investigations. PayPal webhook events are accepted at /api/v1/webhooks/paypal (with a compatibility route at /api/webhooks/paypal); configured webhooks are signature-verified and deduplicated. Interactive API documentation is available from FastAPI at /docs when the backend is running.

For payment processing, PayTrace uses PayPal Checkout Orders v2 and the PayPal Payments/Captures API through its server-side client. It can also use a labelled local mock provider for credential-free demos. The browser app is built with Next.js, React, and TypeScript. It records replay events with rrweb and captures safe Fetch/XHR and console metadata for correlation. FastAPI, Pydantic, SQLAlchemy, and Alembic power the backend and data layer; PostgreSQL is used in the Docker setup, with SQLite available for local development. Docker Compose runs the services together.

How AI is used

The AI investigator helps explain evidence; it does not establish payment facts on its own. LangGraph coordinates bounded, read-only tools that retrieve local payment state, lifecycle and webhook history, relevant PayPal order or capture status, and comparisons with similar or successful payments. The configured OpenAI-compatible model (such as OpenAI, xAI Grok, or Groq) receives the retrieved evidence and returns a structured explanation that separates facts, inferences, and recommended next steps. Fleet-level questions use database aggregates for counts and comparisons, so those values come from SQL rather than generated text.

If the model or graph is unavailable, PayTrace falls back to deterministic evidence-based reporting. AI cannot capture, refund, or retry a payment. Sensitive financial actions remain behind explicit operator approval. During development, an APIMatic PayPal context plugin can help developers work with integration documentation; it is a coding aid, not a service used by PayTrace at runtime.

How we built it and what we learned

We built the operator experience and demo storefront with Next.js and TypeScript, the API with FastAPI, and persistence with PostgreSQL and SQLAlchemy. PayPal Sandbox provides the checkout integration, rrweb provides session replay, and Docker Compose brings the services together. The most demanding work was correlating separate browser, backend, and provider lifecycles despite different identifiers and timing. Session expiry, concurrent session initialization, buffered event delivery, delayed webhooks, and duplicate-event handling all required careful design.

That work taught us that useful observability depends on reliable correlation and honest uncertainty. A missing response is not proof that a payment failed; a missing webhook is not proof that PayPal never sent one. PayTrace is designed to show what the available evidence supports and make the next investigation step clearer.

What’s next

We’d like to improve failure detection, cross-signal correlation, and investigation analytics, while making it easier to follow a customer journey from the first checkout interaction through the final payment outcome. Our goal is to help developers resolve payment issues faster with a shared, trustworthy view of the evidence.