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

Última atualização: 16 de agosto de 2026

Principais lições deste artigo

• Empresas podem oferecer Pix com liquidação LBTR em tempo real por meio de participação indireta no SPI, sem necessidade de Conta PI própria no Banco Central.

• A integração exige mTLS, OAuth 2.0, webhook público e processamento idempotente para garantir segurança e conformidade regulatória.

• O status do pedido só deve ser atualizado para “pago” após a confirmação de liquidação via webhook, nunca após a leitura do QR Code.

• Validar assinatura HMAC, rejeitar eventos fora da janela de tempo e deduplicar webhooks é essencial para evitar fraudes e crédito em duplicidade.

• Usar a infraestrutura da Celcoin como participante direto homologado permite que fintechs, bancos digitais, gestoras, varejistas e ERPs lancem Pix em tempo real com mais rapidez e segurança; saiba mais.

Passo 1: entender o desafio e os pré-requisitos regulatórios

O SPI liquida cada transação Pix individualmente em tempo real, 24 horas por dia, 7 dias por semana, 365 dias por ano. Diferentemente de sistemas que usam liquidação líquida diferida em ciclos diários, o Pix garante que o momento da confirmação pelo usuário coincide com a liquidação interbancária final, o que elimina o risco de crédito entre PSPs.

Participantes diretos do Pix mantêm conta própria no SPI e liquidam transações diretamente na infraestrutura do Banco Central. Participantes indiretos acessam o SPI por meio de um participante direto mediante acordo bilateral, sem necessidade de conta própria no BCB.

O Pix é regulado pela Resolução BCB nº 1, de 12 de agosto de 2020, com atualizações posteriores. Participantes diretos assumem obrigações operacionais perante o Banco Central.

Essas regras definem os pré-requisitos técnicos para integração via participação indireta. A empresa precisa implementar:

• Autenticação mTLS com certificado de cliente emitido pelo participante direto e OAuth 2.0 com escopos definidos por operação

• Endpoints HTTPS com TLS 1.2 ou superior

• URL de webhook acessível publicamente, que responda a HTTP POST com JSON

• Capacidade de processar eventos de forma assíncrona e idempotente

O fluxo geral do Pix via SPI segue esta sequência:

Pagador → PSP pagador → SPI (BCB) → PSP recebedor → Empresa (webhook) [mTLS/OAuth] [LBTR] [confirmação] [pix.received]

Integre Pix com liquidação LBTR em tempo real usando a infraestrutura homologada da Celcoin.

Passo 2: criar a cobrança via API

A criação de uma cobrança Pix gera um QR Code estático ou dinâmico associado a um identificador único de transação. APIs modernas para Pix expõem o endpoint POST /cash-in para criação de cobrança via QR Code ou Open Finance, com autenticação JWT via POST /auth/token.

Exemplo genérico de requisição de criação de cobrança:

POST /cash-in Authorization: Bearer {access_token} X-Idempotency-Key: {uuid-v4} Content-Type: application/json { "amount": 15000, "currency": "BRL", "expiresIn": 3600, "debtor": { "name": "João Silva", "taxId": "123.456.789-00" }, "additionalInfo": "Pedido #98765" }

Fluxo ASCII da criação:

Empresa → POST /cash-in → API BaaS → Gera txid + QR Code ↓ Retorna { txid, qrCode, status: "ATIVA" }

A criação correta da cobrança define o ponto de partida do fluxo financeiro. O status do pedido interno só deve ser atualizado para “pago” após a confirmação de liquidação via webhook, nunca após a leitura do QR Code pelo pagador. Marcar pedidos como pagos antes da confirmação de liquidação gera inconsistências contábeis e risco operacional.

Passo 3: configurar e validar o webhook de confirmação

O webhook é o mecanismo que o PSP usa para notificar a empresa sobre eventos de pagamento. Endpoints de webhook para integrações Pix devem responder a HTTP POST com payloads JSON e precisam implementar processamento idempotente, porque o mesmo evento pode ser entregue mais de uma vez.

Eventos relevantes para liquidação em tempo real incluem pix.received, pix.sent, pix.qrcode.paid, pix.chargeback.requested e pix.chargeback.approved.

Exemplo de payload pix.received:

{ "event": "pix.received", "id": "evt_01HZ9K3M2P", "timestamp": "2026-08-16T14:32:00Z", "data": { "txid": "abc123def456", "amount": 15000, "status": "LIQUIDADA", "endToEndId": "E1234567820260816143200abc123" } }

Checklist de validação do webhook:

• Verificar o cabeçalho X-Webhook-Signature usando HMAC-SHA256 sobre o corpo bruto da requisição, e não sobre o JSON parseado

• Usar comparação em tempo constante, como crypto.timingSafeEqual, para evitar ataques de timing

