Faturamento, Organizações e Reembolsos
Configurações de faturamento
Modelo
- Um gateway ativo para toda a plataforma (sem carrinho com vários provedores).
- Credenciais e motorista ativo: Administrador → Configurações → Pagamentos.
- Webhooks: POST /webhooks/{driver} (isento de CSRF).
Provedores disponíveis
| 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 verificação do operador
- Escolha o gateway de pagamento ativo.
- Cole as chaves da API + o segredo do webhook para esse provedor.
- Registre a URL do webhook de produção no painel do provedor.
- Faça um teste de checkout com chaves de teste antes de entrar no ar.
- Nunca deixe o “Fake” como fallback silencioso — erros de configuração devem falhar ruidosamente.
Modelo de assinatura (resumo)
- Uma assinatura por instalação (não por organização).
- Os add-ons são vinculados a essa assinatura/entitlement da instalação.
- O objeto do cliente do provedor é mapeado para o perfil de faturamento da organização.
- Cancelar renovação: utilizável até o fim do período; depois, caminho de exclusão suave (regras de negócio).
- Falha no pagamento: cobrança → banner de carência → suspensão → exclusão suave → exclusão definitiva após os dias de retenção.
Gravação e retenção: Admin → Configurações → Cobrança
Tarefa agendada: billing:process-lifecycle (Compose scheduler).
Reembolsos
Fluxo do cliente
- Na guia de Cobrança da Instalação, um membro de uma organização com permissão envia uma solicitação de reembolso (referência de fatura opcional).
- Apenas uma solicitação pendente por instalação (aplicado no serviço).
- O cliente é notificado da aprovação/rejeição por e-mail quando o SMTP funciona.
Fluxo do administrador
- Admin → Reembolsos lista solicitações pendentes.
- Aprovar ou Rejeitar.
Placeholder de captura de tela: lista de solicitações de reembolso do administrador com Aprovar / Rejeitar
O que acontece ao aprovar
Sequência aproximada (BillingService::approveRefund + gateway):
- Chame o provedor de pagamentos para reembolsar o pagamento mais recente (integral ou parcial, conforme a implementação).
- Cancele a assinatura do provedor.
- Marque a instalação para encerramento imediato / exclusão suave.
- Defina hard_delete_after usando refund_hard_delete_days (padrão de 7 dias, não a janela normal de exclusão suave de 30 dias).
- Suspenda o acesso à borda para que a loja fique offline.
- Notifique o cliente.
- Quando o hard_delete_after expira, o job de ciclo de vida faz hard-delete: purga backups, destrói recursos do host e remove os dados do tenant conforme implementado.
Efeitos colaterais (mensagens do 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. |
Contraste com outras saídas
| 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 |
Organizações e assentos
Organização pessoal
Criado automaticamente no cadastro. O utilizador é o proprietário. Os limites vêm de:
- Admin → Configurações → Deployments → instalações máximas padrão / assentos máximos
- Ou substituições do administrador no registro da organização
Organizações da equipe
Os proprietários/admins podem criar organizações de equipe (consulte a interface do usuário da organização do cliente). Assentos e limites de instalação se aplicam por organização.
Papéis
| 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 |
As portas exatas seguem as políticas no aplicativo; trate o proprietário/admin como privilegiado.
Convites
- Convida usuários existentes da plataforma (o e-mail já deve ter uma conta).
- Não existe um “e-mail de convite” para um MVP que crie uma conta do zero.
- Verificação de assento: não é possível convidar além de max_seats.
Substituições do administrador
Os administradores da plataforma podem aumentar/diminuir max_seats e max_installations por organização na interface de organizações de administração, quando disponível.