FusionXPay

Overview

FusionXPay is an AI-native payment platform built with Spring Cloud microservices. Beyond standard payment processing (Stripe and PayPal), webhook-driven status updates, refunds, and async notifications, FusionXPay ships with a full AI integration layer:

• MCP Server — Exposes payment and order tools via the Model Context Protocol, allowing AI agents (e.g., Claude, Cursor) to query orders, initiate payments, and trigger refunds with AOP-enforced safety guards.
• AI CLI — A picocli-based command-line interface for AI agents and automation pipelines to interact with FusionXPay programmatically.
• AI Auth — An OAuth2-inspired browser-based consent flow that lets AI agents acquire scoped tokens for authorized API access.
• Platform Audit — API Gateway emits ingress audit events to Kafka (platform-audit-log topic) for every external request, while CLI/MCP attach X-Audit-* metadata for source/action attribution.

Architecture

Services

AI Layer

Infrastructure

AI Integration

MCP Server

The MCP Server (ai/ai-mcp-server) implements the Model Context Protocol so that AI agents can interact with FusionXPay as a native tool provider.

Available tools (via FusionXMcpTools):

AOP Safety Pipeline — every tool call passes through three aspects in sequence:

InputSafetyAspect → ToolAuditAspect → OutputSafetyAspect

• InputSafetyAspect — validates and sanitizes tool inputs before execution
• ToolAuditAspect — attaches MCP audit metadata (X-Audit-*) to downstream gateway-bound requests
• OutputSafetyAspect — redacts or prevents sensitive data from leaking to the AI agent

AI CLI

The AI CLI (ai/ai-cli) is a picocli-based Spring Boot application that AI agents or automated pipelines can invoke from the command line.

Available command groups:

AI Auth Flow

AI agents obtain scoped access tokens through a browser-based consent flow managed by Admin Service (POST /api/v1/admin/auth/ai/*). The flow mode depends on the client:

• CLI — attempts a callback flow first (PKCE + local HTTP server on 127.0.0.1 to receive the redirect); if that fails (e.g., no browser or port conflict), it falls back to the device-code flow where the user visits a verification URL manually.
• MCP — uses the device-code flow directly, since MCP clients run headlessly without a local callback server.

Both flows share a two-phase poll-then-token exchange: poll returns only a status, and the token is obtained in a separate POST /token call once the status is APPROVED.

API base path: http://localhost:8080/api/v1/admin/auth/ai/{endpoint} (via API Gateway on port 8080; browser approval uses GET /consent, token/session operations use POST)

Platform Audit

Every external request that crosses API Gateway is recorded to Kafka and can be persisted to MySQL through Kafka Connect:

MCP Server path: ToolAuditAspect (AOP) → injects X-Audit-Source=MCP-Java, tool action name, and a correlation ID into each gateway request

CLI path: CliExecutionStrategy (picocli execution hook) → injects X-Audit-Source=CLI-Java, command action name, and a correlation ID into each gateway request

Both paths converge at:

1. GatewayAuditFilter emits a PlatformAuditEvent to the platform-audit-log topic for every inbound request
2. Kafka Connect JDBC Sink persists events to the platform_audit_log table
3. Source/action attribution remains consistent across CLI, MCP, and future SDK clients through the shared X-Audit-* contract

Quick Start

Prerequisites

Setup

git clone https://github.com/Manho/FusionXPay.git
cd FusionXPay
cp .env.always-on.example .env.always-on

Edit .env.always-on with your infrastructure hosts, database credentials, payment provider keys, and callback URLs.

Start Everything

docker compose -f docker-compose.always-on.yml --env-file .env.always-on up -d --build

Verify

./scripts/check-always-on-health.sh ./.env.always-on
./scripts/verify-service-chain.sh

Useful Endpoints

Docker Compose Profiles

Testing

# Unit tests
mvn test

# Integration tests (Testcontainers spins up MySQL, Redis, Kafka)
mvn verify -pl services/api-gateway

# Service-specific tests
mvn test -pl services/payment-service
mvn test -pl services/admin-service
mvn test -pl ai/ai-mcp-server
mvn test -pl ai/ai-cli

# Runtime verification (requires running stack)
./scripts/check-always-on-health.sh ./.env.always-on
./scripts/verify-service-chain.sh

# End-to-end payment flows (sandbox keys required)
./scripts/e2e-payment-refund.sh stripe
./scripts/e2e-payment-refund.sh paypal

Project Structure

FusionXPay/
├── services/
│   ├── api-gateway/           # Spring Cloud Gateway, rate limiting, auth routing, platform audit emission
│   ├── order-service/         # Order lifecycle and merchant isolation
│   ├── payment-service/       # Provider integration, webhooks, refunds
│   ├── notification-service/  # Kafka-driven notifications
│   └── admin-service/         # Admin/merchant APIs and AI auth sessions
├── ai/
│   ├── ai-mcp-server/         # Model Context Protocol server with AOP safety pipeline
│   ├── ai-cli/                # picocli-based CLI for AI agent interactions
│   └── ai-common/             # Shared DTOs for AI auth flows
├── common/                    # Shared DTOs and utilities
├── mysql-init/                # Database initialization scripts
├── scripts/                   # Deploy, verify, backup, rollback, E2E utilities
├── monitoring/                # Prometheus, Grafana, Loki, Promtail configs
├── docs/                      # Architecture, deployment, platform audit, and testing docs
└── .github/workflows/         # CI, Docker build, and deployment pipelines

Documentation

Related

License

This project is licensed under the MIT License. See LICENSE for details.