Como integrar Pix via plataforma BaaS no Brasil

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

Principais lições deste artigo

• Integrar Pix via BaaS regulado elimina a necessidade de licenças próprias e conexão direta com o SPI, o que reduz custos e acelera a entrada no mercado.

• As Resoluções BCB nº 518/2025 e CMN nº 5.261/2025 tornaram obrigatório o uso de contas individualizadas por titular, o que torna essencial escolher um parceiro BaaS em conformidade.

• Boas práticas de segurança, como armazenar credenciais em cofres de segredos e validar assinaturas de webhooks, são indispensáveis para evitar fraudes e duplicidade de transações.

• Uma integração bem-sucedida exige testes completos de cash-in, cash-out, reconciliação via end_to_end_id e validação de relatórios regulatórios antes de entrar em produção.

• Para acelerar sua integração Pix com APIs modulares, compliance automatizado e suporte especializado, acesse a plataforma da Celcoin.

Fintechs, ERPs e varejistas que precisam oferecer pagamentos instantâneos enfrentam uma escolha: conectar-se diretamente ao Sistema de Pagamentos Instantâneos do Banco Central, com licença própria, infraestrutura dedicada e equipe de compliance, ou integrar via plataforma Banking as a Service regulada, que fornece acesso ao Pix em semanas. Este guia apresenta o segundo caminho e descreve o fluxo completo de integração, da escolha do parceiro à entrada em produção, com foco em segurança, conformidade e operação diária.

1. Visão geral do processo de integração

Integrar Pix via BaaS segue um fluxo técnico previsível. A empresa escolhe o parceiro, conclui o onboarding regulatório, configura credenciais em sandbox, cria chaves Pix e cobranças, implementa webhooks, realiza homologação em produção e estrutura o fluxo de cash-out e reconciliação. Cada etapa reduz riscos operacionais e garante aderência às normas do Banco Central.

2. Escolha e onboarding na plataforma BaaS

A escolha do parceiro BaaS determina a velocidade de entrada no mercado e o nível de exposição regulatória. Os critérios essenciais de avaliação cobrem três dimensões: capacidade regulatória, capacidade técnica e capacidade operacional. Avalie cada parceiro nestes pontos:

• Licença de Instituição de Pagamento (IP) ativa junto ao Banco Central, com participação direta no Pix

• Conformidade com as Resoluções BCB nº 518/2025 e CMN nº 5.261/2025, garantindo contas individualizadas por titular

• Cobertura de KYC/AML automatizada, com relatórios para o Coaf e e-Financeira, obrigatórios para instituições de pagamento desde janeiro de 2025

• APIs modulares com documentação completa, sandbox e SDKs disponíveis

• Suporte técnico com acesso direto a especialistas

Durante o onboarding, o parceiro BaaS conduz o processo de KYC/AML da empresa contratante e verifica a legitimidade da estrutura societária e do modelo de negócio. Os documentos exigidos refletem essas duas frentes: contrato social ou estatuto atualizado e documentos dos sócios e administradores comprovam a estrutura legal. Comprovante de endereço da pessoa jurídica e informações sobre o modelo de negócio e fluxo de pagamentos esperado permitem avaliar o perfil de risco operacional. O tempo médio de aprovação varia de alguns dias a algumas semanas, conforme a complexidade societária e a completude da documentação.

3. Configuração de credenciais no sandbox

Após a aprovação do onboarding, o parceiro BaaS disponibiliza as credenciais de acesso ao ambiente de sandbox. O fluxo padrão envolve obter um Client ID e um Client Secret no painel do desenvolvedor e gerar tokens de acesso por OAuth 2.0.

Boas práticas de segurança nesta etapa formam uma estratégia de defesa em camadas:

• Armazenar Client ID e Client Secret exclusivamente em cofres de segredos, nunca em repositórios de código-fonte, onde quase 13 milhões de segredos de API foram expostos publicamente em um único ano

• Rotacionar credenciais periodicamente e revogar imediatamente em caso de suspeita de comprometimento

• Usar variáveis de ambiente ou serviços como AWS Secrets Manager ou HashiCorp Vault para centralizar o controle

• Aplicar HTTPS/TLS em todas as chamadas, sem exceção, para proteger dados em trânsito

4. Criação de chaves Pix e QR Codes via API

Com as credenciais de sandbox configuradas e armazenadas de forma segura, a empresa está pronta para interagir com a API para Pix. O primeiro passo operacional é registrar chaves Pix, que são os identificadores usados pelos clientes para receber pagamentos, e gerar cobranças.

O Banco Central limita as contas a 5 chaves para pessoas físicas e 20 chaves para pessoas jurídicas. Chaves do tipo EVP (Endereço Virtual de Pagamento) são geradas automaticamente pela plataforma BaaS.

