API Reference - Monitoreo de Transacciones

• PAYMENT - Compra o pago a comerciante
• TRANSFER - Transferencia entre cuentas/usuarios
• WITHDRAWAL - Retiro de efectivo o débito de cuenta
• DEPOSIT - Depósito o crédito de cuenta
• REFUND - Reembolso de una transacción anterior
• CHARGEBACK - Disputa de contracargo
• REVERSAL - Reversión de transacción
• FEE - Cargo de comisión o tarifa
• ADJUSTMENT - Ajuste de saldo
• OTHER - Otro tipo de transacción

• CREATED - Transacción creada (por defecto)
• PROCESSING - Transacción en proceso
• SUSPENDED - Transacción temporalmente suspendida

• SENT - Transacción enviada/transmitida
• EXPIRED - Transacción expirada
• DECLINED - Transacción rechazada/declinada
• REFUNDED - Transacción reembolsada/reversada
• SUCCESSFUL - Transacción completada exitosamente

• CARD - Pago con tarjeta de crédito o débito
• ACH - Automated Clearing House (transferencia bancaria US)
• PIX - Sistema de pagos instantáneos de Brasil
• TED - Transferencia bancaria brasileña (Transferência Eletrônica Disponível)
• BOLETO - Boleto de pago brasileño
• WALLET - Billetera digital (PayPal, Venmo, etc.)
• SWIFT - Transferencia internacional SWIFT
• IBAN - Transferencia bancaria basada en IBAN
• CBU - Cuenta bancaria argentina (Clave Bancaria Uniforme)
• CVU - Cuenta virtual argentina (Clave Virtual Uniforme)
• DEBIN - Sistema de débito instantáneo argentino
• GENERIC_BANK_ACCOUNT - Transferencia de cuenta bancaria genérica
• MPESA - M-Pesa mobile money (Kenia)
• UPI - Unified Payments Interface (India)
• CHECK - Pago con cheque
• ECHECK - Cheque electrónico
• QR_CODE - Pago con código QR
• ONLINE_PAYMENT - Pago online genérico
• WITHDRAWAL_ORDER - Orden de retiro

• originCountry (campo directo) = País de la entidad
• originDetails.country = País del dispositivo/IP al momento de la transacción (puede diferir si está viajando)

• deviceId (string) - Identificador del dispositivo
• deviceFingerprint (string) - Hash de huella digital del dispositivo
• deviceType (enum) - mobile | desktop | tablet | pos | atm
• userAgent (string) - User agent del navegador
• ipAddress (string) - Dirección IP (formato validado)

• country (string) - Código ISO de 2 letras
• city (string) - Nombre de la ciudad
• region (string) - Estado/provincia
• latitude (number) - Latitud (-90 a 90)
• longitude (number) - Longitud (-180 a 180)
• timezone (string) - Identificador de zona horaria

• paymentDetails (object) - Información específica de pago para el origen. Puede enviar cualquier campo relacionado con el pago:
  • Detalles Bancarios/Cuenta:
    • accountNumber (string) - Número de cuenta
    • accountType (enum) - checking | savings | business | personal
    • bankCode (string) - Código del banco
    • bankName (string) - Nombre del banco
    • routingNumber (string) - Routing number (US)
    • swiftCode (string) - Código SWIFT/BIC
    • iban (string) - IBAN (International Bank Account Number)
  • Detalles PIX (Brasil):
    • pixKey (string) - Clave PIX
    • pixType (enum) - Tipo de clave PIX: email | phone | cpf | cnpj | random
  • Detalles de Tarjeta:
    • cardLast4 (string) - Últimos 4 dígitos de la tarjeta
    • cardBrand (string) - Marca de tarjeta (Visa, Mastercard, Amex, etc.)
    • cardholderName (string) - Nombre en la tarjeta
    • cardBin (string) - Primeros 6 dígitos de la tarjeta (BIN)
    • cardType (enum) - credit | debit | prepaid
    • cardCountry (string) - País emisor de la tarjeta (ISO 2 letras)
    • cardExpiry (string) - Fecha de vencimiento (MM/YY)
    • cardFingerprint (string) - Huella digital única de la tarjeta para seguimiento
  • Detalles Crypto:
    • walletAddress (string) - Dirección de wallet de criptomoneda
    • walletType (string) - Tipo de wallet (ej: “metamask”, “coinbase”)
    • blockchain (string) - Red blockchain (ej: “ethereum”, “bitcoin”)
    • tokenSymbol (string) - Símbolo del token (ej: “ETH”, “BTC”, “USDT”)
  • Wallet/Pago Digital:
    • walletId (string) - Identificador de wallet digital
    • walletProvider (string) - Proveedor de wallet (ej: “paypal”, “venmo”, “cashapp”)
    • walletEmail (string) - Email asociado con el wallet
  • Y cualquier otro campo relacionado con el pago que necesite

