APIs RESTful Seguras para Fintech: OAuth2, Rate Limiting y Validación en PHP 8.4

CORS Preflight: Responder OPTIONS inmediatamente sin tocar BD/auth.
Autenticación: Validar token JWT. Rechazar 401 si inválido/expirado.
Autorización: Verificar scopes del token vs endpoint solicitado. Rechazar 403 si insuficientes.
Rate Limiting: Verificar quota adaptativa. Rechazar 429 si excedida.
Validación Input: Parsear y validar payload. Rechazar 400 si inválido.
Idempotencia Check: Verificar si idempotency_key ya fue procesada. Retornar resultado cacheado si sí.
Business Logic: Solo tras pasar todos los filtros anteriores.

Este orden es crítico: autenticación antes de rate limiting (para aplicar límites por cliente, no por IP), validación antes de business logic (para evitar procesamiento de datos corruptos), idempotencia al final (para cachear resultados válidos únicamente).

6. Logging y Auditoría de API

Toda operación financiera vía API debe ser auditada inmutablemente. Logs deben incluir:

Request ID único: Generar UUID al inicio de cada request. Propagar a todos los logs y respuestas (header X-Request-ID).
Cliente autenticado: client_id y scopes del token. Nunca loguear tokens completos ni secrets.
Payload sanitizado: Loguear estructura y campos no sensibles. Enmascarar PAN, CVV, API keys.
Resultado y latencia: Status code, tiempo de procesamiento, errores estructurados.
IP y User-Agent: Para forense y detección de anomalías geográficas/comportamentales.

Almacenar logs en sistema separado de la BD transaccional (S3/R2/Elasticsearch). Retener mínimo 12 meses para cumplimiento regulatorio LATAM. Configurar alertas proactivas para patrones anómalos (picos de 4xx/5xx, clientes con tasa de error >10%, accesos desde geolocalizaciones inesperadas).

7. Conclusión y Recursos Oficiales

APIs RESTful seguras para fintech requieren disciplina en tres frentes: autenticación robusta (OAuth2 Client Credentials), rate limiting adaptativo al contexto del cliente, y validación estricta de payloads financieros. Implementar estos pilares en PHP 8.4 sin frameworks pesados es viable y eficiente, siempre que se respete el orden de ejecución del middleware pipeline y se mantenga auditoría inmutable de toda operación.

Referencias oficiales:

RFC 6749: OAuth 2.0 Authorization Framework: Especificación oficial.
RFC 7519: JSON Web Token (JWT): Estándar de tokens firmados.
OWASP REST Security Cheat Sheet: Mejores prácticas de seguridad API.
Stripe API Authentication Guide: Referencia de implementación production-grade.

Nota técnica: Este artículo utiliza marcado Schema.org Article coexistente con el nodo FinancialService corporativo. Los metadatos semánticos se indexan automáticamente vía The SEO Framework.

Tier-based: Partners premium tienen límites superiores a free/trial. Almacenar tier en token JWT claim.
Endpoint-specific: /payments tiene límite más estricto que /catalog. Operaciones financieras sensibles requieren protección reforzada.
Burst allowance: Permitir ráfagas cortas (burst) sobre el límite sostenido para absorber picos legítimos sin bloquear.
Penalty escalation: Si cliente excede límite repetidamente, reducir temporalmente su quota o requerir re-autenticación.

<?php
declare(strict_types=1);

namespace App\Api\Middleware;

use Redis;

class AdaptiveRateLimiter 
{
    private Redis $redis;
    
    // Límites por tier (requests por minuto)
    private const TIER_LIMITS = [
        'free'     => ['default' => 60,  'payments' => 10],
        'basic'    => ['default' => 300, 'payments' => 60],
        'premium'  => ['default' => 1000,'payments' => 200],
        'enterprise'=>['default' => 5000,'payments' => 1000]
    ];

    public function __construct(Redis $redis) 
    {
        $this->redis = $redis;
    }

    /**
     * Verifica rate limit usando algoritmo sliding window
     */
    public function check(string $clientId, string $tier, string $endpoint): array 
    {
        $limit = self::TIER_LIMITS[$tier][$endpoint] 
                 ?? self::TIER_LIMITS[$tier]['default'] 
                 ?? 60;
        
        $windowKey = "ratelimit:{$clientId}:{$endpoint}:" . floor(time() / 60);
        
        // Incrementar contador atómicamente
        $current = $this->redis->incr($windowKey);
        
        // Establecer TTL solo en primera petición de la ventana
        if ($current === 1) {
            $this->redis->expire($windowKey, 120); // 2 min TTL para cleanup
        }

        $remaining = max(0, $limit - $current);
        $resetAt = (floor(time() / 60) + 1) * 60;

        // Headers estándar RFC 6585
        header("X-RateLimit-Limit: {$limit}");
        header("X-RateLimit-Remaining: {$remaining}");
        header("X-RateLimit-Reset: {$resetAt}");

        if ($current > $limit) {
            header("Retry-After: " . ($resetAt - time()));
            return ['allowed' => false, 'reason' => 'rate_limit_exceeded'];
        }

        return ['allowed' => true];
    }
}

