Como implementar API para Pix no seu negócio: guia completo

março 7, 2026

Última atualização: 26 de julho de 2026

Principais lições deste artigo

O Pix processou 79,8 bilhões de transações em 2025 e deve responder por 50% do e-commerce brasileiro até 2028, o que torna a integração de API para Pix um requisito básico para empresas.
Uma instituição sem licença própria de IP deve adotar o modelo Banking as a Service para entrar em produção em semanas, em vez de anos.
A Resolução BCB nº 457/2025 exige validação de CPF e CNPJ na Receita Federal e bloqueia chaves vinculadas a cadastros irregulares, o que impacta onboarding e split de pagamentos.
Boas práticas de segurança incluem mTLS com certificado ICP-Brasil, IP allowlist, validação de assinatura HMAC em webhooks e reconciliação diária via logs.
Para implementar API para Pix com segurança e conformidade, a empresa pode contar com a infraestrutura completa da Celcoin.

Por que o Pix se tornou essencial para empresas brasileiras?

O Pix já funciona como infraestrutura central de pagamentos para empresas brasileiras. Em dezembro de 2025, as transações B2B no Pix atingiram 263 milhões, com crescimento de 50,3% em relação a dezembro de 2024. No segundo semestre de 2025, as transações pessoa-para-empresa (P2B) superaram as transferências entre pessoas físicas pela primeira vez, o que mostra a consolidação do Pix em pagamentos corporativos.

O Pix Automático amplia ainda mais esse papel ao atender pagamentos recorrentes. Lançado em junho de 2025, o Pix Automático registrou crescimento de 182% no volume processado entre o quarto trimestre de 2025 e o primeiro trimestre de 2026. Esse recurso também abre acesso a aproximadamente 60 milhões de brasileiros sem cartão de crédito, o que amplia o mercado endereçável para empresas de SaaS e assinaturas.

O que é Pix, API para Pix, webhook, certificado digital, sandbox e homologação?

Dominar alguns conceitos básicos acelera a implementação da API para Pix e reduz retrabalho.

Pix: sistema de pagamentos instantâneos do Banco Central do Brasil, disponível 24 horas por dia, 7 dias por semana, com liquidação em segundos.
API para Pix: interface de programação que permite criar cobranças, consultar status e receber notificações de pagamento de forma automatizada, sem intervenção manual.
Endpoint /cob: recurso que cria cobranças imediatas com QR Code dinâmico e prazo de expiração configurável.
Endpoint /cobv: recurso que cria cobranças com vencimento, com suporte a multa, juros e desconto, adequado para boletos híbridos e faturas.
Webhook: notificação HTTP enviada pelo provedor ao sistema da empresa quando o status de uma cobrança muda, o que elimina a necessidade de polling.
Certificado digital ICP-Brasil: certificado x509 v3 de 2048 bits emitido por autoridade certificadora reconhecida, obrigatório para autenticação mTLS nas conexões com o ecossistema do Banco Central.
Sandbox: ambiente de testes isolado que simula transações sem movimentação financeira real, o que permite validar toda a integração antes da produção.
Homologação: processo formal de validação técnica e regulatória que antecede a entrada em produção.

Com esses conceitos estabelecidos, a empresa consegue entender como as regras de 2026 afetam cada etapa da jornada, do credenciamento à operação diária.

Quais são os requisitos regulatórios do Pix em 2026

A Resolução BCB nº 457/2025 exige que as instituições participantes do Pix validem a conformidade dos nomes com CPF e CNPJ da Receita Federal antes de registrar, alterar ou portar chaves Pix, bloqueando o registro de chaves vinculadas a CPFs com situação SUSPENSA, CANCELADA, TITULAR FALECIDO ou NULA e a CNPJs SUSPENSOS, INAPTOS, BAIXADOS ou NULOS. Essa exigência impacta diretamente o onboarding de clientes e a configuração de arranjos de split.

A Resolução BCB nº 506/2025 ajusta critérios de autorização para instituições de pagamento no Pix e redefine penalidades ligadas às regras de validação. A instituição que atua no Pix precisa revisar políticas internas e contratos à luz dessas mudanças.

