paypal-ai-reconciliation

Inspiration

I joined this hackathon to challenge myself with a new project and learn how a real payment integration works from beginning to end. I wanted to go beyond tutorials and understand how developers build on the APIs of a global company like PayPal: authenticating requests, creating orders, capturing payments, handling notifications, and keeping reliable records.

Taking part in the PayPal AI Hackathon was an exciting opportunity to turn that curiosity into something practical. That became ClearLedger AI: a tool that helps a shop understand how its order expectations compare with verified payment evidence.

What it does

ClearLedger AI connects PayPal Sandbox checkout with a reconciliation dashboard and a local AI assistant.

It stores orders and completed captures in PostgreSQL, verifies payment webhooks, and handles repeated deliveries without creating duplicate payments. Users can import a shop ledger through CSV, identify mismatches, and track which matching paid orders still await fulfilment.

For example, if the shop expects EUR 12.00 but the recorded capture is EUR 10.00, the dashboard flags the difference. Users can then ask the assistant about the finding and inspect its cited evidence.

How I built it

I built the backend with Python, FastAPI, HTTPX, and asyncpg, using PostgreSQL for persistent records and audit history. Docker Compose runs the database and a dedicated webhook listener, while Cloudflare Tunnel provides a temporary endpoint for PayPal notifications.

The interface uses HTML, CSS, and JavaScript. The assistant runs Qwen3 4B locally through Ollama, without paid AI API calls.

An important design decision was to keep reconciliation deterministic: application code calculates the findings, while AI explains the supplied facts. The model cannot execute SQL, initiate payments, or change fulfilment status.

Challenges I faced

The challenges went beyond getting checkout to work. I had to configure the correct Sandbox credentials and buyer accounts, distinguish payment approval from completed capture, verify webhook signatures, and handle repeated notifications safely.

Connecting a local model introduced another challenge: making its answers useful and traceable. I added structured responses, evidence references, numerical checks, and clear error handling. These checks help, but users still need to review the cited records.

What I learned

I learned that payment integration involves much more than a checkout button. Persistence, retries, idempotency, verification, and clear payment states all matter.

I also learned how to combine data engineering with AI responsibly: preserve the evidence, calculate results consistently, and let the model explain those results without giving it control over transactions.

Accomplishments

The project now has a working Sandbox checkout, persistent records, verified webhook handling, CSV reconciliation, fulfilment tracking, and an integrated local AI assistant.

The latest automated backend run passed 88 tests using real PostgreSQL with simulated PayPal and Ollama responses. I also tested actual Sandbox payments, webhook resends, persistence across restarts, CSV mismatch correction, and a local AI response with expandable evidence.

What’s next

I want to extend reconciliation to refunds and disputes, evaluate the assistant across more difficult questions, and improve the experience for larger ledgers.

This project began as an opportunity to learn. It has become a working foundation for exploring how payment systems, reliable data pipelines, and local AI can work together.

Built With

• asyncpg
• cloudflare
• css3
• docker
• fastapi
• html5
• httpx
• javascript
• ollama
• paypal
• postgresql
• pydantic
• python
• qwen3