Consultar Status de Cobrança PIX

Esta seção explica como consultar o status de uma cobrança PIX específica usando sua referência única.

Visão Geral

Após criar uma cobrança, você precisará verificar periodicamente se ela foi paga. O endpoint de status permite consultar o estado atual de uma cobrança específica usando a referência retornada no momento da criação.

Endpoint

GET /account/{account_id}/charge/pix/status

Consulta o status de uma cobrança PIX específica através da referência.

URL Completa:

https://app.finexis.com.br/api/v1/gateway/account/{account_id}/charge/pix/status?reference={reference}

Headers:

Authorization: Bearer {token}

Parâmetros da URL:

• account_id (obrigatório): ID da conta

Query Parameters:

• reference (obrigatório): Referência da cobrança retornada no momento da criação

Exemplo de URL:

https://app.finexis.com.br/api/v1/gateway/account/5/charge/pix/status?reference=f8a5ed1f774f4ac4ad4849c5e2

Exemplo de Requisição:

curl -X GET \
  'https://app.finexis.com.br/api/v1/gateway/account/5/charge/pix/status?reference=f8a5ed1f774f4ac4ad4849c5e2' \
  -H 'Authorization: Bearer {seu_token}'

Resposta de Sucesso (200):

{
  "status": "success",
  "message": "Charge status retrieved successfully",
  "data": {
    "id": 1,
    "account_id": 5,
    "provider_id": 2,
    "amount": "4.000000000000000000",
    "currency": "BRL",
    "status": "pending",
    "description": null,
    "content": "00020101021226880014br.gov.bcb.pix2566qrcode.microcashif.com.br/pix/fc52d462-1f2d-4828-b7f0-e57d60c9c3fb5204000053039865802BR5909VITALCRED6005Natal61085905476062070503***6304C116",
    "external_id": "1e97ebcb-d550-4e3c-942a-16ef9cc61f62",
    "reference": "f8a5ed1f774f4ac4ad4849c5e2",
    "metadata": {
      "emv": "00020101021226880014br.gov.bcb.pix2566qrcode.microcashif.com.br/pix/fc52d462-1f2d-4828-b7f0-e57d60c9c3fb5204000053039865802BR5909VITALCRED6005Natal61085905476062070503***6304C116",
      "amount": 4,
      "description": "Sistema Prometheus - Cobrança",
      "uuid": "1e97ebcb-d550-4e3c-942a-16ef9cc61f62",
      "nonce": "nOPuuXLj4u8naSPd",
      "reference": "f8a5ed1f774f4ac4ad4849c5e2",
      "sha256": "7af064168ba9f6a149b846b703652124f4da53fc729cbe07e31a697b59f166be",
      "hash_schema": ["reference", "amount", "nonce"],
      "expires_in": 3600,
      "expires_at": "2025-11-17T17:45:34.371Z",
      "coust": 0,
      "tx_id": "f8a5ed1f774f4ac4ad4849c5e2",
      "id": 7763887,
      "status": "ACTIVE"
    },
    "created_at": "2025-11-17 17:35:34",
    "updated_at": "2025-11-17 17:35:34"
  }
}

Status Possíveis

Status	Descrição	Ação
pending	Cobrança pendente de pagamento	Continue monitorando
paid	Cobrança paga	Processe a confirmação
expired	Cobrança expirada	Crie uma nova cobrança se necessário
cancelled	Cobrança cancelada	Não será processada

Estratégias de Consulta

Polling (Consulta Periódica)

A forma mais comum de verificar o status é fazer consultas periódicas:

// Exemplo: consultar a cada 5 segundos
const checkChargeStatus = async (accountId, reference) => {
  const interval = setInterval(async () => {
    const response = await fetch(
      `https://app.finexis.com.br/api/v1/gateway/account/${accountId}/charge/pix/status?reference=${reference}`,
      {
        headers: {
          'Authorization': `Bearer ${token}`
        }
      }
    );
    
    const data = await response.json();
    
    if (data.data.status === 'paid') {
      clearInterval(interval);
      console.log('Cobrança paga!');
      // Processar confirmação de pagamento
    } else if (data.data.status === 'expired' || data.data.status === 'cancelled') {
      clearInterval(interval);
      console.log('Cobrança expirada ou cancelada');
    }
  }, 5000); // Consultar a cada 5 segundos
};

Recomendação

• Para cobranças com expiração de 1 hora, consulte a cada 5-10 segundos
• Pare de consultar quando o status for paid, expired ou cancelled
• Considere implementar um timeout para evitar consultas infinitas

Consulta Única

Se você já sabe que a cobrança foi paga (por exemplo, através de webhook), pode fazer uma consulta única para confirmar:

const verifyPayment = async (accountId, reference) => {
  const response = await fetch(
    `https://app.finexis.com.br/api/v1/gateway/account/${accountId}/charge/pix/status?reference=${reference}`,
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  const data = await response.json();
  return data.data.status === 'paid';
};

Verificando Expiração

Você pode verificar se a cobrança expirou comparando a data atual com metadata.expires_at:

const isExpired = (charge) => {
  const expiresAt = new Date(charge.metadata.expires_at);
  const now = new Date();
  return now > expiresAt;
};

Próximos Passos

• Criar Nova Cobrança
• Listar Todas as Cobranças
• Ver Fluxo de Trabalho Completo