Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Introducción

La detección de fraude en tiempo real es crítica para prevenir pérdidas financieras, proteger a tus clientes y mantener la confianza en tu plataforma. gu1 te permite implementar múltiples capas de protección que analizan cada transacción en milisegundos.

​
Tipos de Fraude Detectables

Fraude de Tarjetas

Tarjetas robadas, clonadas o comprometidas

Account Takeover

Cuentas comprometidas por atacantes

Fraude Amistoso

Chargebacks fraudulentos de clientes

Testing de Tarjetas

Validación masiva de números de tarjeta

​
Indicadores de Fraude

​
🔴 Señales de Alto Riesgo (Bloqueo Inmediato - SYNC)

  1. Primera transacción con monto muy alto
    • Nueva tarjeta + monto >$500
    • Nuevo usuario + monto >$1000
    • Sin historial + compra de alto valor
  2. Cambios repentinos de comportamiento
    • Cambio de país en menos de 1 hora
    • Nuevo dispositivo + transacción inmediata
    • Cambio de método de pago + monto alto
  3. Patrones de testing
    • Múltiples transacciones fallidas seguidas
    • Montos pequeños repetidos (1−1-5)
    • Diferentes tarjetas desde mismo dispositivo
  4. Ubicación sospechosa
    • IP de Tor, VPN o proxy
    • País de alto riesgo
    • Mismatch entre país de tarjeta y ubicación

​
🟡 Señales de Riesgo Medio (Revisión - SYNC)

  1. Velocidad inusual
    • Múltiples transacciones en minutos
    • Frecuencia superior al patrón histórico
  2. Montos atípicos
    • Significativamente mayor al promedio del usuario
    • Justo debajo de límites de alerta
  3. Horarios inusuales
    • Transacciones fuera del horario habitual
    • Actividad nocturna sin precedentes

​
🟢 Señales de Monitoreo (Alertas - ASYNC)

  1. Patrones emergentes
    • Incremento gradual de montos
    • Cambio de productos comprados
    • Nueva preferencia de merchants
  2. Comportamiento de dispositivo
    • Nuevo dispositivo pero comportamiento normal
    • Cambio de ubicación con explicación válida

​
Reglas de Ejemplo

​
1. Bloqueo de Testing de Tarjetas

Detecta intentos de validar múltiples tarjetas robadas. 
{
  "name": "Card Testing Detection - BLOCK",
  "category": "fraud",
  "priority": 950,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "operator": "OR",
        "conditions": [
          {
            "field": "metadata.failedTransactionsLast10m",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": 3
          },
          {
            "field": "metadata.differentCardsLast10m",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": 3
          }
        ]
      },
      {
        "field": "amountInUsd",
        "operator": "LESS_THAN",
        "value": 10
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "critical",
        "type": "card_testing",
        "message": "Card testing pattern detected: Multiple cards or failures with small amounts"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "REJECT",
        "reason": "Card testing pattern detected"
      }
    },
    {
      "type": "create_investigation",
      "config": {
        "priority": "critical",
        "assignToTeam": "fraud_team",
        "autoAssign": true
      }
    }
  ]
}

​
2. Nueva Tarjeta con Monto Alto

Requiere verificación adicional para la primera compra costosa. 
{
  "name": "First Transaction High Amount",
  "category": "fraud",
  "priority": 850,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.isFirstTransactionWithCard",
        "operator": "EQUALS",
        "value": true
      },
      {
        "field": "amountInUsd",
        "operator": "GREATER_THAN",
        "value": 500
      },
      {
        "field": "origin.paymentMethod",
        "operator": "IN",
        "value": ["CREDIT_CARD", "DEBIT_CARD", "PREPAID_CARD"]
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "type": "first_transaction_high_amount",
        "message": "First transaction with new card exceeds $500"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "ADDITIONAL_AUTH_REQUIRED",
        "reason": "First high-value transaction requires additional verification"
      }
    }
  ]
}

​
3. Cambio Imposible de Ubicación

