Skip to main content
GET
/
api
/
v1
/
payments
/
{identifier}
Buscar Pagamento
curl --request GET \
  --url https://zeus-sandbox.autorizou.dev/api/v1/payments/{identifier} \
  --header 'Authorization: Bearer <token>'
Este endpoint permite recuperar as informações detalhadas de um pagamento específico usando o UUID ou a Hash do pagamento.

Casos de Uso

  • 📊 Consultar status de pagamentos em tempo real
  • 💰 Verificar valores e detalhes da transação
  • 🔍 Auditoria e reconciliação financeira
  • 📱 Exibir dados na interface do usuário

Parâmetros de URL

identifier
string
required
Identificador do pagamento. Pode ser:
  • UUID do pagamento (ex: `0026621e-ae0c-477b-998d-6442fa0645b2)
  • Hash do pagamento (ex: AUTCUS01K8RSCH3T5FNB7EVACV8DQVNX)

Exemplo de Requisição

curl -X GET https://zeus-sandbox.autorizou.dev/api/v1/payments/0026621e-ae0c-477b-998d-6442fa0645b2 \
  -H "Authorization: Bearer 4eC39HqLyjWDarjtT1zdp7dc"

Resposta de Sucesso

{
  "id": "abe4454e-32d3-49cd-8f79-782080a57b3c",
  "hash": "AUTCUS01K8RSCH3T5FNB7EVACV8DQVNX",
  "merchant_reference": "f916d357-4efc-3648-9633-bfc0686f27ec",
  "status": "paid",
  "payment_method": "credit_card",
  "amount": 15500,
  "original_amount": 15500,
  "installments": 1,
  "currency": "BRL",
  "description": "Compra na Loja Virtual ABC",
  "description": "Omnis omnis rerum omnis delectus et vero recusandae.",
  "notification_url": "http://www.block.info/incidunt-eligendi-impedit-earum-esse-accusantium-dicta-et.html",
  "acquirer_reference": null,
  "return_code": null,
  "refused_reason": null,
  "metadata": null,
  "created_at": "2025-10-24T12:54:51.000000Z",
  "updated_at": "2025-10-24T12:54:51.000000Z"
}

Detalhes da Resposta

Dados Principais

CampoTipoDescrição
idstringUUID único do pagamento
hashstringHash do pagamento
merchant_referencestringReferência do merchant
statusstringStatus atual da transação
payment_methodstringMétodo: credit_card, pix, bank_slip, google_pay
amountintegerValor em centavos
original_amountintegerValor em centavos
installmentsintegerNúmero de parcelas
currencystringMoeda
descriptionstringDescrição da transação
notification_urlstringUrl da notificação
acquirer_referencestringRerefencia do adquirente
return_codestringCódigo de autorização
metadataarrayDados adicionais do pagamento

Status Possíveis

StatusDescriçãoFinalizado
authorizedAutorizado (aguarda captura)
authentication_requestedAutenticação solicitada
waiting_paymentAguardando pagamento
refusedRecusado pelo banco
refundedEstornado
errorErro
processingSendo processado

Códigos de Erro

Pagamento não encontrado
{
  "message": "Pagamento não encontrado"
}
Possíveis causas:
  • UUID ou hash não existe
  • Pagamento pertence a outro merchant
  • UUID ou hash mal formado
UUID inválido
{
  "message": "UUID do pagamento é inválido"
}

Casos de Uso Práticos

Verificação de Status

async function verificarStatusPagamento(paymentId) {
  const payment = await fetch(`https://zeus-sandbox.autorizou.dev/api/v1/payments/${paymentId}`, {
    headers: { 'Authorization': 'Bearer ...' }
  }).then(res => res.json());
  
  const statusMap = {
    pending: { color: 'yellow', text: 'Aguardando' },
    processing: { color: 'blue', text: 'Processando' },
    authorized: { color: 'orange', text: 'Autorizado' },
    paid: { color: 'green', text: 'Pago' },
    refused: { color: 'red', text: 'Recusado' },
    cancelled: { color: 'gray', text: 'Cancelado' },
    refunded: { color: 'purple', text: 'Estornado' }
  };
  
  return {
    id: payment.id,
    status: payment.status,
    display: statusMap[payment.status] || { color: 'gray', text: 'Desconhecido' },
    amount: payment.amount / 100,
    canRefund: payment.status === 'paid',
    canCancel: payment.status === 'authorized'
  };
}

Formatação para Display

function formatarPagamentoParaExibicao(payment) {
  const paymentMethods = {
    credit_card: '💳 Cartão de Crédito',
    pix: '🏦 PIX',
    bank_slip: '📄 Boleto'
  };
  
  const statusIcons = {
    paid: '✅',
    pending: '⏳',
    refused: '❌',
    cancelled: '🚫'
  };
  
  return {
    id: payment.id,
    displayId: payment.id.substring(0, 8) + '...',
    method: paymentMethods[payment.payment_method] || payment.payment_method,
    status: `${statusIcons[payment.status] || '⚪'} ${payment.status}`,
    amount: `R$ ${(payment.amount / 100).toLocaleString('pt-BR', { minimumFractionDigits: 2 })}`,
    date: new Date(payment.created_at).toLocaleDateString('pt-BR'),
    reference: payment.merchant_reference
  };
}

Polling de Status

async function aguardarPagamento(paymentId, timeout = 300000) { // 5 minutos
  const startTime = Date.now();
  const interval = 5000; // 5 segundos
  
  return new Promise((resolve, reject) => {
    const checkPayment = async () => {
      try {
        const payment = await buscarPagamento(paymentId);
        
        // Status finais
        if (['paid', 'refused', 'cancelled', 'refunded'].includes(payment.status)) {
          resolve(payment);
          return;
        }
        
        // Timeout
        if (Date.now() - startTime > timeout) {
          reject(new Error('Timeout aguardando confirmação do pagamento'));
          return;
        }
        
        // Continuar aguardando
        setTimeout(checkPayment, interval);
      } catch (error) {
        reject(error);
      }
    };
    
    checkPayment();
  });
}

Considerações de Performance

Cache inteligente: Status finais (paid, refused, cancelled, refunded) podem ser cached por longos períodos.
Polling eficiente: Para pagamentos em processamento, use intervalos de 5-10 segundos para verificar status.

Webhook vs Polling

Use webhooks: Prefira sempre webhooks em vez de polling para receber atualizações de status em tempo real.
// ✅ Recomendado: Webhook
app.post('/webhook/autorizou', (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'payment.status_changed') {
    console.log(`Pagamento ${data.payment.id} mudou para ${data.payment.status}`);
    // Atualizar base de dados
    updatePaymentStatus(data.payment.id, data.payment.status);
  }
  
  res.status(200).send('OK');
});

// ❌ Evitar: Polling excessivo
setInterval(() => {
  checkAllPendingPayments(); // Sobrecarrega a API
}, 1000);

Próximos Passos

Após consultar um pagamento:
  1. Processar estorno se necessário
  2. Configurar webhooks
  3. Atualizar detalhes do pagamento
  4. Analisar métricas de conversão