Cashier for mailcow — guía

Antes de empezar

El paquete mailcow Toolkit 0.4.0 o posterior, instalado con install.sh como se describe en la guía de mailcow Toolkit. Cashier for mailcow forma parte del paquete.
Sign-up for mailcow con su propia licencia válida y configurado (consulta la guía de Sign-up): las cuentas de pago se crean a través de su página de registro.
Tu clave de licencia de Cashier for mailcow (también vale una clave del paquete para mailcow), o una dirección de correo para la prueba gratuita de 30 días.
Tu propia cuenta de Stripe. Los pagos van directamente a ella; MediaLab Works no participa en tus ventas.
La interfaz de mailcow accesible desde internet por HTTPS (Stripe llama ahí al webhook), y HTTPS saliente hacia api.stripe.com y medialab.works.

Licencia y prueba gratuita

Abre System > Updates (Toolkit) y usa la tarjeta License · Cashier for mailcow: introduce la clave y pulsa Activate, o empieza la prueba gratuita de 30 días con tu dirección de correo (la tarjeta se pide en la página de pago de Stripe de medialab.works y no se cobra durante los 30 días). Cada herramienta para mailcow tiene su propia prueba, una vez por servidor y por dirección de correo. Con una clave del paquete para mailcow, introduce la misma clave en la tarjeta de cada producto. En la consola: docker compose exec -u www-data php-fpm-mailcow php /web/mlw-toolkit/cli.php activate mailcow-cashier <KEY> desde la carpeta de mailcow.

La licencia se comprueba cuando el servidor arranca y una vez al día; sin internet, Cashier sigue funcionando 7 días después de la última comprobación exitosa. Sin una licencia válida no se inicia ningún pago nuevo y los trabajos del temporizador se detienen para Cashier (los períodos de gracia no se convierten en suspensiones hasta que la licencia vuelve). Los webhooks de los suscriptores existentes siguen procesándose, y un pago completado mientras tanto espera hasta que la licencia vuelve. No se borra nada.

Conexión de Stripe

Abre System > Cashier. En la tarjeta Stripe:

En tu Stripe Dashboard crea una clave restringida (Developers > API keys > Create restricted key) con acceso de escritura a Customers, Checkout Sessions, Customer portal, Products, Prices, Subscriptions, Subscription items y Webhook Endpoints, y acceso de lectura a Invoices. Una clave secreta (sk_…) también vale, pero una clave restringida (rk_…) es más segura.
Pega la Publishable key (pk_test_… o pk_live_…) y la Secret / restricted key; ambas deben ser de prueba o ambas reales. Cashier las comprueba con Stripe y muestra la cuenta y el modo. La clave secreta se guarda cifrada y no se vuelve a mostrar nunca (deja el campo vacío para conservarla).
Pulsa Create the webhook. Cashier registra https://<mail host>/mlw-cashier/webhook.php en tu cuenta de Stripe con los eventos que necesita y guarda su secreto de firma. Si un proxy reescribe el nombre de host, define primero Public webhook address en Rules. Un webhook añadido a mano en Stripe también funciona: pega su Signing secret.
Last event muestra el último evento que envió Stripe; úsalo para comprobar que el webhook llega.

Disconnect quita las claves del servidor (tu cuenta de Stripe no cambia). Para pasar del modo de prueba al modo real, conecta las claves reales y crea de nuevo el webhook.

Planes

En Plans pulsa New plan:

Kind: mailbox (un buzón con su cuota) o domain package (para administradores de dominio: Domains (package), Mailboxes / domain, Aliases / domain, Quota (MB; package: per domain), Default quota / mailbox (MB)).
Name (English), Name (Romanian) y las descripciones en ambos idiomas, que se muestran en la página de registro en el idioma del visitante.
Monthly price y/o Yearly price, en la moneda de tu cuenta de Stripe. Cashier crea el producto y los precios en tu cuenta de Stripe.
Trial days (0 = ninguno): la prueba de tu plan, para tus clientes.
Visible on the registration page: desmárcala para un plan oculto, accesible solo a través de su enlace directo (/mlw-signup/?plan=<token>) o de un código de invitación vinculado al plan.