4. Validación Estricta de Payloads Financieros

En APIs financieras, toda entrada es hostil hasta demostrar lo contrario. Validación laxa permite inyecciones, desbordamientos enteros y lógica de negocio corrupta. PHP 8.4 con tipado estricto ayuda, pero no es suficiente sin validación explícita de reglas de negocio.

<?php
declare(strict_types=1);

namespace App\Api\Validation;

use InvalidArgumentException;

class PaymentRequestValidator 
{
    /**
     * Valida payload de creación de pago con reglas financieras estrictas
     */
    public static function validate(array $data): array 
    {
        $errors = [];

        // Monto: entero positivo en centavos (evita problemas float)
        if (!isset($data['amount_cents']) || !is_int($data['amount_cents'])) {
            $errors[] = 'amount_cents: requerido, tipo entero';
        } elseif ($data['amount_cents'] <= 0) {
            $errors[] = 'amount_cents: debe ser > 0';
        } elseif ($data['amount_cents'] > 999999999) {
            $errors[] = 'amount_cents: excede máximo permitido (9,999,999.99)';
        }

        // Moneda: ISO 4217 válida
        $validCurrencies = ['USD', 'MXN', 'COP', 'PEN', 'BRL', 'CLP', 'ARS'];
        if (!isset($data['currency']) || !in_array(strtoupper($data['currency']), $validCurrencies, true)) {
            $errors[] = 'currency: debe ser una de ' . implode(', ', $validCurrencies);
        }

        // Merchant ID: formato UUID v4
        if (!isset($data['merchant_id']) || 
            !preg_match('/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i', $data['merchant_id'])) {
            $errors[] = 'merchant_id: formato UUID v4 inválido';
        }

        // Idempotency Key: obligatoria para operaciones financieras
        if (empty($data['idempotency_key']) || strlen($data['idempotency_key']) < 16) {
            $errors[] = 'idempotency_key: requerida, mínimo 16 caracteres';
        }

        if (!empty($errors)) {
            throw new InvalidArgumentException(
                json_encode(['errors' => $errors], JSON_UNESCAPED_SLASHES)
            );
        }

        // Retornar datos normalizados y sanitizados
        return [
            'amount_cents'    => $data['amount_cents'],
            'currency'        => strtoupper($data['currency']),
            'merchant_id'     => strtolower($data['merchant_id']),
            'idempotency_key' => $data['idempotency_key'],
            'metadata'        => $data['metadata'] ?? []
        ];
    }
}

5. Middleware Pipeline: Orquestación Segura

Los componentes de seguridad deben ejecutarse en orden estricto antes de cualquier lógica de negocio. Un middleware pipeline garantiza consistencia y evita omisiones accidentales:

CORS Preflight: Responder OPTIONS inmediatamente sin tocar BD/auth.
Autenticación: Validar token JWT. Rechazar 401 si inválido/expirado.
Autorización: Verificar scopes del token vs endpoint solicitado. Rechazar 403 si insuficientes.
Rate Limiting: Verificar quota adaptativa. Rechazar 429 si excedida.
Validación Input: Parsear y validar payload. Rechazar 400 si inválido.
Idempotencia Check: Verificar si idempotency_key ya fue procesada. Retornar resultado cacheado si sí.
Business Logic: Solo tras pasar todos los filtros anteriores.

6. Logging y Auditoría de API

Toda operación financiera vía API debe ser auditada inmutablemente. Logs deben incluir:

Request ID único: Generar UUID al inicio de cada request. Propagar a todos los logs y respuestas (header X-Request-ID).
Cliente autenticado: client_id y scopes del token. Nunca loguear tokens completos ni secrets.
Payload sanitizado: Loguear estructura y campos no sensibles. Enmascarar PAN, CVV, API keys.
Resultado y latencia: Status code, tiempo de procesamiento, errores estructurados.
IP y User-Agent: Para forense y detección de anomalías geográficas/comportamentales.

7. Conclusión y Recursos Oficiales

Referencias oficiales:

