Como Integrar API Pix no Seu Sistema: Guia Completo para Startups e Empresas

O Pix processou mais de R$ 30 trilhões em transações desde seu lançamento em 2020. Para startups e empresas digitais, integrar a API Pix não é mais diferencial: é requisito mínimo para competir. A questão não é se integrar, mas como fazer isso da forma certa, sem retrabalho e com infraestrutura correta desde o início.

Este guia cobre tudo: da decisão arquitetural à configuração de webhooks em produção.

Pix manual vs. API Pix: a diferença real

Muitos negócios começam com Pix "na mão": o cliente envia via chave e manda o comprovante no WhatsApp. Isso funciona para zero a trinta transações por mês. A partir daí, o modelo quebra:

Aspecto	Pix Manual	API Pix
Confirmação de pagamento	Manual (comprovante)	Automática (webhook em <1s)
Conciliação	Planilha	Automática
QR Code	Estático (risco de confusão)	Dinâmico (por transação)
Escala	Até ~30 trans/mês	Ilimitado
Estorno	Manual	Via API
Relatórios	Manual	Dashboard + API

O ponto de inflexão é o webhook: a notificação automática que o sistema recebe quando um Pix é pago. Isso elimina a verificação manual e permite automatizar tudo o que vem depois: liberar acesso, emitir nota fiscal, atualizar status do pedido.

Conceitos fundamentais antes de começar

QR Code Dinâmico vs. Estático

QR Code estático é gerado uma vez e pode ser pago múltiplas vezes. Útil para doações e pagamentos avulsos sem controle de conciliação. Problema: dois clientes podem pagar o mesmo QR Code, gerando confusão.

QR Code dinâmico é gerado por transação, com valor definido, data de expiração e identificador único (txid). É o padrão para cobranças automatizadas. Cada pagamento é rastreável individualmente.

txid: o identificador que une tudo

O txid é o identificador único da cobrança Pix no seu sistema. Você define ao criar a cobrança e usa para correlacionar o webhook recebido com o pedido no seu banco de dados.

Boas práticas para txid:

• Use UUID v4 para garantir unicidade global
• Prefixe com seu sistema para facilitar depuração: order_abc123_1714500000
• Armazene junto ao pedido desde a criação

endToEndId: a prova do pagamento

O endToEndId é o identificador fim a fim da transação, gerado conforme as regras do arranjo Pix e usado pelos participantes durante o processamento e a liquidação. É a referência que você usa em conciliação e em disputas. Armazene sempre. É o que você usa em disputas e auditorias.

Autenticação e credenciais

Suas credenciais de API são geradas durante o credenciamento com o time da Infopago, junto com os acessos do ambiente. O fluxo exato de autenticação (headers, geração e validade do token) está na documentação oficial, mas três regras valem sempre:

1. Credenciais ficam no backend, em variável de ambiente ou secret manager. Nunca no código, nunca no repositório, nunca no frontend.
2. Trate a renovação do token como parte do fluxo. Tokens de acesso expiram; implemente a renovação automática antes da expiração, não espere a requisição falhar.
3. Um par de credenciais por ambiente. O que testa em homologação não é o que assina produção.

Criando uma cobrança Pix

Cobrança imediata

PUT /v2/cob/{txid}
Content-Type: application/json
Authorization: Bearer {token}

{
  "calendario": { "expiracao": 3600 },
  "valor": { "original": "129.90" },
  "chave": "82.842.386/0001-43",
  "solicitacaoPagador": "Pedido #12345 - Plano Pro",
  "infoAdicionais": [
    { "nome": "pedido", "valor": "12345" }
  ]
}

Resposta inclui pixCopiaECola (string copia-e-cola) e location para gerar o QR Code.

Cobrança com vencimento (substituir boleto)

PUT /v2/cobv/{txid}

{
  "calendario": { "dataDeVencimento": "2026-06-01" },
  "valor": {
    "original": "500.00",
    "multa": { "modalidade": 2, "valorPerc": "2.00" },
    "juros": { "modalidade": 1, "valorPerc": "1.00" },
    "desconto": {
      "modalidade": 1,
      "descontoDataFixa": [{ "data": "2026-05-25", "valorPerc": "5.00" }]
    }
  },
  "devedor": { "cpf": "12345678900", "nome": "João Silva" },
  "chave": "comercial@infopago.com.br"
}

Isso gera um Pix com multa por atraso, juros e desconto para pagamento antecipado: funcionalidade idêntica ao boleto, mas com liquidação instantânea.

Configurando webhooks

O webhook é o coração da integração. Sem ele, você está de volta ao Pix manual.

Registrando o endpoint

PUT /v2/webhook/{chave}

{ "webhookUrl": "https://seu-sistema.com.br/webhooks/pix" }

Estrutura do payload recebido