• Rejeitar mensagens com timestamp fora da janela de 300 segundos em relação ao servidor para bloquear replay attacks

• Retornar HTTP 200 imediatamente após a verificação da assinatura e enfileirar o processamento de forma assíncrona

• Validar o payload contra schema JSON estrito e rejeitar campos desconhecidos

Passo 4: confirmar a liquidação no SPI (LBTR)

Existe uma distinção técnica entre confirmação no nível do PSP e liquidação final no SPI. A confirmação do PSP indica que o pagamento foi aceito e processado internamente. A liquidação LBTR no SPI significa que os fundos foram transferidos em dinheiro de banco central, com finalidade irrevogável.

No Pix, o momento da confirmação pelo usuário coincide com a liquidação interbancária final via SPI, o que elimina o risco de crédito interbancário presente em sistemas de liquidação diferida. O webhook com status: "LIQUIDADA" e o campo endToEndId preenchido é a evidência técnica de que a liquidação no SPI ocorreu.

Fluxo de confirmação de liquidação:

SPI (BCB) → Liquida LBTR → PSP recebedor (o banking da Celcoin) ↓ POST webhook → Empresa { status: "LIQUIDADA", endToEndId: "E..." } ↓ Empresa credita conta do usuário final

O crédito ao usuário final deve ocorrer somente após a recepção e validação do webhook com status de liquidação confirmada. Esse controle garante que nenhum valor seja creditado antes da finalização no SPI.

Garanta liquidação final no SPI com a participação direta da Celcoin no Banco Central.

Passo 5: implementar idempotência e controles de segurança

APIs modernas para Pix suportam idempotência por meio do cabeçalho X-Idempotency-Key em operações de escrita. A implementação correta exige alguns cuidados.

• Armazenar a chave de idempotência no banco de dados antes de chamar a API do provedor, usando UPSERT atômico, para que retentativas após timeout retornem o mesmo resultado sem criar cobranças duplicadas

• Deduplicar eventos de webhook armazenando o event_id do provedor com TTL de 86.400 segundos em Redis ou banco de dados e rejeitar duplicatas antes de aplicar efeitos colaterais

• Armazenar segredos de assinatura em gerenciadores dedicados, como AWS Secrets Manager ou HashiCorp Vault, e rotacioná-los com janela de validade sobreposta

• Configurar mTLS no endpoint de webhook, com verificação do certificado de cliente do provedor

• Criptografar payloads sensíveis em repouso com AES-256 em filas de retry e logs de auditoria

Erros comuns e boas práticas

• Webhook não validado: processar eventos sem verificar a assinatura HMAC expõe a integração a spoofing de eventos de pagamento, permitindo que atacantes forjem notificações falsas de liquidação. Para prevenir esse risco, sempre valide o cabeçalho X-Webhook-Signature sobre o corpo bruto antes de processar qualquer evento.

• Marcação prematura de pedidos como pagos: atualizar o status do pedido na leitura do QR Code, e não na confirmação de liquidação, gera inconsistências contábeis e risco operacional.

• Ausência de idempotência: o banking da Celcoin realiza tentativas de entrega de webhook, e sem deduplicação o mesmo pagamento pode ser creditado mais de uma vez.

• Processamento síncrono no handler do webhook: operações lentas no handler causam timeout no provedor e reentregas desnecessárias. A prática recomendada é retornar HTTP 200 imediatamente e processar o evento em fila assíncrona.

• Ausência de controle de estado: webhooks podem chegar fora de ordem, e uma máquina de estados com transições explícitas evita que um evento tardio sobrescreva um estado terminal.

Infraestrutura da Celcoin para integração Pix via BaaS

A infraestrutura da Celcoin como participante direto no Pix oferece recursos técnicos e regulatórios que reduzem o tempo de integração e o risco operacional para empresas que usam Banking as a Service.

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 que 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 melhoram o tempo para geração de receita.
Distribuição white-label e embutida (embedded)	Suporte a produtos financeiros com marca própria.
Escalabilidade com confiabilidade	Solução com alta disponibilidade e escalável na nuvem mantém serviços funcionando mesmo com altos volumes e protege a receita.
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 e melhoram conversão e retenção.
Compliance e conformidade como princípio	KYC, AML e relatórios integrados reduzem risco regulatório e aceleram 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, recursos e velocidade de entrada no mercado.

A Celcoin não oferece nenhum tipo de empréstimo para consumidores. A Celcoin fornece a infraestrutura tecnológica para que empresas consigam ofertar produtos de crédito aos seus clientes.

Critérios de sucesso e validação

Uma integração Pix via participação indireta é considerada estável quando atende a critérios de disponibilidade, segurança e aderência regulatória.

• Disponibilidade: conformidade com os requisitos operacionais do regulamento do Pix.

