/home/suroeste/public_html/payments.transportessuroeste.com
Edit: /home/suroeste/public_html/payments.transportessuroeste.com/README.md (6599B)
# Transportes Suroeste - API Pasarela de Pagos
[](https://www.php.net/)
[](https://www.mysql.com/)
[](https://www.docker.com/)
[](https://epayco.co/)
[](https://www.pcisecuritystandards.org/)
[](LICENSE)
API REST para procesamiento de pagos de tickets de autobus mediante **ePayco Smart Checkout v2**. Implementa estandares bancarios de seguridad PCI-DSS e ISO 27001.
---
## Inicio Rapido (Docker)
```bash
# 1. Clonar y configurar
git clone
transportes-suroeste && cd transportes-suroeste
cp .env.example .env # Editar con credenciales reales
# 2. Iniciar
make setup
make up
# 3. Verificar
curl http://localhost:8080/api/v1/health
```
La aplicacion estara disponible en `http://localhost:8080`.
phpMyAdmin (desarrollo) en `http://localhost:8081`.
## Caracteristicas
- **Cifrado AES-256-GCM** para datos sensibles del pagador
- **Autenticacion API Key + HMAC-SHA512** para endpoints protegidos
- **Rate Limiting** (100 req/min) con bloqueo automatico anti-DDoS
- **Proteccion SQL Injection** via prepared statements PDO
- **Proteccion XSS** con sanitizacion + Content Security Policy
- **Auditoria completa** con trazabilidad bancaria
- **Webhooks** para notificaciones en tiempo real
- **ePayco Smart Checkout v2** (tarjetas, PSE, Nequi, efectivo)
- **Dockerizado** con configuracion de produccion y desarrollo
## Arquitectura
```
Internet
|
[Nginx] <-- Rate limiting, Security headers, Gzip
|
[PHP-FPM] <-- SecurityMiddleware -> RateLimiter -> AuthMiddleware
|
[ApiController]
/ | \
PaymentService LogService EncryptionService
| | |
[ePayco] [Archivos] [AES-256-GCM]
| |
[MySQL] <---------+
```
## Endpoints
| Metodo | Endpoint | Auth | Descripcion |
|--------|----------|:----:|-------------|
| `POST` | `/api/v1/payments` | Si | Crear transaccion de pago |
| `GET` | `/api/v1/payments/{uuid}` | Si | Consultar por UUID |
| `GET` | `/api/v1/payments/ticket/{ref}` | Si | Consultar por ticket |
| `GET` | `/api/v1/banks/pse` | No | Listar bancos PSE |
| `POST` | `/api/v1/webhook/epayco` | - | Webhook ePayco |
| `GET` | `/api/v1/health` | No | Health check |
## Ejemplo de Uso
```php
'TK-2024-001',
'amount' => 45000,
'description' => 'Ticket Medellin - Bogota',
'payer_email' => 'cliente@email.com',
'payer_name' => 'Juan Perez',
'payer_document_type' => 'CC',
'payer_document' => '1234567890'
]);
$timestamp = time();
$signature = hash_hmac('sha512', "POST\n/api/v1/payments\n{$timestamp}\n{$body}", $apiSecret);
$ch = curl_init('https://api.transportessuroeste.com/api/v1/payments');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-Key: ' . $apiKey,
'X-Timestamp: ' . $timestamp,
'X-Signature: ' . $signature
]
]);
$result = json_decode(curl_exec($ch), true);
// Redirigir al usuario a $result['data']['payment_url']
```
## Requisitos
| Componente | Version |
|-----------|---------|
| Docker + Docker Compose | 24+ / v2 |
| PHP (si sin Docker) | 8.1+ |
| MySQL / MariaDB | 8.0+ / 10.5+ |
| Composer | 2.0+ |
**Extensiones PHP**: pdo_mysql, openssl, mbstring, curl, json, gd, intl
## Comandos (Makefile)
```bash
make up # Iniciar servicios (desarrollo)
make down # Detener servicios
make build # Rebuild de contenedores
make logs # Ver logs en tiempo real
make logs-php # Solo logs PHP
make shell # Shell en contenedor PHP
make mysql # CLI MySQL
make backup # Backup de BD
make health # Health check
make prod-up # Iniciar en produccion
make status # Estado de contenedores
make clean # Limpiar todo (volumes incluidos)
```
## Estructura del Proyecto
```
transportes-suroeste/
├── config/ # Configuracion (.env, config.php)
├── docker/ # Configuracion Docker
│ ├── nginx/ # Nginx reverse proxy
│ ├── php/ # PHP-FPM + Dockerfile
│ └── mysql/ # MySQL config
├── public/ # Document root
│ ├── index.php # Front controller
│ ├── assets/ # CSS/JS
│ └── payment/ # Checkout + Response pages
├── src/ # Codigo fuente (PSR-4)
│ ├── Controllers/ # ApiController
│ ├── Models/ # Database (PDO)
│ ├── Services/ # Payment, Encryption, Log
│ ├── Middleware/ # Auth, Security, RateLimit
│ ├── Validators/ # Input validation
│ ├── Exceptions/ # Custom exceptions
│ └── Utils/ # Router, JsonResponse
├── sql/ # Database schema
├── docs/ # Documentacion
├── scripts/ # Backup, deploy
├── docker-compose.yml # Base config
├── Makefile # Quick commands
└── .env.example # Variables template
```
## Seguridad
| Amenaza | Proteccion |
|---------|-----------|
| SQL Injection | Prepared Statements PDO |
| XSS | Sanitizacion + CSP Headers |
| DDoS | Rate Limiting + IP Block |
| MITM | TLS + HSTS |
| Data Breach | AES-256-GCM + Argon2id |
| CSRF | Token validation |
| Clickjacking | X-Frame-Options: DENY |
## Documentacion
- [Documentacion Funcional](docs/DOCUMENTACION_FUNCIONAL.md) - Arquitectura, modulos, modelo de datos
- [Documentacion API](docs/DOCUMENTACION.html) - Endpoints, autenticacion, ejemplos
- [Diagramas de Flujo](docs/DIAGRAMAS.html) - Secuencia, estados, arquitectura
- [Changelog](CHANGELOG.md) - Historial de cambios
- [Contribuir](CONTRIBUTING.md) - Guia de contribucion
## Licencia
Propietario. (c) 2024-2026 Transportes Suroeste. Todos los derechos reservados.