Configuración de Reglas

Tipos de Reglas

El sistema de monitoreo transaccional soporta dos tipos de reglas que se comportan de manera diferente:

🔴 Reglas Síncronas (SYNC)

Las reglas síncronas se ejecutan en tiempo real durante el análisis de la transacción y afectan directamente la decisión final. Características:

Se ejecutan antes de retornar la respuesta al cliente
Pueden cambiar el estado de la transacción (APPROVE → REJECT)
Bloquean el flujo hasta completar la evaluación
Tiempo de ejecución incluido en los ~500ms de respuesta
Ideales para decisiones críticas inmediatas

Cuándo usar SYNC:

Bloquear transacciones de alto riesgo
Validar límites operacionales
Prevenir fraude en tiempo real
Cumplimiento regulatorio crítico
Autenticación adicional requerida

🟢 Reglas Asíncronas (ASYNC)

Las reglas asíncronas se ejecutan en paralelo sin afectar el tiempo de respuesta ni la decisión de la transacción. Características:

Se ejecutan después de retornar la respuesta
No afectan la decisión de la transacción
No bloquean el flujo de pago
Generan alertas para revisión posterior
Aparecen solo en el tablero de Intelligence

Cuándo usar ASYNC:

Monitoreo de patrones a largo plazo
Análisis de comportamiento acumulativo
Alertas informativas
Auditoría y reportes
Detección de fraude no urgente

Estructura de una Regla

{
  "name": "High Amount Transaction Check",
  "description": "Blocks transactions above $10,000",
  "category": "risk",
  "priority": 100,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amount",
        "operator": "GREATER_THAN",
        "value": 10000
      },
      {
        "field": "currency",
        "operator": "EQUALS",
        "value": "USD"
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "message": "Transaction exceeds $10,000 limit"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "HOLD"
      }
    }
  ]
}

Campos de Configuración

Campos Básicos

name

string

required

Nombre descriptivo de la regla (máx. 255 caracteres)

description

string

Descripción detallada del propósito de la regla

Condiciones

Las condiciones determinan cuándo se activa la regla. Soportan operadores lógicos anidados.

conditions.operator

enum

required

Operador lógico:

AND - Todas las condiciones deben cumplirse
OR - Al menos una condición debe cumplirse

conditions.conditions

array

required

Array de condiciones individuales o grupos anidados

Operadores de Comparación

EQUALS - Igualdad exacta
NOT_EQUALS - Diferente de
GREATER_THAN - Mayor que
GREATER_THAN_OR_EQUAL - Mayor o igual que
LESS_THAN - Menor que
LESS_THAN_OR_EQUAL - Menor o igual que
CONTAINS - Contiene (para strings y arrays)
NOT_CONTAINS - No contiene
IN - Está en lista
NOT_IN - No está en lista
MATCHES_REGEX - Coincide con expresión regular
IS_NULL - Es nulo
IS_NOT_NULL - No es nulo

Campos Disponibles para Transacciones

// Campos principales
"amount"                    // Monto
"currency"                  // Moneda
"amountBaseCurrency"        // Monto convertido a moneda base
"type"                      // Tipo de transacción
"timestamp"                 // Fecha/hora

// Entidades
"originEntityId"            // ID entidad origen
"destinationEntityId"       // ID entidad destino

// Métodos de pago
"origin.paymentMethod"      // Método de pago origen
"origin.accountType"        // Tipo de cuenta origen
"origin.cardLast4"          // Últimos 4 dígitos tarjeta
"origin.cardBrand"          // Marca de tarjeta
"destination.paymentMethod" // Método de pago destino

// Datos de dispositivo
"deviceData.ipAddress"      // IP
"deviceData.country"        // País del dispositivo
"deviceData.city"           // Ciudad
"deviceData.platform"       // Plataforma (web/ios/android)

// Otros
"mccCode"                   // Código MCC
"tags"                      // Tags personalizados
"metadata.*"                // Cualquier campo en metadata

Acciones

Las acciones se ejecutan cuando las condiciones se cumplen.

generate_alert

Genera una alerta en el sistema.

{
  "type": "generate_alert",
  "config": {
    "severity": "high",
    "type": "high_amount",
    "message": "Transaction amount exceeds threshold"
  }
}

Severidades disponibles:

info - Informativa
low - Baja
medium - Media
high - Alta
critical - Crítica

set_decision

Cambia la decisión de la transacción (solo SYNC).

