Como gerar QR Code Pix via API: passo a passo com exemplo

Com um gateway, gerar QR Code Pix via API é uma chamada POST: a resposta já traz a imagem do QR e o copia e cola. Com a API Pix do banco (padrão Bacen), você cuida de certificado/mTLS, monta o BR Code e só então gera a imagem.

Este tutorial usa a API Pix da AbacatePay (checkout transparente, API v2): endpoint, campos e exemplos conferidos em docs.abacatepay.com em 02/11/2026. Se ainda está escolhendo provedor, o post par é melhores APIs de pagamento no Brasil.

QR Code Pix estático x dinâmico (e qual usar)

O Manual de Padrões para Iniciação do Pix (BCB) distingue QR estático e dinâmico.

Para vender online com baixa automática, use dinâmico. A conciliação (txid, webhook, idempotência) está em como confirmar um Pix automaticamente — este post não repete aquele guia; só gera a cobrança.

O que você precisa antes de começar

1. Conta com CNPJ (MEI serve) — precisa de CNPJ?
2. Chave de API v2 no dashboard (Integração → API Keys)
3. Modo Dev para testar sem dinheiro real (prefixo de chave de desenvolvimento; mesma URL de produção)

Documentação de autenticação: Chaves de API. Visão de produto: /desenvolvedores, gateway Pix.

Passo a passo: gerar o QR Code Pix pela API

1) Autenticar com Bearer token

Toda chamada leva:

Authorization: Bearer SEU_TOKEN

Sem chave ou com chave inválida: 401. Chave sem permissão: 403. Nunca coloque a chave no frontend.

2) Criar a cobrança Pix

Endpoint oficial (v2):

POST https://api.abacatepay.com/v2/transparents/create

Corpo mínimo para Pix (valores em centavos; 1000 = R$ 10,00):

• method: "PIX"
• data.amount: inteiro em centavos (mínimo 100 = R$ 1,00, conforme llms.txt / doc)
• Opcionais úteis: data.description, data.expiresIn (segundos de validade do QR)

Referência: Criar cobrança PIX.

3) Exemplo em cURL

curl -X POST https://api.abacatepay.com/v2/transparents/create \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "PIX",
    "data": {
      "amount": 5000,
      "description": "Pedido #1234",
      "expiresIn": 600
    }
  }'

expiresIn: 600 = 10 minutos. Ajuste ao seu checkout; a doc descreve o campo como tempo de expiração em segundos (não encontramos valor padrão fixo publicado na página em 02/11/2026 — envie o que a UX precisa).

4) Exemplo em Node.js / TypeScript (fetch)

const res = await fetch("https://api.abacatepay.com/v2/transparents/create", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ABACATE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    method: "PIX",
    data: {
      amount: 5000,
      description: "Pedido #1234",
      expiresIn: 600,
    },
  }),
});

const json = await res.json();

if (!json.success) {
  throw new Error(json.error ?? "Falha ao criar Pix");
}

const { id, brCode, brCodeBase64, expiresAt } = json.data;
// brCodeBase64 → <img src={brCodeBase64} />
// brCode → botão "Pix copia e cola"

SDK oficial Node.js (API v2): docs SDKs. O envelope segue data / success / error (introdução).

5) Ler a resposta e mostrar na tela

A resposta de sucesso traz, entre outros campos:

Exiba brCodeBase64 num <img> e ofereça brCode para colar no app do banco. Sem redirecionar: é o checkout transparente. Sem código de tela: link de pagamento.

Confirmar o pagamento por webhook

Não libere pedido no print. Cadastre um endpoint HTTPS e escute transparent.completed (eventos transparent).

Regras práticas:

• Valide a origem (secret na URL + integridade do corpo — segurança de webhooks)
• Trate idempotência: o mesmo evento pode ser reenviado
• Responda 2xx rápido

Produto: /api/webhooks. Conceito e txid: confirmar Pix automaticamente.

Plano B — consultar status:

curl -X GET "https://api.abacatepay.com/v2/transparents/check?id=ID_DA_COBRANCA" \
  -H "Authorization: Bearer SEU_TOKEN"

(Checar status — query id obrigatória.)

Testar no sandbox

No Dev mode a URL continua https://api.abacatepay.com/v2. Com a chave de Dev, simule o Pix:

curl -X POST "https://api.abacatepay.com/v2/transparents/simulate-payment?id=ID_DA_COBRANCA" \
  -H "Authorization: Bearer SEU_TOKEN"

Só funciona em Dev. Guia completo: como testar o gateway no sandbox. Pelo terminal: /cli. Agentes: /mcp.

Falar com o time para integrar Pix.

Erros comuns

API Pix do banco ou API de gateway?

Se você quer certificado, mTLS e montar BR Code, use a API do banco. Se quer Bearer token e QR pronto na resposta, use um gateway. Critérios e comparativo: melhores APIs de pagamento no Brasil (2026).

Quanto custa

Na AbacatePay:

• Gerar QR Code: grátis
• Pix recebido: R$ 0,80 por cobrança paga
• Sem mensalidade
• Saque Pix: R$ 0,80 (até 20/mês)

Tabela: /pricing.

Perguntas frequentes

A API Pix do Banco Central gera a imagem do QR Code?

Não. O padrão Bacen define a cobrança/BR Code; a imagem você (ou o gateway) gera. Na AbacatePay a resposta já traz brCodeBase64 e brCode.

Qual a diferença entre QR Code Pix estático e dinâmico?

Estático reutiliza a mesma cobrança; dinâmico é por pedido — o padrão para vender online com conciliação. Ver seção acima e o Manual do BCB.

Quanto tempo o QR Code Pix fica válido?

Você controla com expiresIn (segundos) na criação. Envie o valor adequado ao checkout; confira sempre expiresAt na resposta.

Como saber se o Pix foi pago pela API?

Webhook transparent.completed (preferencial) e/ou GET /v2/transparents/check?id=....

Precisa de certificado digital para gerar Pix por API?

Na AbacatePay, não: autenticação por Bearer token. Certificado/mTLS é típico da API Pix de banco.

Dá para testar sem dinheiro real?

Sim: Dev mode + POST /v2/transparents/simulate-payment — sandbox.

Quanto custa gerar QR Code Pix via API?

Gerar é grátis. Você paga R$ 0,80 quando o Pix é pago — /pricing.

Ainda escolhendo a API?

Veja o comparativo das melhores APIs de pagamento. Pronto para integrar? Use a API Pix da AbacatePay e fale com o time.