Exemplo de geração de cobrança Pix (cash-in) em Node.js:

// Node.js, geração de cobrança Pix via BaaS const axios = require('axios'); async function criarCobrancaPix(token, valor, chave) { const response = await axios.post( 'https://api.baas-parceiro.com.br/pix/cashIn', { valor: valor, // em centavos chave_pix: chave, expiracao: 3600 // segundos }, { headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' } } ); return response.data; // retorna qrCode e paymentCode } 

Exemplo equivalente em Python:

# Python, geração de cobrança Pix via BaaS import requests def criar_cobranca_pix(token: str, valor: int, chave: str) -> dict: url = "https://api.baas-parceiro.com.br/pix/cashIn" headers = { "Authorization": f"Bearer {token}", "Content-Type": "application/json", } payload = { "valor": valor, # em centavos "chave_pix": chave, "expiracao": 3600, # segundos } response = requests.post(url, json=payload, headers=headers) response.raise_for_status() return response.json() # retorna qrCode e paymentCode 

A resposta inclui o QR Code estático ou dinâmico e o código copia-e-cola. O pagador escaneia o código em seu aplicativo bancário e a liquidação ocorre em tempo real via SPI.

5. Configuração e validação de webhooks

Webhooks são o mecanismo pelo qual a plataforma BaaS notifica o sistema da empresa sobre eventos de pagamento. O acesso a status de transação em tempo real é um dos principais diferenciais operacionais do modelo BaaS em relação à integração direta com o SPI.

O fluxo de configuração segue estas etapas:

1. Registrar a URL de webhook no painel ou via API do parceiro BaaS, apontando para um endpoint HTTPS público da empresa

2. Configurar a validação de assinatura, em que o parceiro BaaS envia um cabeçalho de assinatura, como X-Webhook-Signature, que deve ser verificado com a chave pública fornecida antes de processar qualquer evento

3. Responder com HTTP 200 em até 5 segundos para confirmar o recebimento, pois falhas geram reenvios automáticos

4. Implementar idempotência usando o end_to_end_id do evento para evitar processamento duplicado

O payload padrão de um evento Pix contém o id da transação, o valor, o status, como paid ou canceled, e o end_to_end_id, que é o identificador único gerado pelo SPI para rastreabilidade e reconciliação.

Explore a plataforma Celcoin para implementar webhooks seguros e reconciliação automatizada.

6. Homologação em produção

Com chaves Pix criadas, cobranças geradas e webhooks configurados para notificar o sistema em tempo real, a integração em sandbox fica completa. A transição para produção exige validar que todos esses componentes funcionam corretamente com transações reais e cumprir os requisitos de homologação do parceiro BaaS.

A conta da empresa deve estar 100% aprovada e a prova de vida concluída antes de a funcionalidade de criação de chaves Pix ser habilitada em produção.

A lista de verificação para homologação inclui:

• Realizar testes de cash-in com valores reais e verificar o crédito na conta

• Realizar testes de cash-out com validação de chave no DICT e confirmação de débito

• Simular falhas, como chave inexistente, saldo insuficiente e timeout de webhook

• Verificar os limites de chaves Pix por tipo de conta, pessoa física ou jurídica

• Confirmar que os relatórios regulatórios, como e-Financeira e Coaf, estão sendo gerados corretamente pelo parceiro BaaS

7. Cash-out via DICT e reconciliação

Após dominar o fluxo de cash-in, que trata do recebimento de pagamentos, a integração completa exige implementar o cash-out, que é a capacidade de enviar pagamentos Pix para terceiros. O cash-out Pix utiliza o Diretório de Identificadores de Contas Transacionais, o DICT, para validar a chave do destinatário antes de executar a transferência.

O fluxo padrão de cash-out é receber a chave Pix do destinatário, validar os dados via DICT, iniciar a ordem de transferência na API do parceiro BaaS e aguardar confirmação via webhook ou consulta de status, com liquidação geralmente instantânea.

Para reconciliação, cada transação carrega um end_to_end_id único gerado pelo SPI. A empresa deve armazenar esse identificador em seu banco de dados e utilizá-lo para cruzar eventos de webhook com registros internos. Plataformas BaaS fornecem ferramentas de reconciliação detalhadas que aproveitam a visibilidade em tempo real mencionada anteriormente, o que reduz o esforço de desenvolvimento interno de relatórios de liquidação.

Erros comuns e boas práticas

Os erros mais frequentes em integrações Pix via BaaS se concentram em segurança de credenciais, validação de eventos e conformidade regulatória.

