Pular para o conteúdo principal
POST
/
pix
/
v2
/
payment
/
withdraw
/
qrcode
Transferência via QR Code
curl --request POST \
  --url https://api-gateway.firebanking.dev/pix/v2/payment/withdraw/qrcode \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "type": "PIX",
  "value": 5000,
  "details": {
    "qrCode": "00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff6b2f8cd520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***63041D3D",
    "name": "Estabelecimento XYZ",
    "document": "12345678000190"
  },
  "externalId": "payment-12345-abc",
  "callbackWebhookUrl": "<string>"
}
'
{
  "transactionId": "8f4a2b1c-9d3e-4a5f-b6c7-d8e9f0a1b2c3",
  "status": "WAITING_CONFIRMATION"
}

Visão Geral

Realize transferências PIX (cash out) utilizando QR Code dinâmico ou código Copia e Cola. Este método permite enviar pagamentos para cobranças PIX geradas por terceiros, seja escaneando um QR Code ou colando o código alfanumérico.
Este endpoint é ideal para pagamento de boletos PIX, cobranças de terceiros e pagamentos via QR Code dinâmico.
Certifique-se de ter saldo suficiente na sua conta antes de realizar a transferência.

Diferenças entre Métodos de Cash Out

  • Uso: Transferências para chaves PIX conhecidas (CPF, email, telefone, chave aleatória)
  • Dados necessários: Chave PIX + tipo de chave
  • Exemplo: Transferir R$ 100,00 para o CPF 123.456.789-00
  • Uso: Pagamento de cobranças PIX (QR Code dinâmico)
  • Dados necessários: String do QR Code (Copia e Cola)
  • Exemplo: Pagar boleto PIX escaneando QR Code ou colando código
  • Características: Valor pode estar pré-definido no QR Code

Exemplo de Requisição

curl -X POST "https://api-gateway.firebanking.com.br/pix/v2/payment/withdraw/qrcode" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PIX",
    "value": 5000,
    "details": {
      "qrCode": "00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff6b2f8cd520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***63041D3D",
      "name": "Estabelecimento XYZ",
      "document": "12345678000190"
    },
    "externalId": "payment-12345-abc"
  }'

Campos da Requisição

Campos Principais

type
string
required
Tipo da transferência. Valor fixo: PIX
value
number
required
Valor da transferência em centavos.
  • Exemplo: 5000 = R$ 50,00
  • Mínimo: 1 centavo (R$ 0,01)
  • Máximo: Conforme limites do business
details
object
required
Detalhes da transferência via QR Code
externalId
string
ID único da sua aplicação para rastreamento.
  • Deve ser único por business
  • Útil para reconciliação e idempotência
  • Máximo: 255 caracteres
callbackWebhookUrl
string
URL customizada para receber webhook desta transação específica

Objeto details

details.qrCode
string
required
String completa do QR Code PIX (Copia e Cola)
  • Formato: Código EMV padrão Banco Central
  • Começa com: 00020126...
  • Contém: Chave PIX, valor, beneficiário, etc.
  • Obtido: Ao escanear QR Code ou através de API do recebedor
details.name
string
Nome do beneficiário (estabelecimento/pessoa)
  • Usado para referência e logs
  • Não afeta o processamento
details.document
string
CPF ou CNPJ do beneficiário
  • Formato: Apenas números (sem formatação)
  • CPF: 11 dígitos
  • CNPJ: 14 dígitos
  • Usado para auditoria e logs

Exemplo de Resposta

{
  "transactionId": "8f4a2b1c-9d3e-4a5f-b6c7-d8e9f0a1b2c3",
  "status": "WAITING_CONFIRMATION"
}

Campos de Resposta

transactionId
string
ID único da transferência no FireBanking (UUID v4)
  • Use este ID para consultar status via /pix/v2/payment/{transactionId}
  • Será enviado no webhook de confirmação
status
string
Status da transferência:
  • WAITING_CONFIRMATION - Aguardando confirmação/processamento
  • WITHDRAW_PAID - Transferência realizada com sucesso
  • ERROR - Erro no processamento

Fluxo de Processamento

1. Validação Inicial

  • Verificação do QR Code: Decodificação e validação do formato EMV
  • Extração de dados: Chave PIX, valor, beneficiário, expiração
  • Validação de saldo: Verificação de saldo disponível
  • Limites de horário: Validação de limites diurnos/noturnos

