trading-platform/docs/02-definicion-modulos/OQI-004-investment-accounts/requerimientos/RF-INV-003-depositos.md

id	title	type	status	priority	epic	project	version	created_date	updated_date
RF-INV-003	Sistema de Depositos	Requirement	Done	Alta	OQI-004	trading-platform	1.0.0	2025-12-05	2026-01-04

RF-INV-003: Sistema de Depósitos

Metadata

Campo	Valor
ID	RF-INV-003
Épica	OQI-004 - Cuentas de Inversión
Tipo	Requerimiento Funcional
Prioridad	P0
Story Points	8
Estado	Aprobado
Última actualización	2025-12-05

---

Descripción

El sistema debe permitir a los usuarios depositar fondos en sus cuentas de inversión a través de múltiples métodos de pago, con procesamiento seguro y tracking completo de transacciones.

---

Métodos de Depósito

1. Stripe (Tarjeta de Crédito/Débito)

Característica	Valor
Mínimo	$50 USD
Máximo	$10,000 USD
Comisión	2.9% + $0.30
Tiempo procesamiento	Instantáneo
Monedas	USD, EUR (conversión automática)

2. Transferencia desde Wallet Interno

Característica	Valor
Mínimo	$10 USD
Máximo	Balance disponible
Comisión	Sin comisión
Tiempo procesamiento	Instantáneo

3. Crypto (Futuro - Fase 2)

Característica	Valor
Monedas	USDT, USDC
Red	Ethereum, BSC, Polygon
Confirmaciones	3-12 según red

---

Flujo de Depósito

Diagrama de Flujo

┌─────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  User   │────▶│  Select  │────▶│  Enter   │────▶│ Confirm  │
│ Account │     │  Method  │     │  Amount  │     │ Payment  │
└─────────┘     └──────────┘     └──────────┘     └────┬─────┘
                                                       │
                    ┌──────────────────────────────────┘
                    ▼
              ┌──────────┐     ┌──────────┐     ┌──────────┐
              │ Process  │────▶│  Update  │────▶│  Send    │
              │ Payment  │     │  Balance │     │ Confirm  │
              └──────────┘     └──────────┘     └──────────┘

Estados de Transacción

Estado	Descripción
pending	Transacción iniciada, esperando pago
processing	Pago recibido, procesando
completed	Fondos acreditados a la cuenta
failed	Pago rechazado o error
refunded	Pago devuelto (por solicitud o error)

---

Funcionalidades Requeridas

RF-INV-003.1: Iniciar Depósito

El usuario debe poder:

• Seleccionar cuenta de inversión destino
• Elegir método de pago
• Ingresar monto a depositar
• Ver resumen con comisiones
• Confirmar transacción

RF-INV-003.2: Procesamiento Stripe

interface StripeDepositRequest {
  accountId: string;           // Cuenta de inversión destino
  amount: number;              // Monto en USD
  paymentMethodId: string;     // Stripe payment method
}

interface StripeDepositResponse {
  transactionId: string;
  status: 'pending' | 'completed' | 'failed';
  amount: number;
  fee: number;
  netAmount: number;           // amount - fee
  receiptUrl?: string;
}

RF-INV-003.3: Transferencia desde Wallet

interface WalletTransferRequest {
  accountId: string;           // Cuenta de inversión destino
  amount: number;              // Monto en USD
}

interface WalletTransferResponse {
  transactionId: string;
  status: 'completed';
  amount: number;
  fee: 0;
  newWalletBalance: number;
  newAccountBalance: number;
}

RF-INV-003.4: Validaciones

Validación	Mensaje de Error
Monto < mínimo	"El monto mínimo es $50 USD"
Monto > máximo	"El monto máximo es $10,000 USD"
Cuenta inactiva	"La cuenta debe estar activa para depositar"
Saldo insuficiente (wallet)	"Saldo insuficiente en wallet"
Tarjeta rechazada	"El pago fue rechazado. Verifica tu tarjeta"

RF-INV-003.5: Primer Depósito

Cuando es el primer depósito de una cuenta:

• Cambiar estado de cuenta a active
• Registrar timestamp de primer depósito
• Iniciar trading automático
• Enviar email de bienvenida

---

Modelo de Datos

Entidad: DepositTransaction

interface DepositTransaction {
  id: string;                   // UUID
  accountId: string;            // FK a investment_accounts
  userId: string;               // FK a users

  method: 'stripe' | 'wallet' | 'crypto';
  status: TransactionStatus;

  // Montos
  amount: number;               // Monto solicitado
  fee: number;                  // Comisión cobrada
  netAmount: number;            // Monto acreditado
  currency: 'USD';

  // Stripe specific
  stripePaymentIntentId?: string;
  stripeReceiptUrl?: string;

  // Wallet specific
  walletTransactionId?: string;

  // Metadata
  ipAddress: string;
  userAgent: string;

  // Timestamps
  createdAt: Date;
  processedAt?: Date;
  completedAt?: Date;
  failedAt?: Date;
}

---

Reglas de Negocio

1. RN-020: Los depósitos solo pueden hacerse a cuentas activas o pending_deposit
2. RN-021: Las comisiones de Stripe se descuentan del monto depositado
3. RN-022: Los depósitos desde wallet son instantáneos y sin comisión
4. RN-023: El primer depósito activa automáticamente la cuenta
5. RN-024: Límite diario de depósitos: $50,000 USD (prevención de fraude)
6. RN-025: Los depósitos generan registro de auditoría inmutable

---

Criterios de Aceptación

Escenario: Depósito con tarjeta exitoso
DADO que el usuario tiene cuenta activa en Atlas
Y tiene tarjeta guardada en Stripe
CUANDO deposita $500 USD
ENTONCES se procesa el pago exitosamente
Y se descuenta la comisión de Stripe
Y el balance de la cuenta aumenta en $485.20
Y recibe confirmación por email

Escenario: Depósito desde wallet
DADO que el usuario tiene $1,000 en su wallet
Y tiene cuenta activa en Orion
CUANDO transfiere $200 desde su wallet
ENTONCES el balance del wallet disminuye en $200
Y el balance de la cuenta aumenta en $200
Y no se cobra comisión
Y la transferencia es instantánea

Escenario: Primer depósito activa cuenta
DADO que el usuario tiene cuenta en estado "pending_deposit"
CUANDO realiza su primer depósito de $100
ENTONCES la cuenta cambia a estado "active"
Y el trading automático se inicia
Y recibe email de bienvenida con instrucciones

Escenario: Depósito por debajo del mínimo
DADO que el usuario intenta depositar $30 USD
CUANDO confirma la transacción
ENTONCES recibe error "El monto mínimo es $50 USD"
Y la transacción no se procesa

---

API Endpoints

Método	Endpoint	Descripción
POST	/investment/deposits/stripe	Crear depósito con Stripe
POST	/investment/deposits/wallet	Transferir desde wallet
GET	/investment/deposits	Listar depósitos del usuario
GET	/investment/deposits/:id	Detalle de depósito

---

Webhooks (Stripe)

Evento	Acción
payment_intent.succeeded	Acreditar fondos, actualizar transacción
payment_intent.payment_failed	Marcar transacción como fallida
charge.refunded	Revertir acreditación, notificar usuario

---

Referencias

• US-INV-003: Realizar depósito
• ET-INV-003: Stripe Integration
• RF-PAY-002: Checkout y Pagos

---

Autor: Requirements-Analyst Fecha: 2025-12-05