Facturación, Organizaciones y Reembolsos
Configuración de facturación
Modelo
- Una pasarela activa para toda la plataforma (sin carrito multi-proveedor).
- Credenciales y conductor activo: Administrador → Configuración → Pagos.
- Webhooks: POST /webhooks/{driver} (exento de CSRF).
Proveedores disponibles
| Driver | Implemented | Best for |
|---|---|---|
| stripe | Yes | Global cards, Checkout, mature subscriptions |
| paddle | Yes | Merchant of Record, tax-heavy SaaS |
| mollie | Yes | European methods + recurring mandates |
| airwallex | No (credentials UI only) | Future multi-currency; not selectable yet |
| fake | Tests only | PHPUnit; blocked by launch-check in production |
Lista de verificación del operador
- Elija la pasarela de pago activa.
- Pega las claves de la API + el secreto del webhook para ese proveedor.
- Registrar la URL del webhook de producción en el panel del proveedor.
- Realiza una compra de prueba con claves de prueba antes de salir en producción.
- Nunca dejes Fake como alternativa silenciosa: los errores de configuración deben fallar con estruendo.
Modelo de suscripción (resumen)
- Una suscripción por instalación (no por organización).
- Los complementos se adjuntan a esa suscripción o derecho de la instalación.
- El objeto de cliente del proveedor se asigna al perfil de facturación de la organización.
- Cancelar renovación: utilizable hasta el final del período y luego eliminar de forma diferida (reglas de negocio).
- Fallo en el pago: recordatorio de cobro → banner de gracia → suspensión → eliminación suave → eliminación definitiva después de los días de retención.
Gracia y retención: Admin → Configuración → Facturación
Trabajo programado: billing:process-lifecycle (Componer programador).
Reembolsos
Flujo de clientes
- Desde la pestaña Facturación de la instalación, un miembro de la organización con permisos envía una solicitud de reembolso (referencia de factura opcional).
- Solo una solicitud pendiente por instalación a la vez (aplicado en el servicio).
- El cliente recibe una notificación de aprobación o rechazo por correo electrónico cuando el SMTP funciona.
Flujo de administración
- Admin → Reembolsos muestra solicitudes pendientes.
- Aprobar o Rechazar.
Marcador de captura de pantalla: lista de solicitudes de reembolso del administrador con opciones Aprobar / Rechazar
¿Qué sucede al aprobar?
Secuencia aproximada (BillingService::approveRefund + gateway):
- Llamar al proveedor de pagos para reembolsar el pago más reciente (total o parcial según la implementación).
- Cancelar la suscripción del proveedor.
- Marque la instalación para su terminación inmediata / eliminación suave.
- Establecer hard_delete_after usando refund_hard_delete_days (valor predeterminado: 7 días, no la ventana normal de eliminación suave de 30 días).
- Suspende el acceso a los bordes para que la tienda en línea esté fuera de servicio.
- Notifique al cliente.
- Cuando expire hard_delete_after, el trabajo del ciclo de vida hard-deletes: elimina las copias de seguridad, destruye los recursos del host y elimina los datos del tenant según lo implementado.
Efectos secundarios (mensajes del operador)
| Topic | Effect |
|---|---|
| Money | Provider refund of the latest payment path (gateway-specific). |
| Access | Installation stops being usable quickly (soft-deleted / suspended). |
| Data retention | Short window (default 7 days) then hard delete. |
| Backups | Purged on hard delete path. |
| Re-open | Not a simple “undo”; customer would need a new installation/checkout. |
Contrasta con otras salidas
| Action | Typical effect |
|---|---|
| Cancel renewal | Runs until period end; then soft-delete with longer retention |
| Approved refund | Immediate terminate path; shorter hard-delete (default 7 days) |
| ToS suspend (admin) | Offline; no automatic refund |
| Payment failure | Grace banner → suspend → soft-delete rules |
Organizaciones y asientos
Organización personal
Creado automáticamente al registrarse. El usuario es el propietario. Los límites provienen de:
- Administrador → Configuración → Implementaciones → instalaciones máximas predeterminadas / asientos máximos
- O las anulaciones del administrador en el registro de la organización
Organizaciones del equipo
Los propietarios/administradores pueden crear organizaciones de equipo (consulte la interfaz de organización del cliente). Los asientos y los límites de instalación se aplican por organización.
Roles
| Role | Typical powers |
|---|---|
| Owner | Full org control, billing, members |
| Admin | Manage members & installs |
| Member | Work on installations (no full billing admin) |
| Billing | Billing-focused access |
Las puertas exactas siguen las políticas en la aplicación; trata al propietario/administrador como privilegiado.
Invitaciones
- Invita a usuarios existentes de la plataforma (el correo electrónico ya debe tener una cuenta).
- No hay un “correo de invitación” de MVP que cree una cuenta desde cero.
- Verificación de asiento: no se puede invitar más allá de max_seats.
Anulaciones del administrador
Los administradores de la plataforma pueden aumentar o reducir max_seats y max_installations por organización desde la interfaz de organizaciones de administración cuando esté disponible.