Consultar Cobrança

Visão Geral

Consulte informações detalhadas de uma cobrança PIX utilizando o ID da transação. Este endpoint retorna dados completos sobre o status, valores, participantes e metadados da transação.

A API aceita tanto o id interno da transação quanto o externalId fornecido na criação da cobrança. A identificação é feita automaticamente.

Outras formas de consulta

GET /pix/v2/payment/pix-key/{pixKey}/{transactionId}: filtra pela combinação de chave PIX + transactionId (ou externalId).
GET /pix/v2/payment/pix-key/{pixKey}: lista todas as transações do negócio autenticado vinculadas à chave PIX.
GET /pix/v2/payment/pix-key/{pixKey}/e2e/{providerId}: consulta pela combinação chave PIX + providerID (endToEndId).

Parâmetros da URL

string

required

ID da transação PIX ou externalId fornecido na criação

Exemplo de Requisição

curl -X GET "https://api-gateway.firebanking.com.br/pix/v2/payment/pix_12345678901234567890" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json"

Consulta por chave PIX + transactionId

cURL

curl -X GET "https://api-gateway.firebanking.com.br/pix/v2/payment/CHAVE_PIX/TRANSACTION_ID" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json"

Consulta por chave PIX + providerID (endToEndId)

cURL

curl -X GET "https://api-gateway.firebanking.com.br/pix/v2/payment/pix-key/CHAVE_PIX/e2e/END_TO_END_ID" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json"

Listar transações por chave PIX

cURL

curl -X GET "https://api-gateway.firebanking.com.br/pix/v2/payment/pix-key/CHAVE_PIX?providerId=END_TO_END_ID" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json"

Exemplo de Resposta

{
  "id": "997d58ca-bdfb-481d-93cd-7401e68cc0ea",
  "externalId": "your-external-id",
  "businessId": "6864503fed937a987efcc5f3",
  "endToEndId": null,
  "operation": {
    "provider": "providerName",
    "type": "PAYMENT",
    "status": "WAITING_PAYMENT",
    "value": 0.15,
    "fee": 0.1,
    "finalValue": 0.05,
    "refundValue": 0,
    "description": "Cobrança de teste",
    "additionalInfo": {
      "sellerId": "123",
      "whatsAppPhone": "37988996655"
    }
  },
  "negotiator": {
    "fullName": "John Marvin",
    "document": "***123667**"
  },
  "payer": null,
  "receiver": null,
  "createdAt": "2025-06-28T18:16:09.069Z",
  "updatedAt": "2025-06-28T18:16:09.069Z"
}

Campos de Resposta

string

ID único da transação PIX no FireBanking

externalId

string

ID externo fornecido na criação da transação

businessId

string

ID da empresa/negócio no FireBanking

endToEndId

string

Identificador fim-a-fim da transação PIX (apenas para transações processadas)

operation

object

Dados da operação PIX

Mostrar operation

operation.provider

string

Provedor de pagamento utilizado

operation.type

string

Tipo da operação: PAYMENT (cobrança) ou WITHDRAW (transferência)

operation.status

string

Status atual da transação:

WAITING_PAYMENT - Aguardando pagamento
PAID - Pago com sucesso
WITHDRAW_PAID - Transferência realizada
EXPIRED - Expirado
CANCELLED - Cancelado
REFUNDED - Reembolsado

operation.value

number

Valor da transação em reais

operation.fee

number

Taxa cobrada pela transação

operation.finalValue

number

Valor final líquido da transação

operation.refundValue

number

Valor do estorno (se aplicável)

operation.description

string

Descrição da transação

operation.additionalInfo

object

Informações adicionais da transação

negotiator

object

Dados do solicitante da transação

Mostrar negotiator

negotiator.fullName

string

Nome completo do solicitante

negotiator.document

string

CPF/CNPJ mascarado do solicitante

payer

object

Dados do pagador (apenas para transações pagas)

Mostrar payer

payer.fullName

string

Nome completo do pagador

payer.document

string

CPF/CNPJ mascarado do pagador

receiver

object