• Credenciais em código-fonte: usar sempre cofres de segredos e variáveis de ambiente para proteger Client ID e Client Secret

• Ausência de validação de assinatura no webhook: processar eventos sem verificar a assinatura expõe o sistema a injeção de dados falsos

• Falta de idempotência: sem controle por end_to_end_id, reenvios de webhook geram créditos ou débitos duplicados

• Chave Pix criada antes da prova de vida: a plataforma BaaS gera uma chave temporária que pode causar atrasos no processamento

• Operar no modelo de conta-bolsão: prática proibida pelas resoluções de 2025 sobre individualização de contas, sujeita a encerramento compulsório de conta

• Ignorar rate limiting: aplicar rate limiting em todos os endpoints é prática essencial de segurança para APIs em produção

Critérios de sucesso e validação

Algumas métricas indicam se a integração Pix via BaaS está madura e confiável.

• Tempo de implementação: integrações via BaaS com APIs bem documentadas podem ser concluídas em semanas

• Disponibilidade do serviço: monitorar uptime do endpoint de cobrança e do webhook receiver, com meta mínima de 99,9%

• Taxa de reconciliação: 100% das transações liquidadas devem ter end_to_end_id registrado e cruzado com o extrato do parceiro BaaS

• Conformidade regulatória: manter zero notificações de irregularidade do Banco Central relacionadas a contas-bolsão ou ausência de relatórios obrigatórios

• Latência de webhook: processar eventos de pagamento e refletir o saldo do usuário final em menos de 5 segundos após a liquidação no SPI

FAQ

Quanto tempo leva para integrar Pix via BaaS e entrar em produção?

O prazo varia conforme a complexidade da estrutura da empresa e a completude da documentação entregue no onboarding. Com documentação completa e equipe técnica dedicada, algumas empresas concluem a integração e entram em produção em uma semana. Estruturas societárias mais complexas ou integrações com sistemas legados podem levar até três meses. A Celcoin disponibiliza documentação, SDKs e sandbox para reduzir esse ciclo.

Qual é o custo de integrar Pix via plataforma BaaS?

O modelo de remuneração da Celcoin é centrado em transações, sem custo de setup inicial elevado. Esse modelo reduz barreiras de entrada e permite que a empresa escale o custo conforme o volume de transações cresce. Não há necessidade de investimento em licenças próprias, infraestrutura de conexão com o SPI ou equipe especializada em compliance regulatório.

É possível migrar de outra infraestrutura para a Celcoin sem interromper as operações?

Sim. A Celcoin possui equipe dedicada para suporte à migração, com acompanhamento técnico em todas as etapas. O processo é planejado para minimizar impacto operacional, e a empresa mantém a mesma base tecnológica ao longo de toda a jornada, desde o uso das licenças da Celcoin no modelo BaaS até a eventual migração para licença própria com Core Banking.

O que são contas-bolsão e por que representam risco regulatório?

Contas-bolsão são estruturas em que recursos de terceiros são movimentados por uma conta sem individualização por titular, o que impede a rastreabilidade dos fundos. As resoluções mencionadas anteriormente tornaram obrigatório o encerramento de contas utilizadas nesse modelo. A Celcoin opera com contas individualizadas por titular, em conformidade com as normas vigentes, e elimina esse risco para as empresas que utilizam sua plataforma.

A Celcoin oferece suporte técnico durante e após a integração?

Sim. A Celcoin oferece suporte técnico especializado com acesso direto a decisores, tanto durante o processo de integração quanto após a entrada em produção. Em caso de incidentes, a equipe age rapidamente para minimizar o impacto no usuário final. Esse modelo de atendimento é relevante para fintechs, ERPs e varejistas que não podem tolerar longos períodos de indisponibilidade em serviços de pagamento.

Conclusão

Integrar Pix via plataforma BaaS regulada é um caminho eficiente para fintechs, ERPs e varejistas que precisam oferecer pagamentos instantâneos sem os custos e a complexidade de uma conexão direta com o Banco Central. O processo segue um fluxo técnico claro, do onboarding e configuração de credenciais à criação de chaves, configuração de webhooks, homologação e reconciliação via DICT, e pode ser concluído em semanas com o parceiro certo. As atualizações regulatórias de 2025 e 2026 tornam ainda mais crítica a escolha de um parceiro BaaS que já opere com contas individualizadas e compliance automatizado.

A Celcoin reúne licença de IP, participação direta no Pix, APIs modulares, KYC/AML integrado e suporte especializado em uma única plataforma, atendendo mais de 6 mil clientes e mediando mais de R$ 30 bilhões em transações mensalmente.

Conheça a solução completa da Celcoin para integração Pix via BaaS.