Pular para o conteúdo principal

​
Visão Geral de Status

Um pagamento passa por vários status desde a criação até a liquidação final. Rastrear esses status permite confirmar a entrega, detectar falhas antecipadamente e fornecer informações precisas aos seus usuários.

​
Fluxo de Status

​
Descrição dos Status

StatusDescriçãoMensagem Sugerida
CREATEDO pagamento foi recebido e persistido. Aguarda entrada na fila de processamento.”Pagamento enviado”
PENDINGO pagamento está na fila aguardando ser despachado ao provedor de pagamentos.”Em breve em processamento”
PROCESSINGO desembolso foi submetido ao provedor de pagamentos e aguarda confirmação.”Transferência em andamento”
COMPLETEDO provedor de pagamentos confirmou a entrega bem-sucedida dos fundos ao beneficiário.”Pagamento entregue!”
ERROROcorreu um erro interno no sistema. Nenhum fundo foi desembolsado. Contate o suporte se persistir.”Erro interno — contate o suporte”
FAILEDO desembolso foi recusado devido a dados de conta do beneficiário inválidos ou incorretos.”Transferência falhou — verifique os dados do beneficiário”
REJECTEDO pagamento foi bloqueado por uma revisão de conformidade e não será processado.”Transferência rejeitada — problema de conformidade”
REFUNDEDOs fundos desembolsados foram devolvidos ao saldo pré-financiado.”Fundos reembolsados ao saldo”

​
Obter Status do Pagamento

GET /api/v2/payouts/{id}

const obterStatusPagamento = async (payoutId) => {
  const response = await fetch(
    `https://sandbox.killb.app/api/v2/payouts/${payoutId}`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );

  const pagamento = await response.json();
  return pagamento.status;
};

​
Polling de Status

Use polling como fallback quando webhooks não estiverem disponíveis: 
const aguardarPagamento = async (payoutId, timeoutMs = 300000) => {
  const statusTerminais = ['COMPLETED', 'ERROR', 'FAILED', 'REJECTED', 'REFUNDED'];
  const inicio = Date.now();

  while (Date.now() - inicio < timeoutMs) {
    const response = await fetch(
      `https://sandbox.killb.app/api/v2/payouts/${payoutId}`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );

    const pagamento = await response.json();
    console.log('Status:', pagamento.status);

    if (statusTerminais.includes(pagamento.status)) {
      return pagamento;
    }

    // Aguardar 15 segundos antes da próxima verificação
    await new Promise(resolve => setTimeout(resolve, 15000));
  }

  throw new Error(`Pagamento ${payoutId} não liquidou dentro do timeout`);
};

const resultado = await aguardarPagamento('payout-abc123');

if (resultado.status === 'COMPLETED') {
  console.log('Fundos entregues com sucesso');
} else {
  console.error('Pagamento encerrado com status:', resultado.status);
}
Use webhooks como método de notificação principal. Polling a cada 15–30 segundos é apropriado como backup.

​
Webhooks para Atualizações de Status

Assine o tipo de evento PAYOUT para receber notificações em tempo real a cada mudança de status: 
// Assinar eventos de pagamento
await fetch('/api/v2/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://seu-app.com/webhooks/killb',
    secret: 'seu-segredo-webhook',
    events: ['PAYOUT'],
    active: true
  })
});
Gerencie os eventos webhook de pagamento recebidos: 
app.post('/webhooks/killb', (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case 'payout.pending':
      atualizarStatusPagamento(data.id, 'PENDING');
      break;

    case 'payout.processing':
      atualizarStatusPagamento(data.id, 'PROCESSING');
      break;

    case 'payout.completed':
      atualizarStatusPagamento(data.id, 'COMPLETED');
      notificarDestinatario(data);
      break;

    case 'payout.error':
      // Erro interno do sistema — nenhum fundo desembolsado
      atualizarStatusPagamento(data.id, 'ERROR');
      alertarEquipeOps(data);
      break;

    case 'payout.failed':
      // Dados de conta do beneficiário inválidos ou incorretos
      atualizarStatusPagamento(data.id, 'FAILED');
      notificarBeneficiarioInvalido(data);
      break;

    case 'payout.rejected':
      // Bloqueado por revisão de conformidade
      atualizarStatusPagamento(data.id, 'REJECTED');
      escalarParaConformidade(data);
      break;

    case 'payout.refunded':
      // Fundos devolvidos ao saldo pré-financiado
      atualizarStatusPagamento(data.id, 'REFUNDED');
      reconciliarSaldo(data);
      break;
  }

  res.status(200).json({ received: true });
});

​
Boas Práticas

Sempre configure um endpoint webhook para eventos PAYOUT. Isso fornece atualizações instantâneas de status sem sobrecarga de polling e reduz chamadas desnecessárias à API.
Se a entrega do webhook falhar, consulte GET /api/v2/payouts/{id} a cada 15–30 segundos. Defina um timeout razoável (ex.: 5 minutos) e alerte sua equipe se um pagamento permanecer em PROCESSING por mais tempo que o esperado.
Cada status de falha tem uma causa distinta e a remediação apropriada difere:
  • ERROR — Um problema interno do sistema na KillB. Nenhuma ação é necessária nos dados do beneficiário; contate o suporte se o problema persistir.
  • FAILED — O banco do beneficiário recusou a transferência devido a dados de conta inválidos ou incorretos. Revise e corrija os dados do beneficiário antes de retentar.
  • REJECTED — O pagamento foi bloqueado por uma revisão de conformidade. Não retentar automaticamente; escalar internamente para revisão.
Obtenha todos os pagamentos do dia anterior via GET /api/v2/payouts e reconcilie com seu livro-razão interno. Compare os status terminais esperados vs. reais para detectar discrepâncias antecipadamente.
const { payouts } = await listarPagamentos({ limit: 100 });
const precisamAtencao = payouts.filter(p =>
  ['ERROR', 'FAILED', 'REJECTED'].includes(p.status)
);

if (precisamAtencao.length > 0) {
  console.warn(`${precisamAtencao.length} pagamentos precisam de atenção`, precisamAtencao);
}

​
Próximos Passos

Configurar Webhooks

Configure e proteja notificações webhook

Tratamento de Erros

Gerencie falhas da API com elegância