Como funciona a API para Pix com liquidação em tempo real?

Principais lições deste artigo

• O fluxo completo de Pix com liquidação em tempo real exige integração com SPI, DICT, mTLS e webhooks assíncronos para reduzir timeouts e inconsistências.

• É fundamental distinguir liquidação interna, na mesma instituição, de liquidação interbancária, via SPI, pois os caminhos de código e o tratamento de erros são diferentes.

• Webhooks com validação de assinatura, idempotência via EndToEndId e resposta em até 5 segundos aumentam a confiabilidade da reconciliação automática.

• Requisitos de segurança como mTLS, rotação de certificados e conformidade com limites regulatórios precisam de monitoramento contínuo para evitar interrupções.

• Para implementar essa infraestrutura com agilidade e conformidade, conte com a Celcoin: conheça a plataforma completa.

Visão geral dos componentes centrais

O funcionamento da liquidação em tempo real via Pix depende de alguns componentes principais e de como eles se conectam no fluxo transacional. A seguir, veja os elementos estruturais dessa infraestrutura e o impacto de cada um no desenho da sua API.

Componentes SPI e DICT

O SPI é a infraestrutura de liquidação bruta em tempo real operada pelo Banco Central. Cada transação Pix é liquidada individualmente, de forma irrevogável, com disponibilidade 24 horas por dia, 7 dias por semana. O DICT é o diretório que mapeia chaves Pix, como CPF, CNPJ, e-mail, telefone ou chave aleatória, às contas transacionais dos participantes.

Antes de qualquer envio de ordem ao SPI, a API para Pix consulta o DICT para resolver a chave e obter os dados da instituição de destino, o número da conta e o nome do titular. Participantes diretos do SPI, instituições homologadas pelo Banco Central, se conectam à Rede do Sistema Financeiro Nacional, a RSFN, e enviam mensagens no padrão ISO 20022. Participantes indiretos operam por meio de um participante direto, que assume a responsabilidade pela liquidação junto ao Banco Central.

Fluxo end-to-end de liquidação com timings

O fluxo de uma transação Pix segue etapas bem definidas, com limites de tempo regulatórios que orientam o desenho da API e dos timeouts de aplicação.

1. Iniciação: o pagador autoriza a transação na interface do PSP pagador. O PSP envia a mensagem de ordem de pagamento ao SPI dentro dos prazos regulatórios aplicáveis.

2. Validação no SPI: o SPI valida saldo, limites e integridade da mensagem. Em condições normais, essa etapa ocorre em poucos segundos.

3. Liquidação: o SPI debita a conta de reservas do PSP pagador e credita a conta de reservas do PSP recebedor de forma simultânea e irrevogável.

4. Confirmação ao PSP recebedor: o PSP recebedor recebe a confirmação e credita a conta do beneficiário. O prazo regulatório total, da iniciação ao crédito disponível, é de até 10 segundos em condições normais de operação, conforme estabelecido pelo Banco Central.

5. Notificação ao pagador: o PSP pagador envia o comprovante de liquidação ao usuário pagador, fechando o ciclo da transação.

Diferença entre liquidação interna e interbancária

A liquidação interna ocorre quando pagador e recebedor mantêm contas na mesma instituição. Nesse cenário, a transação é processada no ledger interno do PSP, sem envio ao SPI. O crédito costuma ocorrer em milissegundos e não depende da disponibilidade da RSFN.

A liquidação interbancária exige o ciclo completo pelo SPI descrito anteriormente, com envio de mensagem ISO 20022, validação de reservas e confirmação bilateral. Para equipes de produto, o ponto crítico é manter o mesmo status de confirmação para o usuário final em ambos os casos, mesmo com caminhos de código e tratamentos de erro distintos.

Automação via webhooks para reconciliação instantânea

Após a liquidação, o PSP recebedor notifica o sistema do integrador por meio de um webhook HTTP POST. A payload inclui o EndToEndId, o valor, a data e hora de liquidação, os dados do pagador e o status final. Para reconciliação automática confiável, o sistema receptor deve seguir uma sequência clara de validações e garantias.

