Sua aplicação fala um idioma só. O DigitalPixHub traduz para o banco de cada cliente, confere o pagamento na fonte e devolve a baixa com o código do seu pedido.
Da chamada da sua aplicação até o aviso de que o dinheiro entrou.
Um POST autenticado por token, com o valor, o código do pedido no seu sistema e a descrição. Nenhum dado de banco trafega: quem sabe qual instituição usar é o token.
POST /api/{cliente}/pixO token aponta para uma conexão bancária cadastrada. O sistema decifra as credenciais e o certificado daquela conexão em memória, pega um token OAuth — reaproveitado do cache enquanto for válido — e chama a API do banco.
mTLS + OAuth por conexãoVolta para você o copia-e-cola, a imagem do QR Code, o txid e o instante de expiração. A cobrança fica gravada com o seu código de pedido do lado.
pixCopiaECola + QR em base64O banco notifica o webhook do sistema. Essa notificação não é tratada como verdade: ela serve para acordar o sistema, não para dar a baixa.
webhook do PSPAntes de mudar qualquer status, o sistema reconsulta a cobrança na API da instituição e confirma valor e situação na fonte. Só então concilia.
GET /cob/{txid}Callback assinado com HMAC-SHA256 devolvendo o mesmo código de pedido que você mandou. Se sua aplicação estiver fora do ar, o aviso é reenviado — de 1 minuto até 24 horas, e manualmente pelo painel a qualquer momento.
X-PagPix-Signature: sha256=…Os passos 2 e 3 acima são a parte cara do caminho, e são eles que o caixa espera. Para os valores que se repetem — a recarga de R$ 50, a ficha de R$ 20 — dá para pagá-los antes: o cliente cadastra faixas por valor e o sistema mantém aquela quantidade de QR codes prontos, entregando um deles na hora do pedido.
O pedido chega, leva um QR que já existia, e a resposta volta sem nenhuma chamada à instituição. A vaga aberta é reposta pela passagem seguinte do sistema — nunca pela requisição que a esvaziou, senão o custo tirado do caminho voltaria pela porta dos fundos.
Cada QR nasce com o tempo máximo da faixa e sai de circulação quando resta menos que o mínimo — ainda longe de vencer. É o que garante que ninguém receba um código a segundos do fim. Lido como idade, a mesma configuração entregaria ora duas horas, ora quarenta segundos.
R$ 50 tem uma faixa só, mesmo com vários bancos cadastrados. Com duas, não haveria como dizer de qual conta sai cada cobrança — e quem descobrisse descobriria depois, olhando o extrato.
O texto que o pagador lê e os dados do devedor ficam gravados na instituição no instante em que o QR nasce — e ele nasceu antes de este pedido existir. Então pedido que traz dados do pagador, validade própria ou escolhe outro banco sai pelo caminho normal, com o comportamento de sempre. Entregar do estoque assim mesmo faria a resposta da API descrever uma cobrança diferente da que está no banco.
O QR que envelhece sem ser usado é cancelado na instituição e substituído por outro. Isso passa pela conta bancária do cliente e pelos limites de API do banco dele — por isso há um intervalo mínimo entre uma rotação e a seguinte. O que gira sem ser entregue não conta como cobrança no faturamento da plataforma, nem aparece nas listas e nos gráficos: ele só passa a existir para o cliente quando vira o pedido de alguém.
Três coisas que costumam dar errado numa integração Pix, e o que o sistema faz a respeito de cada uma.
O risco
Marcar a cobrança como expirada só no seu banco de dados não a apaga na instituição. O cliente paga um QR antigo, o dinheiro entra e não existe pedido para conciliar.
No DigitalPixHub
Ao vencer, o sistema também remove a cobrança na instituição. Um cron passa a cada minuto — o atraso entre expirar e sumir do banco é de um minuto, não de um dia.
O risco
O Pix permite que chegue menos do que foi cobrado. Se o sistema dá baixa antes de comparar os valores, o pedido é liberado com o caixa faltando.
No DigitalPixHub
O valor recebido é comparado com o cobrado antes de qualquer baixa. Chegando menos, a cobrança vai para pagamento parcial e fica visível na lista, com a diferença destacada.
O risco
Notificação de banco é entrega best-effort. Uma instabilidade de poucos minutos e o pagamento fica sem baixa, sem ninguém perceber até o cliente reclamar.
No DigitalPixHub
O webhook é só o caminho rápido. Um cron varre as cobranças em aberto e reconsulta cada uma na instituição — se o pagamento existe, ele é encontrado mesmo que a notificação nunca tenha chegado.
O sistema guarda o certificado digital e as credenciais bancárias dos clientes. O desenho parte do princípio de que cada camada pode falhar e a de baixo precisa segurar.
Certificado .p12, senha e credenciais são gravados cifrados em AES-256-GCM. A chave que decifra vive fora do banco de dados, e cada bloco é amarrado ao cliente e à conexão a que pertence — um blob copiado para outro cliente não abre.
Do token de acesso o sistema guarda só o SHA-256. O valor em texto aparece uma única vez, no momento em que é criado. Perdeu, revoga e gera outro — não existe tela que mostre o token de novo, nem para o administrador.
Cada consulta carrega a identidade de quem pediu e o Postgres filtra por cliente na origem, com Row Level Security. As tabelas de credenciais vão além: não têm política de leitura nenhuma, para usuário nenhum.
Na saída, o certificado do cliente autentica o sistema perante o banco. Na entrada, o webhook chega por um endereço secreto por conexão e o certificado do PSP é validado na borda antes de tocar a aplicação.
Cada token tem teto de requisições por minuto e pode ser restrito a uma lista de IPs. Um token vazado sem o IP certo não passa, e um laço acidental no seu código não vira volume no banco.
Toda requisição recebida e toda chamada aos bancos ficam gravadas, com credenciais mascaradas. É o que responde "o sistema mandou esse valor?" meses depois, sem depender de memória.
Quem opera o sistema também não alcança as credenciais dos clientes: elas só são decifradas dentro da chamada que vai falar com o banco, e nenhuma tela as exibe de volta.
A parte cara de um Pix é a viagem até o banco. O estoque acima evita a primeira; quase tudo o mais aqui existe para não fazer a mesma viagem duas vezes.
Não há servidor a dimensionar. Cada requisição sobe onde há capacidade, com as instâncias reaproveitadas entre chamadas — o que também evita refazer o handshake TLS com o banco a cada cobrança. A execução fica em São Paulo, perto das APIs bancárias.
Consultar um Pix não vai ao banco de dados quando a resposta já está em cache. A validade é configurável e o sistema impõe um teto de 24 horas — e nunca guarda além do vencimento da própria cobrança, para não devolver como aberta uma cobrança que já expirou.
Cada token tem seu próprio limite de requisições por minuto. Um cliente em pico não consome a capacidade dos outros, e o excesso volta com a orientação de tentar de novo em vez de derrubar a fila.
Expiração, reconciliação e envio de avisos rodam em tarefas agendadas, a cada minuto. Sua chamada nunca espera por esse trabalho — ela responde assim que o banco responde.
O token de cada banco é guardado até pouco antes de vencer. Isso corta uma ida à instituição por cobrança e mantém o sistema dentro dos limites de quem restringe o pedido de token — o Inter, por exemplo, aceita cinco por minuto.
Erro vindo de um banco é contado por conexão. Passando do normal, a conexão é marcada como instável e o alerta aparece no painel — antes de a fila de pedidos parados chegar ao suporte.
A documentação para desenvolvedores tem o passo a passo da primeira cobrança, do cancelamento e do webhook da sua aplicação.