Consulta de chave Pix (BaaS)

Informações sobre o balde de fichas

Ao integrar a API de Consulta DICT da Celcoin, é fundamental seguir as diretrizes estabelecidas pelo Banco Central do Brasil (Bacen) para garantir a saúde e a segurança do ecossistema Pix.

Este guia detalha as melhores práticas de consumo, regras de cache e os mecanismos de proteção da nossa API, baseados no Manual Operacional do DICT (Seções 12 e 13.2.3).
Manual Operacional do DICT - Bacen

O Bacen exige um Monitoramento Qualitativo e Permanente (Seção 13.2.3) baseado na relação VCD / EOS:

• VCD: Volume de Consultas ao DICT (Consultas).
• EOS: Efetivação de Ordem de Liquidação (Pagamentos concluídos).

O Bacen estabelece que o cenário ideal é é que o volume máximo seja ligeiramente superior a 1, com uma proporção máxima próxima a 2:1 (duas consultas para cada um pagamento efetivado).
Ou seja, idealmente, para cada consulta deverá existir um pagamento associado.

O que acontece na prática?
Mesmo que o PayerID seja uma Pessoa Jurídica (PJ) e possua um balde de 1.000 fichas, você não conseguirá realizar, por exemplo, 300 consultas consecutivas sem efetuar nenhum pagamento.
Se o seu sistema apenas consultar chaves em massa e não converter essas consultas em pagamentos , a relação VCD/EOS irá "explodir", caracterizando um comportamento anômalo e de alto risco para o Bacen.

Regras Anti-Scam da Celcoin e o Erro 429 Too Many Requests
Para proteger a operação e manter a conformidade com o Banco Central, a Celcoin possui um motor de regras Anti-Scam. Quando o sistema apresenta um comportamento de risco (como uma péssima relação VCD/EOS), a nossa API passará a retornar o status HTTP 429 Too Many Requests.

O que NÃO fazer ao receber um Erro 429
Se a sua aplicação receber um retorno 429, não faça retentativas (retries) em loop e não force novas consultas.
Ficar forçando chamadas na API enquanto está bloqueado e recebendo novos erros 429 piora ainda mais o score e a relação VCD/EOS, podendo levar a sanções mais severas na sua integração. O correto é pausar as consultas e analisar o motivo da baixa conversão em pagamentos.

Observação: Para a contagem das consultas ao DICT, todas as chamadas na API são consideradas, não somente aquelas com sucesso. Erros 404, 429 ou qualquer outro erro 4xx entra na contagem igualmente.

Resumo das Melhores Práticas
Equilibre suas requisições: Busque manter sua taxa de conversão (Consultas vs. Pagamentos) o mais próximo possível de 1:1.

Trate o Erro 429 corretamente: Implemente mecanismos de Circuit Breaker (interrupção de chamadas). Se tomar um erro 429, pare de consultar imediatamente.

Não confie apenas no balde de fichas: O saldo de fichas é um limite quantitativo, mas o limite qualitativo (comportamento de conversão) tem peso maior na prevenção de fraudes.

Janelas Móveis de Curto e Longo Prazo
A avaliação dessa volumetria não ocorre apenas no momento da requisição. Conforme o Manual do Bacen, o monitoramento avalia o comportamento do cliente em múltiplas escalas de tempo (janelas móveis):

• Janela de Curto Prazo: Avalia minutos ou poucas horas.
• Janela de Longo Prazo: Avalia o histórico de dias ou até meses.

O que isso significa na prática?
Um cliente que possui um comportamento "saudável" no curto prazo pode ser penalizado e bloqueado se, ao analisado o período de longo prazo, for detectado um alto volume de consultas acumuladas sem as devidas liquidações. O histórico do PayerID importa tanto quanto o volume do dia.

Fluxos de Integração Recomendados
Para evitar distorções na relação VCD/EOS, recomendamos arquiteturas específicas para cenários comuns:

Pagamentos em Lote (Necessidade de Aprovação)

