API Reference - Monitoramento de Transações

• PAYMENT - Compra ou pagamento a comerciante
• TRANSFER - Transferência entre contas/usuários
• WITHDRAWAL - Saque ou débito de conta
• DEPOSIT - Depósito ou crédito de conta
• REFUND - Reembolso de transação anterior
• CHARGEBACK - Disputa de estorno
• REVERSAL - Reversão de transação
• FEE - Cobrança de taxa ou comissão
• ADJUSTMENT - Ajuste de saldo
• OTHER - Outro tipo de transação

• CREATED - Transação criada (padrão)
• PROCESSING - Transação em processamento
• SUSPENDED - Transação temporariamente suspensa

• SENT - Transação enviada/transmitida
• EXPIRED - Transação expirada
• DECLINED - Transação recusada/declinada
• REFUNDED - Transação reembolsada/revertida
• SUCCESSFUL - Transação concluída com sucesso

• CARD - Pagamento com cartão de crédito ou débito
• ACH - Automated Clearing House (transferência bancária US)
• PIX - Sistema de pagamentos instantâneos do Brasil
• TED - Transferência bancária brasileira (Transferência Eletrônica Disponível)
• BOLETO - Boleto de pagamento brasileiro
• WALLET - Carteira digital (PayPal, Venmo, etc.)
• SWIFT - Transferência internacional SWIFT
• IBAN - Transferência bancária baseada em IBAN
• CBU - Conta bancária argentina (Clave Bancaria Uniforme)
• CVU - Conta virtual argentina (Clave Virtual Uniforme)
• DEBIN - Sistema de débito instantâneo argentino
• GENERIC_BANK_ACCOUNT - Transferência de conta bancária genérica
• MPESA - M-Pesa mobile money (Quênia)
• UPI - Unified Payments Interface (Índia)
• CHECK - Pagamento com cheque
• ECHECK - Cheque eletrônico
• QR_CODE - Pagamento com código QR
• ONLINE_PAYMENT - Pagamento online genérico
• WITHDRAWAL_ORDER - Ordem de saque

• originCountry (campo direto) = País da entidade
• originDetails.country = País do dispositivo/IP no momento da transação (pode diferir se estiver viajando)

• deviceId (string) - Identificador do dispositivo
• deviceFingerprint (string) - Hash de impressão digital do dispositivo
• deviceType (enum) - mobile | desktop | tablet | pos | atm
• userAgent (string) - User agent do navegador
• ipAddress (string) - Endereço IP (formato validado)

• country (string) - Código ISO de 2 letras
• city (string) - Nome da cidade
• region (string) - Estado/província
• latitude (number) - Latitude (-90 a 90)
• longitude (number) - Longitude (-180 a 180)
• timezone (string) - Identificador de fuso horário

