Políticas e Regras

O sistema de políticas permite configurar regras de segurança, limites e restrições para operações PIX. As regras são avaliadas automaticamente em cada transação e podem bloquear, estornar ou notificar sobre violações.

Hierarquia de Configuração

As políticas seguem uma hierarquia de três níveis:

Default (base) -> Tenant (sobrescreve default) -> Account (sobrescreve tenant)

Cada nível pode definir regras específicas. Valores não definidos em um nível são herdados do nível anterior. Isso permite ter regras globais no nível default e ajustes por tenant ou conta.

Regras de PIX Out (Transferências de Saída)

As regras são avaliadas na ordem abaixo. A primeira violação encontrada interrompe a avaliação.

Ordem	Regra	Descrição	Ação
1	Kill Switch	Desabilita todas as transferências de saída	REJECT
2	Horário de Operação	Restringe operações a uma janela de horário	REJECT
3	Whitelist	Se o destinatário está na whitelist, permite e pula todas as regras abaixo	ALLOW
4	Blacklist	Bloqueia se o destinatário está na blacklist	REJECT
5	Mesma Titularidade	Permite apenas transferências para o mesmo CPF/CNPJ	REJECT
6	Limite por Transação	Valor máximo por transferência	REJECT
7	Limite Noturno	Valor máximo reduzido entre 20:00 e 06:00 (BRT)	REJECT
8	Tipo de Pessoa	Restringe por tipo de destinatário (PF/PJ)	REJECT
9	Aprovação	Acima de um valor, requer aprovação manual	HOLD_FOR_APPROVAL

Regras de PIX In (Transferências Recebidas)

Para transferências recebidas, todas as violações usam a mesma ação configurável (violationAction).

Ordem	Regra	Descrição
1	Whitelist	Se o pagador está na whitelist, permite e pula todas as regras abaixo
2	Blacklist (Documento)	Bloqueia se o pagador está na blacklist de CPF/CNPJ
3	Blacklist (Banco)	Bloqueia se o banco de origem está na blacklist
4	Mesma Titularidade	Aceita apenas PIX do mesmo CPF/CNPJ
5	Limite de Valor	Valor máximo por transação recebida
6	Tipo de Pessoa	Restringe por tipo de pagador (PF/PJ)
7	Bancos Permitidos	Aceita apenas PIX de bancos específicos

Ações de Violação (PIX In)

Quando uma regra de PIX In é violada, a ação configurada é aplicada:

Ação	Descrição
ALLOW_AND_NOTIFY	Permite a transação mas registra a violação (padrão)
AUTO_REFUND	Estorna automaticamente o valor ao pagador
QUARANTINE	Coloca a transação em quarentena por N dias
BLOCK	Bloqueia o saldo correspondente à transação

Regras de QR Code

Regra	Descrição
QR Dinâmico	Habilita/desabilita criação de QR codes dinâmicos
QR Estático	Habilita/desabilita criação de QR codes estáticos
Valor Máximo	Limite de valor por QR code
Valor Mínimo	Valor mínimo por QR code

Regras de Chaves PIX

Regra	Descrição
Criação	Habilita/desabilita criação de chaves PIX
Máximo de Chaves	Número máximo de chaves por conta

Regras de Estorno (Refund)

Regra	Descrição
Habilitado	Habilita/desabilita estornos
Valor Máximo	Limite de valor por estorno

Regras de MED (Disputas)

Regra	Descrição
Auto-block	Bloqueia automaticamente o saldo para MEDs acima de um valor
Taxa Máxima	Limite para a proporção MED/PIX-In
Ação	O que fazer quando a taxa é excedida: NOTIFY, BLOCK PIX IN, BLOCK PIX OUT, BLOCK ALL

Horário de Operação

Restringe todas as operações a uma janela de horário. Suporta janelas que cruzam a meia-noite (ex: 22:00-06:00).

Campo	Descrição	Exemplo
start	Hora de início	06:00
end	Hora de fim	22:00
timezone	Fuso horário	America/Sao_Paulo

Princípio da Whitelist

Em ambos PIX Out e PIX In, a whitelist é avaliada primeiro. Se o documento (CPF/CNPJ) do pagador/destinatário estiver na whitelist, todas as outras regras são ignoradas e a transação é permitida.

Isso permite criar exceções para parceiros de confiança que não devem ser afetados por limites, blacklists ou outras restrições.

Visibilidade de Violações

Todas as violações de política são registradas na transação e visíveis:

• No extrato (GET /v1/accounts/{accountId}/statement), nos campos policyViolations e violationAction
• Via webhook policy.violation (quando configurado)
• No painel de administração (Backoffice)

Consulte o guia de Disputas (MED) para detalhes sobre as regras específicas de MED.