A arquitetura do PIX vista por dentro: SPI, ISO 20022 e um orçamento de dez segundos

O PIX é um dos poucos sistemas em que a latência aceitável está publicada em norma, por percentil, e auditada mensalmente. Este texto é sobre o que isso faz com a arquitetura de quem precisa caber ali dentro — do lado do Banco Central e do lado de um participante direto.

Vale começar por aqui porque tudo do lado do banco é consequência disso.

O PIX não é um sistema único. São dois sistemas principais, com papéis bem separados:

A comunicação com essa infraestrutura acontece exclusivamente pela RSFN — a Rede do Sistema Financeiro Nacional. Rede dedicada, fora da internet pública, com autenticação por certificado ICP-Brasil e validação de formato e assinatura em cada mensagem.

Isso muda tudo no modelo mental de quem vem de web. Não existe “chamar uma API e tratar o erro 500”. Existe um protocolo de mensageria financeira com ordem de campos, schema validado, assinatura digital e um catálogo de erros que você precisa mapear inteiro. As mensagens centrais da iniciação são a pacs.008, que carrega a ordem de pagamento com pagador, recebedor, valor e o EndToEndId — o identificador único da transação, gerado na origem e que acompanha a operação até o fim — e a pacs.002, que devolve o status.

Do lado da infraestrutura do próprio BC, a escolha foi pública e interessante: o edital já definia uma arquitetura distribuída baseada em Apache Kafka, e a solução contratada foi a stack open source da Red Hat — AMQ Streams (Kafka), OpenShift e Ansible Automation Platform. Em teste, com volume de 2 mil transações por segundo, 99% foram processadas em menos de quatro segundos.

O Banco Central não pediu “seja rápido”. Ele publicou o Manual de Tempos do Pix, que fatia o ciclo de liquidação em marcos e define acordo de nível de serviço por percentil sobre a diferença entre eles. Os marcos são estes: t0' é quando o PSP do pagador recebe a confirmação do usuário; t1 é quando ele cria a pacs.008 — medido antes da assinatura; t1' é quando o SPI recebe a requisição; t2 é quando o SPI disponibiliza a mensagem ao PSP do recebedor; t3' é quando o SPI recebe a pacs.002; t4 é a liquidação, a troca de saldos entre as Contas PI; t5a é quando a pacs.002 fica disponível para o pagador; e t6a é quando o pagador é notificado.

Vale parar na linha em negrito. Os “dez segundos” que viraram slogan do PIX são o P99 da experiência do usuário pagador — a mediana pactuada é 6 segundos. E existe um teto duro por cima de tudo: um PIX enviado ao canal primário de mensagens tem limite máximo de 40 segundos entre a ordem do usuário e a liquidação. Passou disso, o próprio SPI rejeita a transação e comunica os participantes.

Do lado do participante, o roteiro de participação direta traz um número que não é um acordo de nível de serviço permanente, e sim critério de aprovação no teste de capacidade: durante o teste, a instituição precisava consumir em até 200 milissegundos no mínimo 99% das mensagens pacs.008 e pacs.002 disponibilizadas pelo SPI, além de demonstrar recebimento de pelo menos 50% das ordens em 1,4 segundo e 95% em 2,3 segundos. Ainda assim, o número diz muito sobre o desenho esperado. Repare no verbo: as mensagens são disponibilizadas e você as consome. Isso empurra a arquitetura para um modelo de consumo contínuo e agressivo, não de espera passiva.

E havia o teste de capacidade, que na nossa época estava na Carta Circular 4.055: enviar mensagens pacs.008 distribuídas uniformemente ao longo de dez minutos — 10 mil, 20 mil ou 40 mil, conforme a faixa de contas transacionais do PSP — e depois receber o mesmo volume, acatando cada uma com sua pacs.002. Não é um teste que você passa raspando: ou a arquitetura absorve, ou você reprova e agenda de novo com o BC.

E, fechando o pacote, há meta de disponibilidade por categoria — e a categoria não é definida por porte da instituição, e sim pela participação do participante no total de transações Pix liquidadas no SPI no ano anterior. As faixas atuais vão de 99,5% para quem responde por mais de 2% do total a 95,0% para os demais, com o BC se comprometendo com 99,9% no SPI. Como o índice do participante direto inclui as transações dos indiretos que ele liquida, a disponibilidade de quem usa a sua infraestrutura entra na sua nota. Guarde essa frase para a seção do PIX Indireto.

Do lado de dentro, a plataforma foi construída em .NET, com RabbitMQ como barramento de mensagens, MS SQL Server para o estado transacional e CouchDB para documentos e payloads — as representações inteiras de cobranças, QR Codes e mensagens, que não cabem confortavelmente num modelo relacional normalizado e que você precisa guardar exatamente como chegaram, para auditoria.

Por que .NET

A resposta honesta é a menos glamourosa: porque já era a stack do banco e o time inteiro era .NET. Não houve prova de conceito, benchmark comparativo nem estudo de linguagem. Havia sete meses e um prazo publicado em norma.

