Inspiration
Payment integrations can fail in ways that are difficult to reproduce and diagnose. Developers often need to understand what happened during a checkout failure, identify its likely cause, and determine a safer recovery approach.
Although payment monitoring and debugging tools already exist, PayPal Failure Doctor explores a focused developer workflow for reproducing selected PayPal checkout failures and investigating them through a single workspace.
What it does
PayPal Failure Doctor is a React-based dashboard supported by a Node.js and Express backend. It allows developers to simulate three selected payment failure scenarios:
INSTRUMENT_DECLINED– a declined funding source.DUPLICATE_INVOICE_ID– a duplicate invoice identifier.INTERNAL_SERVER_ERROR– a simulated temporary server error.
The application displays execution traces, diagnostic explanations, and recovery checks to help developers investigate these scenarios.
For optional AI-assisted diagnosis, the application integrates OpenRouter using the openrouter/free model alias. The AI analyzes the selected scenario, execution trace, and relevant sample code to generate explanations and troubleshooting suggestions. A local rule-based advisor provides a fallback when the external AI service is unavailable or not configured.
With PayPal Sandbox credentials configured, developers can also create and capture test orders and inspect the corresponding Sandbox responses.
A live activity panel displays recent simulator and Sandbox events. Server-Sent Events (SSE) stream new activity to the dashboard. The application also includes webhook visibility and signature verification when configured.
How we built it
The frontend uses React and Vite, while the backend uses Node.js and Express.
The project integrates:
- PayPal Developer Platform: PayPal JavaScript SDK v6 and Orders v2 REST API for Sandbox payment workflows.
- PayPal Sandbox: A controlled environment for testing order creation and capture without processing real payments.
- OpenRouter AI: An optional AI-assisted diagnosis layer using the
openrouter/freemodel alias. - Local Rule-Based Advisor: Provides deterministic diagnostic guidance when external AI is unavailable.
- Server-Sent Events: Streams recent simulator and Sandbox activity to the frontend.
- Database and backend services: Support application authentication, security, and workspace functionality.
The AI diagnosis feature is separate from payment execution. It explains supplied diagnostic information but does not create, approve, or capture payments.
Challenges we ran into
One of our main challenges was distinguishing simulated payment failures from actual PayPal Sandbox responses. We kept these workflows separate and identified their event sources to avoid confusing simulated outcomes with real Sandbox responses.
We also worked on keeping payment credentials on the server, making external AI optional, and ensuring that the diagnostic workflow remains useful when external credentials are unavailable.
Another challenge was connecting the frontend, backend, database, payment integration, and activity streaming into one working application.
Accomplishments we're proud of
We brought together a repeatable payment failure simulator, execution traces, AI-assisted diagnosis, local rule-based fallback, recovery checks, optional PayPal Sandbox checkout, and live activity monitoring in one developer-focused prototype.
We are particularly proud that the diagnostic experience can still provide basic guidance without requiring an external AI service.
What we learned
We learned that a useful payment debugging workflow needs more than an error message. Developers need evidence about what happened, an explanation of possible causes, and clear guidance on what to investigate next.
We also learned to distinguish simulated failures from actual payment responses and to treat AI as a diagnostic assistant rather than an authority on payment outcomes. Payment execution and its results must remain grounded in the application and PayPal responses.
What's next for PayPal Failure Doctor
Future improvements include expanding the number of supported PayPal failure scenarios, strengthening automated retry and fulfillment checks, improving persistent event storage for multi-user deployments, and evaluating AI-generated diagnoses against a larger collection of known failure cases.
We also plan to improve the diagnostic workflow and provide more detailed analysis of payment execution traces.
Conclusion
PayPal Failure Doctor is a hackathon prototype that explores a more guided way to reproduce and investigate PayPal checkout failures.
By combining PayPal Sandbox testing, failure simulation, execution traces, optional AI-assisted explanations, and recovery checks, it aims to help developers understand payment issues more effectively.
Live payment mode is disabled. The application is intended for Sandbox testing and simulated failure investigation, and it does not process live customer payments.
Built With
- ai
- api-integration
- artificial-intelligence
- authentication
- debugging
- encryption
- express.js
- full-stack
- javascript
- neon
- node.js
- openrouter
- payment-integration
- payment-processing
- paypal
- paypal-sandbox
- postgresql
- react
- real-time-monitoring
- rest-api
- server-sent-events
- vite
- web-development