• isVpn (boolean) - VPN detectado
• isTor (boolean) - Red Tor detectada
• isProxy (boolean) - Proxy detectado
• governmentAccount (boolean) - Bandera de cuenta gubernamental

{
  "deviceType": "mobile",
  "ipAddress": "189.123.45.67",
  "country": "BR",
  "city": "São Paulo",
  "isVpn": false,
  "paymentDetails": {
    "accountNumber": "12345",
    "accountType": "personal",
    "bankName": "Banco do Brasil",
    "pixKey": "user@email.com",
    "pixType": "email"
  }
}

• mcc (string) - Merchant Category Code (4 dígitos, ISO 18245)
• mccDescription (string) - Descripción del MCC (ej: “Restaurants”)
• merchantId (string) - Identificador del comerciante
• merchantName (string) - Nombre del comerciante
• merchantType (string) - Tipo/categoría del comerciante

• deviceId (string) - Identificador del dispositivo
• deviceType (enum) - pos | online | mobile | atm
• ipAddress (string) - Dirección IP (formato validado)

• country (string) - Código ISO de 2 letras
• city (string) - Nombre de la ciudad
• region (string) - Estado/provincia

• paymentDetails (object) - Información específica de pago para el destino. Puede enviar cualquier campo relacionado con el pago:
  • Detalles Bancarios/Cuenta:
    • accountNumber (string) - Número de cuenta destino
    • accountType (enum) - checking | savings | business | merchant
    • bankCode (string) - Código del banco
    • bankName (string) - Nombre del banco
    • routingNumber (string) - Routing number (US)
    • swiftCode (string) - Código SWIFT/BIC
    • iban (string) - IBAN (International Bank Account Number)
  • Detalles PIX (Brasil):
    • pixKey (string) - Clave PIX
    • pixType (enum) - Tipo de clave PIX: email | phone | cpf | cnpj | random
  • Detalles de Tarjeta:
    • cardLast4 (string) - Últimos 4 dígitos de la tarjeta
    • cardBrand (string) - Marca de tarjeta (Visa, Mastercard, Amex, etc.)
    • cardholderName (string) - Nombre en la tarjeta
    • cardBin (string) - Primeros 6 dígitos de la tarjeta (BIN)
    • cardType (enum) - credit | debit | prepaid
    • cardCountry (string) - País emisor de la tarjeta (ISO 2 letras)
    • cardExpiry (string) - Fecha de vencimiento (MM/YY)
    • cardFingerprint (string) - Huella digital única de la tarjeta para seguimiento
  • Detalles Crypto:
    • walletAddress (string) - Dirección de wallet de criptomoneda
    • walletType (string) - Tipo de wallet (ej: “metamask”, “coinbase”)
    • blockchain (string) - Red blockchain (ej: “ethereum”, “bitcoin”)
    • tokenSymbol (string) - Símbolo del token (ej: “ETH”, “BTC”, “USDT”)
  • Wallet/Pago Digital:
    • walletId (string) - Identificador de wallet digital
    • walletProvider (string) - Proveedor de wallet (ej: “paypal”, “venmo”, “cashapp”)
    • walletEmail (string) - Email asociado con el wallet
  • Y cualquier otro campo relacionado con el pago que necesite

• cryptoExchange (boolean) - Es exchange de criptomonedas
• highRisk (boolean) - Bandera de comerciante de alto riesgo
• privateSector (boolean) - Bandera de sector privado

{
  "mcc": "5812",
  "mccDescription": "Restaurants",
  "merchantName": "Restaurant ABC",
  "country": "US",
  "highRisk": false,
  "paymentDetails": {
    "accountNumber": "98765",
    "accountType": "merchant",
    "bankName": "Bradesco"
  }
}

• mobile_app - Aplicación móvil
• web_browser - Navegador web
• pos_terminal - Terminal punto de venta
• api - Integración API directa
• atm - Cajero automático
• phone_banking - Banca telefónica
• branch - Sucursal física
• call_center - Centro de llamadas
• partner_api - Integración con partner

{
  "channel": "mobile_app"
}