2. Processamento

  • Débito do valor: Adição ao saldo bloqueado da conta
  • Envio ao provedor: Transmissão da transferência PIX
  • Confirmação SPI: Processamento pelo Sistema de Pagamentos Instantâneos
  • Atualização de status: Transição WAITING_CONFIRMATIONWITHDRAW_PAID

3. Confirmação

  • Webhook enviado: Notificação com status final
  • Atualização de saldo: Débito confirmado do saldo
  • Comprovante gerado: Dados disponíveis para consulta
  • Log de auditoria: Registro completo da operação

Estados da Transferência

  • Descrição: Transferência criada, aguardando processamento pelo provedor
  • Duração típica: 3-10 segundos
  • Saldo: Valor adicionado ao saldo bloqueado
  • Ação: Sistema está processando no SPI (Sistema de Pagamentos Instantâneos)
  • Próximo status: WITHDRAW_PAID ou ERROR
  • Descrição: Transferência realizada com sucesso
  • Valor: Debitado do saldo bloqueado e confirmado
  • Beneficiário: Valor creditado na conta de destino
  • Comprovante: Dados completos disponíveis via API
  • Status final: Transação concluída e irreversível
  • Descrição: Erro no processamento da transferência
  • Possíveis causas:
    • QR Code expirado ou inválido
    • Saldo insuficiente
    • Limite de horário excedido
    • Erro na comunicação com provedor
  • Valor: Removido do saldo bloqueado (estorno automático)
  • Ação: Verificar erro e tentar novamente com novo QR Code

Validações e Limites

Limites Operacionais

Os limites abaixo seguem regulamentação do Banco Central (Resolução BCB nº 1/2020)
  • Valor mínimo: R$ 0,01
  • Valor máximo diurno: R$ 20.000,00 (6h às 20h)
  • Valor máximo noturno: R$ 1.000,00 (20h às 6h)
  • Limite por transação: Configurável por business no business-rules
  • Limite mensal: Configurável por business

Validações Automáticas

  • Formato EMV: Validação do padrão Banco Central
  • Checksum: Verificação de integridade do código
  • Expiração: Validação de data de validade (se presente)
  • Valor: Extração e validação do valor (se pré-definido)
  • Saldo disponível: balance - (assuranceBalance + blockedBalance)
  • Verificação em tempo real: Antes do processamento
  • Reserva de saldo: Adição ao blockedBalance durante processamento
  • Liberação: Débito ou estorno após confirmação
  • Limite por transação: Verificação em businessRules.limits.pixOut.perTransactionLimit
  • Limite de horário: Aplicação de limites diurnos/noturnos (regulamentação BC)
  • Limite acumulado: Validação de limites diários/mensais
  • Business ativo: Verificação de business.active === true

Formato do QR Code PIX

O QR Code PIX segue o padrão EMV (Europay, Mastercard e Visa) e contém:

Estrutura do Código Copia e Cola

00020126580014br.gov.bcb.pix0136[CHAVE_PIX]5204000053039865405[VALOR]5802BR5913[BENEFICIARIO]6008[CIDADE]62070503***6304[CRC]

Campos Principais

CampoIDDescriçãoExemplo
Payload Format00Versão do formato01
Merchant Account26Informações da contaChave PIX + domínio
Merchant Category52Código de categoria0000 (pessoa física)
Currency53Código da moeda986 (BRL)
Amount54Valor da transação10.00 (opcional)
Country58Código do paísBR
Merchant Name59Nome do beneficiárioFulano de Tal
Merchant City60Cidade do beneficiárioBRASILIA
Additional Info62Informações adicionaisID da transação
CRC63Checksum CRC161D3D
O campo 54 (valor) é opcional. Se presente no QR Code, ele será usado. Se ausente, o valor do campo value da requisição será considerado.

Códigos de Erro

