Inspiration

Small-business owners often spend valuable time switching between invoicing platforms, payment dashboards, spreadsheets, and reports just to answer simple questions such as: How much have I invoiced this week?, Which invoices are still outstanding?, or Can I send an invoice to this customer?

We wanted to explore how conversational AI could make these everyday financial workflows simpler without giving an AI model uncontrolled access to financial actions.

That idea became MerchantMate AI — a conversational business assistant that lets small-business owners interact with their PayPal invoicing and financial data using natural language while keeping sensitive actions deterministic, validated, and under the user's control.

What it does

MerchantMate AI provides a conversational interface for common small-business financial workflows.

A user can ask questions such as:

  • "How much did I invoice this week?"
  • "Show me my outstanding invoices."
  • "Who is my highest-value customer?"
  • "Give me my business summary."
  • "Create an invoice for Sarah."

For analytics requests, MerchantMate retrieves real invoice data from the PayPal Sandbox and calculates metrics using deterministic Python logic.

For invoice creation, MerchantMate supports a multi-turn conversation. If information such as the customer's email, amount, or description is missing, the assistant asks for it instead of inventing a value. Once all required information is collected, it displays an invoice preview and waits for explicit confirmation before interacting with PayPal.

Users can also cancel the pending invoice before confirmation.

How we built it

MerchantMate AI is built with a modular Python architecture combining Ollama, FastAPI, Streamlit, Pydantic, and the PayPal Sandbox REST APIs.

Ollama provides local AI-powered natural-language understanding. The model interprets a user's message and converts it into structured intent information.

FastAPI acts as the backend orchestration layer. It routes requests between the AI service, conversation state management, analytics engine, validation logic, and PayPal integration.

Pydantic provides structured models and validation for AI intents, invoice drafts, conversation state, and API responses.

PayPal Sandbox REST APIs handle invoice creation, sending, and retrieval without moving real money.

Streamlit provides the conversational frontend and business dashboard, allowing users to chat with MerchantMate while viewing metrics such as total invoiced, outstanding amount, paid amount, and average invoice value.

The architecture deliberately separates AI interpretation from financial execution. The AI model does not directly create PayPal invoices or calculate financial totals.

Safety and reliability

Financial workflows require more safeguards than a typical chatbot, so we designed several protections into MerchantMate.

Before an invoice can be sent, the system validates the required information, generates a preview, and requires explicit user confirmation. Ambiguous responses do not trigger execution, and cancellation stops the pending transaction.

We also designed duplicate-invoice protection for partial failures. If PayPal successfully creates an invoice but sending it fails, MerchantMate retains the PayPal invoice ID. A retry attempts to send the existing invoice rather than creating another one.

The application is stateless at the API level: conversation state is passed between the frontend and backend rather than relying on a global server-side conversation object.

Challenges we faced

One of the biggest challenges was making AI useful without allowing unpredictable model output to control financial operations.

Natural-language requests can be incomplete or ambiguous, so we built a structured intent layer and deterministic corrections for important financial intents. This gave us the flexibility of conversational AI while keeping calculations and financial actions in regular application code.

Integrating PayPal Sandbox invoicing also presented challenges around authentication, permissions, invoice creation, sending, and testing realistic workflows. We worked through these issues and validated the complete flow from a natural-language request to a successfully sent Sandbox invoice.

Another challenge was handling failures safely. A network or API failure between invoice creation and invoice sending could otherwise result in duplicate invoices during a retry. Designing the state machine to distinguish between a new invoice and an already-created PayPal invoice became an important reliability feature.

What we learned

Building MerchantMate taught us that integrating AI into financial software is not simply about connecting an LLM to an API.

We learned to treat the AI model as an interpretation layer, while deterministic application logic remains responsible for validation, calculations, state transitions, and financial execution.

We also gained practical experience with PayPal REST APIs, OAuth authentication, FastAPI architecture, local LLM integration with Ollama, conversational state management, Pydantic validation, automated testing, and CI with GitHub Actions.

The project now includes 47 automated tests covering API behaviour, conversation state, financial safety logic, PayPal execution boundaries, period-aware analytics, assistant routing, and frontend behaviour.

What's next

MerchantMate could be extended with payment-event-based cash-flow analytics, automated invoice reminders, richer customer insights, enhanced visual analytics, persistent conversation history, additional PayPal business workflows, production authentication, and multi-user deployment.

Our goal with MerchantMate AI was to demonstrate that conversational AI can make financial tools easier to use without sacrificing control.

Instead of allowing AI to control the financial workflow, MerchantMate combines the strengths of both approaches:

Built With

Share this project:

Updates

Submission history