RFC 6749: OAuth 2.0 Authorization Framework: Especificación oficial.
RFC 7519: JSON Web Token (JWT): Estándar de tokens firmados.
OWASP REST Security Cheat Sheet: Mejores prácticas de seguridad API.
Stripe API Authentication Guide: Referencia de implementación production-grade.

Nota técnica: Este artículo utiliza marcado Schema.org Article coexistente con el nodo FinancialService corporativo. Los metadatos semánticos se indexan automáticamente vía The SEO Framework.

Descargo de responsabilidad: Este artículo es material educativo de ingeniería de software aplicada a APIs financieras. Las implementaciones de seguridad presentadas deben auditarse según el perfil de riesgo específico de cada plataforma. Ninguna API es segura por defecto; la seguridad es un proceso continuo de defensa en profundidad. El uso de este contenido es bajo exclusiva responsabilidad del arquitecto u operador del sistema.

1. Por Qué las APIs Fintech Son Objetivo Prioritario

Las APIs de plataformas financieras B2B concentran el mayor valor por línea de código de cualquier sistema. Un endpoint mal protegido que procesa pagos, transfiere fondos o expone datos de clientes puede generar pérdidas directas en minutos tras ser comprometido. Los atacantes no buscan vulnerabilidades complejas; explotan configuraciones débiles de autenticación, ausencia de rate limiting y validación laxa de inputs.

El estándar de facto para APIs fintech es OAuth2 Client Credentials para comunicación máquina-a-máquina (microservicios, partners B2B) combinado con rate limiting adaptativo y validación estricta de schemas. Esta guía implementa los tres pilares en PHP 8.4 sin frameworks pesados, compatible con Nginx + MariaDB y optimizada para alto rendimiento.

2. OAuth2 Client Credentials: Autenticación M2M

Para APIs consumidas por otros sistemas (no usuarios finales), el flujo Client Credentials es el más seguro y simple. El cliente intercambia credenciales estáticas (client_id + client_secret) por un token JWT efímero. No hay sesiones, no hay redirecciones, no hay cookies.

<?php
declare(strict_types=1);

namespace App\Api\Auth;

use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use RuntimeException;

class OAuth2TokenService 
{
    private string $jwtSecret;
    private int $tokenTtl;

    public function __construct(string $jwtSecret, int $tokenTtl = 3600) 
    {
        if (strlen($jwtSecret) < 32) {
            throw new RuntimeException("JWT secret debe tener mínimo 32 bytes.");
        }
        $this->jwtSecret = $jwtSecret;
        $this->tokenTtl = $tokenTtl;
    }

    /**
     * Genera token JWT para cliente autenticado
     */
    public function issueToken(string $clientId, array $scopes = []): string 
    {
        $now = time();
        
        $payload = [
            'iss' => 'https://clicdinamico.com',
            'sub' => $clientId,
            'aud' => 'https://api.clicdinamico.com',
            'iat' => $now,
            'exp' => $now + $this->tokenTtl,
            'scope' => implode(' ', $scopes),
            'jti' => bin2hex(random_bytes(16)) // Token ID único para revocación
        ];

        return JWT::encode($payload, $this->jwtSecret, 'HS256');
    }

    /**
     * Valida token JWT entrante
     */
    public function validateToken(string $token): ?object 
    {
        try {
            $decoded = JWT::decode($token, new Key($this->jwtSecret, 'HS256'));
            
            // Verificar audience correcto
            if ($decoded->aud !== 'https://api.clicdinamico.com') {
                return null;
            }
            
            return $decoded;
        } catch (\Throwable) {
            return null; // Token inválido, expirado o firma incorrecta
        }
    }
}

Flujo OAuth2	Uso en Fintech	Complejidad	Seguridad
Client Credentials	M2M: microservicios, partners B2B, webhooks	Baja	Alta (sin user context)
Authorization Code + PKCE	Apps móviles/web con usuario final	Media	Muy alta (PKCE previene interceptación)
Implicit	OBSOLETO – No usar en producción	Baja	Baja (tokens en URL)
Resource Owner Password	Legacy – Evitar en nuevas implementaciones	Baja	Media (credenciales en cliente)

3. Rate Limiting Adaptativo: Más Allá del Contador Simple

Rate limiting genérico (ej: 100 req/min para todos) falla en fintech porque trata igual a un partner de alto volumen que a un atacante probando endpoints. El modelo correcto es adaptativo por tier + endpoint crítico:

