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

---
id: "RF-INV-003"
title: "Sistema de Depositos"
type: "Requirement"
status: "Done"
priority: "Alta"
epic: "OQI-004"
project: "trading-platform"
version: "1.0.0"
created_date: "2025-12-05"
updated_date: "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

```typescript
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

```typescript
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

```typescript
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

```gherkin
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](../historias-usuario/US-INV-003-realizar-deposito.md)
- [ET-INV-003: Stripe Integration](../especificaciones/ET-INV-003-stripe.md)
- [RF-PAY-002: Checkout y Pagos](../../OQI-005-payments-stripe/requerimientos/RF-PAY-002-checkout.md)

---

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