Detecta transacciones desde ubicaciones imposibles de alcanzar en el tiempo transcurrido. 
{
  "name": "Impossible Travel Detection",
  "category": "fraud",
  "priority": 900,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.lastTransactionCountry",
        "operator": "IS_NOT_NULL",
        "value": null
      },
      {
        "field": "metadata.lastTransactionCountry",
        "operator": "NOT_EQUALS",
        "value": "{{deviceData.location.country}}"
      },
      {
        "field": "metadata.timeSinceLastTransaction",
        "operator": "LESS_THAN",
        "value": 3600
      },
      {
        "field": "metadata.distanceFromLastTransaction",
        "operator": "GREATER_THAN",
        "value": 1000
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "critical",
        "type": "impossible_travel",
        "message": "Transaction from impossible location: {{metadata.distanceFromLastTransaction}}km in {{metadata.timeSinceLastTransaction}}s"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "HOLD",
        "reason": "Geographic impossibility detected - manual review required"
      }
    }
  ]
}

​
4. Velocidad Sospechosa

Detecta ráfagas de transacciones en tiempo corto. 
{
  "name": "Transaction Velocity - High Risk",
  "category": "fraud",
  "priority": 800,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "metadata.transactionsLast5m",
        "operator": "GREATER_THAN_OR_EQUAL",
        "value": 5
      },
      {
        "field": "metadata.transactionsLast1h",
        "operator": "GREATER_THAN_OR_EQUAL",
        "value": 15
      },
      {
        "operator": "AND",
        "conditions": [
          {
            "field": "metadata.transactionsLast10m",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": 3
          },
          {
            "field": "amountInUsd",
            "operator": "GREATER_THAN",
            "value": 1000
          }
        ]
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "type": "velocity_fraud",
        "message": "Unusual transaction velocity detected"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "REVIEW_REQUIRED",
        "reason": "Transaction velocity exceeds normal patterns"
      }
    }
  ]
}

​
5. IP de Alto Riesgo

Bloquea transacciones desde IPs conocidas por fraude. 
{
  "name": "High-Risk IP Block",
  "category": "fraud",
  "priority": 920,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "metadata.ipReputationScore",
        "operator": "LESS_THAN",
        "value": 20
      },
      {
        "field": "metadata.isProxyOrVPN",
        "operator": "EQUALS",
        "value": true
      },
      {
        "field": "metadata.isTorExit",
        "operator": "EQUALS",
        "value": true
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "type": "suspicious_ip",
        "message": "Transaction from high-risk IP address"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "REJECT",
        "reason": "Transaction from suspicious IP address"
      }
    }
  ]
}

​
6. Patrón de Fraude Amistoso

Detecta usuarios con historial de chargebacks. 
{
  "name": "Friendly Fraud Pattern",
  "category": "fraud",
  "priority": 700,
  "enabled": true,
  "evaluationMode": "async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "metadata.chargebackCount",
        "operator": "GREATER_THAN_OR_EQUAL",
        "value": 2
      },
      {
        "operator": "AND",
        "conditions": [
          {
            "field": "metadata.refundCount",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": 5
          },
          {
            "field": "metadata.refundRate",
            "operator": "GREATER_THAN",
            "value": 0.5
          }
        ]
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "medium",
        "type": "friendly_fraud_risk",
        "message": "Customer has history of chargebacks/refunds"
      }
    }
  ]
}

​
Estrategias de Implementación

​
Enfoque por Capas

Implementa múltiples capas de protección, de menos a más restrictivo:

​
Configuración Recomendada

​
Para E-commerce

{
  "layerConfig": {
    "layer1_block": {
      "rules": [
        "Card Testing Detection",
        "Impossible Travel",
        "High-Risk IP Block"
      ],
      "action": "REJECT",
      "priority": "900-999"
    },
    "layer2_verify": {
      "rules": [
        "First Transaction High Amount",
        "Transaction Velocity",
        "New Device High Amount"
      ],
      "action": "ADDITIONAL_AUTH_REQUIRED",
      "priority": "800-899"
    },
    "layer3_review": {
      "rules": [
        "Unusual Time Pattern",
        "Chargeback History"
      ],
      "action": "REVIEW_REQUIRED",
      "priority": "700-799"
    },
    "layer4_monitor": {
      "rules": [
        "Behavior Change Pattern",
        "Friendly Fraud Pattern"
      ],
      "evaluationMode": "async",
      "priority": "500-699"
    }
  }
}

