Skip to navigation

Políticas e Regras

As políticas permitem configurar regras preventivas para operações PIX. Elas são configuradas no painel (Backoffice) e avaliadas automaticamente pela API. Tudo que a tela oferece é avaliado em runtime: PIX Out, PIX In, QR Code, chaves, estorno, horário de operação e limites de DICT.

Hierarquia de Configuração

As políticas têm dois níveis:

Tenant (base) -> Account (sobrescreve o tenant)

A resolução é por seção: se a conta define pixOut, a seção pixOut da conta é usada inteira, e a do tenant é ignorada. Seções não definidas na conta são herdadas do tenant. Uma seção que não existe em nenhum dos dois níveis simplesmente não é avaliada — não há um nível “default” por trás com valores implícitos.

A única exceção são os limites de DICT, que têm defaults globais da plataforma quando a policy não os define — ver Limites de DICT Lookup.

Regras de PIX Out

As regras são avaliadas nesta ordem:

OrdemRegraruleDescrição
1Kill SwitchpixOutDisabledenabled: false recusa toda saída. É absoluto — vence inclusive a whitelist
2Whitelist—Documento do destinatário na whitelist: permite e pula todas as regras abaixo
3BlacklistcpfCnpjBlacklistRecusa se o documento do destinatário está na blacklist
4Mesma TitularidadesameOwnershipOnlyPermite apenas transferências para o CPF/CNPJ do titular da conta
5Horário de OperaçãooperatingHoursRecusa fora da janela configurada
6Tipo de PessoaallowedPersonTypesRestringe o destinatário a PF ou PJ (pelo tamanho do documento)

Ao contrário da whitelist, que curto-circuita, as demais regras são todas avaliadas: uma transação pode violar mais de uma, e o violations da resposta traz todas.

Duas fases de avaliação

O documento do destinatário nem sempre existe no momento do POST:

  • No POST (borda): kill switch e horário. As regras de documento também, quando o modo é BANK_ACCOUNT, o único que traz documentNumber no corpo.
  • Depois de resolver o destinatário: nos modos KEY e QRCODE, o documento só aparece quando a chave é consultada no DICT ou o BR Code é decodificado. As regras de documento são avaliadas nesse ponto, antes de o pagamento ser submetido ao parceiro.

Teto por valor de PIX out não é regra de policy. O disponível e o pedido de aumento estão no guia de limites. pixOut.maxAmount e pixOut.nightMaxAmount deixam de ser avaliados (o JSON antigo é ignorado). A recusa por valor é 422 limit_exceeded_transaction, e o disponível vem de GET /v1/accounts/{accountId}/limits/available.

Na prática isso significa que uma violação de blacklist no modo chave não devolve 422 na resposta do POST: o pagamento é aceito, o paymentId é criado, e o desfecho é FAILED com errorCode: policy_denied. O webhook policy.violation e o pix.out.failed avisam do resultado.

Resposta a uma violação (fase de POST)

HTTP/1.1 422 Unprocessable Entity
{
"errorCode": "policy_denied",
"message": "recipient document is blacklisted",
"violations": [
{ "rule": "cpfCnpjBlacklist", "message": "recipient document is blacklisted" }
]
}

Não é 403 (que significa falta de permissão) nem 400 (o payload é válido): a requisição está correta e foi recusada por uma regra que o próprio tenant configurou.

Modo monitor (NOTIFY_ONLY)

O campo violationAction da seção pixOut define o que fazer com as violações:

ValorEfeito
BLOCK (padrão)Recusa o pagamento
NOTIFY_ONLYRegistra a violação e envia o webhook policy.violation, mas o pagamento segue

NOTIFY_ONLY é o ensaio antes do bloqueio: salve a regra em modo monitor, acompanhe os avisos por alguns dias no painel e no webhook, e promova para BLOCK quando estiver convencido de que a regra não pega tráfego legítimo.

Em modo monitor a violação não aparece na timeline da transação — o pagamento seguiu e vai ter o desfecho normal (pix_out.completed). A violação vive no webhook e no painel.

Regras de PIX In

Um recebimento não pode ser recusado

O liquidante credita a conta e só depois nos avisa. Quando a política é avaliada, o dinheiro já entrou — não existe momento em que dava para recusar. O teto e a ação valem para PIX, TED, transferência interna recebida e boleto de cobrança liquidado. A escolha é o que fazer depois.