O primeiro passo é validar a assinatura do webhook antes de processar qualquer atualização de saldo, o que reduz o risco de eventos fraudulentos alterarem o ledger. Em seguida, o sistema precisa responder com HTTP 200 em até 5 segundos para evitar reenvios automáticos, já que o PSP interpreta timeouts como falha de entrega.

Como reenvios são esperados em caso de timeout, a aplicação deve implementar idempotência usando o EndToEndId como chave de deduplicação. Por fim, o sistema precisa armazenar eventos em fila persistente antes de processar, o que preserva notificações mesmo em caso de falhas em serviços downstream.

Falhas de webhook representam um dos pontos de maior risco operacional em integrações com Pix. Um endpoint indisponível por alguns minutos já pode gerar acúmulo de reenvios e inconsistências temporárias entre o saldo liquidado no SPI e o saldo exibido ao usuário.

Requisitos de segurança e certificados

A autenticação em APIs para Pix exige mTLS, mutual TLS, em que cliente e servidor apresentam certificados X.509 para validação mútua. Na prática, o integrador precisa de um arquivo PFX, protegido por senha e contendo o certificado do cliente e a chave privada, além de um client ID para configurar o HttpClientHandler e estabelecer conexões mTLS com os endpoints do participante direto. O padrão mTLS é obrigatório para integrações Pix v2 junto ao Banco Central.

O fluxo de autorização utiliza OAuth 2.0 com escopos específicos por operação, como cobrança, pagamento e devolução. Credenciais expostas, como client ID, caminho do PFX e senha do PFX, precisam ser revogadas imediatamente, com reemissão de certificados e rotação de client IDs, pois permitem a impersonação do integrador junto à instituição participante.

Pix Automático versus Pix imediato

O Pix imediato é a modalidade transacional padrão, em que o pagador autoriza cada transação individualmente no momento do pagamento. O Pix Automático, regulamentado pelo Banco Central e em expansão na agenda regulatória de 2025-2026, permite que o pagador conceda autorização prévia para débitos recorrentes, como assinaturas e mensalidades, sem autenticação a cada cobrança.

Do ponto de vista da API, o Pix Automático exige a criação e a gestão de mandatos de autorização, com endpoints específicos para criação, consulta, alteração e cancelamento do mandato. A solução também precisa de fluxos de notificação para cobranças agendadas, falhas de débito e cancelamentos iniciados pelo usuário.

Integração via APIs e Open Finance

A integração de APIs para Pix em plataformas de Open Finance segue padrões definidos pelo Banco Central para iniciação de pagamentos. O consentimento do usuário ocorre em um fluxo OAuth com redirecionamento, e a iniciação da transação acontece por chamada autenticada com mTLS ao endpoint do PSP detentor da conta.

Para ERPs e varejistas, esse modelo permite automatizar pagamentos a fornecedores e recebimentos de clientes diretamente no fluxo de gestão, sem redirecionamento manual para aplicativos bancários. A prevenção a fraudes nesse contexto depende da validação cruzada entre os dados do DICT e os dados informados pelo pagador, da análise de comportamento transacional em tempo real e do monitoramento de limites por canal e horário, em linha com as novas regras de segurança do Banco Central publicadas em março de 2026.

Integre sua plataforma ao ecossistema Pix com a infraestrutura da Celcoin.

Erros comuns e pontos de atenção

Mesmo com a infraestrutura correta e as integrações bem implementadas, alguns erros recorrentes podem comprometer a estabilidade do sistema. Conhecer esses pontos de atenção ajuda a antecipar falhas e a definir métricas de monitoramento mais eficientes.

Timeouts no SPI: o SPI pode rejeitar mensagens enviadas fora da janela de 10 segundos. O sistema deve implementar retry com backoff exponencial e verificar o status da transação via endpoint de consulta antes de reenviar, para reduzir o risco de duplicidade.

Essa estratégia de retry depende de um identificador único bem gerenciado. Falhas de idempotência ocorrem quando o sistema usa o mesmo EndToEndId em duas requisições distintas, o que causa rejeição pela infraestrutura. Cada transação precisa gerar um identificador único no formato UUID v4, conforme especificação do Banco Central.