Se a sua plataforma permite o agendamento ou pagamento em lotes que exigem aprovação de um gestor/alçada antes da liquidação, você não deve consultar o DICT no momento da criação do lote.

Caso ainda seja necessário construir uma experiência que necessite enviar múltiplos pagametos via Chave Pix, é importante entender estará suscetível a bloqueios que podem impactar o pagador pelos motivos descritos no próprio documento. Ainda querendo seguir, o fluxo recomendado é:

• Montagem e Aprovação: O lote deve ser montado e submetido à aprovação apenas com a informação da Chave Pix (sem consultar o DICT).
• Consulta e Efetivação: Somente após o lote ser aprovado, o seu sistema deve iterar sobre os pagamentos, realizando a consulta ao DICT um a um, gerando o E2EID e efetivando a transação.

Validação de Segurança (ownerTaxID):
Como a consulta foi postergada para o momento do pagamento, é crucial garantir que a chave pertence a quem você espera. Para isso, utilize o campo ownerTaxID na API de consulta ao DICT (https://developers.celcoin.com.br/docs/transferencia-para-uma-chave-pix).
Se ao realizar a consulta a nossa API retornar o campo isSameTaxID: false, significa que a chave Pix está registrada para um CPF/CNPJ diferente do esperado. Neste caso, não siga com o pagamento.

Validade do End To End ID: todo E2EID gerado tem validade de 12 horas e pode ser utilizado para qualquer pagamento do PayerID informado na consulta.
Reforçamos que não é permitido consultar uma chave Pix com um PayerID 1 e tentar efetivar a transação com um PayerID 2. É obrigatório que o PayerID utilizado na consulta ao DICT e gerado o EndToEndID seja o mesmo PayerID informado no pagamento que utiliza aquele EndToEndID.

Pagamentos via QR Code Pix (Decodificação)
Se o seu fluxo de pagamento se baseia na leitura de QR Codes, não utilize a API de consulta DICT para extrair os dados do recebedor.

Fluxo Recomendado:

1. Decodificação: Para exibir os dados da cobrança para o seu usuário (nome, valor, etc.), utilize a nossa rota de decodificação de QR Code (/v2/pix/emv). Ela retorna todas as informações do recebedor sem contabilizar como uma consulta ao DICT.
2. Pagamento: Você só deve efetuar a consulta ao DICT no momento exato em que o usuário confirmar a transação, com o objetivo exclusivo de gerar o E2EID e finalizar a liquidação (EOS). Para mais detalhes, consulte a Documentação de Retorno de informações de QR Code (EMV).
   

Política de Cache de Chaves Pix (Seção 12 do Manual Operacional do DICT - Bacen)
O Banco Central possui regras estritas sobre o armazenamento de dados de chaves Pix. É obrigatório que a sua aplicação respeite as seguintes diretrizes:

Chaves Pix pertencentes a Pessoa Jurídica (PJ): É permitido o cache das informações retornadas pelo DICT por um período máximo de 3 minutos. Após esse tempo, os dados devem ser descartados.

Chaves Pix pertencentes a Pessoa Física (PF): NÃO há previsão legal para cache. Os dados de chaves Pix de pessoas físicas não podem ser armazenados sob nenhuma hipótese. A consulta deve ser sempre feita em tempo real no momento da transação.

Outros pontos importantes
A Celcoin não pode abrir quais são os gatilhos da da regra anti-scam, dado que são políticas internas confidenciais, que podem levar ao bloqueio dos usuários e nem abrir qual a frequencia e recorrencia dos eventos de bloqueio/desbloqueio. Não podemos abrir também a janela de curto ou a janela de longo prazo efetivamente utilizada pela Celcoin para o controle.

O controle da relação VCD/EOS é sempre individualizado, por PayerID. Um PayerID que eventualmente for bloqueado nunca impactará em outro PayerID.

Os eventos de controle do ratio, bloqueios e desbloqueios não se misturam com a política da ficha de baldes e o processo de reposição de fichas no balde segue normalmente, conforme detalhado na documentação específica do balde de fichas.