Inspiration
Payment disputes seem straightforward until you look at the evidence.
Take a customer who says their package never arrived. The merchant has a tracking number showing that it was delivered. At first, that sounds like enough to resolve the dispute. But what if the package went to the wrong address? What if the tracking number was entered by the merchant but never checked against the carrier's records? What if it was delivered to the right building, but nobody knows who received it?
We started thinking about how much of a dispute depends on these small details, and how difficult it can be for merchants to figure out which details actually matter.
There are already tools that help merchants prepare dispute responses. We were more interested in what happens before that: figuring out whether the available evidence supports the response in the first place.
That became ProofGraph.
What it does
ProofGraph helps merchants investigate payment disputes and work out what information they need before responding.
When a merchant opens a case, they can see the customer's claim, the transaction details, the evidence collected so far, and what still needs to be checked. The application suggests a next step based on the current state of the investigation.
For example, if a customer reports that an order never arrived and the merchant hasn't provided tracking information, ProofGraph can ask for the tracking number. Once that information is added, the investigation can be updated.
If the delivery address doesn't match the order, the system flags the discrepancy instead of treating the package as successfully delivered to the customer.
We use an evidence graph to keep track of how the different pieces of information relate to one another. This also lets us record where evidence came from, which claims it supports, and where information conflicts.
Merchants can add tracking details, upload supporting documents, and review a case summary showing the available evidence and unresolved questions.
The application is designed to help with the investigation. It doesn't automatically decide who wins a dispute or submit a final decision on anyone's behalf.
How we built it
We used Next.js, React, and TypeScript for the merchant interface, with a Python FastAPI backend.
The investigation logic uses NetworkX to represent relationships between transactions, orders, shipments, customer claims, and supporting evidence. Each piece of evidence has information about its origin and verification status.
We also developed a next-best-evidence approach. Instead of giving the merchant a long checklist of documents to collect, the system evaluates which missing piece of information would be most useful at that point in the investigation.
For testing, we created synthetic disputes covering different situations: missing deliveries, conflicting shipping addresses, items that don't match their descriptions, and duplicate transactions.
We built automated tests for the investigation logic, API, and frontend. We also added browser tests that run the interface against the actual FastAPI backend, rather than relying entirely on mocked responses.
Challenges we ran into
A surprisingly tricky problem was deciding what counts as verified evidence.
For example, when someone uploads a shipping receipt, we can check the file format and record when it was submitted. But that doesn't mean the shipment actually happened. The same applies to tracking numbers: receiving one from a merchant is different from confirming its status with a carrier.
We had to account for that distinction throughout the system, especially when working with simulated carrier information.
Another difficult part was deciding when the investigation had enough information to proceed. A delivery confirmation might be relevant, but it shouldn't automatically settle a dispute if the delivery address is wrong or other important questions remain unanswered.
The frontend was also harder than we initially expected. Evidence graphs and investigation policies are useful internally, but merchants shouldn't need to understand any of that to use the application. We spent time organising the interface around the case itself, the available evidence, and the next action.
Getting all three parts of the application to work together was another challenge. The frontend, backend, and investigation engine were developed separately, so integration testing exposed questions about how information should move between them and how updates should appear in the interface.
What we learned
A lot of the work turned out to be about handling incomplete information.
It's relatively easy to build a system that takes some documents and produces a confident-looking response. It's much harder to make sure that the response is justified, especially when different sources disagree or something hasn't been verified.
We also found that the way an investigation is presented matters almost as much as the underlying logic. A recommendation isn't particularly useful if the merchant can't understand why they're being asked to do something.
What's next
We're currently testing the complete merchant workflow and improving how the interface handles new evidence, conflicting information, and case reviews.
We'd also like to connect ProofGraph to more real payment and shipping data sources. For now, synthetic cases let us test the investigation process without using real customer information.
Eventually, we'd like merchants to be able to open a dispute, understand what's going on, collect the evidence that matters, and prepare a response without having to piece everything together manually.
Built With
- ai
- fastapi
- graph
- next.js
- payment
- paypal
- python
- react
- typescript
