Uma plataforma de assinaturas emite 600 cobranças Pix por dia. O financeiro confere os pagamentos pelo extrato no fim do expediente e, quando um cliente paga a mesma fatura duas vezes, ninguém percebe até a semana seguinte. O problema não se resolve com mais planilha. Afinal, o que faz uma API Pix e o que é preciso para integrá-la ao sistema da empresa?
A API Pix permite que o seu sistema crie cobranças, mostre o QR Code, receba um aviso no instante em que o pagamento é liquidado e faça devoluções, com um identificador que liga cada Pix a um pedido. O Banco Central (BCB) publica a especificação de referência dessa API, e o acesso acontece por meio de uma instituição autorizada que participa do Pix.
O que é uma API Pix?
A API Pix é a interface que um participante do Pix oferece para a empresa recebedora automatizar cobranças, recebimentos e devoluções. O BCB publica a especificação da API Pix no GitHub, em formato OpenAPI 3.0, para padronizar os serviços que o PSP recebedor oferece aos clientes.
Quem opera a API não é o Banco Central: é o banco ou a instituição de pagamento da empresa, que implementa o padrão, emite as credenciais e conecta o sistema ao Pix. Para rever o funcionamento do arranjo, veja o que é o Pix e como ele funciona.
O que dá para fazer com uma API Pix?
A especificação organiza os serviços por recurso. Estes são os cinco que mais importam para quem recebe em reais.
1. Criar cobrança imediata e cobrança com vencimento
A cobrança imediata (cob) é para pagamento na hora, como um checkout ou uma compra no app. A cobrança com vencimento (cobv) tem data de vencimento e pode trazer multa, juros e desconto, o que faz dela o equivalente Pix de um boleto. O padrão também prevê cobranças com vencimento em lote e cobranças ligadas a pagamentos recorrentes.
2. Gerar QR Code estático e dinâmico
O QR Code estático traz informações fixas e tem poucas funções configuráveis, por isso serve para pagamentos simples e repetidos. O QR Code dinâmico aponta para um endereço onde a instituição do pagador busca os dados da cobrança, o que permite que cada pedido tenha valor, validade e identificador próprios.
3. Receber webhook quando o Pix é liquidado
O webhook é o aviso que a instituição manda para o seu sistema quando um Pix é recebido. Em vez de consultar o extrato, o sistema de pedidos fica sabendo do pagamento assim que ele é liquidado e pode liberar o produto ou dar baixa na fatura.
4. Consultar Pix recebidos e conciliar
Toda cobrança tem um txid, o identificador que o seu sistema atribui a ela, e todo Pix tem um identificador fim a fim (E2E ID), que identifica a transação entre as instituições. A consulta de Pix recebidos por período, txid ou E2E ID é o que torna a conciliação automática.
5. Fazer devolução total ou parcial
A devolução é pedida com base no identificador fim a fim do Pix original, no valor total ou em parte dele. Como a devolução referencia o pagamento original, a contabilidade mantém um histórico limpo por pedido.
E para enviar Pix?
A especificação do BCB trata do lado do recebedor: cobranças, Pix recebidos, devoluções e consultas. O envio de Pix a fornecedores, prestadores ou usuários é oferecido por cada instituição numa interface própria, e o escopo e o formato mudam de um fornecedor para outro.
Se a operação também paga pessoas e empresas, peça as duas funções na mesma integração. A integração de pagamentos e recebimentos aos sistemas da empresa está em Pix e Banking as a Service.
Como funciona a integração com uma API Pix, passo a passo?
As etapas se repetem entre fornecedores. O que muda é quanto cada um faz por você em cada uma delas.
1. Contratar um participante do Pix
A empresa abre conta numa instituição autorizada que participa do Pix, passa pelo cadastro e registra suas chaves. As exigências de cadastro e de contrato dependem dos serviços e do modelo de operação.
2. Receber as credenciais e configurar a segurança
A especificação usa OAuth 2.0, com um escopo de permissão para cada recurso, como criar ou consultar cobranças. Os demais requisitos de segurança vêm do manual de segurança do Pix do BCB e da própria instituição: confirme antes de começar o desenvolvimento.
3. Desenvolver em ambiente de testes
A especificação prevê servidores separados de produção e de homologação. Use a homologação para criar cobranças, simular pagamentos e testar devoluções antes de movimentar dinheiro.
4. Tratar webhook e reenvio
O endpoint do webhook precisa aceitar o mesmo aviso mais de uma vez sem processá-lo duas vezes. Use o txid e o identificador fim a fim como chaves de idempotência, para que um aviso reenviado nunca dê baixa em dois pedidos.
5. Automatizar a conciliação
Ligue cada Pix recebido a um pedido pelo txid, guarde o identificador fim a fim e rode uma consulta diária na instituição para pegar o que o webhook não trouxe. Exceções, como pagamento a maior ou Pix sem cobrança correspondente, vão para uma fila de revisão.
6. Entrar em produção e monitorar
Suba para produção com alertas para webhook com falha, pagamento sem correspondência e erro de devolução. O Pix funciona 24 horas por dia, todos os dias, e o monitoramento precisa acompanhar.
Como fica uma cobrança, do QR Code à conciliação?
Uma empresa de software cobra R$ 1.200 pelo plano anual de um cliente. Os valores são ilustrativos.
O sistema de cobrança cria uma cobrança imediata de R$ 1.200 com um txid ligado ao pedido.
O checkout mostra o QR Code dinâmico, e o cliente paga pelo app do banco.
A instituição manda o webhook com o txid e o identificador fim a fim do pagamento.
O sistema dá baixa no pedido e lança o valor na contabilidade.
Uma semana depois, o cliente muda de plano, e o sistema pede a devolução parcial de R$ 200 com base no mesmo identificador fim a fim.
A conciliação do dia mostra um recebimento de R$ 1.200 e uma devolução de R$ 200, os dois ligados ao mesmo pedido.
Ainda concilia Pix pelo extrato? Veja como cobrar e pagar via Pix numa integração só.
O que avaliar numa instituição que oferece API Pix?
Quase toda instituição gera QR Code. As diferenças aparecem na operação, depois do lançamento.
Autorização: a instituição é autorizada pelo BCB e participa do Pix.
Cobertura do padrão: cobrança imediata e com vencimento, webhook, devolução e consulta estão disponíveis, e você sabe o que não está.
Envio de Pix: pagar fornecedores e usuários está na mesma integração, se você precisar.
Homologação e documentação: dá para desenvolver e testar sem movimentar dinheiro.
Contestação: a instituição explica como trata pedidos de devolução e o Mecanismo Especial de Devolução (MED).
Limites e suporte: limites de transação, comportamento do aviso e horário de suporte estão no contrato.
Como a Transfero apoia empresas que integram o Pix?
O Banking as a Service (BaaS) da Transfero permite movimentar dinheiro no Brasil sem ser um banco. A Transfero Instituição de Pagamento Ltda. é autorizada pelo Banco Central a operar como instituição de pagamento.
Infraestrutura bancária para receber e enviar reais via Pix
Trilhos bancários sem precisar montar uma entidade local nem pedir licença própria
Implantação medida em semanas: a maioria dos clientes começa a operar em poucas semanas
Disponibilidade de 99,999% publicada para a infraestrutura de BaaS
Perguntas para fazer antes de integrar uma API Pix
Quais partes da especificação da API Pix do BCB a instituição atende?
Dá para enviar Pix na mesma integração, ou só receber?
Como a instituição autentica as chamadas e protege as credenciais?
Existe ambiente de homologação igual ao de produção?
Como o webhook é reenviado, e como você evita processar um pagamento duas vezes?
Como devoluções e pedidos do MED chegam ao seu sistema?
Quais limites valem para transações e chamadas à API?
Fale com o time da Transfero sobre integrar o Pix ao seu sistema: entre em contato.
Perguntas frequentes
Existe um padrão oficial de API Pix?
Sim. O Banco Central publica a especificação da API Pix no GitHub, em formato OpenAPI 3.0. Ela padroniza os serviços que a instituição recebedora oferece aos clientes, como cobranças, Pix recebidos, devoluções e consultas. Cada instituição implementa o padrão e emite as próprias credenciais.
Preciso ter CNPJ ou conta no Brasil?
Sim, é preciso ter conta numa instituição que participa do Pix, porque o Pix é um arranjo doméstico em reais. Algumas instituições autorizadas oferecem trilhos bancários sem que o cliente precise pedir licença própria. As exigências de cadastro e de contrato dependem dos serviços e do modelo de operação.
O que acontece se o cliente pagar a mesma cobrança duas vezes?
Cada Pix tem o próprio identificador fim a fim, então o segundo pagamento chega como outra transação. Um sistema que concilia por txid e identificador fim a fim encontra a duplicidade e devolve o valor pela API, referenciando o segundo pagamento, em vez de deixar o caso para o financeiro descobrir depois.
O que é o MED e como ele afeta a integração?
O Mecanismo Especial de Devolução (MED) é o processo do BCB para devolver recursos de Pix em casos de fraude ou falha operacional, criado pela Resolução BCB nº 103 e atualizado pela Resolução BCB nº 493. A integração precisa receber o aviso de um pedido do MED e refletir o valor devolvido no pedido e na contabilidade.
O Pix funciona 24 horas?
Sim. O Pix funciona 24 horas por dia, todos os dias, inclusive em fins de semana e feriados, e o dinheiro chega ao recebedor em segundos. O endpoint do webhook, o monitoramento e o suporte precisam funcionar no mesmo ritmo.