{
  "type": "set_decision",
  "config": {
    "decision": "REJECT",
    "reason": "High risk transaction"
  }
}

Decisiones disponibles:

APPROVE - Aprobar
REJECT - Rechazar
HOLD - En espera
REVIEW_REQUIRED - Requiere revisión
ADDITIONAL_AUTH_REQUIRED - Requiere autenticación adicional

create_investigation

Crea una investigación inmediata (disponible en SYNC y ASYNC).

{
  "type": "create_investigation",
  "config": {
    "priority": "high",
    "assignToTeam": "fraud_team"
  }
}

Ejemplos de Reglas

1. Límite de Monto Diario (SYNC)

Rechaza transacciones que excedan $10,000 USD.

{
  "name": "Daily Limit - $10K",
  "category": "operational",
  "priority": 800,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amountBaseCurrency",
        "operator": "GREATER_THAN",
        "value": 10000
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "type": "amount_limit_exceeded",
        "message": "Transaction exceeds daily limit of $10,000"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "REJECT",
        "reason": "Amount exceeds daily limit"
      }
    }
  ]
}

2. Velocidad de Transacciones (ASYNC)

Alerta cuando un usuario hace más de 5 transacciones en 10 minutos.

{
  "name": "Transaction Velocity Alert",
  "category": "fraud",
  "priority": 500,
  "enabled": true,
  "evaluationMode": "async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.transactionCount10m",
        "operator": "GREATER_THAN",
        "value": 5
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "medium",
        "type": "velocity_pattern",
        "message": "Unusual transaction velocity detected"
      }
    }
  ]
}

3. País de Alto Riesgo (SYNC)

Bloquea transacciones desde países de alto riesgo.

{
  "name": "High-Risk Country Block",
  "category": "compliance",
  "priority": 900,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "deviceData.location.country",
        "operator": "IN",
        "value": ["KP", "IR", "SY", "CU"]
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "critical",
        "type": "sanctioned_country",
        "message": "Transaction originated from sanctioned country"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "REJECT",
        "reason": "Transaction from restricted country"
      }
    }
  ]
}

4. Patrón de Estructuración AML (ASYNC)

Detecta posible estructuración (múltiples transacciones justo debajo del límite de reporte).

{
  "name": "Structuring Pattern Detection",
  "category": "aml",
  "priority": 700,
  "enabled": true,
  "evaluationMode": "async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amountBaseCurrency",
        "operator": "GREATER_THAN",
        "value": 9000
      },
      {
        "field": "amountBaseCurrency",
        "operator": "LESS_THAN",
        "value": 10000
      },
      {
        "field": "metadata.transactionsLast24h",
        "operator": "GREATER_THAN",
        "value": 3
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "type": "possible_structuring",
        "message": "Possible structuring: Multiple transactions near reporting threshold"
      }
    },
    {
      "type": "create_investigation",
      "config": {
        "priority": "high",
        "assignToTeam": "aml_team"
      }
    }
  ]
}

5. Nueva Tarjeta con Monto Alto (SYNC)

Requiere autenticación adicional para tarjetas nuevas con montos altos.

{
  "name": "New Card High Amount",
  "category": "fraud",
  "priority": 850,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.isFirstTransactionWithCard",
        "operator": "EQUALS",
        "value": true
      },
      {
        "field": "amountBaseCurrency",
        "operator": "GREATER_THAN",
        "value": 500
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "medium",
        "type": "new_card_high_amount",
        "message": "First transaction with new card exceeds $500"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "ADDITIONAL_AUTH_REQUIRED",
        "reason": "Additional verification required for new card"
      }
    }
  ]
}

6. Horario Inusual (ASYNC)

Monitorea transacciones fuera del horario habitual del usuario.

{
  "name": "Unusual Time Pattern",
  "category": "fraud",
  "priority": 400,
  "enabled": true,
  "evaluationMode": "async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "metadata.hourOfDay",
        "operator": "LESS_THAN",
        "value": 6
      },
      {
        "field": "metadata.hourOfDay",
        "operator": "GREATER_THAN",
        "value": 23
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "low",
        "type": "unusual_time",
        "message": "Transaction outside of normal hours"
      }
    }
  ]
}

Condiciones Avanzadas

Condiciones Anidadas

Puedes anidar múltiples niveles de AND/OR:

{
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amountBaseCurrency",
        "operator": "GREATER_THAN",
        "value": 1000
      },
      {
        "operator": "OR",
        "conditions": [
          {
            "field": "origin.paymentMethod",
            "operator": "EQUALS",
            "value": "CREDIT_CARD"
          },
          {
            "field": "origin.paymentMethod",
            "operator": "EQUALS",
            "value": "DEBIT_CARD"
          }
        ]
      },
      {
        "operator": "NOT",
        "condition": {
          "field": "deviceData.location.country",
          "operator": "EQUALS",
          "value": "US"
        }
      }
    ]
  }
}

Expresiones Regulares

Útil para patrones de texto complejos:

{
  "field": "metadata.customerEmail",
  "operator": "MATCHES_REGEX",
  "value": "^[a-zA-Z0-9._%+-]+@tempmail\\.(com|net|org)$"
}

Agregaciones Temporales

Usa metadata para agregar datos históricos:

{
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.totalAmountLast24h",
        "operator": "GREATER_THAN",
        "value": 50000
      },
      {
        "field": "metadata.transactionCountLast24h",
        "operator": "GREATER_THAN",
        "value": 10
      }
    ]
  }
}

Best Practices

✅ DO

Usa SYNC solo cuando sea necesario
- Cada regla SYNC añade latencia
- Reserva para decisiones críticas
Prioriza correctamente
- Reglas de bloqueo primero (alta prioridad)
- Reglas informativas al final (baja prioridad)
Agrupa condiciones eficientemente
- Condiciones más restrictivas primero
- Usa AND para requisitos estrictos
Documenta tus reglas
- Descripción clara del propósito
- Razón de negocio para la regla
Monitorea el rendimiento
- Revisa tiempos de ejecución
- Optimiza reglas lentas

❌ DON’T

No uses SYNC para análisis histórico
- Usa ASYNC para patrones a largo plazo
No crees reglas demasiado amplias
- Genera falsos positivos
- Frustra a usuarios legítimos
No ignores la prioridad
- Puede causar decisiones inconsistentes
No uses demasiadas reglas SYNC
- Impacta el rendimiento
- Consolida reglas similares

Testing de Reglas

Antes de activar una regla en producción:

Test en ambiente de desarrollo
- Valida la lógica con transacciones de prueba
Modo dry-run
- Configura la regla como ASYNC temporalmente
- Monitorea cuántas alertas genera
A/B Testing
- Activa para un % de tráfico primero
- Mide impacto en conversión
Monitoreo continuo
- Revisa falsos positivos/negativos
- Ajusta umbrales según necesidad

Comenzando

Referencia API

Ingesta de Datos

Entidades

Documentos

Conozca Su Negocio (KYB)

Conozca Su Cliente (KYC)

Monitoreo de Transacciones

Tutoriales Interactivos

​Tipos de Reglas

​🔴 Reglas Síncronas (SYNC)

​🟢 Reglas Asíncronas (ASYNC)

​Estructura de una Regla

​Campos de Configuración

​Campos Básicos

​Condiciones

​Operadores de Comparación

​Campos Disponibles para Transacciones

​Acciones

​generate_alert

​set_decision

​create_investigation

​Ejemplos de Reglas

​1. Límite de Monto Diario (SYNC)

​2. Velocidad de Transacciones (ASYNC)

​3. País de Alto Riesgo (SYNC)

​4. Patrón de Estructuración AML (ASYNC)

​5. Nueva Tarjeta con Monto Alto (SYNC)

​6. Horario Inusual (ASYNC)

​Condiciones Avanzadas

​Condiciones Anidadas

​Expresiones Regulares

​Agregaciones Temporales

​Best Practices

​✅ DO

​❌ DON’T

​Testing de Reglas

​Próximos Pasos

Casos de Uso: Fraude

Casos de Uso: AML

Tipos de Reglas

🔴 Reglas Síncronas (SYNC)

🟢 Reglas Asíncronas (ASYNC)

Estructura de una Regla

Campos de Configuración

Campos Básicos

Condiciones

Operadores de Comparación

Campos Disponibles para Transacciones

Acciones

generate_alert

set_decision

create_investigation

Ejemplos de Reglas

1. Límite de Monto Diario (SYNC)

2. Velocidad de Transacciones (ASYNC)

3. País de Alto Riesgo (SYNC)

4. Patrón de Estructuración AML (ASYNC)

5. Nueva Tarjeta con Monto Alto (SYNC)

6. Horario Inusual (ASYNC)

Condiciones Avanzadas

Condiciones Anidadas

Expresiones Regulares

Agregaciones Temporales

Best Practices

✅ DO

❌ DON’T

Testing de Reglas

Próximos Pasos