Criar PIX QR Code

Visão Geral

Crie um PIX com QR Code dinâmico para receber pagamentos. O QR Code gerado é único para cada transação e pode ser usado uma única vez.

Exemplo de Requisição

curl -X POST "https://api-gateway.firebanking.com.br/pix/v2/payment" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "value": 0.15,
      "description": "Cobrança de teste",
      "expirationTime": 300,
      "externalId": "uuid-123",
      "additionalInfo": {
        "sellerId": 123,
        "whatsAppPhone": "37988996655"
      }
    },
    "payer": {
      "fullName": "John Marvin",
      "document": "12312312387"
    },
    "callback_url": "https://meusite.com/webhooks/pix"
  }'

Implementação Frontend

Exibir QR Code

<div id="pix-payment">
  <h3>Pague com PIX</h3>
  <img id="qr-image" src="" alt="QR Code PIX" />
  <p>
    <strong>Pix Copia e Cola:</strong>
    <input type="text" id="pix-code" readonly />
    <button onclick="copyPixCode()">Copiar</button>
  </p>
  <p>Valor: R$ <span id="amount"></span></p>
  <p>Expira em: <span id="expires"></span></p>
</div>

<script>
  function showPixPayment(pixData) {
    document.getElementById("qr-image").src = `data:image/png;base64,${pixData.pixQrCode}`;
    document.getElementById("pix-code").value = pixData.pixCode;
    document.getElementById("expires").textContent = new Date(
      pixData.expirationDate
    ).toLocaleString("pt-BR");
  }

  function copyPixCode() {
    const pixCode = document.getElementById("pix-code");
    pixCode.select();
    navigator.clipboard.writeText(pixCode.value);
    alert("Código PIX copiado!");
  }
</script>

Verificar Status (Polling)

async function checkPaymentStatus(pixId) {
  try {
    const response = await fetch(
      `https://api-gateway.firebanking.com.br/pix/v2/payment/${pixId}`,
      {
        headers: {
          "x-api-key": "SUA_CHAVE_DE_API",
        },
      }
    );

    const payment = await response.json();

    if (payment.status === "PAID") {
      // Pagamento confirmado!
      showSuccess("Pagamento recebido com sucesso!");
      window.location.href = "/pedido-confirmado";
    } else if (payment.status === "EXPIRED") {
      // PIX expirou
      showError("PIX expirou. Gere um novo código.");
    }

    return payment.status;
  } catch (error) {
    console.error("Erro ao verificar status:", error);
  }
}

// Verificar a cada 5 segundos
const statusInterval = setInterval(() => {
  checkPaymentStatus("cd722e93-032f-45e1-b638-87a2490dcea7").then((status) => {
    if (status === "PAID" || status === "EXPIRED") {
      clearInterval(statusInterval);
    }
  });
}, 5000);

Boas Práticas

Expiração do QR Code

Padrão recomendado: 30 minutos a 2 horas
E-commerce: Até 24 horas
Pagamentos presenciais: 5 a 15 minutos
Sempre configure: Evite QR Codes sem expiração

Experiência do Usuário

Exiba o valor: Sempre mostre o valor em reais
Botão de copiar: Facilite o “Copia e Cola”
Status em tempo real: Use polling ou websockets
Instruções claras: Oriente como usar o PIX

Segurança

Validate dados: Sempre valide valores e formatos
Use HTTPS: Apenas endpoints seguros
Não exponha chaves: Mantenha API keys seguras
Log transações: Registre para auditoria

Códigos de Erro

Código	Descrição
`INVALID_AMOUNT`	Valor inválido (mín: R $0,01, máx: R$ 20.000,00)
`INVALID_EXPIRATION`	Data de expiração inválida ou no passado
`INVALID_DOCUMENT`	CPF ou CNPJ inválido
`EXTERNAL_ID_EXISTS`	ExternalId já usado em transação ativa
`INVALID_CALLBACK_URL`	URL de callback inválida
`ACCOUNT_LIMIT_EXCEEDED`	Limite da conta excedido

Webhooks

Quando o PIX for pago, você receberá um webhook:

{
  "transactionId": "03cadd36-fddd-4091-9ffe-67b0483cbcf5",
  "businessTransactionId": "pedido-12345",
  "status": "PAID",
  "value": 15000,
  "movementType": "CREDIT",
  "endToEndId": "E00000000202401151045300123456789",
  "pixKey": "[email protected]",
  "createdDate": "2024-01-15T10:30:00.123Z",
  "ReceiverBankAccount": "567890",
  "ReceiverToBankAccountDigit": "1",
  "ReceiverBankBranch": "0001",
  "ReceiverBankCode": "077",
  "ReceiverDocumentNumber": "45438750000188",
  "ReceiverBankName": "BANCO INTER S.A.",
  "ReceiverBankISPB": "00416968",
  "ReceiverName": "MINHA EMPRESA LTDA",
  "PayerBankAccount": "123456",
  "PayerBankAccountDigit": "7",
  "PayerBankBranch": "0001",
  "PayerBankCode": "001",
  "PayerDocumentNumber": "12345678901",
  "PayerBankName": "BANCO DO BRASIL S.A.",
  "PayerBankISPB": "00000000",
  "PayerName": "JOAO COSTA SILVA",
  "VoucherUrl": "https://voucher.firebanking.com/pix/03cadd36-fddd-4091-9ffe-67b0483cbcf5.pdf"
}