Tier-based: Partners premium tienen límites superiores a free/trial. Almacenar tier en token JWT claim.
Endpoint-specific: /payments tiene límite más estricto que /catalog. Operaciones financieras sensibles requieren protección reforzada.
Burst allowance: Permitir ráfagas cortas (burst) sobre el límite sostenido para absorber picos legítimos sin bloquear.
Penalty escalation: Si cliente excede límite repetidamente, reducir temporalmente su quota o requerir re-autenticación.

<?php
declare(strict_types=1);

namespace App\Api\Middleware;

use Redis;

class AdaptiveRateLimiter 
{
    private Redis $redis;
    
    // Límites por tier (requests por minuto)
    private const TIER_LIMITS = [
        'free'     => ['default' => 60,  'payments' => 10],
        'basic'    => ['default' => 300, 'payments' => 60],
        'premium'  => ['default' => 1000,'payments' => 200],
        'enterprise'=>['default' => 5000,'payments' => 1000]
    ];

    public function __construct(Redis $redis) 
    {
        $this->redis = $redis;
    }

    /**
     * Verifica rate limit usando algoritmo sliding window
     */
    public function check(string $clientId, string $tier, string $endpoint): array 
    {
        $limit = self::TIER_LIMITS[$tier][$endpoint] 
                 ?? self::TIER_LIMITS[$tier]['default'] 
                 ?? 60;
        
        $windowKey = "ratelimit:{$clientId}:{$endpoint}:" . floor(time() / 60);
        
        // Incrementar contador atómicamente
        $current = $this->redis->incr($windowKey);
        
        // Establecer TTL solo en primera petición de la ventana
        if ($current === 1) {
            $this->redis->expire($windowKey, 120); // 2 min TTL para cleanup
        }

        $remaining = max(0, $limit - $current);
        $resetAt = (floor(time() / 60) + 1) * 60;

        // Headers estándar RFC 6585
        header("X-RateLimit-Limit: {$limit}");
        header("X-RateLimit-Remaining: {$remaining}");
        header("X-RateLimit-Reset: {$resetAt}");

        if ($current > $limit) {
            header("Retry-After: " . ($resetAt - time()));
            return ['allowed' => false, 'reason' => 'rate_limit_exceeded'];
        }

        return ['allowed' => true];
    }
}

4. Validación Estricta de Payloads Financieros

<?php
declare(strict_types=1);

namespace App\Api\Validation;

use InvalidArgumentException;

class PaymentRequestValidator 
{
    /**
     * Valida payload de creación de pago con reglas financieras estrictas
     */
    public static function validate(array $data): array 
    {
        $errors = [];

        // Monto: entero positivo en centavos (evita problemas float)
        if (!isset($data['amount_cents']) || !is_int($data['amount_cents'])) {
            $errors[] = 'amount_cents: requerido, tipo entero';
        } elseif ($data['amount_cents'] <= 0) {
            $errors[] = 'amount_cents: debe ser > 0';
        } elseif ($data['amount_cents'] > 999999999) {
            $errors[] = 'amount_cents: excede máximo permitido (9,999,999.99)';
        }

        // Moneda: ISO 4217 válida
        $validCurrencies = ['USD', 'MXN', 'COP', 'PEN', 'BRL', 'CLP', 'ARS'];
        if (!isset($data['currency']) || !in_array(strtoupper($data['currency']), $validCurrencies, true)) {
            $errors[] = 'currency: debe ser una de ' . implode(', ', $validCurrencies);
        }

        // Merchant ID: formato UUID v4
        if (!isset($data['merchant_id']) || 
            !preg_match('/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i', $data['merchant_id'])) {
            $errors[] = 'merchant_id: formato UUID v4 inválido';
        }

        // Idempotency Key: obligatoria para operaciones financieras
        if (empty($data['idempotency_key']) || strlen($data['idempotency_key']) < 16) {
            $errors[] = 'idempotency_key: requerida, mínimo 16 caracteres';
        }

        if (!empty($errors)) {
            throw new InvalidArgumentException(
                json_encode(['errors' => $errors], JSON_UNESCAPED_SLASHES)
            );
        }

        // Retornar datos normalizados y sanitizados
        return [
            'amount_cents'    => $data['amount_cents'],
            'currency'        => strtoupper($data['currency']),
            'merchant_id'     => strtolower($data['merchant_id']),
            'idempotency_key' => $data['idempotency_key'],
            'metadata'        => $data['metadata'] ?? []
        ];
    }
}

5. Middleware Pipeline: Orquestación Segura

Los componentes de seguridad deben ejecutarse en orden estricto antes de cualquier lógica de negocio. Un middleware pipeline garantiza consistencia y evita omisiones accidentales:

CORS Preflight: Responder OPTIONS inmediatamente sin tocar BD/auth.
Autenticación: Validar token JWT. Rechazar 401 si inválido/expirado.
Autorización: Verificar scopes del token vs endpoint solicitado. Rechazar 403 si insuficientes.
Rate Limiting: Verificar quota adaptativa. Rechazar 429 si excedida.
Validación Input: Parsear y validar payload. Rechazar 400 si inválido.
Idempotencia Check: Verificar si idempotency_key ya fue procesada. Retornar resultado cacheado si sí.
Business Logic: Solo tras pasar todos los filtros anteriores.

6. Logging y Auditoría de API

Toda operación financiera vía API debe ser auditada inmutablemente. Logs deben incluir:

Request ID único: Generar UUID al inicio de cada request. Propagar a todos los logs y respuestas (header X-Request-ID).
Cliente autenticado: client_id y scopes del token. Nunca loguear tokens completos ni secrets.
Payload sanitizado: Loguear estructura y campos no sensibles. Enmascarar PAN, CVV, API keys.
Resultado y latencia: Status code, tiempo de procesamiento, errores estructurados.
IP y User-Agent: Para forense y detección de anomalías geográficas/comportamentales.

7. Conclusión y Recursos Oficiales

Referencias oficiales:

RFC 6749: OAuth 2.0 Authorization Framework: Especificación oficial.
RFC 7519: JSON Web Token (JWT): Estándar de tokens firmados.
OWASP REST Security Cheat Sheet: Mejores prácticas de seguridad API.
Stripe API Authentication Guide: Referencia de implementación production-grade.

Nota técnica: Este artículo utiliza marcado Schema.org Article coexistente con el nodo FinancialService corporativo. Los metadatos semánticos se indexan automáticamente vía The SEO Framework.

Tier-based: Partners premium tienen límites superiores a free/trial. Almacenar tier en token JWT claim.
Endpoint-specific: /payments tiene límite más estricto que /catalog. Operaciones financieras sensibles requieren protección reforzada.
Burst allowance: Permitir ráfagas cortas (burst) sobre el límite sostenido para absorber picos legítimos sin bloquear.
Penalty escalation: Si cliente excede límite repetidamente, reducir temporalmente su quota o requerir re-autenticación.

<?php
declare(strict_types=1);

namespace App\Api\Middleware;

use Redis;

class AdaptiveRateLimiter 
{
    private Redis $redis;
    
    // Límites por tier (requests por minuto)
    private const TIER_LIMITS = [
        'free'     => ['default' => 60,  'payments' => 10],
        'basic'    => ['default' => 300, 'payments' => 60],
        'premium'  => ['default' => 1000,'payments' => 200],
        'enterprise'=>['default' => 5000,'payments' => 1000]
    ];

    public function __construct(Redis $redis) 
    {
        $this->redis = $redis;
    }

    /**
     * Verifica rate limit usando algoritmo sliding window
     */
    public function check(string $clientId, string $tier, string $endpoint): array 
    {
        $limit = self::TIER_LIMITS[$tier][$endpoint] 
                 ?? self::TIER_LIMITS[$tier]['default'] 
                 ?? 60;
        
        $windowKey = "ratelimit:{$clientId}:{$endpoint}:" . floor(time() / 60);
        
        // Incrementar contador atómicamente
        $current = $this->redis->incr($windowKey);
        
        // Establecer TTL solo en primera petición de la ventana
        if ($current === 1) {
            $this->redis->expire($windowKey, 120); // 2 min TTL para cleanup
        }

        $remaining = max(0, $limit - $current);
        $resetAt = (floor(time() / 60) + 1) * 60;

        // Headers estándar RFC 6585
        header("X-RateLimit-Limit: {$limit}");
        header("X-RateLimit-Remaining: {$remaining}");
        header("X-RateLimit-Reset: {$resetAt}");

        if ($current > $limit) {
            header("Retry-After: " . ($resetAt - time()));
            return ['allowed' => false, 'reason' => 'rate_limit_exceeded'];
        }

        return ['allowed' => true];
    }
}

4. Validación Estricta de Payloads Financieros

<?php
declare(strict_types=1);

namespace App\Api\Validation;

use InvalidArgumentException;

