Antifraude & Fluxo de Aprovação

As transações financeiras (transferências PIX, pagamento de contas, transferências externas) passam por uma camada de avaliação antifraude antes da execução.

Fluxo

Requisição do cliente
     │
     ▼
┌─────────────────┐
│  Rate Limiter   │ ── 429 Too Many Requests
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Tenant Billing  │ ── 402 Suspenso (ACCOUNT_SUSPENDED)
└────────┬────────┘    402 Restrito (ACCOUNT_RESTRICTED)
         │
         ▼
┌─────────────────┐
│   Antifraude    │ ── 503 Service Unavailable
└────────┬────────┘    (SECURITY_SERVICE_UNAVAILABLE, fail-safe)
         │
    ┌────┼────┐
    ▼    ▼    ▼
   200   202   403
    OK  Pendente  Bloqueado

Códigos de resposta

200 OK — Transação aprovada

A transação foi aprovada e executada com sucesso.

202 Accepted — Aprovação pendente

A transação foi sinalizada e exige aprovação manual. O corpo da resposta é:

{
  "error": "TRANSACTION_PENDING_APPROVAL",
  "status": "PENDING_USER",
  "antifraudId": "af_9f8e7d6c",
  "pendingExpiresAt": 1710786400000
}

O valor de status (uma string começando com PENDING) indica quem deve aprovar. A aprovação é concluída pela rota de aprovação correspondente:

Tipo de aprovação	Rota de aprovação	Descrição
USER	GET /v1/antifraud/approval/user	O titular da conta deve aprovar
ADMIN	GET /v1/antifraud/approval/admin	O admin do tenant deve aprovar
COMPLIANCE	GET /v1/antifraud/approval/compliance	O responsável de compliance deve aprovar

403 Forbidden — Transação bloqueada

A transação foi bloqueada pelas regras de segurança.

{
  "error": "TRANSACTION_BLOCKED",
  "message": "Transação bloqueada pelo sistema de segurança. Entre em contato com o suporte.",
  "antifraudId": "af_9f8e7d6c"
}

402 Payment Required — Conta suspensa / restrita

Retornado pelo gate de billing do tenant quando a conta do cliente está inadimplente. O error é ACCOUNT_SUSPENDED (ou ACCOUNT_RESTRICTED), acompanhado do campo billingStatus.

503 Service Unavailable — Serviço de segurança indisponível

Retornado quando o próprio serviço de antifraude está inacessível e a política de fail-safe está ativa (ANTIFRAUD_FAIL_SAFE não definido como false). Body: {"error":"SECURITY_SERVICE_UNAVAILABLE", ...}. Tente novamente após um curto intervalo.

Idempotência

Em todas as operações financeiras, envie o header Idempotency-Key com um UUID para evitar transações duplicadas:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

• Se uma requisição com a mesma chave já tiver sido processada, a resposta original é retornada
• As chaves são válidas por 24 horas
• Gere sempre um novo UUID para cada intenção de transação distinta

---