FinShield AI — MVP Explainer

Concepto

FinShield AI es un microservicio B2B de detección de fraude en tiempo real diseñado para fintechs y e-commerce que no pueden permitirse las soluciones empresariales tradicionales (Kount, Sift, Forter). Modelo API-first, integración en minutos, latencia < 200 ms, precio por volumen de transacciones.

---

Problema

Las PYMEs de e-commerce y fintech emergentes sufren:

• Fraude creciente sin herramientas de IA accesibles
• Sistemas de reglas que generan excesivos falsos positivos
• Integración compleja y costos prohibitivos de soluciones enterprise

---

Arquitectura

┌─────────────────────────────────────────────────┐
│             FinShield AI (Spring Boot 4)         │
│                                                  │
│  ┌─────────────┐  ┌──────────────┐               │
│  │AuthController│  │TxnController │ POST /v1/score│
│  │ /auth/login │  │              │               │
│  │ /auth/reg.  │  │ScoringService│               │
│  └─────────────┘  └──────┬───────┘               │
│                          │                       │
│               ┌──────────▼──────────┐            │
│               │   MlClientService   │            │
│               │  (OpenFeign client) │            │
│               └──────────┬──────────┘            │
│                      fail│fast + fallback         │
│               ┌──────────▼──────────┐            │
│               │  Local Heuristic    │            │
│               │  Scorer (fallback)  │            │
│               └─────────────────────┘            │
│                                                  │
│  ┌──────────────┐  ┌────────────────┐            │
│  │FeedbackCtrl  │  │ApiKeyController│            │
│  │/api/dashboard│  │/api/keys       │            │
│  │/api/feedback │  │                │            │
│  └──────────────┘  └────────────────┘            │
│                                                  │
│  Security: JwtAuthFilter + ApiKeyAuthFilter       │
│  DB:  H2 (dev) / PostgreSQL (prod)               │
└─────────────────────────────────────────────────┘
         │  OpenFeign (optional)
         ▼
┌────────────────────┐
│  Python / FastAPI  │
│  ML Microservice   │
│  POST /predict     │
│  (XGBoost / IF)    │
└────────────────────┘

Componentes clave

