Monitoramento transacional

Monitoramento transacional

O módulo transacao_monitor faz uma varredura retrospectiva sobre as transações que você já nos mandou pela rota de ingestão, procurando padrões que uma transação sozinha não revela. Ele roda no nosso relógio, sobre uma janela fechada, e ninguém fica esperando por ele: quando um padrão fecha, você recebe um alerta no mesmo webhook assinado de sempre, com a janela e a evidência em número.

Disponível desde 11 de setembro de 2026. Ele aparece na tabela de preços e no GET /v1/capabilities com preço e status available, e pode ser ligado num flow. Até essa data as duas travas eram comerciais, não técnicas: a unidade de cobrança e o número. As duas foram decididas, e a unidade é o alerta emitido, não a assinatura mensal. O alerta nunca reprova ninguém: o pior desfecho é revisão humana.

O campo pattern diz qual padrão fechou, e o seu código pode receber estes valores: structuring, payee_concentration_growth, device_farm, post_approval_blocklist, dormant_reactivation, velocity_escalation e unverified_volume. Receptores devem tolerar valor novo.

A severidade tem dois valores, e só dois: high e medium. Não existe low, e a ausência é decisão de produto: alerta que não muda o comportamento de ninguém é ruído cobrado.

// transacao_monitor no check_details: um alerta de fracionamento
{ "module": "transacao_monitor", "passed": null, "outcome": "pending", "score": 60,
  "data": {
    "transaction_monitor": {
      "pattern": "structuring",
      "severity": "high",
      "window": { "from": "2026-08-01T00:00:00Z", "to": "2026-08-08T00:00:00Z" },
      "evidence": { "tx_count": 7, "sum_cents": 6900000, "max_single_cents": 990000 }
    }
  } }

Repare em passed e outcome: eles são sempre esses. passed é null e outcome é "pending" nas duas severidades, sempre. A severidade viaja em data.transaction_monitor.severity e nunca em passed. Quem programar lendo passed === false como "reprovado" nunca vai entrar nesse ramo, e é exatamente essa a intenção: um passed: false aqui faria a verificação sair denied no webhook assinado, e um cliente que automatizou "denied = bloquear conta" bloquearia o titular sozinho. Leia o pattern e a severity, e trate o resto como evidência.

O campo evidence muda de chaves conforme o pattern, e ele só carrega número: contagem, soma em centavos e intervalo em dias. Nunca documento, nome, e-mail, chave Pix em claro nem endereço IP. O sujeito do alerta, que chega em reference_id, depende do pattern: pode ser o titular, a conta de destino ou o aparelho que o padrão observou.

O que este módulo não faz. Ele não bloqueia nada, como acabou de ser dito, e essa é a primeira. Ele não consulta o DICT, o MED, bureau nem dado de consórcio entre instituições: o universo da varredura é só o que você nos mandou, sob o seu próprio tenant, e nunca o histórico de outro cliente. E ele não é o Gate transacional, que é a seção logo acima.

A varredura é grátis: você paga pelo alerta emitido. Uma janela em que nenhum padrão fecha não gera verificação, não gera check e não custa nada, e por isso não existe um estado "limpo" neste payload: ele só nasce quando um padrão fecha. Alerta suprimido por repetição não é cobrado.

A conta fica no painel. Em Monitoramento você vê, no período que escolher, quantos alertas por 1.000 eventos recebidos o módulo produziu, quantos foram entregues e quantos ficaram retidos sem cobrança, com o motivo de cada retenção em palavras.

Alerta de severidade alta nunca é retido. Nem por volume, nem por falta de saldo: ele é entregue sempre, e quando sai acima do volume contratado ou sem saldo chega sem cobrança, com billing.waived dizendo o porquê: above_volume ou no_credit. Alerta cobrado normalmente não traz o bloco billing.

// data do alerta high entregue sem cobrança
{ "object": "verification", "billing": { "waived": "above_volume" },
  "check_details": [ { "module": "transacao_monitor", "passed": null, "outcome": "pending" } ] }