PayDiagnose

Debug payment webhooks in seconds, not hours — "an AI agent that diagnoses integration failures and hands you the fix."

Comment

Inspiration

I was building a merchant payment platform as part of the Nomba x DevCareer hackathon 2026 I took part and kept running into the same problem, an error would come back from a webhook or API call, and there was no clear signal for what actually went wrong. 403 errors, signature mismatches, DNS issues, environment variable misconfigurations every time it meant digging through docs, guessing, and losing hours. After hitting this enough times, I noticed the bugs weren't random. They were the same handful of failure patterns, over and over, no matter which payment provider I was using. What was missing wasn't documentation, it was a fast way to go from "here's my error" to "here's what's actually wrong." That's what PayDiagnose is for.

What it does

PayDiagnose takes a webhook payload, error log, or failed request and diagnoses the root cause — authentication issues, signature verification failures, timeout/retry misconfiguration, DNS/routing problems, environment variable mistakes, and malformed payloads. It returns a plain-English explanation and a working code fix.

It's provider-agnostic. I tested it against Nomba, Stripe, and Paystack error formats, and it handled all three correctly, because the underlying failure patterns are the same regardless of which payment API is involved. If an error is genuinely unclear, it doesn't guess. It says so, explains what information is missing, and suggests a way to gather more evidence instead of making up a fix.

How I built it

The app is Next.js with Tailwind, deployed on Vercel. The diagnosis engine calls GPT-5.6 Terra live via the OpenAI API on every request, it's the actual engine the product runs on, not something used only at build time. I used Codex CLI, also on GPT-5.6 Terra at high reasoning effort, to harden the diagnosis engine after the initial build. It added input length validation, added handling for rate-limit errors from the OpenAI API (checking the SDK's actual type definitions rather than guessing at the error shape), and caught and fixed a type-safety issue it introduced along the way, then re-ran the linter to confirm. It also suggested the rule that the model should say "unclear" instead of guessing on ambiguous input. I reviewed that suggestion and applied it to the prompt myself. The category list, the scope of what the tool covers, and the decision that it should never confidently guess wrong were product calls I made based on the real bugs I hit building my own payment integration. Codex implemented and hardened the logic around those decisions.

Challenges I ran into

So, deciding on what to scope the tool was harder than expected. Payment integration failures cover a lot of ground, and trying to handle every possible case would have made the tool shallow across the board. I focused on the failure categories I'd actually hit myself rather than trying to be exhaustive. Close to the deadline, I also ran into an recurrent 401 error from OpenAI's API on the GPT-5.6 Sol model, it turned out to be an active issue affecting other developers too, not something wrong with my setup. I found this by checking Vercel's runtime logs and confirming the failure pattern, then switched the product over to GPT-5.6 Terra, which resolved it. Also choosing the project name was a tussle for me to be honest.

Accomplishments that I am proud of

Getting the tool to correctly hold back when it's not sure. It would have been easy to have it always return a confident-sounding answer, but having it say "unclear, here's what's missing" on a vague input, instead of guessing, felt like the right call for a debugging tool a wrong confident answer wastes more of a developer's time than an honest one.

What I learned

Most of the real debugging pain in payment integrations comes from a small, repeated set of failure patterns, not from novel or complex bugs. The bottleneck is diagnosis speed, not raw difficulty. While working through the Codex session also reinforced a smaller but useful habit: checking a library's actual type definitions before writing error-handling code, instead of assuming the shape of an error. Overall, the experience was good.

What's next for PayDiagnose

  • Interactive follow-up on a diagnosis. Right now, each diagnosis is a single request/response. A natural next step is letting the user reply directly to a result e.g. "this didn't fix it, here's the new error" or "can you also show me the fix in Python instead of TypeScript", so the tool becomes a short conversation rather than a one-shot lookup.
  • Expanded provider coverage. Add failure patterns specific to more providers (Flutterwave, Razorpay, Square) beyond the general categories already covered.
  • Test mode. A lightweight way to send a mock webhook to a local dev server, so a diagnosis can be reproduced and verified live instead of only reasoned about from a pasted log.
  • Diagnosis history. Persistence, so a developer can revisit past diagnoses during a debugging session without re-pasting the same error.
  • Team/shared use. A way for a team to share a diagnosis link with a colleague, useful when debugging a production incident together.

Built With

Share this project:

Updates