class PaymentRequestValidator 
{
    /**
     * Valida payload de creación de pago con reglas financieras estrictas
     */
    public static function validate(array $data): array 
    {
        $errors = [];

        // Monto: entero positivo en centavos (evita problemas float)
        if (!isset($data['amount_cents']) || !is_int($data['amount_cents'])) {
            $errors[] = 'amount_cents: requerido, tipo entero';
        } elseif ($data['amount_cents'] <= 0) {
            $errors[] = 'amount_cents: debe ser > 0';
        } elseif ($data['amount_cents'] > 999999999) {
            $errors[] = 'amount_cents: excede máximo permitido (9,999,999.99)';
        }

        // Moneda: ISO 4217 válida
        $validCurrencies = ['USD', 'MXN', 'COP', 'PEN', 'BRL', 'CLP', 'ARS'];
        if (!isset($data['currency']) || !in_array(strtoupper($data['currency']), $validCurrencies, true)) {
            $errors[] = 'currency: debe ser una de ' . implode(', ', $validCurrencies);
        }

        // Merchant ID: formato UUID v4
        if (!isset($data['merchant_id']) || 
            !preg_match('/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i', $data['merchant_id'])) {
            $errors[] = 'merchant_id: formato UUID v4 inválido';
        }

        // Idempotency Key: obligatoria para operaciones financieras
        if (empty($data['idempotency_key']) || strlen($data['idempotency_key']) < 16) {
            $errors[] = 'idempotency_key: requerida, mínimo 16 caracteres';
        }

        if (!empty($errors)) {
            throw new InvalidArgumentException(
                json_encode(['errors' => $errors], JSON_UNESCAPED_SLASHES)
            );
        }

        // Retornar datos normalizados y sanitizados
        return [
            'amount_cents'    => $data['amount_cents'],
            'currency'        => strtoupper($data['currency']),
            'merchant_id'     => strtolower($data['merchant_id']),
            'idempotency_key' => $data['idempotency_key'],
            'metadata'        => $data['metadata'] ?? []
        ];
    }
}

5. Middleware Pipeline: Orquestación Segura

Los componentes de seguridad deben ejecutarse en orden estricto antes de cualquier lógica de negocio. Un middleware pipeline garantiza consistencia y evita omisiones accidentales:

CORS Preflight: Responder OPTIONS inmediatamente sin tocar BD/auth.
Autenticación: Validar token JWT. Rechazar 401 si inválido/expirado.
Autorización: Verificar scopes del token vs endpoint solicitado. Rechazar 403 si insuficientes.
Rate Limiting: Verificar quota adaptativa. Rechazar 429 si excedida.
Validación Input: Parsear y validar payload. Rechazar 400 si inválido.
Idempotencia Check: Verificar si idempotency_key ya fue procesada. Retornar resultado cacheado si sí.
Business Logic: Solo tras pasar todos los filtros anteriores.

6. Logging y Auditoría de API

Toda operación financiera vía API debe ser auditada inmutablemente. Logs deben incluir:

Request ID único: Generar UUID al inicio de cada request. Propagar a todos los logs y respuestas (header X-Request-ID).
Cliente autenticado: client_id y scopes del token. Nunca loguear tokens completos ni secrets.
Payload sanitizado: Loguear estructura y campos no sensibles. Enmascarar PAN, CVV, API keys.
Resultado y latencia: Status code, tiempo de procesamiento, errores estructurados.
IP y User-Agent: Para forense y detección de anomalías geográficas/comportamentales.

7. Conclusión y Recursos Oficiales

Referencias oficiales:

RFC 6749: OAuth 2.0 Authorization Framework: Especificación oficial.
RFC 7519: JSON Web Token (JWT): Estándar de tokens firmados.
OWASP REST Security Cheat Sheet: Mejores prácticas de seguridad API.
Stripe API Authentication Guide: Referencia de implementación production-grade.

Nota técnica: Este artículo utiliza marcado Schema.org Article coexistente con el nodo FinancialService corporativo. Los metadatos semánticos se indexan automáticamente vía The SEO Framework.

1. Por Qué las APIs Fintech Son Objetivo Prioritario

2. OAuth2 Client Credentials: Autenticación M2M

<?php
declare(strict_types=1);

namespace App\Api\Auth;

use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use RuntimeException;

class OAuth2TokenService 
{
    private string $jwtSecret;
    private int $tokenTtl;

    public function __construct(string $jwtSecret, int $tokenTtl = 3600) 
    {
        if (strlen($jwtSecret) < 32) {
            throw new RuntimeException("JWT secret debe tener mínimo 32 bytes.");
        }
        $this->jwtSecret = $jwtSecret;
        $this->tokenTtl = $tokenTtl;
    }