A CMN 5.274/2025 e a BCB 538/2025, publicadas em dezembro de 2025 com prazo de conformidade em março de 2026, adicionam 14 controles de cibersegurança auditáveis, incluindo autenticação multifator obrigatória para acesso administrativo a ambientes Pix e STR, prevenção de vazamento de dados, segurança de APIs e monitoramento de credenciais na Dark Web e Deep Web. Esses controles passam a fazer parte do escopo de auditorias.

A partir de dezembro de 2025, as instituições também devem adotar monitoramento em tempo real de movimentações atípicas no Pix, o que exige ferramentas de detecção e resposta mais robustas.

Como abrir conta PJ e escolher provedor para Pix?

Uma empresa sem licença própria de Instituição de Pagamento não pode participar diretamente do Pix. Tornar-se participante direto exige investimentos e prazos significativos. O modelo Banking as a Service permite operar Pix em semanas, usando a licença e a infraestrutura regulatória de um provedor homologado.

Os critérios essenciais para escolher um provedor incluem:

Licença de Instituição de Pagamento ativa e participação direta no Pix.
Sandbox documentado com suporte a /cob, /cobv e webhooks.
Gestão de KYC, AML e relatórios regulatórios incluída.
SLA de disponibilidade compatível com operação 24/7.
Suporte técnico com acesso direto a especialistas.
Capacidade de escalar para Core Banking quando a empresa obtiver licença própria.

Como obter credenciais, configurar certificado e IP allowlist

O fluxo padrão de credenciamento segue uma sequência clara de etapas.

Abertura de conta PJ no provedor BaaS: envio de documentação, realização de KYC e assinatura de contrato.
Geração de credenciais sandbox: obtenção de Client ID e Client Secret para o ambiente de testes.
Emissão do certificado digital: uso de certificado x509 v3 de 2048 bits emitido por CA externa reconhecida, fornecido em formato PEM com cadeia completa, com root, intermediário e parceiro, para autenticação mTLS.
Configuração de IP allowlist: registro dos IPs de saída dos servidores da empresa no provedor, liberando chamadas aos endpoints de Cash-Out e a operações sensíveis.
Promoção para produção: repetição do processo com certificado de produção e credenciais definitivas após aprovação na homologação.

Como integrar os endpoints /cob e /cobv

A integração dos endpoints /cob e /cobv segue o mesmo padrão de autenticação, com ajustes apenas no payload e no escopo. Os exemplos abaixo utilizam autenticação OAuth 2.0 com mTLS. Substitua BASE_URL, CLIENT_ID, CLIENT_SECRET e os caminhos dos certificados pelos valores fornecidos pelo provedor BaaS.

