MerchantPilot AI

MerchantPilot AI automates merchant onboarding by combining document verification, explainable AI risk & compliance reviews, and a human-in-the-loop approval workflow.

Comment

Inspiration

MerchantPilot AI was born from a fundamental tension in fintech compliance: the need to move fast and the absolute requirement to stay safe. Traditional merchant onboarding is slow—humans manually review documents, cross-check details, chase missing information, and repeat. Yet automation alone feels reckless; regulatory bodies (and your own risk appetite) demand transparency and human judgment at critical gates.

I wanted to build a system that doesn't choose between speed and control, but instead optimizes both. The key insight: AI isn't meant to replace humans; it's meant to prepare airtight decision packages that humans can understand, challenge, and approve in seconds instead of days.

What it does

MerchantPilot AI is an end-to-end merchant onboarding automation platform that bridges the gap between speed and compliance. It ingests merchant profiles and supporting documents, runs them through a document verification pipeline and an AI-powered risk & compliance agent, and presents a human reviewer with a fully explainable decision package—all within minutes instead of days.

The Workflow:

  1. Merchant submits onboarding form + CAC and ID documents.
  2. System verifies CAC (extracts RC/BN, cross-checks business name, assigns confidence).
  3. Qwen AI agent reviews the merchant profile, documents, and verification output, returning a risk score (0–100), risk level (low/medium/high), confidence percentage, compliance requirements, identified gaps, and supporting reasons.
  4. Human reviewer opens the review center, sees the AI recommendation with evidence, and clicks Approve / Reject / Request Info.
  5. Every action (document upload, AI run, human decision, failure) is logged to an audit trail queryable by merchant or timestamp.

How we built it

  • Backend: FastAPI + SQLAlchemy on Python. Modular service layer for CAC verification (mock provider), Qwen agent orchestration, and audit logging.
  • Frontend: Next.js + React + TypeScript. Server components for data fetching, client components for interactivity. TanStack React Query for cache management.
  • Agent Integration: Qwen API via DashScope (OpenAI-compatible chat completions). Strict JSON output parsing and Pydantic validation before persistence.
  • Database: SQLAlchemy ORM mapping merchants, documents, agent runs, risk assessments, compliance reviews, approval decisions, and audit logs to a relational schema.
  • Storage: Pluggable abstraction (local file system by default) for document artifacts.
  • Deployment is containerized (Docker Compose) with both backend and frontend services co-orchestrated. The database persists to SQLite in dev or PostgreSQL in production.

Challenges we ran into

Qwen API Reliability: The first integration treated Qwen responses as gospel. I learned to validate, retry, and degrade gracefully. Timeouts, parse errors, and schema violations now trigger audit-logged failures that surface to humans with context.

CAC Document Parsing: Real CAC documents are messy—scanned images, varying layouts, extracted text with OCR artifacts. The mock provider had to be smart enough to extract RC/BN and business name reliably, yet simple enough to demo without a production OCR service. I settled on regex + fuzzy matching and clear confidence scores.

State Management in a Distributed Workflow: A merchant is "pending" until AI runs, then "flagged" or "needs_information" based on the output. But what if Qwen times out mid-review? I added explicit failure events and status guards so a partial update doesn't leave a merchant in limbo.

Frontend Real-Time Feedback: Clicking "Run AI Review" triggers a backend task that can take 10–30 seconds. Users need to see progress without polling. I use React Query's useQuery with async operations and optimistic updates, plus explicit error boundaries for service failures.

Audit Log Querying: With hundreds of merchants and thousands of events, queries can be slow. I indexed by created_at and entity_id, but also realized that metadata_json searching (looking for a merchant ID buried in event metadata) requires database-specific full-text search. This is a future optimization.

Accomplishments that we're proud of

Human-in-the-Loop Architecture That Works

AI generates explainable recommendations, but humans retain final authority. No "set and forget." Merchants flagged by AI can still be approved if a human finds justification; system respects override decisions and logs them. End-to-End Observability

Agent timeline shows every micro-step (document exists? text extracted? RC/BN found? name matches?).

Audit logs record who made each decision, when, and why. Failure events persist to the database so engineers can diagnose failures without log-file hunting. Modular, Swappable Services

CAC verification is a pluggable abstraction; mock provider works out-of-the-box, but real registry integrations can be dropped in.

Qwen agent is orchestrated via a service class; switching to another LLM requires minimal changes. Storage is abstracted; local file system for dev, cloud (S3, etc.) for production. Graceful Degradation Under Failure

Qwen timeout? System logs a failure event and notifies the human. No silent corruption.

Invalid API key? System returns a 401 and recommends correcting config. CAC PDF unreadable? System flags it with confidence 0.2 and recommends human review. Production-Ready Foundation

Database migrations with Alembic.

Containerized with Docker Compose. Configurable via .env file. Type-safe (Python type hints + Pydantic, TypeScript everywhere). Testable service layer (CAC, Qwen, audit logic are dependency-injectable). Compelling UI for Complex Workflows

Dashboard at a glance: pending reviews, approved today, risk distribution, recent applications.

Merchant detail page with 7 tabs covering profile, documents, agent analysis, risk, compliance, approval history, and audit trail. Review center—a streamlined card view showing AI recommendation, risk score, confidence, reasons, and CAC summary side-by-side. Agent timeline visualizes workflow steps as a clean vertical narrative.

What we learned

Explainability is non-negotiable: A risk score of 72/100 is meaningless without reasons. I learned that agent outputs must be structured, validated, and timestamped at every step so a human reviewer can trace "why" without digging through logs.

Composition over monoliths: Breaking the workflow into CAC Verification → Qwen AI Review → Compliance Assembly → Audit Logging made it easier to swap or test each piece independently.

JSON schema validation saves lives: Qwen outputs are creative. Pydantic validation catching schema mismatches early prevented silent failures and corrupted state.

Audit trails are a feature, not an afterthought: Once I committed to logging every decision (approvals, rejections, API calls, errors), debugging and compliance became trivial. Every merchant's journey is a queryable narrative.

Human-in-the-loop requires good defaults: The AI isn't there to make decisions; it's there to make human decisions faster. If the AI recommends "approve with standard monitoring" but the merchant has a flagged CAC, the system adjusts the recommendation to "manual review required." The human still decides.

What's next for MerchantPilot AI

  • Multi-Tier Risk & Compliance: Support different onboarding rules per merchant type (e.g., sole trader vs. company vs. NGO).
  • KYC/AML Integration: Fetch sanctions lists, PEP checks, and identity verification from external KYC providers. Fold results into risk scoring.
  • Agent Multi-Turns: Allow the AI agent to ask follow-up questions (e.g., "Please clarify the business activity") and update the review iteratively instead of one-shot.
  • Dashboard Analytics: Trend merchant risk over time, onboarding velocity, approval/rejection rates by reviewer.
  • Mobile Review App: Let approvers review and decide on mobile (iOS/Android) so compliance teams can work flexibly.
  • Marketplace Integration: Allow merchants to onboard via partner platforms (banks, marketplaces) and sync status bidirectionally.

Built With

Share this project:

Updates