    /**
     * Genera token JWT para cliente autenticado
     */
    public function issueToken(string $clientId, array $scopes = []): string 
    {
        $now = time();
        
        $payload = [
            'iss' => 'https://clicdinamico.com',
            'sub' => $clientId,
            'aud' => 'https://api.clicdinamico.com',
            'iat' => $now,
            'exp' => $now + $this->tokenTtl,
            'scope' => implode(' ', $scopes),
            'jti' => bin2hex(random_bytes(16)) // Token ID único para revocación
        ];

        return JWT::encode($payload, $this->jwtSecret, 'HS256');
    }

    /**
     * Valida token JWT entrante
     */
    public function validateToken(string $token): ?object 
    {
        try {
            $decoded = JWT::decode($token, new Key($this->jwtSecret, 'HS256'));
            
            // Verificar audience correcto
            if ($decoded->aud !== 'https://api.clicdinamico.com') {
                return null;
            }
            
            return $decoded;
        } catch (\Throwable) {
            return null; // Token inválido, expirado o firma incorrecta
        }
    }
}

Flujo OAuth2	Uso en Fintech	Complejidad	Seguridad
Client Credentials	M2M: microservicios, partners B2B, webhooks	Baja	Alta (sin user context)
Authorization Code + PKCE	Apps móviles/web con usuario final	Media	Muy alta (PKCE previene interceptación)
Implicit	OBSOLETO – No usar en producción	Baja	Baja (tokens en URL)
Resource Owner Password	Legacy – Evitar en nuevas implementaciones	Baja	Media (credenciales en cliente)

3. Rate Limiting Adaptativo: Más Allá del Contador Simple

Tier-based: Partners premium tienen límites superiores a free/trial. Almacenar tier en token JWT claim.
Endpoint-specific: /payments tiene límite más estricto que /catalog. Operaciones financieras sensibles requieren protección reforzada.
Burst allowance: Permitir ráfagas cortas (burst) sobre el límite sostenido para absorber picos legítimos sin bloquear.
Penalty escalation: Si cliente excede límite repetidamente, reducir temporalmente su quota o requerir re-autenticación.

<?php
declare(strict_types=1);

namespace App\Api\Middleware;

use Redis;

class AdaptiveRateLimiter 
{
    private Redis $redis;
    
    // Límites por tier (requests por minuto)
    private const TIER_LIMITS = [
        'free'     => ['default' => 60,  'payments' => 10],
        'basic'    => ['default' => 300, 'payments' => 60],
        'premium'  => ['default' => 1000,'payments' => 200],
        'enterprise'=>['default' => 5000,'payments' => 1000]
    ];

    public function __construct(Redis $redis) 
    {
        $this->redis = $redis;
    }

    /**
     * Verifica rate limit usando algoritmo sliding window
     */
    public function check(string $clientId, string $tier, string $endpoint): array 
    {
        $limit = self::TIER_LIMITS[$tier][$endpoint] 
                 ?? self::TIER_LIMITS[$tier]['default'] 
                 ?? 60;
        
        $windowKey = "ratelimit:{$clientId}:{$endpoint}:" . floor(time() / 60);
        
        // Incrementar contador atómicamente
        $current = $this->redis->incr($windowKey);
        
        // Establecer TTL solo en primera petición de la ventana
        if ($current === 1) {
            $this->redis->expire($windowKey, 120); // 2 min TTL para cleanup
        }

        $remaining = max(0, $limit - $current);
        $resetAt = (floor(time() / 60) + 1) * 60;

        // Headers estándar RFC 6585
        header("X-RateLimit-Limit: {$limit}");
        header("X-RateLimit-Remaining: {$remaining}");
        header("X-RateLimit-Reset: {$resetAt}");

        if ($current > $limit) {
            header("Retry-After: " . ($resetAt - time()));
            return ['allowed' => false, 'reason' => 'rate_limit_exceeded'];
        }

        return ['allowed' => true];
    }
}

4. Validación Estricta de Payloads Financieros

<?php
declare(strict_types=1);

namespace App\Api\Validation;

use InvalidArgumentException;

