Consultar Status de Transferência PIX

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

Visão Geral

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

Endpoint

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

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

URL Completa:

https://app.finexis.com.br/api/v1/gateway/account/{account_id}/transfer/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 transferência retornada no momento da criação

Exemplo de URL:

https://app.finexis.com.br/api/v1/gateway/account/5/transfer/pix/status?reference=4a31c00169c84021ae61d9b71c

Exemplo de Requisição:

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

Resposta de Sucesso (200):

{
  "status": "success",
  "message": "Transaction status retrieved successfully",
  "data": {
    "id": 1,
    "account_id": 5,
    "provider_id": 2,
    "amount": "0.100000000000000000",
    "currency": "BRL",
    "type": "credit",
    "status": "paid",
    "description": null,
    "external_id": null,
    "reference": "4a31c00169c84021ae61d9b71c",
    "metadata": [],
    "created_at": "2025-11-18 02:03:02",
    "updated_at": "2025-11-18 02:03:02"
  }
}

Status Possíveis

Status	Descrição	Ação
pending	Transferência pendente	Continue monitorando
paid	Transferência concluída	Processo finalizado com sucesso
failed	Transferência falhou	Verifique os detalhes e tente novamente
cancelled	Transferência cancelada	Não será processada

Estratégias de Consulta

Polling (Consulta Periódica)

Para transferências que podem demorar alguns segundos para serem processadas:

// Exemplo: consultar a cada 3 segundos
const checkTransferStatus = async (accountId, reference) => {
  const maxAttempts = 20; // Máximo de 20 tentativas (1 minuto)
  let attempts = 0;
  
  const interval = setInterval(async () => {
    attempts++;
    
    const response = await fetch(
      `https://app.finexis.com.br/api/v1/gateway/account/${accountId}/transfer/pix/status?reference=${reference}`,
      {
        headers: {
          'Authorization': `Bearer ${token}`
        }
      }
    );
    
    const data = await response.json();
    const status = data.data.status;
    
    if (status === 'paid') {
      clearInterval(interval);
      console.log('Transferência concluída!');
      // Processar confirmação
    } else if (status === 'failed' || status === 'cancelled') {
      clearInterval(interval);
      console.log('Transferência falhou ou foi cancelada');
      // Tratar erro
    } else if (attempts >= maxAttempts) {
      clearInterval(interval);
      console.log('Timeout: transferência ainda pendente');
      // Tratar timeout
    }
  }, 3000); // Consultar a cada 3 segundos
};

Recomendação

• Para transferências PIX, geralmente são processadas rapidamente (segundos)
• Consulte a cada 2-3 segundos
• Implemente um timeout para evitar consultas infinitas
• Pare de consultar quando o status for final (paid, failed, cancelled)

Consulta Única

Se você já recebeu uma notificação (webhook) ou quer apenas verificar o status atual:

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

Tratamento de Erros

Transferência Falhou

Quando uma transferência falha, você pode:

1. Verificar o motivo: Alguns erros podem estar nos metadados
2. Verificar saldo: Certifique-se de que há saldo suficiente
3. Validar chave PIX: Verifique se a chave está correta e ativa
4. Tentar novamente: Se o erro foi temporário, você pode criar uma nova transferência

if (transfer.status === 'failed') {
  // Log do erro para análise
  console.error('Transferência falhou:', transfer);
  
  // Verificar se pode tentar novamente
  if (isRetryableError(transfer)) {
    // Tentar novamente após um delay
    setTimeout(() => {
      retryTransfer(accountId, pixKey, pixType, amount);
    }, 5000);
  }
}

Verificando Conclusão

Para garantir que uma transferência foi realmente concluída:

const isTransferCompleted = (transfer) => {
  return transfer.status === 'paid' && 
         transfer.type === 'debit' && // Transferências de envio são débitos
         transfer.updated_at !== transfer.created_at; // Foi atualizada
};

Próximos Passos

• Criar Nova Transferência
• Listar Todas as Transferências
• Ver Fluxo de Trabalho Completo