Inspiration

One of the most confusing situations in online payments is when money appears to have been deducted, but the merchant still cannot confirm whether the payment was successful.

Imagine a customer purchasing something online. The checkout page keeps showing "Processing", or the request times out. The customer sees a debit notification, but the merchant's system has not received confirmation. The merchant asks the customer to try again, but what if the first payment actually went through and its confirmation was simply delayed? The customer could end up paying twice.

We wanted to solve this problem because a timeout should not automatically mean a payment has failed. There needs to be a way to investigate the original transaction, understand what actually happened, and decide what is safe to do next.

That is where ResolveAI came in.

What it does

ResolveAI is an AI-powered payment recovery and dispute-prevention layer built on the PayPal Developer Platform. It investigates uncertain payment outcomes using actual PayPal transaction data and verified webhook events, then helps buyers and sellers understand the situation.

The main things we built are:

  • Payment investigation: When a payment is not confirmed, the backend retrieves the original PayPal order and capture details and checks the available webhook events. This gives us a more reliable picture than simply depending on the checkout response.
  • Duplicate payment prevention: We built a deterministic policy engine with rules R01–R09. If an existing attempt is still pending or its outcome is unknown, the system blocks another attempt. A timeout is marked as UNKNOWN, never automatically treated as a failure.
  • AI-powered investigation: We integrated Google Gemini 2.5 Flash to examine the available evidence, identify missing information, and explain the payment situation in understandable language. The AI uses restricted, read-only tools and cannot independently execute payment or refund operations.
  • Shared buyer and seller experience: Both parties can access the same case timeline and see the verified status, investigation results, and permitted next steps. Updates are pushed through Server-Sent Events (SSE).
  • Controlled refund workflow: A buyer can request a refund for an eligible completed payment, but the request does not immediately send money back. It first enters REFUND_PENDING, and the seller must approve it before the PayPal refund operation is submitted.
  • Fault-Injection Lab: We also built a dedicated lab to test situations that are difficult to reproduce consistently in the PayPal sandbox, such as dropped responses, delayed webhook events, and repeated payment attempts. Simulated events are clearly distinguished from real sandbox operations.

How we built it

We used React and TypeScript for the frontend and FastAPI with Python for the backend.

For payment processing, we integrated PayPal Orders API v2 and Payments API v2, along with OAuth2 authentication and the PayPal JavaScript SDK Smart Buttons. We also implemented webhook signature verification and event deduplication so that repeated notifications would not create duplicate side effects.

One important part was handling idempotency. We used the PayPal-Request-Id header for applicable operations, along with a database-level uniqueness constraint to enforce our one-active-attempt rule. This is important because two requests can arrive close together, even when the frontend tries to prevent repeated clicks.

For the AI layer, we used Gemini 2.5 Flash through Google's google-genai SDK. The investigator can retrieve evidence through a restricted set of tools and produces structured output containing evidence references. We also implemented an offline fallback so that investigation can continue in a predictable way when the model API is unavailable or returns invalid output.

The application uses SQLite by default, with PostgreSQL support, and includes a merchant investigation console built with AG Grid.

Challenges we ran into

One of our biggest challenges was handling payment timeouts correctly. Initially, it is tempting to treat a failed HTTP request as a failed payment. But the payment provider may have processed the request even if our application never received the response. We therefore had to separate the status of an HTTP request from the actual status of a payment.

Another challenge was testing these situations reliably. The PayPal sandbox allowed us to test the normal checkout, capture, and refund flows, but reproducing a specific network timeout or a prolonged pending state whenever we wanted was difficult. We addressed this by building the Fault-Injection Lab alongside the real sandbox integration. This gave us repeatable test scenarios without pretending that simulated events were real PayPal transactions.

We also had to be careful about how much responsibility we gave the AI. In a payment system, an incorrect recommendation can have financial consequences. We therefore made the AI an investigator rather than the authority. It can interpret evidence and recommend an action, but the backend policy engine makes the final decision about what is permitted.

Accomplishments we're proud of

We are particularly proud of building the complete recovery workflow rather than stopping at a payment status dashboard. ResolveAI can investigate an uncertain payment, show its evidence timeline, explain the situation, prevent unsafe retries, and coordinate a refund request with seller approval.

We also implemented live case updates, webhook deduplication, background reconciliation, and a Fault-Injection Lab. Our test suite reported approximately 31 passing scenarios covering important cases such as timeouts, duplicate attempts, webhook delivery issues, and refund status delays.

What we learned

The biggest lesson was that payment recovery is not simply about detecting failures. It is about knowing when we do not have enough evidence to make a decision.

We also learned that AI can be useful in financial workflows, but only when it operates within well-defined boundaries. Having deterministic backend rules alongside AI investigation made the system much safer and more predictable.

What's next for ResolveAI

We would like to extend ResolveAI with guided dispute mediation, allowing buyers and sellers to work through a dispute before it becomes a formal claim. We also want to strengthen production authentication and merchant onboarding, and expand support for authorization and void workflows beyond our current capture-focused demo.

Built With

Share this project:

Updates

Submission history