Erros de webhook: os cenários mais frequentes incluem endpoint indisponível, com respostas HTTP 5xx, timeout na resposta acima de 5 segundos e payload malformada por incompatibilidade de versão. O sistema deve registrar todos os eventos recebidos com timestamp e status de processamento para auditoria e reprocessamento.

Certificados expirados: certificados mTLS têm validade definida. A expiração sem renovação prévia interrompe todas as chamadas autenticadas. O monitoramento da data de expiração precisa ser automatizado, com alertas emitidos com pelo menos 30 dias de antecedência.

Conformidade com limites regulatórios: o Banco Central define limites por tipo de transação, canal e horário. As APIs devem consultar e respeitar esses limites de forma dinâmica, já que alterações regulatórias podem ocorrer sem comunicação imediata às equipes de desenvolvimento.

Critérios de sucesso

Uma integração de API para Pix com liquidação em tempo real atinge maturidade quando mantém indicadores operacionais e regulatórios em patamares estáveis. Esses critérios orientam o desenho de SLOs e SLAs internos.

• Taxa de sucesso de liquidação acima de 99,5% em janelas de 24 horas, incluindo fins de semana e feriados.

• Latência de confirmação ao usuário abaixo de 10 segundos em pelo menos 99% das transações interbancárias.

• Taxa de processamento de webhooks acima de 99,9%, com reprocessamento automático de falhas em menos de 60 segundos.

• Zero duplicidade transacional, com controle de idempotência no nível da aplicação e da infraestrutura.

• Conformidade regulatória contínua, com relatórios automáticos enviados ao Banco Central dentro dos prazos definidos.

Atingir esses indicadores exige uma infraestrutura robusta e especializada. Construir essa capacidade internamente demanda meses de desenvolvimento, além de manutenção contínua de conformidade regulatória.

A Celcoin como infraestrutura para essa operação

A Celcoin opera como participante direta no Pix e oferece uma plataforma full stack que abstrai a complexidade técnica e regulatória para fintechs, bancos digitais, ERPs e varejistas. A solução cobre desde o modelo baas até o Core Banking com licença própria e atende mais de 6 mil clientes, com mais de R$ 30 bilhões em transações mensais.

Funcionalidade da Celcoin	Benefício para sua empresa
APIs Modulares	Integrações mais rápidas, com redução de custos e prazos de desenvolvimento.
Experiência e suporte ao desenvolvedor	Documentação, SDKs e sandboxes reduzem ciclos de integração e esforço de engenharia.
Capacidade de lançamento rápido	Módulos pré-construídos e entrega via SaaS aceleram lançamentos e antecipam geração de receita.
Distribuição white-label e embutida (embedded)	Suporte a produtos financeiros com marca própria em diferentes jornadas.
Escalabilidade com confiabilidade	Solução com alta disponibilidade e escalável na nuvem mantém serviços estáveis mesmo em altos volumes.
Cobertura de diversas possibilidades de pagamentos, incluindo crédito	Oferecer pagamentos e emissão de crédito aumenta conversão, ARPU e fidelização.
Acesso a dados e personalização	Dados e análises via Open Finance permitem ofertas personalizadas, com impacto em conversão e retenção.
Compliance e conformidade como princípio	KYC, AML e relatórios integrados reduzem risco regulatório e encurtam ciclos de vendas.
Prevenção de fraude e controles de risco	Monitoramento baseado em IA e autenticação robusta reduzem estornos, perdas e exposição regulatória.
Força do ecossistema de parceiros da Celcoin	Parcerias e integrações com bancos, redes e fintechs ampliam cobertura e velocidade de entrada no mercado.

Próximos passos

Após estabilizar a integração básica, as equipes de produto podem evoluir para funcionalidades que aumentam automação, visibilidade e recorrência de receita.

• Pix Automático: implementação de mandatos para cobranças recorrentes, com gestão de ciclo de vida de autorizações e tratamento de falhas de débito.