CódigoDescriçãoAção Sugerida
INSUFFICIENT_BALANCESaldo insuficiente na contaAdicionar saldo antes de tentar novamente
INVALID_QR_CODEQR Code inválido ou mal formatadoVerificar o código Copia e Cola
QR_CODE_EXPIREDQR Code expiradoSolicitar novo QR Code ao beneficiário
INVALID_AMOUNTValor inválido ou fora dos limitesVerificar limites de horário e transação
LIMIT_EXCEEDEDLimite de transferência excedidoAguardar novo período ou aumentar limite
BUSINESS_INACTIVEBusiness desativadoContatar suporte FireBanking
PIX_OUT_INACTIVEPIX Out desativado no businessAtivar PIX Out nas configurações
EXTERNAL_ID_EXISTSExternalId já utilizadoUsar novo externalId único
PIX_UNAVAILABLESistema PIX temporariamente indisponívelTentar novamente em alguns minutos
PROVIDER_ERRORErro no provedor de pagamentoVerificar providerError na resposta

Boas Práticas

Segurança

  • Verificação prévia: Decodificar e validar QR Code antes de enviar
  • Timeout de expiração: Alertar usuário sobre validade do QR Code
  • Confirmação de valor: Exibir valor extraído do QR Code para confirmação
  • Log detalhado: Registrar todas as tentativas de pagamento
  • API Key segura: Armazenar em variáveis de ambiente
  • HTTPS obrigatório: Todas as requisições devem usar TLS 1.2+
  • Rate limiting: Limitar número de transferências por minuto
  • Confirmação dupla: Implementar confirmação adicional para valores altos
  • ExternalId único: Sempre usar externalId para rastreamento
  • Logs estruturados: Registrar request/response completos
  • Histórico de transações: Manter registro de todas as tentativas
  • Alertas: Configurar alertas para falhas recorrentes

Experiência do Usuário

  • Scan QR Code: Implementar leitor de QR Code nativo
  • Copia e Cola: Permitir colar código manualmente
  • Preview de dados: Mostrar beneficiário e valor antes de confirmar
  • Feedback visual: Indicar progresso do processamento
  • Decodificação imediata: Validar QR Code assim que colado/escaneado
  • Exibir beneficiário: Mostrar nome extraído do QR Code
  • Exibir valor: Mostrar valor se presente no QR Code
  • Alertas de expiração: Avisar se QR Code está próximo de expirar
  • Tela de confirmação: Resumo antes de processar
  • Feedback imediato: Mostrar status WAITING_CONFIRMATION
  • Comprovante: Gerar PDF ou imagem após WITHDRAW_PAID
  • Histórico: Permitir consultar transações anteriores

Performance e Confiabilidade

  • Timeout apropriado: 30 segundos para transferências
  • Retry Strategy:
    • ❌ NÃO retentar se status === "ERROR"
    • ✅ Retentar apenas em timeout ou erro de rede
    • ⚠️ Usar externalId para evitar duplicatas
  • Cache de validações: Armazenar limites do business
  • Webhook prioritário: Usar webhook ao invés de polling
  • Logs detalhados: Registrar tempo de resposta e erros
  • Métricas: Taxa de sucesso, tempo médio de processamento
  • Alertas: Falhas consecutivas, timeouts frequentes
  • Erros de saldo: Orientar usuário a adicionar saldo
  • QR Code expirado: Solicitar novo código ao beneficiário
  • Timeout: Consultar status via /pix/v2/payment/{transactionId}
  • Provider Error: Exibir mensagem de providerError se disponível

Webhook de Confirmação

Após o processamento, você receberá um webhook com o resultado:

Sucesso

{
  "event": "pix.withdraw_completed",
  "transaction_id": "8f4a2b1c-9d3e-4a5f-b6c7-d8e9f0a1b2c3",
  "external_id": "payment-12345-abc",
  "timestamp": "2024-01-15T15:30:15Z",
  "data": {
    "status": "WITHDRAW_PAID",
    "value": 5000,
    "beneficiary": {
      "name": "Estabelecimento XYZ",
      "document": "12345678000190",
      "bank": "Banco ABC"
    },
    "fees": {
      "total": 0
    },
    "operation": {
      "result": 5000,
      "fee": 0
    }
  }
}

Erro

{
  "event": "pix.withdraw_failed",
  "transaction_id": "8f4a2b1c-9d3e-4a5f-b6c7-d8e9f0a1b2c3",
  "external_id": "payment-12345-abc",
  "timestamp": "2024-01-15T15:30:20Z",
  "data": {
    "status": "ERROR",
    "value": 5000,
    "error": {
      "code": "QR_CODE_EXPIRED",
      "message": "QR Code expirado",
      "provider_code": "EXPIRED_PAYLOAD"
    }
  }
}
Configure sua URL de webhook em Dashboard → Configurações → Webhooks ou use o parâmetro callbackWebhookUrl para webhooks específicos por transação.