OrdemRegraruleDescrição
1Whitelist—Documento do pagador na whitelist: aceita e pula todas as regras abaixo
2Blacklist (documento)pixIn.cpfCnpjBlacklistPagador com documento na blacklist
3Mesma TitularidadepixIn.sameOwnershipOnlyAceita apenas PIX do CPF/CNPJ do titular da conta
4Limite por recebimentopixIn.maxAmountValor máximo de um crédito: PIX, TED, transferência interna ou boleto liquidado
5Tipo de PessoapixIn.allowedPersonTypesRestringe o pagador a PF ou PJ
6Bancos PermitidospixIn.allowedBankCodesAceita apenas PIX dos bancos listados
7Bancos BloqueadospixIn.blacklistedBankCodesRecusa PIX dos bancos listados

As listas de banco aceitam código COMPE (3 dígitos) ou ISPB (8 dígitos) — o que você tiver em mãos. Quando o crédito não identifica o banco do pagador, as regras de banco são puladas. Vale o mesmo para documento, tipo de pessoa e mesma titularidade quando o pagador não vem. TED traz esses dados. Transferência interna e boleto, se o pagador não vier, pulam essas regras. O teto de valor vale sempre.

Ações de recebimento

A ação é uma só para a seção. O nome no JSON continua pixIn.violationAction.

violationActionEfeito
ALLOW_AND_NOTIFY (padrão)Registra a violação e envia policy.violation. O crédito permanece
AUTO_REFUNDNo PIX, devolve o valor integral. Em TED, transferência interna e boleto só avisa: o dinheiro fica
LOCK_BALANCETrava no liquidante o valor daquele crédito. O disponível cai. Não desbloqueia sozinho
BLOCK_ACCOUNTA conta passa a blocked na nossa API: a saída responde 423 e consulta e entrada seguem. Não reabre sozinha

AUTO_REFUND inicia uma devolução PIX comum logo após o crédito, com motivo unauthorized-transaction. Ela aparece no extrato do seu cliente como uma devolução e não tem como ser desfeita. Não há devolução automática de TED, nem cancelamento de boleto já liquidado.

LOCK_BALANCE reduz o saldo disponível no liquidante. BLOCK_ACCOUNT só corta saída na nossa API; o liquidante não bloqueia a conta. Marcar o caso como ciente não desfaz nenhum dos dois.

O webhook do crédito (pix.in.completed, ted.in.received, transfer.internal.in ou boleto.charge.settled) sai antes do policy.violation. Falha do lock ou do bloqueio da conta não desfaz o crédito. Quando há devolução de PIX, ela gera os eventos normais de PIX out (pix.out.completed ou pix.out.failed).

Valores antigos QUARANTINE e BLOCK salvos nesta seção continuam valendo como ALLOW_AND_NOTIFY.

Regras de QR Code

Avaliadas na criação do QR Code (estático e dinâmico), antes de o QR existir no parceiro.

RegraruleDescrição
Criação de estáticoqrCode.canCreateStaticfalse recusa a criação de QR estático
Criação de dinâmicoqrCode.canCreateDynamicfalse recusa a criação de QR dinâmico
Valor mínimoqrCode.minAmountValor mínimo do QR
Valor máximoqrCode.maxAmountValor máximo do QR
Cota por diaqrCode.maxIssuesPerDayRecusa quando a conta já criou esse número de QR no dia calendário (horário de Brasília)
Cota por mêsqrCode.maxIssuesPerMonthRecusa quando a conta já criou esse número de QR no mês calendário (horário de Brasília)

Os limites de valor só se aplicam a QR criado com valor. Um QR estático aberto, em que o pagador digita o valor no app do banco dele, não tem montante para comparar na criação — as duas regras de valor são puladas.

As cotas de criação contam unidades, não valor, e por isso valem também para o QR aberto. São por conta: configuradas no tenant, cada conta dele tem a sua cota individual, não um teto somado. A contagem inclui todo QR criado na janela — estático, dinâmico e com vencimento — em qualquer status: cancelar ou deixar expirar um QR não devolve a vaga. Se a contagem falhar, a criação segue, pelo mesmo motivo de keys.maxKeys. QR de PIX Automático não entra nessa cota.

Regras de Chaves PIX

Avaliadas na criação de chave (POST /v1/accounts/{accountId}/pix/keys).

RegraruleDescrição
Criaçãokeys.canCreatefalse recusa a criação de novas chaves
Máximo de chaveskeys.maxKeysRecusa quando a conta já tem esse número de chaves