• WITHOUT_REASON - Sin razón específica (por defecto si se omite)
• INSUFFICIENT_FUNDS - Fondos insuficientes
• LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDED, MONTHLY_LIMIT_EXCEEDED, TRANSACTION_LIMIT_EXCEEDED
• ACCOUNT_BLOCKED, ACCOUNT_FROZEN, ACCOUNT_CLOSED
• CARD_EXPIRED, CARD_BLOCKED, CARD_LOST_OR_STOLEN, INVALID_CARD, INVALID_ACCOUNT
• FRAUD_SUSPECTED, COMPLIANCE_BLOCK, SANCTIONS_MATCH, AML_ALERT, RISK_SCORE_THRESHOLD
• MERCHANT_BLOCKED, COUNTRY_RESTRICTION, CURRENCY_NOT_SUPPORTED, CHANNEL_NOT_ALLOWED
• SYSTEM_ERROR, TIMEOUT, INVALID_AMOUNT, KYC_PENDING, KYC_REJECTED
• EXPIRED, CANCELLED_BY_USER, CANCELLED_BY_MERCHANT, REFUSED_BY_ISSUER, DO_NOT_HONOR
• INVALID_PIN, PIN_TRIES_EXCEEDED, INSUFFICIENT_LIQUIDITY, VALIDATION_FAILED, OTHER

{
  "reason": "INSUFFICIENT_FUNDS"
}

• country (string) - Código de país ISO 3166-1 alpha-2 (ej: “US”, “BR”, “AR”)
• countryName (string) - Nombre completo del país
• city (string) - Nombre de la ciudad
• region (string) - Estado o provincia
• address (string) - Dirección completa
• street (string) - Nombre de la calle
• streetNumber (string) - Número de calle
• postalCode (string) - Código postal
• neighborhood (string) - Barrio o distrito

• latitude (number) - Coordenada de latitud (-90 a 90)
• longitude (number) - Coordenada de longitud (-180 a 180)

• timezone (string) - Zona horaria IANA (ej: “America/Sao_Paulo”)
• placeId (string) - ID de Google Places o identificador similar

{
  "country": "BR",
  "countryName": "Brasil",
  "city": "São Paulo",
  "region": "SP",
  "address": "Av. Paulista, 1578",
  "street": "Av. Paulista",
  "streetNumber": "1578",
  "postalCode": "01310-200",
  "latitude": -23.5505,
  "longitude": -46.6333,
  "timezone": "America/Sao_Paulo"
}

• Detección de Fraude: Identificar transacciones desde ubicaciones inusuales o países de alto riesgo
• Análisis Geográfico: Analizar patrones de transacciones por región
• Cumplimiento: Rastrear transacciones transfronterizas para reportes regulatorios
• Reglas de Velocidad: Detectar viajes imposibles (mismo usuario en diferentes ubicaciones en poco tiempo)

• deviceId (string) - Identificador único del dispositivo
• externalId (string) - Su ID externo del dispositivo

• platform (enum) - Plataforma del dispositivo: android, ios, web, desktop, mobile, tablet, pos, atm
• osName (string) - Nombre del sistema operativo (ej: “Android”, “iOS”, “Windows”, “macOS”)
• osVersion (string) - Versión del SO (ej: “13.0”, “16.4”)

• manufacturer (string) - Fabricante del dispositivo (ej: “Samsung”, “Apple”)
• model (string) - Modelo del dispositivo (ej: “Galaxy S22”, “iPhone 14”)
• brand (string) - Marca del dispositivo
• deviceName (string) - Nombre asignado por el usuario al dispositivo

• browser (string) - Nombre del navegador (ej: “Chrome”, “Safari”, “Firefox”)
• browserVersion (string) - Versión del navegador
• userAgent (string) - String completo del user agent

• isEmulator (boolean) - Si el dispositivo es un emulador
• isRooted (boolean) - Si el dispositivo está rooteado (Android)
• isJailbroken (boolean) - Si el dispositivo está jailbreakeado (iOS)

• ipAddress (string) - Dirección IP (formato validado)
• isVpn (boolean) - Si la conexión es a través de VPN
• isTor (boolean) - Si la conexión es a través de Tor
• isProxy (boolean) - Si la conexión es a través de proxy

• deviceFingerprint (string) - Hash único de huella digital del dispositivo para rastreo

• screenResolution (string) - Resolución de pantalla (ej: “1920x1080”)
• language (string) - Idioma del dispositivo
• timezone (string) - Zona horaria del dispositivo

{
  "platform": "mobile",
  "osName": "Android",
  "osVersion": "13",
  "manufacturer": "Samsung",
  "model": "Galaxy S22",
  "brand": "Samsung",
  "ipAddress": "192.168.1.1",
  "isVpn": false,
  "isTor": false,
  "isEmulator": false,
  "isRooted": false,
  "deviceFingerprint": "abc123def456...",
  "screenResolution": "1080x2400",
  "language": "pt-BR",
  "timezone": "America/Sao_Paulo"
}