Exemplos de Integração

Scanner de QR Code (React Native)

import { Camera } from 'react-native-vision-camera';

const QRCodeScanner = () => {
  const onQRCodeScanned = async (codes) => {
    const qrCode = codes[0]?.value;

    if (!qrCode || !qrCode.startsWith('00020126')) {
      alert('QR Code inválido');
      return;
    }

    // Decodificar informações do QR Code
    const pixData = decodePixQRCode(qrCode);

    // Exibir confirmação
    const confirmed = await showConfirmation({
      beneficiary: pixData.name,
      value: pixData.value || 'A definir',
      city: pixData.city
    });

    if (confirmed) {
      // Processar pagamento
      await processQRCodePayment(qrCode, pixData.value);
    }
  };

  return (
    <Camera
      onCodeScanned={onQRCodeScanned}
      codeTypes={['qr']}
    />
  );
};

Copia e Cola (Web)

const handlePasteQRCode = async (event) => {
  const qrCode = event.clipboardData.getData('text');

  // Validar formato
  if (!qrCode.startsWith('00020126')) {
    showError('Código Copia e Cola inválido');
    return;
  }

  try {
    // Decodificar QR Code
    const pixData = decodePixQRCode(qrCode);

    // Exibir preview
    setPreview({
      beneficiary: pixData.name,
      value: pixData.value || 0,
      city: pixData.city,
      qrCode: qrCode
    });

    setStep('confirm');
  } catch (error) {
    showError('Erro ao processar código: ' + error.message);
  }
};

const processPayment = async () => {
  try {
    setLoading(true);

    const response = await fetch('/pix/v2/payment/withdraw/qrcode', {
      method: 'POST',
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        type: 'PIX',
        value: preview.value * 100, // converter para centavos
        details: {
          qrCode: preview.qrCode,
          name: preview.beneficiary
        },
        externalId: `payment-${Date.now()}`
      })
    });

    const result = await response.json();

    if (result.status === 'WAITING_CONFIRMATION') {
      // Aguardar webhook ou consultar status
      pollTransactionStatus(result.transactionId);
    }
  } catch (error) {
    showError('Erro ao processar pagamento: ' + error.message);
  } finally {
    setLoading(false);
  }
};

Consultar Status da Transação

Use o endpoint de consulta para verificar o status:
curl -X GET "https://api-gateway.firebanking.com.br/pix/v2/payment/{transactionId}" \
  -H "x-api-key: SUA_CHAVE_DE_API"
Resposta:
{
  "_id": "8f4a2b1c-9d3e-4a5f-b6c7-d8e9f0a1b2c3",
  "status": "WITHDRAW_PAID",
  "operation": {
    "type": "CASH_OUT",
    "status": "WITHDRAW_PAID",
    "value": 5000,
    "fee": 0,
    "result": 5000,
    "externalID": "payment-12345-abc"
  },
  "beneficiary": {
    "name": "Estabelecimento XYZ",
    "document": "12345678000190"
  },
  "createdAt": "2024-01-15T15:30:10Z",
  "updatedAt": "2024-01-15T15:30:15Z"
}

Próximos Passos

Authorizations

x-api-key
string
header
required

Chave de API para autenticação

Body

application/json
type
enum<string>
required

Tipo da operação: sempre PIX

Opções disponíveis:
PIX
value
number
required

Valor da transferência em centavos (ex: 5000 = R$ 50,00)

Intervalo obrigatório: x >= 1
Example:

5000

details
object
required
externalId
string

Identificador único da transferência em seu sistema

Example:

"payment-12345-abc"

callbackWebhookUrl
string<uri>

URL customizada para receber webhook desta transação específica

Response

Transferência via QR Code criada com sucesso

transactionId
string
required

ID único da transferência no FireBanking

Example:

"75906707-8c31-479c-b354-aa805c4cefbc"

status
enum<string>
required

Status da transferência

Opções disponíveis:
WAITING_CONFIRMATION,
WITHDRAW_PAID,
ERROR
Example:

"WAITING_CONFIRMATION"