A contagem de chaves é consultada no parceiro no momento da criação. Se essa consulta falhar, a criação segue: indisponibilidade nossa não deve virar violação de política. Chaves que já existem nunca são removidas por uma mudança de política.

Regras de Estorno

Avaliadas nas devoluções que você pede em POST /v1/accounts/{accountId}/pix/out/refund, sejam elas integrais ou parciais.

RegraruleDescrição
Kill switchrefund.disabledenabled: false recusa toda devolução pedida pela API
Valor máximorefund.maxAmountValor máximo por devolução

Devoluções que não são sua escolha ficam fora desta seção: um MED aceito e o AUTO_REFUND da seção PIX In são obrigações, e regra de tenant não sobrepõe obrigação. Pelo mesmo motivo, as regras de documento de PIX Out (blacklist, whitelist, titularidade, tipo de pessoa) não se aplicam a devoluções — o destinatário de uma devolução é quem pagou, não uma escolha sua.

Recusa nas três seções acima

QR Code, chaves e estorno sempre barram: não há modo monitor. As três são operações síncronas que ainda não moveram dinheiro quando a regra é avaliada, então a recusa cabe na resposta — 422 com errorCode: policy_denied, no mesmo formato do PIX Out. Avisar depois de devolver um BR Code, publicar uma chave no DICT ou submeter uma devolução seria avisar sobre fato consumado.

Taxa de MED

Avaliada quando uma disputa (MED) nova é recebida contra a conta. A taxa é a mesma do painel — MEDs recebidas dividido por PIX recebidos com sucesso — só que por conta e numa janela móvel, sem corte diário. A única ação é BLOCK_ACCOUNT: a conta passa a blocked e toda saída responde 423 account_blocked até alguém do suporte reativar. A MED em si segue o fluxo normal.

CamporuleDescrição
windowDays—Janela móvel em dias, contada para trás da MED que chegou. Ausente = 30. Teto 90.
maxRatePercentmed.maxRatePercentTaxa (em %) a partir da qual bloqueia. Ausente ou 0 = regra desligada.
minMedCount—Mínimo de MEDs na janela para a taxa valer. Ausente = 1.
critical.maxRatePercentmed.critical.maxRatePercentMesma conta, só com MEDs críticas. Limite menor que o geral.
critical.minMedCount—Mínimo de MEDs críticas na janela. Ausente = 1.
{
"med": {
"windowDays": 30,
"maxRatePercent": 1.0,
"minMedCount": 5,
"critical": { "maxRatePercent": 0.3, "minMedCount": 2 }
}
}

Uma MED é crítica quando o motivo informado pelo liquidante é fraude (scam-or-fraud) ou quando o relato do reclamante contém uma palavra de uma lista mantida pela CorpX — termos de golpe (“golpe”, “não reconheço”, “conta invadida”) e de apostas (“bet”, “aposta”, “tigrinho”). A lista é única para todas as contas e cresce com o tempo; a policy diz quantas MEDs críticas, em que taxa, bloqueiam.

O bloqueio exige as duas condições ao mesmo tempo: contagem de MEDs igual ou acima do mínimo e taxa igual ou acima do teto. O mínimo evita fechar uma conta por uma disputa só num mês de poucos recebimentos. Sem PIX recebido na janela a taxa conta como 100%. Como nas demais seções, a regra da conta substitui a do tenant por inteiro. Uma falha nossa ao calcular a taxa não bloqueia ninguém.

Horário de Operação

Janela em que as saídas são permitidas. Suporta janelas que cruzam a meia-noite (ex.: 22:00-06:00).

CampoDescriçãoExemplo
startHora de início06:00
endHora de fim22:00
timezoneFuso horário (padrão America/Sao_Paulo)America/Sao_Paulo

Uma janela pela metade (só start ou só end) é tratada como ausente e não barra ninguém.

Limites de DICT Lookup

Consultar uma chave PIX tem limites próprios, avaliados a cada consulta. Ao exceder, a resposta é 429 com errorCode: dict_lookup_limit_exceeded, e um webhook policy.violation com phase: "dict_lookup" é enviado.

Nem todo 429 é a sua cota

A mesma rota também responde 429 com errorCode: partner_rate_limited, que é throttling do liquidante sobre o tráfego da CorpX e não tem relação com os limites desta página — nenhum contador da sua conta fechou. Confira o errorCode antes de concluir que a cota acabou.