• paymentDetails (object) - Informações específicas de pagamento para a origem. Você pode enviar qualquer campo relacionado a pagamento:
  • Detalhes Bancários/Conta:
    • accountNumber (string) - Número da conta
    • accountType (enum) - checking | savings | business | personal
    • bankCode (string) - Código do banco
    • bankName (string) - Nome do banco
    • routingNumber (string) - Routing number (US)
    • swiftCode (string) - Código SWIFT/BIC
    • iban (string) - IBAN (International Bank Account Number)
  • Detalhes PIX (Brasil):
    • pixKey (string) - Chave PIX
    • pixType (enum) - Tipo de chave PIX: email | phone | cpf | cnpj | random
    • endToEndId (string) - ID único end-to-end do PIX
  • Detalhes de Cartão:
    • cardLast4 (string) - Últimos 4 dígitos do cartão
    • cardBrand (string) - Bandeira do cartão (Visa, Mastercard, Amex, etc.)
    • cardholderName (string) - Nome no cartão
    • cardBin (string) - Primeiros 6 dígitos do cartão (BIN)
    • cardType (enum) - credit | debit | prepaid
    • cardCountry (string) - País emissor do cartão (ISO 2 letras)
    • cardExpiry (string) - Data de vencimento (MM/AA)
    • cardFingerprint (string) - Impressão digital única do cartão para rastreamento
  • Detalhes Crypto:
    • walletAddress (string) - Endereço de carteira de criptomoeda
    • walletType (string) - Tipo de carteira (ex: “metamask”, “coinbase”)
    • blockchain (string) - Rede blockchain (ex: “ethereum”, “bitcoin”)
    • tokenSymbol (string) - Símbolo do token (ex: “ETH”, “BTC”, “USDT”)
    • txHash (string) - Hash da transação blockchain
    • confirmations (number) - Número de confirmações blockchain
  • Carteira/Pagamento Digital:
    • walletId (string) - Identificador de carteira digital
    • walletProvider (string) - Provedor de carteira (ex: “paypal”, “venmo”, “mercadopago”)
    • walletEmail (string) - Email associado à carteira
  • Campos Argentina (CBU/CVU):
    • cbu (string) - CBU argentino (22 dígitos)
    • cvu (string) - CVU argentino (22 dígitos)
    • alias (string) - Alias do CBU/CVU
  • Campos México (SPEI):
    • clabe (string) - Número CLABE (México, 18 dígitos)
    • trackingKey (string) - Chave de rastreamento SPEI
  • Campos Dinheiro/Cheque:
    • checkNumber (string) - Número do cheque
    • receiptNumber (string) - Número do recibo
    • location (string) - Localização do pagamento (dinheiro)
  • E quaisquer outros campos relacionados a pagamento que você precisar

• isVpn (boolean) - VPN detectada
• isTor (boolean) - Rede Tor detectada
• isProxy (boolean) - Proxy detectado
• governmentAccount (boolean) - Flag de conta governamental