Layer	Clase	Responsabilidad
Security	%%INLINE0%%	Valida Bearer JWT en %%INLINE1%%
Security	%%INLINE2%%	Valida %%INLINE3%% en /v1/**
Security	JwtUtil	Genera/valida JWTs (jjwt 0.12.6, HS256)
Service	ScoringService	Pipeline de scoring: ML → fallback heurístico
Service	MlClientService	Feign client wrapper con manejo de fallos
Service	FeedbackService	Dashboard analytics + ciclo de feedback
Service	ApiKeyService	CRUD de API keys (SHA-256 hash, nunca en claro)
Service	MerchantService	Registro, auth, gestión de cuotas
Client	%%INLINE11%%	OpenFeign → Python %%INLINE12%%
Entity	Transaction	Transacción puntuada (H2/PostgreSQL)
Entity	Feedback	Veredicto del comerciante (ciclo reentrenamiento)
Entity	ApiKey	Hash SHA-256 de la clave de API
Entity	Merchant	Cuenta, plan, contador de llamadas

---

Endpoints REST

Autenticación (públicos)

Método	Path	Body	Respuesta
POST	%%INLINE17%%	%%INLINE18%%	AuthResponse + JWT
POST	%%INLINE20%%	%%INLINE21%%	AuthResponse + JWT

Scoring API (X-API-Key)

Método	Path	Auth	Body	Respuesta
POST	%%INLINE23%%	%%INLINE24%%	%%INLINE25%%	%%INLINE26%%

Ejemplo de request:

POST /v1/score
X-API-Key: fsa_a1b2c3d4e5f6...

{
  "externalId": "ORD-20260602-001",
  "amount": 8500.00,
  "currency": "USD",
  "userId": "user-42",
  "userEmail": "customer@example.com",
  "ipAddress": "203.0.113.10",
  "countryCode": "US",
  "cardLast4": "4242",
  "cardBin": "424242",
  "deviceId": "dev-abc123"
}

Ejemplo de respuesta:

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "ORD-20260602-001",
  "riskScore": 25,
  "recommendation": "APPROVE",
  "message": "Transaction approved. Risk score: 25/100.",
  "processingTimeMs": 18
}

Dashboard API (JWT Bearer)

Método	Path	Descripción
GET	/api/dashboard/transactions	Lista paginada de transacciones
GET	/api/dashboard/stats	Métricas de fraude agregadas
POST	/api/feedback	Envío de veredicto (fraud/legit)
POST	/api/keys	Crear API key
GET	/api/keys	Listar API keys
DELETE	/api/keys/{id}	Revocar API key

Scores de riesgo

Rango	Recomendación	Acción sugerida
0–30	APPROVE	Aprobar automáticamente
31–65	REVIEW	Enviar a revisión humana
66–100	BLOCK	Rechazar la transacción

---

Heurística de Scoring Local (fallback)

Cuando el servicio Python ML no está disponible:

Señal de riesgo	Puntos
Monto > $10,000	+40
Monto $5,001–$10,000	+25
Monto $1,001–$5,000	+10
País de alto riesgo (NG/KP/IR/SY/MM)	+30
Sin email de usuario	+10
Sin ID de dispositivo	+10
BIN de tarjeta empieza con "9"	+15
Velocidad: >5 txns mismo userId/hora	+30
Velocidad: >2 txns mismo userId/hora	+15

---

Modelo de Negocio

Plan	Cuota mensual	Precio estimado
FREE	1,000 calls	$0
PRO	50,000 calls	~$99/mes
ENTERPRISE	Ilimitado	Negociado

El contador %%INLINE33%% se incrementa en cada llamada a %%INLINE34%%. La cuota se aplica antes del scoring — devuelve HTTP 429 si se excede.

---

Gestión de API Keys

• Las claves se generan con %%INLINE35%% (32 bytes → hex, prefijo %%INLINE36%%)
• Solo el hash SHA-256 se persiste — la clave en claro nunca se almacena
• El primer 12 chars (prefix) se muestra en el dashboard para identificación
• La clave completa se devuelve una sola vez en la respuesta de creación

---

Seguridad

• JWT (jjwt 0.12.6, HS256): expiración configurable (default 24h)
• Contraseñas: BCrypt hashing via Spring Security
• API Keys: SHA-256 hash, nunca en claro en DB
• Sesiones: totalmente stateless (no HttpSession)
• CSRF: deshabilitado (API stateless)
• Aislamiento de tenants: merchantId verificado en cada operación

---

Ciclo de Feedback / Reentrenamiento

1. Merchant llama POST /v1/score → transacción guardada con status=PENDING
2. Dashboard muestra transacciones de alto riesgo
3. Merchant pulsa "Fraud ✓" o "Legit ✓"
4. POST /api/feedback → Feedback entity creado
5. Transaction.status → CONFIRMED_FRAUD / CONFIRMED_LEGITIMATE
6. (Futuro) Job batch exporta feedbacks al servicio Python para reentrenar

---

Cómo Ejecutar

Prerrequisitos

• Java 25
• Maven 3.9+

Desarrollo (H2 in-memory)

# Desde el directorio del proyecto:
mvn spring-boot:run

# La aplicación levanta en http://localhost:8080
# Dashboard en http://localhost:8080/index.html
# H2 Console en http://localhost:8080/h2-console
#   JDBC URL: jdbc:h2:mem:testdb  User: sa  Password: (vacío)

Producción (PostgreSQL)

# Variables de entorno:
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/finshield
export SPRING_DATASOURCE_USERNAME=finshield
export SPRING_DATASOURCE_PASSWORD=secret
export SPRING_JPA_HIBERNATE_DDL_AUTO=update
export FINSHIELD_JWT_SECRET=<base64-256-bit-key>
export FINSHIELD_ML_SERVICE_URL=http://ml-service:8000

mvn clean package -DskipTests
java -jar target/finshield-ai-api-0.0.1-SNAPSHOT.jar

Flujo rápido de prueba

# 1. Registrar merchant
curl -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@acme.com","password":"password123","companyName":"Acme Inc."}'

# 2. Login → obtener JWT
TOKEN=$(curl -s -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@acme.com","password":"password123"}' | grep -o '"token":"[^"]*' | cut -d'"' -f4)

# 3. Crear API key
API_KEY=$(curl -s -X POST http://localhost:8080/api/keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production"}' | grep -o '"fullKey":"[^"]*' | cut -d'"' -f4)

# 4. Puntuar transacción
curl -X POST http://localhost:8080/v1/score \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId":"TXN-001","amount":250.00,"currency":"USD",
    "userId":"user-42","userEmail":"customer@example.com",
    "ipAddress":"203.0.113.10","countryCode":"US",
    "cardLast4":"4242","cardBin":"424242","deviceId":"dev-001"
  }'

# 5. Ver dashboard
curl http://localhost:8080/api/dashboard/stats \
  -H "Authorization: Bearer $TOKEN"

---

Servicio Python ML (Opcional)

El servicio Spring Boot conecta al servicio ML vía OpenFeign. Si no está disponible, el scorer heurístico actúa como fallback automático.

Estructura del servicio Python esperado:

# FastAPI + scikit-learn / XGBoost
POST /predict
{
  "amount": 250.0,
  "currency": "USD",
  "userId": "user-42",
  "ipAddress": "203.0.113.10",
  "countryCode": "US",
  "cardBin": "424242",
  "deviceId": "dev-001"
}

# Response:
{
  "score": 23,
  "confidence": 0.87,
  "features": {
    "amount_risk": 0.12,
    "velocity_risk": 0.05,
    "geo_risk": 0.06
  }
}

---

Referencias

• TechRev: AI in FinTech 2026
• Spring Boot 4 Docs
• Spring Security 7 Docs
• jjwt 0.12.x Migration Guide
• Spring Cloud OpenFeign Docs
• IEEE: XGBoost for Credit Card Fraud Detection

---

Análisis de Negocio

TAM (Total Addressable Market): El mercado global de detección de fraude de pagos alcanzará ~$63B USD en 2028 (CAGR 22%). El segmento de PYMEs / fintechs emergentes representa ~15% del mercado pero está desatendido por las soluciones enterprise.

Ventaja competitiva del MVP:

1. Integración en minutos vs semanas de las soluciones enterprise
2. Precio accesible — modelo freemium con tier gratuito para adquisición
3. Fallback resiliente — el scorer heurístico garantiza 100% de uptime
4. Feedback loop — mejora continua por cada veredicto de comerciante
5. API-first — se integra en cualquier stack sin SDK propietario

Métricas clave a monitorear (KPIs):

• False Positive Rate (FPR) — debe ser < 2% para no friccionar ventas legítimas
• Detection Rate (DR) — objetivo > 95% de fraudes capturados
• Latencia P95 < 200 ms en /v1/score
• Churn rate por plan — indicador de satisfacción del servicio