• Detección de Fraude: Identificar dispositivos sospechosos (emuladores, dispositivos rooteados, uso de VPN)
• Fingerprinting de Dispositivo: Rastrear dispositivos únicos a través de transacciones para análisis de comportamiento
• Análisis de Seguridad: Detectar anomalías en patrones de dispositivos (nuevo dispositivo, velocidad de dispositivo imposible)
• Cumplimiento: Documentar información del dispositivo para rastros de auditoría
• Experiencia de Usuario: Personalizar experiencia basada en tipo y capacidades del dispositivo

​

tags (object) - Sistema de Categorización Clave-Valor

• Filtrado personalizado en dashboards y reportes
• Activar lógica de negocio específica
• Seguimiento del estado de revisión
• Categorización por nivel de riesgo o fuente
• Estados de flujo de trabajo personalizados

• risk_level (string) - “low”, “medium”, “high”, “critical”
• source (string) - “api”, “web”, “mobile”, “batch”, “import”
• channel (string) - “online”, “branch”, “atm”, “call_center”, “partner”
• reviewed (boolean) - false (pendiente de revisión), true (revisado)
• category (string) - “payroll”, “supplier”, “refund”, “investment”, “loan”, “bill_payment”
• priority (string) - “low”, “normal”, “high”, “urgent”
• team (string) - “compliance”, “fraud”, “support”, “operations”
• campaign (string) - Identificador de campaña de marketing o negocio
• approved_by (string) - Usuario o sistema que aprobó
• requires_approval (boolean) - Requiere aprobación manual
• customer_segment (string) - “vip”, “regular”, “new”, “dormant”
• product_type (string) - “savings”, “investment”, “loan”, “transfer”
• region (string) - “north”, “south”, “latam”, “emea”, “apac”
• business_unit (string) - “retail”, “corporate”, “wealth”, “sme”

{
  "tags": {
    "risk_level": "high",
    "reviewed": false,
    "requires_approval": true,
    "assigned_to": "fraud_team"
  }
}

{
  "tags": {
    "category": "payroll",
    "batch_id": "PAY_2025_01",
    "department": "engineering",
    "cost_center": "R&D"
  }
}

{
  "tags": {
    "source": "mobile_app",
    "channel": "online",
    "campaign": "winter_2025",
    "referral_code": "FRIEND123",
    "first_transaction": true,
    "customer_segment": "new"
  }
}

{
  "tags": {
    "channel": "branch",
    "business_unit": "retail",
    "product_type": "loan",
    "region": "latam",
    "requires_approval": true,
    "approved_by": "manager_john"
  }
}

​

Otros Campos de Metadata:

• purpose (string) - Propósito de la transacción (ej: “salary”, “invoice_payment”)
• frequency (string) - Frecuencia de la transacción (ej: “monthly”, “one-time”)
• contract_number (string) - Número de contrato (para pagos empresariales)
• enhanced_due_diligence (boolean) - Bandera de EDD
• block_reason (string) - Razón de bloqueo
• compliance_alert (boolean) - Bandera de alerta de cumplimiento

{
  "tags": {
    "risk_level": "medium",
    "source": "api",
    "reviewed": false,
    "category": "invoice_payment"
  },
  "purpose": "supplier_payment",
  "frequency": "monthly",
  "contract_number": "CNT-2025-001",
  "enhanced_due_diligence": false
}

• rulesHit (array) - Reglas cuyas condiciones se cumplieron. Cada ítem: name, description, score, priority, category, status (ej. active, shadow), conditions (array de { field, value, operator? }), actions (alerts, suggestion, status, assignedUser).
• rulesNoHit (array) - Reglas evaluadas cuyas condiciones no se cumplieron. Misma estructura que rulesHit (incluye acciones configuradas, no ejecutadas).
• actionsExecuted (object) - Acciones ejecutadas agregadas de todas las reglas que hicieron hit: alerts (array de { name?, type?, severity?, description? }), suggestion (BLOCK | SUSPEND | FLAG, la de mayor peso), status (estado de entidad aplicado, si hubo), assignedUser ({ userId }, si hubo), customKeys (array de strings, opcional) — claves de acciones personalizadas de las reglas que hicieron match (ej. require_kyc, flag_for_review). Presente cuando alguna regla que hizo match tiene una acción personalizada con clave; para integraciones/workflows.
• totalScore (number) - Suma del score de todas las reglas que hicieron hit y no están en estado shadow.