Pagamentos

Pagamentos representam tentativas de cobrança associadas a faturas. Cada pagamento rastreia o status, método, gateway utilizado e resposta do provedor.

Estados do Pagamento

pending → processing → succeeded → refunded
             ↓             ↓
           failed    partially_refunded
             ↓
          canceled

Status	Descrição
pending	Aguardando processamento
processing	Enviado ao gateway, aguardando resposta
succeeded	Confirmado como pago
failed	Recusado pelo gateway ou erro
canceled	Cancelado manualmente
partial	Pagamento parcial recebido
refunded	Totalmente reembolsado
partially_refunded	Parcialmente reembolsado

Fluxo de Pagamento

1. Cobrança Automática (charge_automatically)

Fatura finalizada
  → Aplica créditos automaticamente
  → Se créditos pagam tudo: fatura = paid
  → Se não:
    → Obtém método de pagamento padrão
    → Processa pagamento via gateway
    → Cartão: resposta imediata
    → Boleto/PIX: aguarda webhook do gateway
  → Sucesso: fatura = paid
  → Falha: agenda retry (dunning)

2. Pagamento Manual

O operador ou cliente aciona o pagamento via dashboard ou portal.

Processando um Pagamento

Ao processar, o sistema:

1. Valida que a fatura está open
2. Determina o método de pagamento (fornecido, salvo ou padrão)
3. Obtém o gateway da organização para o tipo de pagamento
4. Cria registro do pagamento com chave de idempotência
5. Envia cobrança ao gateway
6. Atualiza o pagamento com a resposta

Idempotência

Cada pagamento tem uma chave de idempotência única. Requisições duplicadas retornam o resultado existente sem processar novamente.

Cenários Especiais

Pagamento Parcial

• O valor recebido é menor que o total
• A fatura permanece open com o saldo atualizado
• O cliente pode pagar o restante com outro pagamento

Pagamento Excedente (Overpayment)

Quando o valor pago excede o saldo da fatura:

1. O valor da fatura é aplicado normalmente
2. O excedente vira crédito automaticamente na conta do cliente
3. O crédito é do tipo adjustment com descrição "Crédito de pagamento excedente na fatura {número}"
4. O crédito será aplicado automaticamente em faturas futuras

Fatura Já Paga

Se a fatura já estava paga quando o pagamento é processado, o valor total vira crédito na conta do cliente.

Operações

Cancelar Pagamento

Apenas pagamentos pending podem ser cancelados. Para boleto/PIX, o cancelamento é enviado ao gateway.

Reembolsar

Pagamentos succeeded ou partially_refunded podem ser reembolsados:

• Reembolso total: Status muda para refunded
• Reembolso parcial: Status muda para partially_refunded
• A requisição é enviada ao gateway quando disponível

Tentar Novamente

Pagamentos failed podem ser retentados. Um novo pagamento é criado com o mesmo valor, fatura e método.

Capturas de tela

Lista de pagamentos

A tela /dashboard/payments agrega todos os pagamentos recebidos, com filtros por status, método, gateway, cliente e período. Cada linha mostra fatura relacionada, valor, taxa do gateway, valor líquido e mensagem de retorno.

Detalhe do pagamento

A página /dashboard/payments/[id] traz o registro completo: gateway, transação no provedor, fatura quitada, método (com últimos 4 dígitos do cartão ou banco do boleto), histórico de tentativas, estornos e webhooks recebidos.