{
  "pix": [{
    "endToEndId": "E82842386202605011930abc",
    "txid": "order_12345_1714500000",
    "valor": "129.90",
    "pagador": {
      "cpf": "12345678900",
      "nome": "João Silva"
    },
    "horario": "2026-05-01T19:30:00.000-03:00"
  }]
}

Processando o webhook com segurança

app.post('/webhooks/pix', async (req, res) => {
  // 200 ANTES de processar (evita retry por timeout)
  res.status(200).send('OK')

  for (const pix of req.body.pix) {
    // Idempotência: ignore duplicatas pelo endToEndId
    const exists = await db.payments.findByEndToEndId(pix.endToEndId)
    if (exists) continue

    await db.payments.create({
      endToEndId: pix.endToEndId,
      txid: pix.txid,
      amount: parseFloat(pix.valor),
      paidAt: new Date(pix.horario),
    })

    const order = await db.orders.findByTxid(pix.txid)
    if (order) {
      await order.markAsPaid()
      await sendConfirmationEmail(order)
    }
  }
})

Regra de ouro: sempre implemente idempotência pelo endToEndId. A Infopago pode reenviar o webhook conforme a política de tentativas. Processar duplicatas gera cobranças duplas ou liberações indevidas.

Casos de uso por tipo de produto

SaaS com cobrança mensal

1. No dia de vencimento, gere cobrança com vencimento (+3 dias de tolerância)
2. Envie o QR Code por e-mail e WhatsApp
3. Webhook confirma pagamento → renova acesso automaticamente
4. Sem confirmação em 3 dias → suspender conta → notificar
5. Pagamento após suspensão → reativar automaticamente

Resultado: zero intervenção humana na gestão de cobranças.

E-commerce com checkout Pix

1. Cliente finaliza carrinho e escolhe Pix
2. Gere cobrança imediata com expiração de 30 minutos
3. Exiba QR Code + copia-e-cola na tela de confirmação
4. Webhook chega em tempo real → atualize status do pedido
5. Redirecione cliente para página de confirmação
6. Inicie separação/envio automaticamente

Marketplace com split de pagamento

1. Cobrança gerada na conta do marketplace
2. Webhook confirma recebimento
3. API de transferência distribui para sellers conforme comissão

Assinatura recorrente

1. Job agendado gera cobrança mensal para cada assinante
2. Notificação multicanal (e-mail + WhatsApp) com QR Code
3. Webhook processa pagamentos conforme chegam
4. Inadimplentes após X dias entram em fluxo de dunning

Erros comuns e como evitar

Não renovar o token de acesso automaticamente. Se a aplicação só descobre a expiração quando uma requisição falha, você tem uma janela de erros a cada ciclo. Implemente um middleware com renovação automática.

Usar QR Code estático para cobranças identificadas. QR Code estático não tem txid. Você não sabe qual pedido foi pago por qual Pix. Use sempre QR Code dinâmico.

Processar o webhook de forma síncrona e lenta. Se seu endpoint demora mais de 5 segundos, o provedor reenvia achando que houve falha. Responda 200 imediatamente e processe em background.

Não armazenar o endToEndId. É a sua prova de pagamento. Sem ele, você não tem como provar para o cliente ou para o Bacen que um pagamento ocorreu.

Expor credenciais da API no frontend. Nunca. As credenciais ficam no backend. O frontend recebe apenas o QR Code e o status do pedido.

Homologação antes da produção

Durante o credenciamento, o time da Infopago disponibiliza o ambiente de homologação da API. Antes de ir a produção, valide nele:

1. O fluxo completo de cobrança e webhook, de ponta a ponta
2. Casos de erro: valor incorreto, cobrança expirada, pagamento duplicado
3. A idempotência do seu processamento (reenvie o mesmo webhook e confira que nada duplica)

Nunca pule a fase de homologação: é onde você descobre os edge cases sem custo, com o canal técnico da Infopago do lado.

Checklist pré-produção

Antes de ativar a integração em produção, confirme:

• Credenciais armazenadas com segurança (não no código)
• Renovação automática do token de acesso implementada
• Webhook configurado em endpoint HTTPS público
• Idempotência por endToEndId implementada
• endToEndId e txid armazenados no banco de dados
• Resposta 200 imediata no webhook (processamento assíncrono)
• Fluxo de expiração de cobrança tratado (QR Code expirado → gerar novo)
• Alertas configurados para falhas no webhook
• Logs de todas as transações para auditoria

Conclusão

Integrar a API Pix corretamente desde o início elimina retrabalho e escala sem atrito. Os pontos críticos são: credenciais bem guardadas e token sempre renovado, QR Codes dinâmicos com txid rastreável, webhook robusto com idempotência e resposta imediata.

A documentação completa da API Infopago está em docs-infopago.apidog.io com exemplos de request/response para cada endpoint.

Pronto para integrar? Acesse a documentação da API ou fale com nossa equipe técnica para suporte durante a integração.