Node.js, criação de cobrança imediata (/cob)

 const axios = require('axios'); const https = require('https'); const fs = require('fs'); const agent = new https.Agent({ cert: fs.readFileSync('./cert.pem'), key: fs.readFileSync('./key.pem'), ca: fs.readFileSync('./ca.pem'), }); async function getToken() { const res = await axios.post( `${process.env.BASE_URL}/oauth/token`, new URLSearchParams({ grant_type: 'client_credentials', client_id: process.env.CLIENT_ID, client_secret: process.env.CLIENT_SECRET, scope: 'cob.write cob.read', }), { httpsAgent: agent } ); return res.data.access_token; } async function criarCobranca(txid) { const token = await getToken(); const res = await axios.put( `${process.env.BASE_URL}/v2/cob/${txid}`, { calendario: { expiracao: 3600 }, devedor: { cpf: '12345678909', nome: 'João Silva' }, valor: { original: '100.00' }, chave: process.env.PIX_KEY, solicitacaoPagador: 'Pedido #1234', }, { headers: { Authorization: `Bearer ${token}` }, httpsAgent: agent, } ); return res.data; // contém pixCopiaECola e qrcode }

Python, criação de cobrança com vencimento (/cobv)

 import os, requests from datetime import date BASE_URL = os.environ["BASE_URL"] session = requests.Session() session.cert = ("cert.pem", "key.pem") session.verify = "ca.pem" def get_token(): r = session.post( f"{BASE_URL}/oauth/token", data={ "grant_type": "client_credentials", "client_id": os.environ["CLIENT_ID"], "client_secret": os.environ["CLIENT_SECRET"], "scope": "cobv.write cobv.read", }, ) r.raise_for_status() return r.json()["access_token"] def criar_cobranca_vencimento(txid: str): token = get_token() payload = { "calendario": { "dataDeVencimento": str(date.today()), "validadeAposVencimento": 30, }, "devedor": { "cnpj": "12345678000195", "nome": "Empresa ABC Ltda", }, "valor": { "original": "500.00", "multa": {"modalidade": 2, "valorPerc": "2.00"}, "juros": {"modalidade": 2, "valorPerc": "1.00"}, }, "chave": os.environ["PIX_KEY"], "solicitacaoPagador": "Fatura #5678", } r = session.put( f"{BASE_URL}/v2/cobv/{txid}", json=payload, headers={"Authorization": f"Bearer {token}"}, ) r.raise_for_status() return r.json()

Como configurar e validar webhook com verificação de assinatura

A validação correta do webhook garante que apenas notificações legítimas atualizem o sistema. A autenticidade do webhook deve ser validada com o recálculo da assinatura HMAC a partir do corpo bruto da requisição e comparação com o cabeçalho X-Signature, rejeitando requisições com assinatura divergente.

Node.js, validação de assinatura de webhook

 const express = require('express'); const crypto = require('crypto'); const app = express(); app.use(express.raw({ type: 'application/json' })); app.post('/webhook/pix', (req, res) => { const secret = process.env.WEBHOOK_SECRET; const signature = req.headers['x-signature']; const expected = crypto .createHmac('sha256', secret) .update(req.body) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { return res.status(401).send('Assinatura inválida'); } const event = JSON.parse(req.body); // processar event.pix[0].status res.status(200).send('OK'); });

Python, validação de assinatura de webhook

 import os, hmac, hashlib from flask import Flask, request, abort app = Flask(__name__) @app.post("/webhook/pix") def webhook_pix(): secret = os.environ["WEBHOOK_SECRET"].encode() signature = request.headers.get("X-Signature", "") expected = hmac.new(secret, request.get_data(), hashlib.sha256).hexdigest() if not hmac.compare_digest(signature, expected): abort(401) event = request.get_json(force=True) # processar event["pix"][0]["status"] return "OK", 200

Checklist de homologação para produção

Uma checklist objetiva reduz falhas na promoção para produção e evita retrabalho com o provedor. Antes de solicitar a promoção para o ambiente de produção, valide todos os itens abaixo.

Chave Pix registrada e associada à conta PJ no provedor.
Fluxo completo de /cob testado, com criação, consulta e expiração.
Fluxo completo de /cobv testado, com criação e aplicação de multa, juros e desconto.
Webhook recebido e assinatura validada com sucesso.
Tratamento de erros HTTP 400, 401, 403 e 404 implementado.
Idempotência garantida com reutilização do mesmo txid em retentativas.
IP allowlist configurado para todos os servidores de produção.
Certificado de produção instalado e mTLS funcionando.
Validação de CPF e CNPJ na Receita Federal integrada ao onboarding.
Consulta ao BC Protege+ implementada antes do processamento de transações.

Quais são as boas práticas de segurança, escalabilidade e conformidade

Uma arquitetura de Pix segura combina controles de transporte, autenticação forte e processos operacionais consistentes. As práticas padrão para APIs para Pix incluem HTTPS obrigatório, autenticação OAuth 2.0, IP allowlist para endpoints de Cash-Out e verificação de assinatura HMAC nos webhooks.

Além desses fundamentos, vale estruturar controles em camadas que se reforçam. Definir limites diários e noturnos de transação, criar listas de beneficiários aprovados e implementar o modelo Maker-Checker com segregação de funções reduz a superfície de ataque operacional. Realizar testes de penetração anuais independentes com retenção de evidências por cinco anos, conforme a CMN 5.274/2025 valida a eficácia desses controles.

Executar reconciliação diária, confirmando cada Pix liquidado via logs de webhook e comparando resumos diários com os outputs do provedor e do SPB, garante que nenhuma transação passe sem registro. Armazenar segredos de webhook em cofres de credenciais, e não em variáveis de ambiente não criptografadas, protege o segredo que sustenta a verificação de assinatura. Implementar monitoramento de credenciais na Dark Web e Deep Web, conforme exigido pela BCB 538/2025, fecha o ciclo de proteção com foco em detecção de comprometimento.

Implemente essas práticas de segurança com a infraestrutura completa da Celcoin.

Quais erros comuns evitar ao implementar API para Pix?

Evitar erros recorrentes em integrações de API para Pix reduz incidentes em produção e esforço de suporte. Os pontos abaixo reúnem falhas frequentes e formas de correção.

Contas-bolsão: operar recursos de terceiros em contas não individualizadas é irregular e vedado pelas normativas do Banco Central. A empresa deve utilizar sempre infraestrutura com contas segregadas por titular.
IPs não autorizados: chamadas a endpoints de Cash-Out sem IP allowlist configurado resultam em erros 403. O time de tecnologia precisa registrar todos os IPs de produção antes do go-live.
Webhook sem validação de assinatura: aceitar callbacks sem verificar o HMAC expõe o sistema a callbacks falsos e payloads adulterados.
Novo txid em retentativas: gerar um novo endToEndId em retentativas após timeout causa lançamentos duplicados no ledger, por isso a integração deve reutilizar sempre o mesmo txid.
Tratar 200 OK como confirmação final: a resposta 200 confirma apenas que a requisição entrou em orquestração, e o status definitivo vem pelo webhook, o que exige lógica de confirmação baseada no evento assíncrono.
Chave Pix não registrada antes de cobranças: tentar pagar um QR Code sem chave Pix registrada na conta retorna erro 404, o que torna o registro prévio da chave um passo obrigatório.
CNPJ inapto em arranjos de split: credenciadoras e subcredenciadoras devem garantir que os CNPJs dos vendedores em arranjos de split mantenham status cadastral regular, sob risco de bloqueio e sanções.

Evite esses erros comuns com o suporte técnico especializado da Celcoin.

Como ERPs, marketplaces e varejistas podem usar Pix?

Cada segmento pode explorar a API para Pix de forma diferente para gerar receita e eficiência operacional.

ERPs: emissão automática de cobranças /cobv com vencimento, multa e juros integradas ao fluxo de contas a receber. A conciliação automática via webhook elimina lançamentos manuais.
Marketplaces: split de pagamento entre vendedores com validação de CNPJ em tempo real. A liquidação instantânea reduz o ciclo financeiro dos lojistas.
Varejistas de grande porte: o Pix Automático permite cobranças recorrentes de assinaturas e programas de fidelidade com custos até 14 vezes menores que cartões. O Pix por Aproximação expande os canais de aceitação nas lojas físicas.
Fintechs: emissão de cobranças dinâmicas para carteiras digitais, com webhook em tempo real para atualização de saldo e liberação de serviços.

Celcoin: infraestrutura completa para Pix via Banking as a Service

O banking da Celcoin oferece infraestrutura regulatória e tecnológica para empresas que desejam operar Pix e outros serviços financeiros sem licença própria. A Celcoin atua como participante direta no Pix e disponibiliza APIs modulares para que fintechs, bancos digitais, ERPs, marketplaces e varejistas integrem Pix, contas digitais, cartões e outros serviços sob a licença de Instituição de Pagamento da Celcoin.

Essas empresas lançam produtos financeiros com marca própria, enquanto a Celcoin gerencia internamente a complexidade de compliance, KYC, AML e relatórios regulatórios. A Celcoin media mais de R$ 30 bilhões em transações mensalmente e atende mais de 6 mil clientes. A tabela abaixo resume as principais funcionalidades da plataforma e como cada uma se traduz em benefícios práticos para a operação.

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 custos de engenharia.
Capacidade de lançamento rápido	Módulos pré-construídos e entrega via SaaS aceleram lançamentos, melhorando o tempo para geração de receita e a competitividade.
Distribuição white-label e embutida	Suporte a produtos financeiros com marca própria.
Escalabilidade com confiabilidade	Solução com alta disponibilidade e escalável na nuvem, que mantém serviços funcionando mesmo com altos volumes e protege a receita.
Cobertura de diversas possibilidades de pagamentos, incluindo crédito	Oferta de pagamentos e emissão de crédito aumenta conversão, ARPU e fidelização. A Celcoin não oferece empréstimo para consumidores, mas fornece a infraestrutura tecnológica para que empresas ofertem produtos de crédito aos seus clientes.
Acesso a dados e personalização	Dados e análises via Open Finance permitem ofertas personalizadas, com impacto direto em 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.
Conectividade com Open Finance	Integração com o ecossistema Open Finance para enriquecimento de dados e ofertas personalizadas.

Perguntas frequentes

O que é uma API para Pix?

Uma API para Pix é uma interface de programação que permite criar cobranças, consultar status de transações e receber notificações de pagamento de forma automatizada. Ela elimina a necessidade de intervenção manual em cada etapa do fluxo financeiro e conecta o sistema da empresa diretamente ao ecossistema Pix.

Uma empresa sem licença de Instituição de Pagamento pode usar o Pix?

Sim. Pelo modelo Banking as a Service, a empresa opera Pix usando a licença e a infraestrutura regulatória de um provedor homologado. Esse modelo permite entrar em produção em semanas, sem os investimentos e prazos exigidos para obter licença própria junto ao Banco Central.

Quais são os principais requisitos de segurança para APIs para Pix em 2026?

A CMN 5.274/2025 e a BCB 538/2025 exigem autenticação multifator para acesso administrativo, testes de penetração anuais com retenção de evidências por cinco anos e monitoramento de credenciais na Dark Web e Deep Web. Além disso, as boas práticas incluem mTLS com certificado ICP-Brasil, IP allowlist para endpoints de Cash-Out e validação de assinatura HMAC em todos os webhooks.

O que é o Pix Automático e para quais empresas ele é relevante?

O Pix Automático é uma funcionalidade para cobranças recorrentes, lançada em junho de 2025. Ele é especialmente relevante para empresas de SaaS, assinaturas e varejistas com programas de fidelidade, pois permite cobrar clientes de forma recorrente com custos até 14 vezes menores que cartões e alcança cerca de 60 milhões de brasileiros sem cartão de crédito.

Como funciona a validação de webhook no Pix?

O provedor envia uma notificação HTTP ao endpoint da empresa sempre que o status de uma cobrança muda. A empresa deve recalcular a assinatura HMAC a partir do corpo bruto da requisição e comparar com o valor recebido no cabeçalho X-Signature. Requisições com assinatura divergente devem ser rejeitadas para evitar callbacks falsos e payloads adulterados.

A Resolução BCB nº 457/2025 afeta o onboarding de clientes?

Sim. A resolução exige que as instituições participantes do Pix validem a conformidade dos nomes com CPF e CNPJ da Receita Federal antes de registrar, alterar ou portar chaves Pix. Cadastros com situação irregular ficam impedidos de registrar chaves, o que impacta diretamente o fluxo de onboarding e a configuração de arranjos de split de pagamento.

Conclusão

O Pix consolidou-se como infraestrutura central de pagamentos para empresas brasileiras. O crescimento do volume B2B, a expansão do Pix Automático e as exigências regulatórias de 2026 tornam a integração de API para Pix um requisito técnico e estratégico para empresas que operam no mercado brasileiro.

Implementar essa integração com segurança exige domínio de autenticação mTLS, validação de webhooks, idempotência e conformidade com as resoluções BCB nº 457/2025, BCB nº 506/2025, CMN 5.274/2025 e BCB 538/2025. Cada um desses pontos representa um risco real em produção quando tratado de forma inadequada.

O banking da Celcoin oferece a infraestrutura regulatória e tecnológica para que fintechs, bancos digitais, ERPs, marketplaces e varejistas operem Pix com conformidade e segurança, sem licença própria. Conheça a infraestrutura completa da Celcoin e reduza o tempo de integração com suporte técnico especializado.

The best service for growth Infratech financeira para potencializar negócios

Oferecemos uma infraestrutura completa e pioneira para conectar empresas de todos os segmentos a oportunidades do mercado financeiro, com soluções incorporadas às necessidades de seus clientes.

Contratar