API PIX: guia técnico completo para integrar cobranças no seu sistema

Mais de 160 milhões de brasileiros usam o Pix. O Banco Central reporta rotineiramente mais de 160 milhões de transações em um único dia. Mas se você opera um e-commerce, um ERP ou um sistema SaaS, o Pix de pessoa física não resolve o seu problema. Receber comprovante pelo WhatsApp e dar baixa manual no sistema é amadorismo. Custa tempo, gera falhas humanas e impede o ganho de escala da sua operação.

A verdadeira revolução do dinheiro em tempo real no Brasil acontece nos bastidores, através da API Pix padronizada pelo Banco Central. Quando automatizamos o fluxo de cobrança — gerando QR Codes dinâmicos sob demanda e recebendo confirmações via webhook em frações de segundo —, o impacto no caixa é brutal. O custo de aceitação cai de 2,5% a 3% (cartão de crédito) para alguns centavos por transação, e o dinheiro cai na conta em D+0.

Nós, da Ouro Capital, acompanhamos o desenvolvimento da infraestrutura do Sistema de Pagamentos Instantâneos (SPI) desde o dia zero. Vimos gigantes como Mercado Pago e adquirentes como Stone e PagSeguro adaptarem seus balcões para essa nova realidade. Hoje, vamos abrir a caixa preta. Este é o guia definitivo para você plugar o seu sistema diretamente na veia do Pix.

O que é a API Pix Padronizada pelo Banco Central?

Antes de colocar a mão no código, precisamos alinhar os conceitos. Nos primeiros meses do Pix, no final de 2020, cada banco e fintech criava sua própria API. Era um caos. Se você integrasse com o Itaú e depois quisesse mudar para o BTG Pactual ou para a Efí (antiga Gerencianet), precisava reescrever todo o módulo de pagamento do seu software.

O BACEN cortou esse mal pela raiz com o Manual de Padrões para Iniciação do Pix. A regra virou clara: todo PSP (Provedor de Serviços de Pagamento) participante do Pix que oferece contas para pessoas jurídicas é obrigado a expor uma API padronizada.

Na prática, os endpoints, o formato do JSON, os nomes dos campos e a arquitetura de webhooks são exatamente os mesmos. O que muda de um banco para outro são apenas a URL base (Base URL) e as credenciais de acesso. Você escreve o código uma vez e ganha a liberdade de trocar de fornecedor bancário quando quiser negociar taxas menores.

A barreira de entrada: Entendendo o mTLS (Mutual TLS)

Se você está acostumado a consumir APIs REST passando apenas um Bearer Token no cabeçalho HTTP, prepare-se para subir o nível. O sistema financeiro exige uma camada extra de proteção chamada mTLS, ou TLS Mútuo.

Essa é a principal dor de cabeça dos desenvolvedores na primeira integração. No TLS comum (o cadeado verde do seu navegador), apenas o servidor prova quem ele é. No mTLS, a verificação ocorre dos dois lados. O servidor do banco verifica a identidade do seu servidor antes mesmo de olhar para o seu token OAuth2 ou para o payload da requisição.

Como funciona na prática

Você precisa gerar um certificado digital (geralmente emitido pelo próprio banco no painel da sua conta PJ). Esse certificado atrela a sua aplicação ao seu CNPJ e à sua chave Pix.

O arquivo costuma vir em formatos como .pem ou .p12. Você deve acoplar esse certificado no nível do cliente HTTP da sua aplicação. Se a requisição bater no firewall do banco sem o certificado mTLS válido, a conexão é derrubada instantaneamente no handshake TCP/IP. O servidor do banco nem chega a processar o HTTP. Você recebe um erro genérico de rede, o que deixa muitos programadores perdidos.

Configurando o certificado no código

Para ilustrar, veja como configuramos um agente HTTP no Node.js usando a biblioteca nativa https e o Axios.

const fs = require('fs');
const https = require('https');
const axios = require('axios');

const certificado = fs.readFileSync('./certificado-banco.pem');

const httpsAgent = new https.Agent({
  cert: certificado,
  key: certificado,
  rejectUnauthorized: true
});

const apiPix = axios.create({
  baseURL: 'https://api.banco.com.br/pix/api/v2',
  httpsAgent
});

Esse pequeno bloco de código é o passaporte para o SPI. Sem ele, nada feito.

Passo a Passo da Integração (O Código)

A jornada de uma cobrança Pix automatizada segue três etapas imutáveis: autenticação, geração da cobrança e recebimento do webhook.

1. Autenticação (OAuth2 + mTLS)

Com o túnel mTLS estabelecido, você precisa trocar o seu client_id e client_secret (fornecidos pelo banco) por um token de acesso. O padrão exigido pelo BACEN é o OAuth2 com o grant type client_credentials.

Você faz um POST para o endpoint /oauth/token passando as credenciais encodadas em Base64 no header de autorização (Basic Auth). O banco retorna um JWT (JSON Web Token) válido por um tempo limitado, geralmente 3600 segundos (uma hora).

2. Criando uma cobrança imediata (Cob)

O BACEN divide as cobranças em duas categorias principais: cob (Cobrança Imediata) e cobv (Cobrança com Vencimento, que funciona como um boleto bancário, calculando juros e multa). Para um e-commerce ou PDV de loja física, usamos o /cob.

Você envia um POST para o endpoint /cob (ou PUT /cob/{txid} se quiser forçar o seu próprio ID de transação). O payload é simples e elegante:

{
  "calendario": {
    "expiracao": 3600
  },
  "valor": {
    "original": "150.50"
  },
  "chave": "seu-cnpj-ou-chave-aleatoria@banco.com.br",
  "solicitacaoPagador": "Pedido #9982 - Loja Ouro Capital"
}

O banco processa essa requisição e devolve um JSON riquíssimo. O campo mais valioso dessa resposta é o pixCopiaECola (a string do padrão EMV, também conhecida como BR Code). É essa string gigante, começando com 000201..., que você deve transformar em uma imagem de QR Code na tela do seu cliente.

3. O QR Code e o Copia e Cola

Nunca tente montar a string EMV na mão. Deixe que o banco (PSP) retorne a string pronta. O seu único trabalho no front-end é usar uma biblioteca de renderização (como qrcode.react ou similar) para pegar a string recebida da API e desenhar os quadrados pretos e brancos na tela.

Lembre-se da usabilidade brasileira: a maioria dos usuários compra pelo celular. Escanear um QR Code na mesma tela em que se navega é impossível. Por isso, sempre exiba um botão generoso de "Copiar Código Pix" atrelado à string EMV.

Webhooks: O jeito certo de saber que o dinheiro caiu

Aqui separamos os amadores dos profissionais. Como o seu sistema sabe que o cliente abriu o app do Nubank, escaneou o código e digitou a senha?

A abordagem ingênua é o polling: programar o seu servidor para ficar batendo no endpoint /cob/{txid} a cada 5 segundos perguntando "já pagou? já pagou?". Não faça isso. Os bancos impõem raté limits severos. O BACEN odeia polling porque sobrecarrega a infraestrutura nacional.

A abordagem correta exigida pela arquitetura do Pix é o Webhook.

Configurando o Webhook via API

Você cria um endpoint no seu próprio servidor (ex: https://api.suaempresa.com.br/pix/webhook). Esse seu endpoint precisa ter um certificado SSL válido (HTTPS).

Em seguida, você faz um PUT na API do banco (endpoint /webhook/{chave}) informando a sua URL. Você diz ao banco: "Sempre que alguém pagar um Pix para esta chave, mande um POST para esta URL".

Quando o pagamento é liquidado no SPI do Banco Central (o que leva cerca de 2 a 3 segundos), o banco envia um payload para o seu servidor contendo os dados da transação, incluindo o txid e o valor pago. O seu sistema recebe esse JSON, cruza com o banco de dados interno e muda o status do pedido para "Pago". A liberação do produto ou serviço acontece em tempo real, sem intervenção humana.

Segurança no Webhook

Você não pode aceitar requisições de qualquer lugar no seu webhook, senão um invasor poderia simular pagamentos enviando POSTs falsos para a sua URL. O BACEN exige que o envio do webhook pelo banco também útilize mTLS.

O seu servidor web (Nginx, Apache ou o seu API Gateway) deve ser configurado para exigir e validar o certificado digital do banco durante o handshake da conexão de entrada. Somente se o certificado bater, o payload do webhook é aceito.

Implicações Práticas para o seu Negócio

Dominar essa integração muda a economia unitária da sua empresa. Observamos que negócios com alto volume de transações de baixo ticket (microtransações, SaaS, delivery) são os maiores beneficiados.

Compare a matemática. Se você vende um software por R$ 50,00 e cobra no cartão de crédito, vai deixar cerca de R$ 1,50 a R$ 2,50 na mesa (taxa percentual + custo fixo da transação), além de esperar 30 dias para receber (ou pagar uma taxa absurda de antecipação).

Com a API Pix configurada diretamente com um banco ou fintech agressiva (como Itaú Empresas, Inter, Efí ou Mercado Pago), você paga uma tarifa fixa que hoje oscila entre R$ 0,50 e R$ 1,50 por transação aprovada. O dinheiro cai na mesma hora. O impacto no Capital de Giro (Working Capital) permite reinvestimento imediato em marketing ou estoque.

Além disso, o risco de chargeback (fraude onde o cliente cancela a compra no cartão) cai para zero. O Pix, uma vez liquidado, é irreversível no fluxo padrão (excluindo-se o Mecanismo Especial de Devolução - MED, que atua apenas em casos comprovados de fraude estrutural, e não em disputas comerciais).

O Futuro: Pix Automático e Cobrança com Vencimento (CobV)

Se você acha que o ecossistema está estabilizado, reveja seus conceitos. O BACEN continua empurrando a fronteira da inovação.

A integração que detalhamos acima cobre 90% dos casos de uso atuais. Mas a API Pix já contempla o cobv (Cobrança com Vencimento), que permite configurar abatimentos, juros mora diários e multas, substituindo integralmente o boleto bancário registrado.

Mais do que isso: o mercado aguarda ansiosamente o lançamento do Pix Automático, previsto no cronograma oficial do Banco Central para o final de 2024 ou início de 2025. Essa nova modalidade permitirá débitos recorrentes diretamente na conta do usuário, mediante uma autorização prévia.

Será o fim da dependência da tokenização de cartões de crédito para academias, escolas, clubes de assinatura e serviços de streaming. A arquitetura técnica para interagir com o Pix Automático será construída sobre a mesma fundação de mTLS e webhooks que abordamos aqui.

Implementar a API Pix não é apenas colocar um novo botão no checkout. É migrar a sua empresa para o trilho principal do sistema financeiro nacional. Coloque seus desenvolvedores para ler a documentação do seu banco hoje. O custo de oportunidade de continuar operando com boletos e conciliação manual é alto demais para ser ignorado.