🚌 Transportes Suroeste - Diagramas de Flujo
1. Diagrama de Secuencia - Flujo de Pago
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Sistema de │ │ API Gateway │ │ ePayco │ │ Banco │
│ Tickets │ │ (Este Sistema) │ │ │ │ │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │ │
│ 1. POST /payments │ │ │
│ (ticket_ref, amount) │ │ │
│──────────────────────>│ │ │
│ │ │ │
│ │ 2. Validar request │ │
│ │ Crear transacción │ │
│ │ Cifrar datos │ │
│ │ │ │
│ 3. Response │ │ │
│ {transaction_uuid, │ │ │
│ payment_url} │ │ │
│<──────────────────────│ │ │
│ │ │ │
│ 4. Usuario va a │ │ │
│ payment_url │ │ │
│ │ │ │
│ │ 5. Tokenizar tarjeta │ │
│ │──────────────────────>│ │
│ │ │ │
│ │ 6. Token response │ │
│ │<──────────────────────│ │
│ │ │ │
│ │ 7. Procesar pago │ │
│ │──────────────────────>│ │
│ │ │ 8. Autorizar │
│ │ │──────────────────────>│
│ │ │ │
│ │ │ 9. Respuesta │
│ │ │<──────────────────────│
│ │ │ │
│ │ 10. Resultado pago │ │
│ │<──────────────────────│ │
│ │ │ │
│ │ 11. Actualizar BD │ │
│ │ Log auditoría │ │
│ │ │ │
│ 12. Webhook │ │ │
│ {status: approved} │ │ │
│<──────────────────────│ │ │
│ │ │ │
│ 13. Confirmar ticket │ │ │
│ Enviar email │ │ │
│ │ │ │
2. Diagrama de Estados de Transacción
┌─────────────┐
│ INICIO │
└──────┬──────┘
│
▼
┌─────────────┐
┌─────│ PENDING │─────┐
│ └──────┬──────┘ │
│ │ │
Timeout Procesar Cancelar
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────────┐ ┌─────────┐
│ EXPIRED │ │ PROCESSING │ │CANCELLED│
└─────────┘ └──────┬──────┘ └─────────┘
│
┌────────────┼────────────┐
│ │ │
Aprobado Rechazado Error
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌────────┐
│ APPROVED │ │ REJECTED │ │ FAILED │
└────┬─────┘ └──────────┘ └────────┘
│
Reembolso
│
▼
┌──────────┐
│ REFUNDED │
└──────────┘
3. Diagrama de Arquitectura
┌────────────────────────────────────────────────────────────────────────────────┐
│ CAPA DE PRESENTACIÓN │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ public/index.php │ │
│ │ (Router + Manejo de errores) │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────────────┐
│ CAPA DE MIDDLEWARE │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Security │ │ RateLimiter │ │ Auth │ │ Input Validator │ │
│ │ Middleware │ │ │ │ Middleware │ │ │ │
│ │ - Headers │ │ - Anti-DDoS │ │ - API Key │ │ - Sanitización │ │
│ │ - HTTPS │ │ - IP Block │ │ - HMAC │ │ - Validación │ │
│ │ - XSS/SQLi │ │ │ │ - Timestamp │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────────────┐
│ CAPA DE CONTROLADORES │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ ApiController │ │
│ │ - createPayment() - processPayment() - getPayment() │ │
│ │ - getPaymentByTicket() - handleCallback() - healthCheck() │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────────────┐
│ CAPA DE SERVICIOS │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────────────┐ │
│ │ PaymentService │ │ EncryptionService│ │ LogService │ │
│ │ - createPayment │ │ - encrypt/decrypt│ │ - transaction() │ │
│ │ - processCard │ │ - hashPassword │ │ - security() │ │
│ │ - callback │ │ - sign/verify │ │ - audit() │ │
│ │ - getStatus │ │ - generateUuid │ │ - access() │ │
│ └────────┬─────────┘ └──────────────────┘ └──────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ ePayco SDK │ │
│ │ - token.create │ │
│ │ - charge.create │ │
│ │ - customer.create│ │
│ └──────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────────────┐
│ CAPA DE DATOS │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ Database (PDO) │ │
│ │ Prepared Statements - Prevención SQL Injection │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────────┐ │
│ │api_clients│ │transactions│ │audit_trail│ │ security │ │rate_limit │ │
│ │ │ │ │ │ │ │ _events │ │_tracking │ │
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ └───────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
4. Diagrama de Casos de Uso
┌─────────────────────────────────────────┐
│ Sistema de Pagos │
│ Transportes Suroeste │
└─────────────────────────────────────────┘
┌──────────┐ ┌──────────┐
│ Sistema │ │ Admin │
│ Tickets │ │ Sistema │
└────┬─────┘ └────┬─────┘
│ │
│ ┌─────────────────────────────────────────────────┐ │
├──│ UC1: Crear Transacción de Pago │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
├──│ UC2: Consultar Estado de Transacción │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
├──│ UC3: Consultar por Referencia de Ticket │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
├──│ UC4: Recibir Notificación Webhook │───┤
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ UC5: Verificar Estado del Servicio (Health) │───┤
│ └─────────────────────────────────────────────────┘ │
│ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ UC6: Gestionar Clientes API │───┤
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ UC7: Consultar Logs de Auditoría │───┤
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ UC8: Generar Reportes de Conciliación │───┤
│ └─────────────────────────────────────────────────┘ │
│ │
┌────┴─────┐ ┌────┴─────┐
│ ePayco │ │ Banco │
│ │ │ │
└──────────┘ └──────────┘
ACTORES:
─────────────────────────────────────────────────────────────────────────────
• Sistema de Tickets: Sistema externo que vende los boletos de autobús
• Admin Sistema: Administrador de la pasarela de pagos
• ePayco: Proveedor de servicios de pago
• Banco: Entidad financiera que procesa la transacción
5. Flujo de Datos Sensibles (Cifrado)
┌─────────────────────────────────────────────────────────────────────────┐
│ FLUJO DE DATOS SENSIBLES │
└─────────────────────────────────────────────────────────────────────────┘
ENTRADA PROCESO ALMACENAMIENTO
─────── ─────── ──────────────
┌──────────────┐ ┌────────────────┐ ┌──────────────────┐
│ payer_email │ ──────> │ AES-256-GCM │ ──────> │ Campo cifrado │
│ (texto plano)│ │ + HMAC-SHA512 │ │ en BD │
└──────────────┘ └────────────────┘ └──────────────────┘
┌──────────────┐ ┌────────────────┐ ┌──────────────────┐
│ payer_doc │ ──────> │ AES-256-GCM │ ──────> │ Campo cifrado │
│ (texto plano)│ │ + HMAC-SHA512 │ │ en BD │
└──────────────┘ └────────────────┘ └──────────────────┘
┌──────────────┐ ┌────────────────┐ ┌──────────────────┐
│ payer_name │ ──────> │ AES-256-GCM │ ──────> │ Campo cifrado │
│ (texto plano)│ │ + HMAC-SHA512 │ │ en BD │
└──────────────┘ └────────────────┘ └──────────────────┘
┌──────────────┐ ┌────────────────┐ ┌──────────────────┐
│ card_number │ ──────> │ ePayco Token │ ──────> │ Solo últimos 4 │
│ (texto plano)│ │ (nunca se │ │ dígitos en BD │
└──────────────┘ │ almacena) │ └──────────────────┘
└────────────────┘
┌──────────────┐ ┌────────────────┐ ┌──────────────────┐
│ api_secret │ ──────> │ Argon2id │ ──────> │ Hash en BD │
│ (texto plano)│ │ (one-way hash)│ │ (irreversible) │
└──────────────┘ └────────────────┘ └──────────────────┘
ALGORITMOS UTILIZADOS:
─────────────────────────────────────────────────────────────────────────
• Cifrado simétrico: AES-256-GCM (autenticado)
• Integridad: HMAC-SHA512
• Hash de contraseñas: Argon2id (memory-hard)
• Firmas: HMAC-SHA512
• Generación de claves: random_bytes() (CSPRNG)