Dados do recebedor (apenas para transferências)

Mostrar receiver

receiver.name

string

Nome do recebedor

receiver.document

string

CPF/CNPJ mascarado do recebedor

receiver.bankName

string

Nome do banco do recebedor

receiver.pixKey

string

Chave PIX do recebedor

receiver.pixKeyType

string

Tipo da chave PIX (DOCUMENT, EMAIL, PHONE, RANDOM)

createdAt

string

Data/hora de criação da transação (ISO 8601)

updatedAt

string

Data/hora da última atualização da transação (ISO 8601)

Status da Transação

Estados Possíveis

WAITING_PAYMENT

Descrição: Cobrança criada, aguardando pagamento
QR Code: Disponível e válido
Ações: Cliente pode pagar, você pode cancelar
Próximo status: PAID, EXPIRED, CANCELLED

PAID

Descrição: Pagamento recebido com sucesso
Dados extras: Informações do pagador
Ações: Pode ser estornado (até 90 dias)
Próximo status: REFUNDED (se estornado)

EXPIRED

Descrição: Cobrança expirou sem pagamento
QR Code: Inválido
Ações: Pode criar nova cobrança
Status final: Não muda mais

CANCELLED

Descrição: Cobrança cancelada manualmente
QR Code: Inválido
Ações: Pode criar nova cobrança
Status final: Não muda mais

REFUNDED

Descrição: Transação estornada
Valor: Devolvido ao pagador original
Ações: Estorno processado
Status final: Não muda mais

Casos de Uso

Verificação de Pagamento

async function verificarPagamento(transactionId) {
  const response = await fetch(`https://api-gateway.firebanking.com.br/pix/v2/payment/${transactionId}`, {
    headers: {
      'x-api-key': 'sua_chave_api'
    }
  });

  const payment = await response.json();

  switch (payment.operation.status) {
    case 'PAID':
      console.log('Pagamento confirmado!');
      processarPedido(payment);
      break;
    case 'EXPIRED':
      console.log('Cobrança expirou');
      gerarNovaCobranca(payment.id);
      break;
    case 'WAITING_PAYMENT':
      console.log('Aguardando pagamento...');
      break;
  }
}

Polling para Atualização

function iniciarMonitoramento(transactionId) {
  const interval = setInterval(async () => {
    const payment = await consultarCobranca(transactionId);

    if (payment.operation.status === 'PAID') {
      clearInterval(interval);
      confirmarPagamento(payment);
    } else if (payment.operation.status === 'EXPIRED') {
      clearInterval(interval);
      notificarExpiracao(payment);
    }
  }, 5000); // Verificar a cada 5 segundos

  // Parar após 30 minutos
  setTimeout(() => clearInterval(interval), 30 * 60 * 1000);
}

Códigos de Erro

Código	Descrição
`TRANSACTION_NOT_FOUND`	Transação não encontrada com o ID fornecido
`INVALID_TRANSACTION_ID`	Format do ID da transação inválido
`UNAUTHORIZED_ACCESS`	Transação não pertence à sua conta

Boas Práticas

Performance

Cache resultados: Para transações pagas, cache a resposta
Polling inteligente: Reduza frequência após tempo limite
Batch requests: Consulte múltiplas transações quando possível
Rate limiting: Respeite os limites da API (60 req/min)

Integração

Webhook primeiro: Use webhooks como fonte primária de eventos
Polling como backup: Consulta periódica apenas se webhook falhar
Timeout razoável: Não monitore indefinidamente
Log eventos: Registre mudanças de status para auditoria

Experiência do Usuário

Status em tempo real: Atualize UI conforme status muda
Feedback claro: Explique cada status para o usuário
Ações contextuais: Ofereça ações baseadas no status
Histórico disponível: Permita consulta de transações passadas

Próximos Passos

Criar Cobrança

Volte para criar uma nova cobrança

Estornar PIX

Processe estornos de transações pagas

Webhooks

Configure notificações automáticas

Split PIX

Divida pagamentos entre beneficiários

Authorizations

x-api-key

string

header

required

Chave de API para autenticação