Próximos Passos

Consultar PIX

Verifique status e histórico de transações

Webhooks PIX

Configure notificações automáticas

Testar no Sandbox

Use dados de teste para desenvolvimento

Authorizations

x-api-key

string

header

required

Chave de API para autenticação

Body

application/json

transaction

object

required

Mostrar atributos filhos

transaction.value

number

required

Valor da transação em reais

Intervalo obrigatório: x >= 0.01

Example:

0.15

transaction.description

string

Descrição da transação

Maximum string length: 140

Example:

"Cobrança de teste"

transaction.expirationTime

integer

Tempo de expiração em segundos

Example:

300

transaction.externalId

string

ID externo da transação

Example:

"uuid-123"

transaction.additionalInfo

object

Mostrar atributos filhos

transaction.additionalInfo.sellerId

integer

Example:

123

transaction.additionalInfo.whatsAppPhone

string

Example:

"37988996655"

payer

object

Mostrar atributos filhos

payer.fullName

string

Nome completo do pagador

Example:

"John Marvin"

payer.document

string

CPF/CNPJ do pagador

Example:

"12312312387"

splits

object[]

Divisão de valores entre múltiplos recebedores

Mostrar atributos filhos

splits.walletId

string

Example:

"wallet_123"

splits.amount

number

Example:

50

splits.percentage

number

Example:

33.33

callback_url

string<uri>

URL para receber webhooks específicos desta transação

metadata

object

Dados adicionais da transação

Mostrar atributos filhos

metadata.{key}

string

Response

Cobrança PIX criada com sucesso

transactionId

string

required

ID único da transação PIX no FireBanking

Example:

"cd722e93-032f-45e1-b638-87a2490dcea7"

status

enum<string>

required

Status atual da transação

Opções disponíveis:

WAITING_PAYMENT,

PAID,

EXPIRED,

CANCELLED,

REFUNDED

Example:

"WAITING_PAYMENT"

pixQrCode

string

required

QR Code em formato base64 (PNG) para exibição

Example:

"iVBORw0KGgoAAAANSUhEUgAABbQAAAW0CAYAAAAeooXXAAAABGdBTUEAALGPC/xhBQ..."

pixCode

string

required

Código PIX Copia e Cola para pagamento

Example:

"00020101021226880014br.gov.bcb.pix2566qrcode-h.firebanking.com.br/QR/cob/EEA7B851BBAFFB546073CE80810F56AA0F95204000053039865802BR5925VICTOR NERY TEIXEIRA CONS6009Sao Paulo610905726-10062070503***630498E0"

generateTime

string<date-time>

required

Data/hora de geração da cobrança (ISO 8601)

Example:

"2024-04-14T02:58:04.997Z"

expirationDate

string<date-time>

required

Data/hora de expiração da cobrança (ISO 8601)

Example:

"2024-04-15T02:58:04.997Z"

paymentLink

string<uri>

required

Link direto para pagamento (ideal para WhatsApp/email)

Example:

"https://pay.firebanking.com.br/cd722e93-032f-45e1-b638-87a2490dcea7"

Visão Geral

Fluxo de Integração

PIX Cobrança (Cash In)

PIX Saque (Cash Out)

Operações

Gestão

Webhooks

Visão Geral

Exemplo de Requisição

Implementação Frontend

Exibir QR Code

Verificar Status (Polling)

Boas Práticas

Expiração do QR Code

Experiência do Usuário

Segurança

Códigos de Erro

Webhooks

Próximos Passos

Consultar PIX

Webhooks PIX

Testar no Sandbox

Authorizations

Body

Response

Visão Geral

Fluxo de Integração

PIX Cobrança (Cash In)

PIX Saque (Cash Out)

Operações

Gestão

Webhooks

​Visão Geral

​Exemplo de Requisição

​Implementação Frontend

​Exibir QR Code

​Verificar Status (Polling)

​Boas Práticas

​Expiração do QR Code

​Experiência do Usuário

​Segurança

​Códigos de Erro

​Webhooks

​Próximos Passos

Consultar PIX

Webhooks PIX

Testar no Sandbox

Authorizations

Body

Response

Visão Geral

Exemplo de Requisição

Implementação Frontend

Exibir QR Code

Verificar Status (Polling)

Boas Práticas

Expiração do QR Code

Experiência do Usuário

Segurança

Códigos de Erro

Webhooks

Próximos Passos