API Pix do Bacen x API de gateway: qual usar

A API Pix do Bacen não é um serviço que o Banco Central abre direto para a sua empresa. É uma especificação padronizada pelo Banco Central que cada prestador de serviços de pagamento (PSP) implementa para os próprios clientes: você integra com a API Pix do banco ou da instituição onde tem conta, seguindo o padrão do Banco Central. Uma API de gateway, como a API Pix da xFlow, fica uma camada acima. Ela entrega uma API própria, mais simples de integrar, e conecta a mesma chamada a várias adquirentes.

O que é a API Pix do Banco Central

Segundo o Manual de Padrões para Iniciação do Pix (versão 2.10.0, consultada em 25/10/2026), a API Pix é uma API padronizada pelo Banco Central para facilitar a integração das soluções de automação ao Pix, ampliar a concorrência e reduzir custos para os usuários finais. O manual a descreve como o componente que permite ao pagador ou ao recebedor, em relações com empresas, automatizar a interação com o seu PSP.

A especificação técnica é publicada em formato OpenAPI pelo próprio Banco Central, no repositório bacen/pix-api, citado no manual. As informações gerais sobre o arranjo estão na página oficial do Pix no site do Banco Central.

O que a especificação cobre

O manual lista as funcionalidades da API Pix. Entre elas:

• Cobrança imediata, para pagamento no ato, como no caixa de uma loja ou num e-commerce.
• Cobrança com vencimento, com cálculo de descontos, abatimentos, juros e multa.
• Devolução de valores, por exemplo quando uma compra é desfeita.
• Webhook, para o PSP avisar o recebedor quando um Pix ligado a um txid é creditado.
• Pix Saque e Pix Troco iniciados por QR Code dinâmico.
• Pix Automático, com criação e gestão de recorrências.

Dois pontos do manual costumam surpreender quem começa. Primeiro, o QR Code dinâmico deve ser gerado pelo recebedor por meio da API Pix, mas a API não retorna um arquivo com a imagem do QR Code: montar a imagem fica com o PSP, com a automação comercial ou com outro software. Segundo, a criação de QR Code estático não faz parte da API Pix. A diferença entre os dois tipos está em QR Code Pix dinâmico por API.

Como é integrar direto com a API Pix de um PSP

A especificação define requisitos de segurança que o PSP precisa seguir, e eles chegam até você como trabalho de integração:

1. Conta no PSP. A API dá acesso só às contas do CPF ou CNPJ associado, no prestador que a oferece.
2. Cadastro no ambiente logado do PSP, com envio seguro das credenciais.
3. OAuth 2.0 com TLS mútuo. O fluxo é o Client Credentials, e a conexão usa certificado digital do cliente, emitido pelo PSP ou por uma autoridade certificadora externa, conforme a regra de cada PSP. Certificado autoassinado não é aceito.
4. TLS 1.2 ou superior em todas as conexões.
5. Webhook por canal com TLS mútuo, de preferência com os mesmos certificados da API.
6. txid em cada cobrança. O identificador tem de 26 a 35 caracteres (letras e números) e não pode se repetir para o mesmo recebedor. Ele pode ser enviado por você ou gerado pelo PSP.
7. Imagem do QR Code por sua conta, se o PSP não oferecer.

Nada disso é ruim. É o padrão que torna o Pix seguro e interoperável. Mas cada item é código, infraestrutura e manutenção. E a integração vale para um prestador: se você quiser um segundo, para ter contingência ou outra condição comercial, refaz boa parte do trabalho, com as regras de certificado e de cadastro do novo PSP.

Como é a API de um gateway como a xFlow

A xFlow trabalha com 11 adquirentes integradas e entrega a você uma API própria, que esconde as diferenças entre elas. Você integra uma vez, com uma interface única, e a escolha de qual adquirente recebe cada cobrança segue as regras definidas para a sua conta.

Na prática, a integração fica assim:

• Uma credencial. HTTP Basic com a chave pública (pk_live_) e o segredo (sk_live_), gerados no painel. Sem certificado de cliente.
• QR Code pronto. A criação da cobrança devolve pix.copyPaste e pix.qrCodeBase64, uma imagem PNG pronta para a tela.
• Webhooks assinados. Cada evento chega por HTTPS com assinatura HMAC-SHA256 do corpo e até 3 reenvios.
• Conciliação pronta. A cobrança paga traz payer (quem pagou) e pix.endToEnd, o End-to-end ID da liquidação.
• Sandbox. Chaves pk_test_ com os mesmos endpoints e simulação de pagamento.
• Saque e estorno pela mesma API. Saque Pix por chave ou QR Code e estorno total da cobrança.
• 11 adquirentes atrás da mesma chamada, com roteamento por regras (valor, horário e dia da semana) e retentativa automática: se uma adquirente não responder, a cobrança é gerada na próxima da cadeia. Veja em orquestração de pagamentos e multiadquirência.

Criar uma cobrança é uma chamada:

curl -X POST https://app.xflowpayments.com/api/v1/charges \
  -u "pk_live_...:sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{"amountCents":1990,"customer":{"name":"Cliente","email":"c@ex.com","document":"00000000000"}}'

Comparativo

Quando cada uma faz sentido

A API Pix direta com um PSP faz sentido quando:

• você tem um único banco e não precisa de contingência entre prestadores;
• o seu time já opera certificados digitais, OAuth com TLS mútuo e geração de QR Code;
• você precisa de recursos da especificação que um gateway não oferece, como cobrança com vencimento com juros e multa ou Pix Automático.

Uma API de gateway como a xFlow faz sentido quando:

• você quer integrar rápido, com uma credencial e QR Code pronto;
• a operação não pode parar se um prestador ficar instável;
• você quer escolher qual adquirente recebe cada cobrança, por regra;
• você precisa de cobrança, estorno, saque, split entre contas e webhooks numa só API, com sandbox e logs.

Uma forma prática de decidir: liste o que o seu produto precisa hoje e compare com o que cada caminho entrega. Se a lista é cobrar por Pix, confirmar o pagamento, devolver e sacar, um gateway resolve com menos código. Se a lista inclui recursos que só a especificação completa cobre, o caminho é integrar com a API Pix do seu PSP.

Para ver a API da xFlow por dentro, comece pela página API Pix e pela documentação. Os exemplos por linguagem estão em Desenvolvedores.

Conteúdo informativo, atualizado em 25/10/2026. Não substitui orientação jurídica.