• Monitoramento em tempo real: dashboards de latência, taxa de sucesso e volume transacional integrados ao sistema de observabilidade da plataforma.

• Reconciliação automatizada: pipelines que cruzam eventos de webhook com registros do ledger interno em tempo real, reduzindo processos manuais de fechamento.

• Expansão para Open Finance: uso da infraestrutura de iniciação de pagamentos para automatizar fluxos de pagamento a fornecedores e recebimentos de clientes em ERPs e plataformas de varejo.

Acelere sua roadmap de pagamentos com as APIs modulares da Celcoin.

Perguntas frequentes

Qual é o prazo máximo regulatório para liquidação de um Pix interbancário?

Conforme detalhado na seção sobre fluxo de liquidação, o Banco Central estabelece prazo de até 10 segundos em condições normais. Esse período abrange a validação no SPI, a liquidação nas contas de reservas dos participantes e o crédito na conta do recebedor pelo PSP de destino.

O que é mTLS e por que ele é obrigatório para APIs para Pix?

mTLS, mutual TLS, é um protocolo de autenticação mútua em que cliente e servidor apresentam certificados digitais X.509 para validação antes de estabelecer a conexão. No contexto de APIs para Pix, o Banco Central exige mTLS para garantir que apenas participantes homologados e integradores autorizados possam enviar ordens de pagamento ao SPI.

Na prática, o integrador precisa de um arquivo PFX, que contém o certificado do cliente e a chave privada, e de um client ID fornecido pelo participante direto. A ausência de mTLS ou o uso de certificados inválidos resulta em rejeição imediata da conexão, sem processamento da transação.

Como funciona a idempotência em APIs para Pix e por que ela é crítica?

Idempotência garante que múltiplas chamadas com o mesmo identificador de transação produzam exatamente o mesmo resultado, sem duplicidade de débito ou crédito. Em APIs para Pix, o EndToEndId, um UUID v4 gerado pelo PSP pagador, atua como chave de idempotência.

Se uma requisição de pagamento não receber resposta dentro do timeout configurado, o sistema pode reenviar a mesma mensagem com o mesmo EndToEndId. A infraestrutura do SPI e do PSP recebedor reconhece o identificador já processado e retorna o status da transação original sem gerar novo débito. Sistemas que não implementam idempotência corretamente podem causar cobranças duplicadas, com impacto direto na experiência do usuário e em obrigações de devolução.

Qual a diferença prática entre Pix Automático e débito automático tradicional para equipes de produto?

O débito automático tradicional opera em janelas de processamento em lote, com liquidação em D+1 ou D+2, e exige cadastro prévio em formulários físicos ou digitais com validação manual. O Pix Automático opera com liquidação em tempo real via SPI, com mandatos de autorização criados e gerenciados via API e notificações de status entregues por webhook.

Para equipes de produto, isso significa incluir endpoints de criação de mandato, fluxo de consentimento do usuário alinhado aos padrões do Banco Central, lógica de retry para cobranças recusadas e gestão de cancelamento de autorização pelo pagador. A agenda regulatória do Banco Central para 2025-2026 prevê expansão das funcionalidades e dos casos de uso do Pix Automático, o que torna essa modalidade relevante para plataformas de assinatura, ERPs e marketplaces.

Como garantir a conformidade regulatória contínua após a integração inicial?

A conformidade regulatória em integrações com Pix continua após o go-live. O Banco Central publica atualizações periódicas nas normas do SPI, nos requisitos de segurança e nas funcionalidades do DICT.

As equipes de tecnologia precisam monitorar o portal do Banco Central para novas resoluções, manter um processo de renovação antecipada de certificados mTLS, atualizar escopos OAuth conforme novas versões das APIs dos participantes e garantir que relatórios regulatórios obrigatórios, como DIMP e CADOCs, sejam gerados e enviados dentro dos prazos definidos.

Plataformas de infraestrutura que automatizam esses relatórios e mantêm atualização contínua com as normas do Banco Central reduzem o risco de não conformidade e o custo operacional de manutenção regulatória.