Edit modifica un plan: un importe cambiado crea un precio nuevo en Stripe y desactiva el anterior, que conservan los suscriptores existentes. Archive retira el plan de la venta (sus precios se desactivan en Stripe); los suscriptores existentes lo conservan.

Complementos

En Add-ons, un complemento se compra con una cantidad sobre la suscripción: buzones adicionales en cada dominio del paquete, o almacenamiento adicional (MB por dominio; en un plan de buzón, por buzón). Define la Unit (mailboxes / MB), los nombres, los precios mensual y anual y Visible. Los clientes los añaden en My account; Stripe prorratea el precio y los límites nuevos se aplican en mailcow al instante.

Reglas

Grace period after a failed payment (days, 0–90): la cuenta sigue funcionando mientras el cliente paga (7 días por defecto).
After the grace period the account is suspended: no sign-in: mail is still received (predeterminado) o inactive: mailboxes, domain administrator and domains. No se borra nunca nada; un pago restaura la cuenta al instante.
E-mail the subscribers about invoices and receipts.
Public webhook address (empty = automatic), Stripe product tax code (con el valor predeterminado se usa el código recomendado con la licencia; none lo omite), Stripe name prefix (cuando varios servidores mailcow comparten una cuenta de Stripe).

Qué ven tus clientes

En la página de registro eligen un plan (mensual o anual), confirman su dirección y pagan en la página de pago de Stripe. La cuenta se crea cuando Stripe confirma el pago.
En My account: el plan, la fecha del próximo pago, los complementos, Change plan (prorrateado; se rechaza un plan más pequeño que lo que usan ahora) y Card, invoices and cancellation (Stripe), el portal de cliente de Stripe.
Un pago fallido envía un correo con el enlace para pagar y la fecha de la suspensión. Un cliente suspendido que no puede iniciar sesión obtiene el enlace de pago en /mlw-cashier/billing.php introduciendo la dirección de correo de la cuenta.
Una cancelación surte efecto al final del período pagado.

Suscriptores y concesiones gratuitas

Subscribers enumera cada suscripción con su estado (activa, gracia, suspendida, terminada), el plan, el importe y el enlace a Stripe, y los ingresos mensuales. Grant a plan for free da un plan a una cuenta (buzón o administrador de dominio) durante un número de Days, sin Stripe; una concesión puede terminarse antes de tiempo. Recent Stripe events muestra lo que recibió el webhook.

Datos y copias de seguridad

Los planes, los clientes y las suscripciones están en la base de datos de mailcow (tablas mlw_ca_*), incluidas en las copias de seguridad de mailcow. Las claves y el secreto del webhook están en la carpeta compartida del Toolkit, cifradas con AES-256-GCM; la clave de cifrado se guarda aparte, en el redis de mailcow. uninstall.sh quita Cashier junto con el Toolkit pero conserva las tablas y cada cuenta; las claves cifradas se van con la carpeta compartida, así que tras reinstalar tendrías que conectar Stripe de nuevo.

Problemas frecuentes

Stripe rechazó la clave. Comprueba que ambas claves son del mismo modo (prueba o real) y que la clave restringida tiene todos los permisos indicados arriba; el mensaje de Stripe se muestra en la página.

Los pagos se completan pero no aparece ninguna cuenta. El webhook no llega: comprueba Last event, las entregas del webhook en el Stripe Dashboard y que la interfaz de mailcow es accesible desde internet por HTTPS. Después pulsa Create the webhook again.

La página de registro no muestra ningún plan de pago. El plan está oculto, no tiene precio, Stripe no está conectado, o la licencia de Cashier o de Sign-up no es válida.

Un cliente no puede cambiar a un plan más pequeño. La cuenta usa más de lo que permite el plan nuevo (dominios, buzones, alias o cuota); el mensaje indica qué reducir.