{
  "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) - Descrição do MCC (ex: “Restaurants”)
• merchantId (string) - Identificador do comerciante
• merchantName (string) - Nome do comerciante
• merchantType (string) - Tipo/categoria do comerciante

• deviceId (string) - Identificador do dispositivo
• deviceType (enum) - pos | online | mobile | atm
• ipAddress (string) - Endereço IP (formato validado)

• country (string) - Código ISO de 2 letras
• city (string) - Nome da cidade
• region (string) - Estado/província

• paymentDetails (object) - Informações específicas de pagamento para o destino. Você pode enviar qualquer campo relacionado a pagamento:
  • Detalhes Bancários/Conta:
    • accountNumber (string) - Número da conta de destino
    • accountType (enum) - checking | savings | business | merchant
    • bankCode (string) - Código do banco
    • bankName (string) - Nome do banco
    • routingNumber (string) - Routing number (US)
    • swiftCode (string) - Código SWIFT/BIC
    • iban (string) - IBAN (International Bank Account Number)
  • Detalhes PIX (Brasil):
    • pixKey (string) - Chave PIX
    • pixType (enum) - Tipo de chave PIX: email | phone | cpf | cnpj | random
    • endToEndId (string) - ID único end-to-end do PIX
  • Detalhes de Cartão:
    • cardLast4 (string) - Últimos 4 dígitos do cartão
    • cardBrand (string) - Bandeira do cartão (Visa, Mastercard, Amex, etc.)
    • cardholderName (string) - Nome no cartão
    • cardBin (string) - Primeiros 6 dígitos do cartão (BIN)
    • cardType (enum) - credit | debit | prepaid
    • cardCountry (string) - País emissor do cartão (ISO 2 letras)
    • cardExpiry (string) - Data de vencimento (MM/AA)
    • cardFingerprint (string) - Impressão digital única do cartão para rastreamento
  • Detalhes Crypto:
    • walletAddress (string) - Endereço de carteira de criptomoeda
    • walletType (string) - Tipo de carteira (ex: “metamask”, “coinbase”)
    • blockchain (string) - Rede blockchain (ex: “ethereum”, “bitcoin”)
    • tokenSymbol (string) - Símbolo do token (ex: “ETH”, “BTC”, “USDT”)
    • txHash (string) - Hash da transação blockchain
    • confirmations (number) - Número de confirmações blockchain
  • Carteira/Pagamento Digital:
    • walletId (string) - Identificador de carteira digital
    • walletProvider (string) - Provedor de carteira (ex: “paypal”, “venmo”, “mercadopago”)
    • walletEmail (string) - Email associado à carteira
  • Campos Argentina (CBU/CVU):
    • cbu (string) - CBU argentino (22 dígitos)
    • cvu (string) - CVU argentino (22 dígitos)
    • alias (string) - Alias do CBU/CVU
  • Campos México (SPEI):
    • clabe (string) - Número CLABE (México, 18 dígitos)
    • trackingKey (string) - Chave de rastreamento SPEI
  • Campos Dinheiro/Cheque:
    • checkNumber (string) - Número do cheque
    • receiptNumber (string) - Número do recibo
    • location (string) - Localização do pagamento (dinheiro)
  • E quaisquer outros campos relacionados a pagamento que você precisar

• cryptoExchange (boolean) - É uma exchange de criptomoedas
• highRisk (boolean) - Flag de comerciante de alto risco
• privateSector (boolean) - Flag de setor privado

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

• mobile_app - Aplicativo móvel
• web_browser - Navegador web
• pos_terminal - Terminal ponto de venda
• api - Integração API direta
• atm - Caixa eletrônico
• phone_banking - Banking telefônico
• branch - Agência física
• call_center - Central de atendimento
• partner_api - Integração com parceiro

{
  "channel": "mobile_app"
}

• WITHOUT_REASON - Sem motivo específico (padrão quando omitido)
• INSUFFICIENT_FUNDS - Fundos 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 (ex: “US”, “BR”, “AR”)
• countryName (string) - Nome completo do país
• city (string) - Nome da cidade
• region (string) - Estado ou província
• address (string) - Endereço completo
• street (string) - Nome da rua
• streetNumber (string) - Número da rua
• postalCode (string) - Código postal/CEP
• neighborhood (string) - Bairro ou distrito

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

• timezone (string) - Fuso horário IANA (ex: “America/Sao_Paulo”)
• placeId (string) - ID do Google Places ou 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"
}

• Detecção de Fraude: Identificar transações de localizações incomuns ou países de alto risco
• Análise Geográfica: Analisar padrões de transações por região
• Conformidade: Rastrear transações transfronteiriças para relatórios regulatórios
• Regras de Velocidade: Detectar viagens impossíveis (mesmo usuário em diferentes localizações em pouco tempo)

• deviceId (string) - Identificador único do dispositivo
• externalId (string) - Seu ID externo do dispositivo

• platform (enum) - Plataforma do dispositivo: android, ios, web, desktop, mobile, tablet, pos, atm
• osName (string) - Nome do sistema operacional (ex: “Android”, “iOS”, “Windows”, “macOS”)
• osVersion (string) - Versão do SO (ex: “13.0”, “16.4”)

• manufacturer (string) - Fabricante do dispositivo (ex: “Samsung”, “Apple”)
• model (string) - Modelo do dispositivo (ex: “Galaxy S22”, “iPhone 14”)
• brand (string) - Marca do dispositivo
• deviceName (string) - Nome atribuído pelo usuário ao dispositivo

• browser (string) - Nome do navegador (ex: “Chrome”, “Safari”, “Firefox”)
• browserVersion (string) - Versão do navegador
• userAgent (string) - String completa do user agent

• isEmulator (boolean) - Se o dispositivo é um emulador
• isRooted (boolean) - Se o dispositivo está com root (Android)
• isJailbroken (boolean) - Se o dispositivo está com jailbreak (iOS)