Path Parameters

string

required

ID da transação PIX ou externalId

Response

Detalhes da transação PIX

string

ID único da transação PIX no FireBanking

externalId

string

ID externo fornecido na criação da transação

businessId

string

ID da empresa/negócio no FireBanking

endToEndId

string | null

Identificador fim-a-fim da transação PIX (apenas para transações processadas)

operation

object

Mostrar atributos filhos

operation.provider

string

Provedor de pagamento utilizado

operation.type

enum<string>

Tipo da operação: PAYMENT (cobrança) ou WITHDRAW (transferência)

Opções disponíveis:

PAYMENT,

WITHDRAW

operation.status

enum<string>

Status atual da transação

Opções disponíveis:

WAITING_PAYMENT,

PAID,

WITHDRAW_PAID,

EXPIRED,

CANCELLED,

REFUNDED

operation.value

number

Valor da transação em reais

operation.fee

number

Taxa cobrada pela transação

operation.finalValue

number

Valor final líquido da transação

operation.refundValue

number

Valor do estorno (se aplicável)

operation.description

string

Descrição da transação

operation.additionalInfo

object

Informações adicionais da transação

negotiator

object

Mostrar atributos filhos

negotiator.fullName

string

Nome completo do solicitante

negotiator.document

string

CPF/CNPJ mascarado do solicitante

payer

object

Dados do pagador (apenas para transações pagas)

Mostrar atributos filhos

payer.fullName

string

Nome completo do pagador

payer.document

string

CPF/CNPJ mascarado do pagador

receiver

object

Dados do recebedor (apenas para transferências)

Mostrar atributos filhos

receiver.name

string

Nome do recebedor

receiver.document

string

CPF/CNPJ mascarado do recebedor

receiver.bankName

string

Nome do banco do recebedor

receiver.pixKey

string

Chave PIX do recebedor

receiver.pixKeyType

enum<string>

Tipo da chave PIX

Opções disponíveis:

DOCUMENT,

EMAIL,

PHONE,

RANDOM

createdAt

string<date-time>

Data/hora de criação da transação (ISO 8601)

updatedAt

string<date-time>

Data/hora da última atualização da transação (ISO 8601)

Visão Geral

Fluxo de Integração

PIX Cobrança (Cash In)

PIX Saque (Cash Out)

Operações

Gestão

Webhooks

Visão Geral

Outras formas de consulta

Parâmetros da URL

Exemplo de Requisição

Consulta por chave PIX + transactionId

Consulta por chave PIX + providerID (endToEndId)

Listar transações por chave PIX

Exemplo de Resposta

Campos de Resposta

Status da Transação

Estados Possíveis

Casos de Uso

Verificação de Pagamento

Polling para Atualização

Códigos de Erro

Boas Práticas

Performance

Integração

Experiência do Usuário

Próximos Passos

Criar Cobrança

Estornar PIX

Webhooks

Split PIX

Authorizations

Path Parameters

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

​Outras formas de consulta

​Parâmetros da URL

​Exemplo de Requisição

​Consulta por chave PIX + transactionId

​Consulta por chave PIX + providerID (endToEndId)

​Listar transações por chave PIX

​Exemplo de Resposta

​Campos de Resposta

​Status da Transação

​Estados Possíveis

​Casos de Uso

​Verificação de Pagamento

​Polling para Atualização

​Códigos de Erro

​Boas Práticas

​Performance

​Integração

​Experiência do Usuário

​Próximos Passos

Criar Cobrança

Estornar PIX

Webhooks

Split PIX

Authorizations

Path Parameters

Response

Visão Geral

Outras formas de consulta

Parâmetros da URL

Exemplo de Requisição

Consulta por chave PIX + transactionId

Consulta por chave PIX + providerID (endToEndId)

Listar transações por chave PIX

Exemplo de Resposta

Campos de Resposta

Status da Transação

Estados Possíveis

Casos de Uso

Verificação de Pagamento

Polling para Atualização

Códigos de Erro

Boas Práticas

Performance

Integração

Experiência do Usuário

Próximos Passos