Isso não é preguiça de arquitetura, é aritmética. Trocar de stack num projeto com data fixa significa gastar as primeiras semanas em curva de aprendizado, ferramental, pipeline, padrão de log, biblioteca de acesso a dados e — o mais caro — na descoberta dos modos de falha que a equipe ainda não conhece. Num sistema onde o P95 é requisito auditável, você não quer estar aprendendo o comportamento do coletor de lixo da plataforma nova em novembro. A stack que o time domina tem uma vantagem que nenhum benchmark mede: quando algo trava em produção às três da manhã, alguém sabe onde olhar.

Por que uma fila, e por que RabbitMQ

Aqui a decisão foi de forma, não de marca. O que o problema pedia era um barramento de mensagens, por quatro razões que vêm direto das restrições das seções anteriores.

RabbitMQ especificamente porque roteamento era o que faltava. O tráfego não é um fluxo único: são pacs.008 de saída, pacs.008 de entrada, pacs.002 nos dois sentidos, devoluções, mensagens de cadastro e avisos operacionais. Um exchange com chave de roteamento resolve isso declarativamente — cada tipo de mensagem chega no consumidor certo sem que ninguém escreva um switch gigante no meio do caminho. Some a isso que era um broker que o banco já operava, e a decisão praticamente se toma sozinha.

O que o PIX tinha que devolver para dentro do banco

Uma coisa que eu não esperava era quanto do trabalho não tinha nada a ver com o usuário final. Um participante direto não precisa apenas mover dinheiro: precisa prestar contas do movimento para dentro da própria instituição, e isso vira requisito de engenharia como qualquer outro.

A divisão entre os dois bancos de dados segue a mesma lógica de “cada coisa no lugar onde ela é barata”. SQL Server guarda o que precisa de transação, restrição e saldo consistente: estado da operação, débito, crédito, conciliação. CouchDB guarda o que é documento — a mensagem como chegou, o payload do QR Code, a cobrança inteira. Esse material tem formato que evolui com o manual do BC, e normalizar isso em tabela é assinar um contrato de migração de schema a cada revisão. Sem schema fixo, um payload no formato novo convive com um no formato antigo sem migração.

A decisão estrutural mais importante foi separar a borda da RSFN do resto. Um arquiteto cuidava exclusivamente da comunicação direta com o BACEN: tudo que estava à frente dos nossos serviços, o XML assinado, o transporte, os certificados, a tradução daquilo para uma mensagem que entrava no nosso RabbitMQ.

Isso parece um detalhe de organograma e é, na verdade, o que tornou o prazo viável. Significava que quem estava construindo iniciação de pagamento não precisava saber montar um envelope ISO 20022 assinado. Recebia e publicava mensagens numa fila, num contrato interno estável. Quando o BC publicava uma correção de schema — e publicava —, o impacto ficava contido numa camada, em vez de se espalhar por cinco times ao mesmo tempo.

Iniciação é a metade do PIX que o usuário associa ao produto: alguém aperta um botão e o dinheiro sai. Havia três formas de origem, e elas convergiam para o mesmo núcleo:

• por chave, com consulta ao DICT para resolver a conta de destino;
• manual, com os dados bancários digitados — banco, agência, conta, documento;
• por QR Code, estático ou dinâmico, que precisa ser interpretado antes de virar uma ordem.

E dois destinos possíveis, que parecem o mesmo produto para o cliente e são coisas completamente diferentes por dentro:

O fluxo do caso interbancário, simplificado — a barra inferior mostra o orçamento de dez segundos correndo em paralelo:

O detalhe que consome mais tempo de engenharia não está no caminho feliz. Está nas duas últimas linhas.

É por isso que o EndToEndId deixa de ser um campo de protocolo e vira a espinha dorsal do desenho interno: ele é a chave de idempotência de tudo. Toda operação em cima de uma transação — confirmar, estornar, consultar, conciliar — se ancora nele. Se você errar isso, o sistema funciona lindamente em homologação e produz divergência de conciliação no primeiro fim de semana de produção.

A segunda parte que eu construí foi o PIX Indireto, e ela é conceitualmente mais interessante que a primeira.

No desenho do arranjo, quem não se conecta diretamente ao SPI pode participar como participante indireto: não tem Conta PI, não fala com o BC, e suas transações são liquidadas por meio de um participante direto — que é quem registra esse indireto no SPI e atua como seu liquidante. Fintechs, instituições de pagamento e carteiras digitais oferecem PIX aos seus clientes usando a infraestrutura de um banco.

O que eu construí foi esse lado: todo o cadastro e controle dos PSPs indiretos, mais a orquestração das chamadas para os demais serviços quando a operação vinha em nome de um deles.

Escrever software que outras instituições financeiras consomem muda o padrão de qualidade de um jeito difícil de explicar para quem nunca fez. Não existe “a gente corrige na próxima sprint”. Existe uma instituição inteira cuja operação parou.

Vale registrar uma coisa que só ficou clara com os anos: a capacidade de participante indireto foi construída ali, em 2020, mas o produto comercial com esse nome só foi anunciado publicamente bem depois — segundo reportagem da Finsiders publicada no lançamento, um executivo do banco afirmou que o projeto chegou a ser engavetado por questões de responsabilidade regulatória antes de ser retomado. É uma lição sobre a diferença entre estar pronto e ser lançado, e sobre não medir o valor do que você construiu pela data em que apareceu no site.