Pular para o conteúdo principal
O Plugin Pix Indireto (BTG) gera e gerencia QR Codes Pix (BR Codes) para que seus clientes possam receber pagamentos. Ele suporta quatro domínios de QR Code: BR Codes estáticos, cobranças imediatas (cobrança imediata / COB), cobranças com vencimento (cobrança com vencimento / COBV) e um decodificador universal para iniciação de pagamento. Todos os QR Codes seguem a especificação EMV QCO e incorporam a chave Pix do recebedor. Antes de criar um QR Code, a chave do recebedor já deve existir no DICT e pertencer à conta solicitante (identificada pelo cabeçalho X-Account-Id). Consulte o guia de DICT para o registro de chaves.

​
Escolhendo um tipo de QR Code

TipoCaracterísticasIndicado para
EstáticoReutilizável (múltiplos pagamentos) · valor opcional (fixo ou informado pelo pagador) · sem expiraçãoTelas de POS, material impresso, doações, e-commerce com valores variáveis
Imediata (COB)Pagamento único · valor obrigatório · expiração baseada em segundosCheckout, faturamento, compras únicas
Com vencimento (COBV)Pagamento único · valor + encargos · data de vencimento + período de tolerânciaContas, parcelamentos, assinaturas, faturamento B2B (semelhante a boleto)
DecodificarLê qualquer QR Code escaneadoIniciar um pagamento a partir de um código escaneado

​
QR Codes estáticos

Os BR Codes estáticos (/v1/brcode/static) são reutilizáveis — o mesmo código pode ser pago muitas vezes por pagadores diferentes. Eles estão vinculados a uma chave Pix e, opcionalmente, a dados do estabelecimento. Valor fixo vs. variável:
  • Com valor — o pagador escaneia e confirma um valor predefinido. Útil para itens de preço fixo.
  • Sem valor — o pagador escaneia e digita o valor manualmente. Útil para doações ou checkout aberto.
Você pode enriquecer o código com dados do estabelecimento (merchant.name, merchant.city, merchant.categoryCode (MCC, 4 dígitos), merchant.postalCode) e um txId opcional (alfanumérico, ≤ 25 caracteres) para conciliação. Se os dados do estabelecimento forem omitidos, o plugin pode enriquecê-los a partir dos dados do titular no CRM. 
POST /v1/brcode/static
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "receiverKey": "+5511999999999",
  "amount": "100.00",
  "description": "Payment for order #12345",
  "txId": "TX123ABC",
  "merchant": { "name": "Loja ABC", "city": "São Paulo", "categoryCode": "5411" }
}
→ 201 Created  { "id": "...", "emv": "00020126580014br.gov.bcb.pix...", "status": "ACTIVE" }
Passe include_base64=true para também receber um PNG do QR Code codificado em Base64. O plugin valida a propriedade da chave (retorna PIX-0092 se a chave não pertencer à conta, PIX-0093 se estiver inativa). Referência: Criar um QR code estático · Listar · Recuperar

​
Cobranças imediatas (COB)

As cobranças imediatas (/v1/collections/immediate) são QR Codes dinâmicos e de uso único para um valor específico com uma janela de validade curta. Cada uma é identificada de forma única por um txId obrigatório e só pode ser paga uma vez. Campos obrigatórios: amount, expirationInSeconds (recomendado ≤ 3600), receiverKey e txId. Um debtor opcional (nome + documento) restringe quem pode pagar — quando definido, somente o CPF/CNPJ especificado pode liquidar a cobrança. Ciclo de vida:
StatusSignificado
ACTIVECriada e disponível para pagamento
CONCLUDEDPagamento recebido com sucesso
REMOVED_BY_RECEIVERCancelada pelo lojista
REMOVED_BY_PSPCancelada pelo PSP (sistema ou política)
Quando criada, o plugin agenda um job de expiração; após decorrido expirationInSeconds, a cobrança não pode mais ser paga. Enquanto ACTIVE, a cobrança pode ser atualizada (PATCH) ou excluída (DELETE) — uma cobrança no status CONCLUDED não pode ser excluída (PIX-0104). Confirmação de pagamento: quando um Pix recebido liquida a cobrança, o plugin a transiciona para CONCLUDED e emite um webhook para que seu sistema seja notificado em tempo real. Consulte o guia de Webhooks e o guia de Cobranças para o fluxo de pagamento completo. Referência: Criar uma cobrança imediata · Listar · Recuperar · Atualizar · Excluir

​
Cobranças com vencimento (COBV)

As cobranças com vencimento (/v1/collections/duedate) são QR Codes dinâmicos para faturamento com data de vencimento, análogos a um boleto. Elas suportam regras de valor complexas e exigem dados completos do pagador e do recebedor. Campos principais: dueDate, validAfterDue (dias em que a cobrança permanece pagável após o vencimento — padrão 30), um debtor obrigatório (nome + CPF/CNPJ, além de e-mail/endereço/cidade/estado/CEP opcionais) e um objeto amount com componentes de encargo opcionais:
ComponenteTiposAplica-se
fineFIXED, PERCENTAGEMulta por pagamento em atraso
interestDAILY_AMOUNT, DAILY_PERCENTAGE, MONTHLY_PERCENTAGEAcumula após o vencimento
discountFIXED, PERCENTAGE, FIXED_UP_TO_DATE, PERCENTAGE_UP_TO_DATERecompensa pelo pagamento antecipado
abatementFIXEDCrédito/redução sobre o valor
O momento do pagamento determina o valor final: antes do vencimento o pagador recebe qualquer desconto aplicável; na data de vencimento aplica-se o valor original; após o vencimento são adicionados multas e juros (descontado qualquer abatimento). Os tipos de desconto UP_TO_DATE exigem uma date que deve ser anterior à dueDate. O plugin valida o formato do documento do pagador (PIX-0073) e agenda a expiração em dueDate + validAfterDue. Referência: Criar uma cobrança com vencimento · Listar · Recuperar · Atualizar

​
Decodificando QR Codes

O decodificador (POST /v1/qrcodes/decode) analisa qualquer QR Code Pix escaneado e retorna os dados de pagamento nele incorporados. Use-o em fluxos de iniciação de pagamento — quando um cliente escaneia um QR Code e você precisa do recebedor, do valor e dos detalhes de cobrança antes de confirmar o pagamento. O plugin detecta automaticamente o tipo de QR Code e retorna uma resposta tipada:
  • STATIC — chave do recebedor, valor/descrição opcionais, dados do estabelecimento, txId.
  • IMMEDIATE (COB) — todos os campos do estático, mais valor obrigatório, expiração, status e número de revisão.
  • DUE_DATE (COBV) — todos os campos do imediato, mais data de vencimento, validAfterDue, pagador, recebedor e a estrutura completa de multa/juros/desconto.
Para códigos dinâmicos, o plugin resolve o payload dinâmico do BTG antes de retornar, de modo que a resposta reflete o estado atual da cobrança. 
POST /v1/qrcodes/decode
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{ "emv": "00020126580014br.gov.bcb.pix..." }
→ 200 OK  { "type": "IMMEDIATE", "amount": "100.00", "receiverKey": "...", "status": "ACTIVE" }
Referência: Decodificar um QR code Pix

​
Próximos passos

  • Cobranças — Ciclo de vida da cobrança, vínculo de pagamento e eventos de webhook
  • DICT — Registrando as chaves Pix em que seus QR Codes recebem
  • Webhooks — Notificações de pagamento e status