OrderTruth: Evidence-Grounded Payment Recovery for Merchants

Inspiration

A successful payment does not always mean a successful order.

An online store may receive a completed PayPal payment while its own order database contains two orders, no order, or inconsistent records. These discrepancies can arise from retries, webhook processing, concurrent handlers, or failures between payment confirmation and merchant-side fulfillment.

For merchants, the consequences can be serious: duplicate fulfillment, inventory inconsistencies, customer confusion, and hours spent manually investigating what happened.

We built OrderTruth around a question:

What if merchants could investigate a payment-order discrepancy, understand the supporting evidence, and safely correct their own records without touching the customer's payment?

What it does

OrderTruth is an evidence-grounded payment-integrity and merchant-recovery prototype built around PayPal Sandbox.

It checks a defined contract for a reference merchant: one eligible completed payment should correspond to exactly one active merchant order.

When that contract is violated, OrderTruth can:

• Detect discrepancies: Identify duplicate merchant orders or missing orders after a defined grace period.
• Connect the evidence: Associate recorded PayPal payment observations with merchant-order records and explain what is known.
• Investigate with AI: Use Google Gemini to suggest competing explanations and a read-only diagnostic, while keeping hypotheses separate from verified facts.
• Plan a safe correction: Generate a narrowly scoped merchant-side recovery plan.
• Require explicit approval: Bind approval to the exact plan and its underlying evidence.
• Verify the outcome: Recheck merchant records and produce an inspectable recovery receipt.

The AI does not authorize financial actions or execute repairs. Deterministic validation and explicit human approval govern the correction.

How we built it

We built OrderTruth using TypeScript, Node.js, Fastify, PostgreSQL, PayPal's developer platform, and Google Gemini.

PayPal integration

OrderTruth uses PayPal Sandbox and the Orders v2 API to create and capture test payments and retrieve authoritative payment observations.

We also implemented a webhook intake process with signature verification, event correlation, deduplication, and payment readback. A local Sandbox experiment successfully received and processed genuine signed PayPal events.

The public judge experience references an existing, genuine Sandbox payment observation. Each visitor receives an isolated merchant scenario, so they can explore recovery without initiating new payments.

Evidence and recovery

OrderTruth evaluates recorded payment facts against merchant-side order records. For duplicates, it prepares a correction that affects only the merchant's records.

The recovery workflow checks approval, record identity, evidence consistency, and the resulting merchant-order state. It refuses unsafe or stale operations instead of guessing.

The final receipt records what the application changed and what its checks verified.

AI investigation

Google Gemini provides bounded, evidence-grounded investigation assistance. It compares possible merchant-side explanations, cites supplied evidence identifiers, identifies missing proof, and recommends a read-only next diagnostic.

AI output is treated as a hypothesis—not a payment verdict, proof of causation, or permission to perform a repair.

When AI is unavailable, deterministic investigation guidance remains accessible.

Infrastructure

The application uses a Vercel-hosted frontend, a Render-hosted API, and Neon PostgreSQL for persistent cases, sessions, approvals, investigation results, and receipts.

We also built automated TypeScript and PostgreSQL tests to check the payment-state rules, recovery behavior, concurrency cases, and security boundaries.

Challenges we ran into

1. Separating payment truth from merchant truth

A completed PayPal capture proves that a payment occurred. It does not prove that the merchant created the right order records. We had to represent these as separate sources of evidence.

2. Handling duplicate events and uncertain operations

Payment systems encounter retries, delayed events, interrupted requests, and repeated handler execution. We designed the recovery process to recheck persisted state rather than blindly repeating mutations.

3. Preventing AI from overstating its conclusions

An AI-generated explanation can sound convincing even when the available evidence does not establish the cause. We constrained model output, validated evidence references, and kept the final decision with deterministic rules and human approval.

4. Making recovery safe

Detecting an extra order is easier than correcting it safely. We implemented exact-plan approval, consistency checks, transactional merchant-side operations, and post-repair verification.

5. Working within free infrastructure limits

The hosted prototype uses free services, so cold starts and request allowances required careful timeout handling, state recovery, and explicit fallback behavior.

What we learned

Building OrderTruth changed how we think about payment reliability.

We learned that a payment provider's successful response is only one part of a merchant's operational truth. Robust systems must also account for database writes, event delivery, retries, and partial failures.

We also learned that trustworthy AI integration requires more than connecting a model. AI explanations must be grounded in evidence, evaluated against deterministic alternatives, and prevented from controlling sensitive financial operations.

Most importantly, we learned that a trustworthy recovery system needs to explain not only what it changed, but why the change was allowed and how the result was verified.

What makes OrderTruth different

OrderTruth is not simply a payment dashboard or an AI chatbot.

It combines payment evidence, merchant-order integrity checks, constrained AI investigation, explicit recovery approval, and a verifiable merchant-side correction record.

The goal is to help a merchant move from “Something looks wrong with this payment” to “Here is the evidence, here is the approved correction, and here is what we verified afterward.”

Try it

Live demo: https://order-truth.vercel.app

Open-source code: https://github.com/ANIRUDDH-001/OrderTruth

The interactive judge experience uses isolated, controlled merchant scenarios referencing a recorded PayPal Sandbox observation. It does not create a new PayPal payment for each visitor, and merchant recovery does not capture, refund, or otherwise modify PayPal financial records.

OrderTruth is a prototype, not a production merchant integration. External effects such as inventory changes, shipment status, and customer communications are outside the current recovery scope.

Built With

• better-auth
• fastify
• github-actions
• google-gemini
• neon
• node.js
• paypal
• paypal-orders-api
• paypal-sandbox
• paypal-webhooks
• pnpm
• postgresql
• render
• typescript
• vercel
• vite
• vitest
• zod