Fatturazione, organizzazioni e rimborsi
Impostazioni di fatturazione
Modello
- Un gateway attivo per l’intera piattaforma (nessun carrello multi-provider).
- Credenziali e driver attivo: Admin → Impostazioni → Pagamenti.
- Webhook: POST /webhooks/{driver} (CSRF-esente).
Fornitori disponibili
| 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 |
Checklist dell’operatore
- Scegli il gateway di pagamento attivo.
- Incolla le chiavi API + il segreto webhook per quel provider.
- Registra l’URL del webhook di produzione nella dashboard del provider.
- Esegui un test di checkout con chiavi di test prima di andare online.
- Non lasciare Fake come fallback silenzioso: gli errori di configurazione devono emergere in modo evidente.
Modello di abbonamento (sintesi)
- Una sottoscrizione per installazione (non per organizzazione).
- I componenti aggiuntivi si collegano a tale abbonamento/entitlement di installazione.
- L’oggetto cliente del provider viene mappato al profilo di fatturazione dell’organizzazione.
- Annulla rinnovo: utilizzabile fino alla fine del periodo, quindi percorso di eliminazione soft (regole aziendali).
- Pagamento non riuscito: sollecito → banner di grazia → sospensione → eliminazione soft → eliminazione hard dopo i giorni di conservazione.
Grace e retentione: Admin → Impostazioni → Fatturazione
Processo pianificato: billing:process-lifecycle (Compose scheduler).
Rimborsi
Flusso dei clienti
- Nella scheda Fatturazione dell’installazione, un membro dell’organizzazione abilitato invia una richiesta di rimborso (riferimento fattura facoltativo).
- Solo una richiesta in sospeso alla volta per installazione (applicata nel servizio).
- Il cliente viene informato dell’approvazione o del rifiuto via e-mail quando l’SMTP funziona.
Flusso di amministrazione
- Admin → Rimborsi elenca le richieste in sospeso.
- Approva o rifiuta.
Segnaposto screenshot: Elenco delle richieste di rimborso dell’amministratore con Approva / Rifiuta
Cosa succede su approva
Sequenza approssimativa (BillingService::approveRefund + gateway):
- Chiama il provider di pagamento refundLatestPayment (completo o parziale, in base all’implementazione).
- Annulla l’abbonamento al provider.
- Contrassegna l’installazione per terminazione immediata / eliminazione soft.
- Imposta hard_delete_after utilizzando refund_hard_delete_days (impostazione predefinita: 7 giorni, non la normale finestra di soft-delete di 30 giorni).
- Disabilita l’accesso al bordo per mettere il negozio online offline.
- Avvisare il cliente.
- Quando scade hard_delete_after, il job del ciclo di vita esegue hard-delete: elimina le copie di backup, distrugge le risorse dell’host e rimuove i dati del tenant come implementato.
Effetti collaterali (messaggistica dell’operatore)
| 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. |
Confronta con le altre uscite
| 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 |
Organizzazioni e seggi
Organizzazione personale
Creato automaticamente al momento della registrazione. L’utente è il proprietario. I limiti provengono da:
- Admin → Impostazioni → Distribuzioni → installazioni massime predefinite / posti massimi
- Oltre alle sovrascritture dell’amministratore sul record dell’organizzazione
Organizzazioni di squadra
I proprietari/amministratori possono creare organizzazioni di team (vedi l’interfaccia utente dell’organizzazione del cliente). I posti e i limiti di installazione si applicano per ogni organizzazione.
Ruoli
| 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 |
I gate esatti seguono le policy nell’app; tratta il proprietario/amministratore come privilegiato.
Inviti
- Invita utenti esistenti della piattaforma (l’e-mail deve già avere un account).
- Non esiste un’email di invito MVP “che crea un account da zero”.
- Controllo posti: impossibile invitare oltre il numero massimo di posti (max_seats).
Sovrascritture dell’amministratore
Gli amministratori della piattaforma possono aumentare/ridurre max_seats e max_installations per organizzazione dall’interfaccia utente delle organizzazioni amministrative, quando disponibile.