Contam como consulta as duas formas de perguntar ao DICT quem é o dono de uma chave:

  • A consulta explícita — GET /v1/accounts/{accountId}/pix/key/{pixKey}.
  • O PIX Out no modo KEY — POST /v1/accounts/{accountId}/pix/out, /async e /bigpix. A chave precisa ser resolvida antes de o dinheiro sair, e essa pergunta vai para o mesmo DICT. Ver “Pagamento por chave também consome cota”, abaixo.

São três limites de contagem absoluta, todos medidos por conta (ver “Todo limite é por conta”, abaixo), e vale o mais restritivo — qualquer um que estoure devolve 429:

LimiteJanelaDefault globalO que protege
maxLookupsPerDaydia-calendário BRT (a partir de 00:00)50Teto absoluto de consultas por dia
maxLookupsPerMinute60s rolantes15Rajada: cabe no teto diário, mas chega tudo de uma vez
maxNotFoundPer5min5 min rolantes10Enumeração de chaves: scan cego gera muito NOT_FOUND antes de o teto diário estourar

Além deles existem os tetos de taxa por janela de tempo, descritos a seguir. Esses valem sempre: quem não declara números próprios herda a linha de base da frota.

Esta seção é a referência dos campos

Para entender por que o DICT é racionado, o que a CorpX espera do seu tráfego, como acompanhar o seu consumo no painel e o que acontece com quem desrespeita a régua, leia Consultas de chave PIX.

Tetos de taxa por janela de tempo

Os três limites acima respondem quanto e quão rápido. Nenhum responde a pergunta que o balde do DICT de fato mede: quantas consultas você gasta por pagamento que efetiva, e que fração das suas consultas não resolve chave nenhuma. Uma conta pode caber folgado em 500 consultas por dia e ainda assim gastar 40 consultas por PIX — perfil de quem varre chave, não de quem paga.

Cada janela de tempo pode ter teto para as duas taxas:

CampoO que mede
maxUsageRatioConsultas ÷ PIX Out concluídos na janela
maxFailureRatio(NOT_FOUND + recusadas) ÷ consultas na janela. É fração, não percentual: 0.4 = 40%
minLookupsPiso de amostra. Abaixo desse número de consultas na janela, nenhuma das duas regras pode recusar

As janelas disponíveis são 5m, 15m, 30m, 1h, 3h, 6h, 12h, 24h, 3d, 7d, 14d, 30d, 60d e 90d.

{
"dictLookup": {
"windows": {
"5m": { "maxFailureRatio": 0.6, "minLookups": 10 },
"1h": { "maxUsageRatio": 6, "maxFailureRatio": 0.4, "minLookups": 50 },
"30d": { "maxUsageRatio": 4, "minLookups": 500 }
}
}
}

O minLookups existe para o rate não travar quem mal começou: uma conta com duas consultas e nenhum pagamento tem taxa de uso infinita, e sem o piso ficaria bloqueada para sempre.

Janela sem teto declarado não é janela desligada. Ela herda a linha de base da frota, que hoje é maxUsageRatio 2.0 em todas as faixas e maxFailureRatio 0.2 até 7d, apertando nas janelas longas (0.18 em 14d, 0.15 em 30d, 0.12 em 60d e 0.10 em 90d), com piso de amostra de 20 nas janelas de até 30 minutos, 50 de 1h a 12h e 500 por dia de janela a partir de 24h (500 em 24h, 1500 em 3d, e assim por diante). Esses números partiram da medição de tráfego real da frota. Declarar valores próprios na policy especializa a conta ou o tenant; não é o que liga a proteção.

Quando mais de uma janela está acima do teto, a resposta cita a mais curta — é a causa imediata e a primeira a liberar. A mensagem do 429 diz qual janela, o que foi medido e qual era o teto:

DICT lookup usage too high for this account in the last 1h:
120 lookups for 10 successful transfers (12.0 per transfer); max 6.0
DICT lookup failure rate too high for this account in the last 5m:
18 of 24 lookups did not resolve a key (75%); max 40%

O errorCode continua sendo dict_lookup_limit_exceeded — nada muda para quem já trata esse código.

Todo limite é por conta

Todos os limites são medidos conta a conta, sempre. Não existe teto agregado por tenant: as consultas de uma conta nunca entram na contagem de outra, mesmo que as duas pertençam ao mesmo tenant.

Isso vale inclusive quando o limite foi configurado no nível do tenant. Uma policy de tenant é um molde aplicado a cada conta individualmente, não um balde compartilhado:

ConfiguraçãoLeitura corretaLeitura errada
Policy do tenant com maxLookupsPerDay: 50Cada conta do tenant pode fazer 50 consultas por diaO tenant todo pode fazer 50 por dia, divididas entre as contas
Policy do tenant com windows.24h.maxUsageRatio: 2.2A taxa de cada conta é medida contra as transferências daquela contaA taxa é medida contra o total de transferências do tenant

A policy de conta continua vencendo a do tenant quando existir — o que muda entre as duas não é a unidade de contagem, apenas de onde saem os números.

A conta é a unidade porque é ela que o BACEN mede no bucket de rate limit do DICT: é nela que a rajada acontece e é nela que a punição chega. Somar as contas de um tenant produzia os dois erros ao mesmo tempo — uma conta parada herdava o consumo da vizinha, e num tenant grande o excesso de uma conta se diluía no total até nenhum limite fechar.

Pagamento por chave também consome cota

Um PIX Out no modo KEY precisa saber quem é o dono da chave antes de enviar o dinheiro. Essa resolução conta na mesma cota da consulta explícita, e por isso um pagamento pode receber 429 com errorCode: dict_lookup_limit_exceeded. Quando isso acontece, nenhum pagamento é criado: não há paymentId, não há transação, e reenviar com a mesma Idempotency-Key continua sendo seguro.

O cache de 24h é o que evita a dupla contagem. O fluxo mais comum — consultar a chave para exibir o destinatário e, confirmado pelo usuário, pagar — gasta uma consulta, não duas: a segunda é servida pelo cache. Quem paga direto, sem consultar antes, também gasta uma. Nos dois casos, 100 pagamentos por chave consomem cerca de 100 da cota, o que deixa o resto do orçamento para consultas avulsas.

O BigPix resolve a chave uma vez para o lote inteiro, independente de em quantas parcelas o valor é dividido.

Dois desfechos merecem atenção no POST de pagamento:

  • Chave inválida ou inexistente devolve o erro na resposta, sem criar pagamento. É preferível a um pagamento que nasce e falha segundos depois.
  • DICT indisponível (erro ou timeout do liquidante) não recusa nada: o pagamento segue e a chave é resolvida pelo liquidante, como antes. Indisponibilidade nossa ou dele não vira pagamento recusado nem consome cota.

O denominador da taxa de uso

A taxa de uso de uma janela é consultas ÷ PIX por chave concluídos na mesma janela. Do lado do denominador entram só as transferências que de fato aconteceram, e só as daquela conta: COMPLETED e REFUNDED (que liquidaram e só depois foram devolvidas). Pagamento que falhou, foi recusado ou ficou indeterminado não amplia o teto — do contrário, quem estivesse repetindo uma tentativa com erro ganharia mais cota de consulta a cada falha. PIX por dados bancários e QR Code sem chave ficam fora, porque não passam pelo DICT.

O PIX por chave pago sem consulta prévia também conta como consulta, porque o liquidante resolve a chave no DICT do mesmo jeito:

SituaçãoConsultasPIX
Consultou a chave e pagou com sucesso+1 (a consulta)+1
Consultou a chave e não pagou+10
Pagou direto por chave, com sucesso+1+1
Pagou direto por chave e a chave não existe+1 (conta também na taxa de falha)0

Uma consulta cobre um pagamento: vale a consulta da mesma conta para a mesma chave nas 24 horas anteriores ao PIX. Dois PIX para a mesma chave depois de uma consulta só contam a consulta e mais uma.

Conta nova ou ociosa tem denominador zero, o que daria taxa infinita. Quem protege esse caso é o minLookups da janela: abaixo do piso de amostra nenhuma das duas regras pode recusar, então a conta faz suas primeiras consultas sem ser barrada por uma taxa que ainda não significa nada.

Ausente não é ilimitado

Um limite ausente na policy não significa ilimitado: vale o default global da tabela acima. Para remover o teto é preciso declarar isso explicitamente (opção No limit no Backoffice, que grava um valor negativo). Os limites de burst continuam ativos mesmo assim — remover o teto diário não libera rajada.

O que consome cota

Cota diária (maxLookupsPerDay) e ratio contam as consultas que chegaram ao DICT por vontade do integrador: chave encontrada, chave inexistente e chave recusada pelo DICT (requisição inválida, ou o limite do próprio DICT para aquele consultante). Falha técnica do liquidante e tentativa já recusada com 429 ficam de fora — não se deve queimar cota por indisponibilidade nossa, nem afundar mais fundo depois de já ter sido bloqueado. Vale igual para a consulta explícita e para a resolução feita dentro de um PIX Out.