​
Para Fintech/Transferencias

{
  "layerConfig": {
    "layer1_block": {
      "rules": [
        "Account Takeover Detection",
        "Impossible Travel",
        "Sanctioned Country Block"
      ],
      "action": "REJECT",
      "priority": "900-999"
    },
    "layer2_mfa": {
      "rules": [
        "High Amount Transfer",
        "New Beneficiary High Amount",
        "Unusual Destination"
      ],
      "action": "ADDITIONAL_AUTH_REQUIRED",
      "priority": "850-899"
    },
    "layer3_cooling": {
      "rules": [
        "First Transfer New Account",
        "Velocity Check"
      ],
      "action": "HOLD",
      "delay": "24h",
      "priority": "800-849"
    }
  }
}

​
Métricas y Optimización

​
KPIs Clave

  1. False Positive Rate
    • Meta: < 5%
    • Transacciones legítimas bloqueadas
  2. False Negative Rate
    • Meta: < 1%
    • Fraudes que pasaron sin detección
  3. Detection Rate
    • Meta: > 95%
    • % de fraude detectado
  4. Response Time
    • Meta: < 300ms para reglas SYNC
    • Tiempo de evaluación

​
Monitoreo Continuo

-- Query para analizar efectividad de reglas
SELECT
  rule_name,
  COUNT(*) as triggers,
  SUM(CASE WHEN confirmed_fraud THEN 1 ELSE 0 END) as true_positives,
  SUM(CASE WHEN NOT confirmed_fraud THEN 1 ELSE 0 END) as false_positives,
  ROUND(100.0 * SUM(CASE WHEN confirmed_fraud THEN 1 ELSE 0 END) / COUNT(*), 2) as precision_rate
FROM alerts
WHERE created_at > NOW() - INTERVAL '30 days'
GROUP BY rule_name
ORDER BY triggers DESC;

​
Best Practices

​
✅ Recomendaciones

  1. Empieza Conservador
    • Comienza con umbrales altos
    • Ajusta según datos reales
    • No bloquees todo desde el inicio
  2. Prueba Antes de Producción
    • Usa modo ASYNC para nuevas reglas
    • Monitorea 1-2 semanas
    • Revisa falsos positivos
  3. Combina Señales
    • Una señal sola puede ser normal
    • Múltiples señales = alto riesgo
    • Usa operador AND para combinaciones
  4. Aprende del Feedback
    • Revisa transacciones marcadas incorrectamente
    • Ajusta umbrales según feedback
    • Documenta casos especiales
  5. Balance Seguridad vs UX
    • No frustres usuarios legítimos
    • Ofrece alternativas (MFA, verificación)
    • Explica por qué se requiere verificación

​
❌ Errores Comunes

  1. Demasiado Restrictivo
    • Bloquear todo genera fricción
    • Pierdes clientes legítimos
  2. Ignorar el Contexto
    • Usuario VIP vs nuevo usuario
    • Temporada alta vs normal
    • Horarios especiales
  3. Reglas Estáticas
    • Los fraudes evolucionan
    • Actualiza reglas regularmente
    • Usa ML cuando sea posible

​
Integración con el Dashboard

Todas las alertas generadas aparecen automáticamente en el Intelligence Dashboard:
  1. Alertas Individuales se crean por cada regla matched
  2. Motor de Consolidación agrupa alertas relacionadas
  3. Investigación Automática se crea para casos de alta severidad
  4. Workflow de Revisión permite marcar como falso positivo o confirmado

​
Próximos Pasos

Monitoreo AML

Reglas para cumplimiento regulatorio y anti-lavado de dinero

Merchant Monitoring

Supervisa merchants para adquirentes y subadquirentes

API Reference

Documentación completa del endpoint /transaction/analyze

Configurar Reglas

Guía completa para crear y optimizar reglas