• ipAddress (string) - Endereço IP (formato validado)
• isVpn (boolean) - Se a conexão é através de VPN
• isTor (boolean) - Se a conexão é através de Tor
• isProxy (boolean) - Se a conexão é através de proxy

• deviceFingerprint (string) - Hash único de impressão digital do dispositivo para rastreamento

• screenResolution (string) - Resolução da tela (ex: “1920x1080”)
• language (string) - Idioma do dispositivo
• timezone (string) - Fuso horário do 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"
}

• Detecção de Fraude: Identificar dispositivos suspeitos (emuladores, dispositivos com root, uso de VPN)
• Fingerprinting de Dispositivo: Rastrear dispositivos únicos através de transações para análise comportamental
• Análise de Segurança: Detectar anomalias em padrões de dispositivos (novo dispositivo, velocidade de dispositivo impossível)
• Conformidade: Documentar informações do dispositivo para rastros de auditoria
• Experiência do Usuário: Personalizar experiência baseada em tipo e capacidades do dispositivo

​

tags (object) - Sistema de Categorização Chave-Valor

• Filtragem personalizada em dashboards e relatórios
• Ativar lógica de negócio específica
• Acompanhamento do status de revisão
• Categorização por nível de risco ou fonte
• Estados de fluxo de trabalho 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 (pendente de revisão), 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 campanha de marketing ou negócio
• approved_by (string) - Usuário ou sistema que aprovou
• requires_approval (boolean) - Requer aprovação 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"
  }
}

​

Outros Campos de Metadata:

• purpose (string) - Propósito da transação (ex: “salary”, “invoice_payment”)
• frequency (string) - Frequência da transação (ex: “monthly”, “one-time”)
• contract_number (string) - Número de contrato (para pagamentos empresariais)
• enhanced_due_diligence (boolean) - Flag de EDD
• block_reason (string) - Razão do bloqueio
• compliance_alert (boolean) - Flag de alerta de compliance

{
  "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
}

• id (string) - UUID interno do gu1
• externalId (string) - Seu ID externo
• type (enum) - Tipo de transação
• status (enum) - Status da transação
• amount (string) - Valor original (string numérica)
• currency (string) - Código de moeda original (ISO 4217)
• amountInUsd (string | null) - Valor convertido em USD
• exchangeRate (string | null) - Taxa de câmbio usada (precisão: 10 decimais)
• rateSource (string | null) - Fonte da taxa de câmbio
• riskScore (string | null) - Pontuação de risco 0-100 (precisão: 2 decimais) se regras foram executadas
• riskFactors (array) - Array de fatores de risco identificados
• flagged (boolean) - Se a transação foi sinalizada para revisão
• reason (string | null) - Motivo opcional do resultado (ex.: WITHOUT_REASON, INSUFFICIENT_FUNDS); padrão WITHOUT_REASON quando omitido

• rulesHit (array) - Regras cujas condições foram atendidas. Cada item: name, description, score, priority, category, status (ex. active, shadow), conditions (array de { field, value, operator? }), actions (alerts, suggestion, status, assignedUser).
• rulesNoHit (array) - Regras avaliadas cujas condições não foram atendidas. Mesma estrutura que rulesHit (inclui ações configuradas, não executadas).
• actionsExecuted (object) - Ações executadas agregadas de todas as regras que deram hit: alerts (array de { name?, type?, severity?, description? }), suggestion (BLOCK | SUSPEND | FLAG, maior peso), status (status da entidade aplicado, se houver), assignedUser ({ userId }, se houver), customKeys (array de strings, opcional) — chaves de ações personalizadas das regras que deram match (ex. require_kyc, flag_for_review). Presente quando alguma regra que deu match tem uma ação personalizada com chave; para integrações/workflows.
• totalScore (number) - Soma do score de todas as regras que deram hit e não estão em status shadow.