• Tempo de implementação: integrações via BaaS com documentação completa, SDKs e sandbox podem ser concluídas em poucas semanas.

• Aderência regulatória: conformidade com a Resolução BCB nº 1/2020, com as obrigações de PLD/FT da Resolução BCB 44/2021 e com a LGPD.

• Segurança: mTLS ativo, rotação de segredos implementada, deduplicação de eventos operacional e logs de auditoria com hash do corpo do webhook.

• Zero duplo crédito: nenhum evento de liquidação processado mais de uma vez, com verificação por meio da contagem de event_id únicos no Redis.

Próximos passos

Com a integração Pix via SPI estabilizada, a empresa pode expandir a oferta de serviços financeiros e automatizar processos internos.

• Open Finance: APIs modernas já suportam o objeto openFinance em transações de cash-in, o que habilita iniciação de pagamento com consentimento do usuário e personalização de ofertas com dados financeiros consentidos.

• Automação de reconciliação: pipelines que comparam cobranças locais com os relatórios do PSP e sinalizam discrepâncias de tipo missing_in_local ou amount_mismatch para investigação imediata.

• Novas modalidades Pix: o Banco Central prevê para 2026 o lançamento de cobrança híbrida, pagamento de duplicata e split tributário dentro do ecossistema Pix, o que exigirá atualização dos fluxos de webhook e reconciliação.

• Governança de relatórios regulatórios: automação de DIMP, CADOCs e CCS para participantes indiretos que evoluem para participação direta ou obtêm licença IP própria.

Expanda sua oferta com Open Finance e novas modalidades Pix usando a plataforma da Celcoin.

FAQ

Como validar o webhook de liquidação Pix?

A validação do webhook de liquidação Pix envolve três camadas. Primeiro, é necessário verificar o cabeçalho X-Webhook-Signature calculando um HMAC-SHA256 sobre o corpo bruto da requisição, usando o segredo compartilhado com o PSP, e comparar o resultado com função de tempo constante para evitar ataques de timing. Segundo, é preciso verificar o timestamp do evento e rejeitar qualquer mensagem cujo campo de data e hora esteja fora de uma janela de 5 minutos em relação ao horário do servidor, o que bloqueia replay attacks. Terceiro, a aplicação deve retornar HTTP 200 imediatamente após a verificação da assinatura e enfileirar o processamento de forma assíncrona para evitar timeout no provedor. O segredo de assinatura deve ficar em um gerenciador dedicado, como AWS Secrets Manager ou HashiCorp Vault, com rotação periódica e janela de validade sobreposta para não interromper entregas em andamento.

Qual a diferença entre confirmação PSP e liquidação SPI LBTR?

A confirmação no nível do PSP indica que o pagamento foi aceito, validado e processado internamente pelo provedor de serviços de pagamento. A liquidação LBTR, liquidação bruta em tempo real, no SPI é a transferência efetiva de fundos em dinheiro de banco central entre as reservas dos PSPs participantes, com finalidade irrevogável. No Pix, essas duas etapas ocorrem de forma praticamente simultânea, porque o SPI liquida cada transação individualmente em tempo real, de modo que a confirmação do usuário coincide com a liquidação interbancária final. A evidência técnica da liquidação SPI é o campo endToEndId preenchido no payload do webhook com status: "LIQUIDADA". Somente após receber e validar esse evento a empresa deve creditar o usuário final ou liberar o pedido.

É possível operar Pix sem Conta PI própria?

Sim. Como explicado anteriormente, a participação indireta permite acesso ao SPI por meio de um participante direto. O participante direto assume obrigações operacionais perante o Banco Central, enquanto a empresa parceira mantém obrigações contratuais bilaterais e deve cumprir normas de PLD/FT. Esse modelo é adequado para fintechs, ERPs e varejistas que desejam lançar Pix com liquidação em tempo real sem o custo e a complexidade de obter licença IP própria.

Quais obrigações do Banco Central se aplicam à participação indireta?

Na participação indireta, as obrigações operacionais diretas perante o Banco Central, como manutenção da Conta PI e reporte ao SPI, recaem sobre o participante direto. A empresa parceira assume obrigações contratuais negociadas bilateralmente com o participante direto e deve cumprir as normas de prevenção à lavagem de dinheiro e financiamento do terrorismo estabelecidas na Resolução BCB 44/2021 e na Lei 9.613/1998, incluindo obrigações de registro, comunicação ao COAF e controles em tempo real. A alocação contratual de responsabilidade por fraudes entre participante direto e indireto é o ponto mais crítico dessa relação e precisa estar detalhada no contrato bilateral. Empresas que evoluem para participação direta ou obtêm licença IP própria passam a assumir integralmente as obrigações regulatórias, incluindo relatórios como DIMP, CADOCs e CCS.