Os limites de burst são o oposto: maxLookupsPerMinute conta todos os resultados, inclusive os recusados, porque a métrica ali é a pressão que o cliente está fazendo, não o proveito que tirou. maxNotFoundPer5min conta só as chaves inexistentes.

Cache de 24h

Consultas repetidas da mesma chave são servidas de um cache de 24h, e cache hit não consome cota. O cache é o mesmo para os dois caminhos: uma consulta explícita serve o pagamento seguinte, e a resolução feita dentro de um pagamento serve a consulta seguinte. Para forçar uma ida ao DICT — dados desatualizados, titularidade que pode ter mudado — use ?noCache=true na consulta explícita, lembrando que aí a consulta conta normalmente.

Webhook policy.violation

Toda violação — recusada ou apenas avisada — dispara o evento policy.violation para quem o assinou.

{
"phase": "edge",
"action": "BLOCK",
"blocked": true,
"accountId": "acc_...",
"identifier": "PEDIDO-1234",
"mode": "KEY",
"amount": 5000.00,
"violations": [
{ "rule": "cpfCnpjBlacklist", "message": "recipient document is blacklisted" }
],
"counterparty": { "document": "12345678900", "name": "FULANO DE TAL" }
}

Em phase: "edge" não há paymentId: o gate roda antes de o pagamento ser criado, e é justamente por isso que a recusa cabe na resposta HTTP. Use o identifier para correlacionar. Na fase counterparty, que roda dentro do workflow, o paymentId já existe e vem no payload.

CampoDescrição
phaseedge (na requisição), counterparty (após resolver o destinatário), pix_in, ted_in, internal_in, boleto_in (após o crédito), med (ao receber uma disputa) ou dict_lookup
actionBLOCK, NOTIFY_ONLY, ALLOW_AND_NOTIFY, AUTO_REFUND, LOCK_BALANCE ou BLOCK_ACCOUNT, conforme a configuração
blockedtrue quando a operação foi de fato recusada. Sempre false num recebimento: o crédito não foi recusado
balanceLockedNo recebimento, true quando o valor daquele crédito foi travado no liquidante
accountBlockedNo recebimento, true quando a conta passou a blocked por esta violação
violationsTodas as regras violadas, com o identificador em rule
counterpartyO destinatário (PIX Out) ou o pagador (PIX In), quando conhecido

Num recebimento o payload troca paymentId por transactionId e a referência do crédito (endToEnd no PIX, creditRef nos demais), e traz refunded. refunded só é true na devolução de PIX. Se a ação pedida não concluiu, balanceLocked ou accountBlocked sai false.

Em phase: "med" a referência é o medId da disputa que disparou a avaliação, e o payload traz os números da janela: windowDays, medCount, criticalMedCount, pixInCount, ratePercent e criticalRatePercent. O pix.med.opened dessa mesma disputa sai com accountBlocked: true.

Detalhes de entrega, retentativas e assinatura no guia de Webhooks.

Visibilidade de Violações

  • Webhook policy.violation — em toda violação, em qualquer seção.
  • Timeline da transação (GET /v1/transactions/{id}/timeline) — quando a violação recusa um PIX Out, o evento pix_out.failed traz errorCode: policy_denied e as regras violadas em policyViolations. Numa recusa na borda, em que ainda não existe paymentId, a âncora do evento é o workflowId determinístico da operação, que é o mesmo id devolvido nas respostas de PIX out. O endpoint aceita os dois, além de endToEndId, txid e o id do parceiro.
  • Painel — a aba Violations lista o histórico, separando o que foi barrado, o que foi só avisado e o que foi devolvido, com o total por regra.
O extrato não mostra violações

Uma operação recusada por política nunca chega ao banco parceiro, e o extrato (GET /v1/accounts/{accountId}/statement) reflete o que aconteceu na conta. Violações não aparecem lá. Use o webhook, a timeline ou o painel. A exceção é a devolução de um PIX por AUTO_REFUND: ela é uma movimentação de verdade e aparece no extrato como devolução. LOCK_BALANCE reduz o disponível no liquidante; BLOCK_ACCOUNT não muda o saldo, só corta a saída na API.

Allowlist de IP e MED

A allowlist de IP que de fato bloqueia tráfego é a do WAF, configurada na tela de Security — não é uma política. Controles de MED têm guia próprio em Disputas (MED).