Pagos

Los pagos representan intentos de cobro asociados a facturas. Cada pago rastrea el estado, método, gateway utilizado y respuesta del proveedor.

Estados del Pago

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

Status	Descripción
pending	Esperando procesamiento
processing	Enviado al gateway, esperando respuesta
succeeded	Confirmado como pagado
failed	Rechazado por el gateway o error
canceled	Cancelado manualmente
partial	Pago parcial recibido
refunded	Totalmente reembolsado
partially_refunded	Parcialmente reembolsado

Flujo de Pago

1. Cobro Automático (charge_automatically)

Factura finalizada
  → Aplica créditos automáticamente
  → Si los créditos pagan todo: factura = paid
  → Si no:
    → Obtiene método de pago predeterminado
    → Procesa pago vía gateway
    → Tarjeta: respuesta inmediata
    → Boleto/PIX: espera webhook del gateway
  → Éxito: factura = paid
  → Fallo: agenda retry (dunning)

2. Pago Manual

El operador o cliente acciona el pago vía dashboard o portal.

Procesando un Pago

Al procesar, el sistema:

1. Valida que la factura esté open
2. Determina el método de pago (proporcionado, guardado o predeterminado)
3. Obtiene el gateway de la organización para el tipo de pago
4. Crea registro del pago con clave de idempotencia
5. Envía cobro al gateway
6. Actualiza el pago con la respuesta

Idempotencia

Cada pago tiene una clave de idempotencia única. Solicitudes duplicadas retornan el resultado existente sin procesar nuevamente.

Escenarios Especiales

Pago Parcial

• El valor recibido es menor que el total
• La factura permanece open con el saldo actualizado
• El cliente puede pagar el restante con otro pago

Pago Excedente (Overpayment)

Cuando el valor pagado excede el saldo de la factura:

1. El valor de la factura se aplica normalmente
2. El excedente se convierte en crédito automáticamente en la cuenta del cliente
3. El crédito es del tipo adjustment con descripción "Crédito de pago excedente en la factura {número}"
4. El crédito será aplicado automáticamente en facturas futuras

Factura Ya Pagada

Si la factura ya estaba pagada cuando el pago es procesado, el valor total se convierte en crédito en la cuenta del cliente.

Operaciones

Cancelar Pago

Solo pagos pending pueden ser cancelados. Para boleto/PIX, la cancelación es enviada al gateway.

Reembolsar

Pagos succeeded o partially_refunded pueden ser reembolsados:

• Reembolso total: El status cambia a refunded
• Reembolso parcial: El status cambia a partially_refunded
• La solicitud es enviada al gateway cuando está disponible

Reintentar

Pagos failed pueden ser reintentados. Un nuevo pago es creado con el mismo valor, factura y método.