class PaymentRequestValidator 
{
    /**
     * Valida payload de creación de pago con reglas financieras estrictas
     */
    public static function validate(array $data): array 
    {
        $errors = [];

        // Monto: entero positivo en centavos (evita problemas float)
        if (!isset($data['amount_cents']) || !is_int($data['amount_cents'])) {
            $errors[] = 'amount_cents: requerido, tipo entero';
        } elseif ($data['amount_cents'] <= 0) {
            $errors[] = 'amount_cents: debe ser > 0';
        } elseif ($data['amount_cents'] > 999999999) {
            $errors[] = 'amount_cents: excede máximo permitido (9,999,999.99)';
        }

        // Moneda: ISO 4217 válida
        $validCurrencies = ['USD', 'MXN', 'COP', 'PEN', 'BRL', 'CLP', 'ARS'];
        if (!isset($data['currency']) || !in_array(strtoupper($data['currency']), $validCurrencies, true)) {
            $errors[] = 'currency: debe ser una de ' . implode(', ', $validCurrencies);
        }

        // Merchant ID: formato UUID v4
        if (!isset($data['merchant_id']) || 
            !preg_match('/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i', $data['merchant_id'])) {
            $errors[] = 'merchant_id: formato UUID v4 inválido';
        }

        // Idempotency Key: obligatoria para operaciones financieras
        if (empty($data['idempotency_key']) || strlen($data['idempotency_key']) < 16) {
            $errors[] = 'idempotency_key: requerida, mínimo 16 caracteres';
        }

        if (!empty($errors)) {
            throw new InvalidArgumentException(
                json_encode(['errors' => $errors], JSON_UNESCAPED_SLASHES)
            );
        }

        // Retornar datos normalizados y sanitizados
        return [
            'amount_cents'    => $data['amount_cents'],
            'currency'        => strtoupper($data['currency']),
            'merchant_id'     => strtolower($data['merchant_id']),
            'idempotency_key' => $data['idempotency_key'],
            'metadata'        => $data['metadata'] ?? []
        ];
    }
}

5. Middleware Pipeline: Orquestación Segura

Los componentes de seguridad deben ejecutarse en orden estricto antes de cualquier lógica de negocio. Un middleware pipeline garantiza consistencia y evita omisiones accidentales:

CORS Preflight: Responder OPTIONS inmediatamente sin tocar BD/auth.
Autenticación: Validar token JWT. Rechazar 401 si inválido/expirado.
Autorización: Verificar scopes del token vs endpoint solicitado. Rechazar 403 si insuficientes.
Rate Limiting: Verificar quota adaptativa. Rechazar 429 si excedida.
Validación Input: Parsear y validar payload. Rechazar 400 si inválido.
Idempotencia Check: Verificar si idempotency_key ya fue procesada. Retornar resultado cacheado si sí.
Business Logic: Solo tras pasar todos los filtros anteriores.

6. Logging y Auditoría de API

Toda operación financiera vía API debe ser auditada inmutablemente. Logs deben incluir:

Request ID único: Generar UUID al inicio de cada request. Propagar a todos los logs y respuestas (header X-Request-ID).
Cliente autenticado: client_id y scopes del token. Nunca loguear tokens completos ni secrets.
Payload sanitizado: Loguear estructura y campos no sensibles. Enmascarar PAN, CVV, API keys.
Resultado y latencia: Status code, tiempo de procesamiento, errores estructurados.
IP y User-Agent: Para forense y detección de anomalías geográficas/comportamentales.

7. Conclusión y Recursos Oficiales

Referencias oficiales:

RFC 6749: OAuth 2.0 Authorization Framework: Especificación oficial.
RFC 7519: JSON Web Token (JWT): Estándar de tokens firmados.
OWASP REST Security Cheat Sheet: Mejores prácticas de seguridad API.
Stripe API Authentication Guide: Referencia de implementación production-grade.

Nota técnica: Este artículo utiliza marcado Schema.org Article coexistente con el nodo FinancialService corporativo. Los metadatos semánticos se indexan automáticamente vía The SEO Framework.

6. Logging y Auditoría de API

7. Conclusión y Recursos Oficiales

4. Validación Estricta de Payloads Financieros

5. Middleware Pipeline: Orquestación Segura

6. Logging y Auditoría de API

7. Conclusión y Recursos Oficiales

1. Por Qué las APIs Fintech Son Objetivo Prioritario

2. OAuth2 Client Credentials: Autenticación M2M

3. Rate Limiting Adaptativo: Más Allá del Contador Simple

4. Validación Estricta de Payloads Financieros

5. Middleware Pipeline: Orquestación Segura

6. Logging y Auditoría de API

7. Conclusión y Recursos Oficiales

4. Validación Estricta de Payloads Financieros

5. Middleware Pipeline: Orquestación Segura

6. Logging y Auditoría de API

7. Conclusión y Recursos Oficiales

1. Por Qué las APIs Fintech Son Objetivo Prioritario

2. OAuth2 Client Credentials: Autenticación M2M

3. Rate Limiting Adaptativo: Más Allá del Contador Simple

4. Validación Estricta de Payloads Financieros

5. Middleware Pipeline: Orquestación Segura

6. Logging y Auditoría de API

7. Conclusión y Recursos Oficiales

Deja un comentario Cancelar la respuesta