Cashier for mailcow — guide

Avant de commencer

Le paquet mailcow Toolkit 0.4.0 ou plus récent, installé avec install.sh comme décrit dans le guide du mailcow Toolkit. Cashier for mailcow fait partie du paquet.
Sign-up for mailcow avec sa propre licence valide et configuré (voir le guide de Sign-up) : les comptes payants sont créés via sa page d’inscription.
Votre clé de licence de Cashier for mailcow (une clé du pack mailcow fonctionne aussi), ou une adresse e-mail pour l’essai gratuit de 30 jours.
Votre propre compte Stripe. Les paiements y arrivent directement ; MediaLab Works n’intervient pas dans vos ventes.
L’interface mailcow accessible depuis Internet en HTTPS (Stripe y appelle le webhook), et du HTTPS sortant vers api.stripe.com et medialab.works.

Licence et essai gratuit

Ouvrez System > Updates (Toolkit) et utilisez la carte License · Cashier for mailcow : saisissez la clé et appuyez sur Activate, ou lancez l’essai gratuit de 30 jours avec votre adresse e-mail (la carte est demandée sur la page de paiement Stripe de medialab.works et n’est pas débitée pendant les 30 jours). Chaque outil mailcow a son propre essai, une fois par serveur et par adresse e-mail. Avec une clé du pack mailcow, saisissez la même clé dans la carte de chaque produit. En shell : docker compose exec -u www-data php-fpm-mailcow php /web/mlw-toolkit/cli.php activate mailcow-cashier <KEY> depuis le dossier mailcow.

La licence est vérifiée au démarrage du serveur puis une fois par jour ; sans Internet, Cashier continue de fonctionner 7 jours après la dernière vérification réussie. Sans licence valide, aucun nouveau paiement ne démarre et les tâches planifiées de Cashier s’arrêtent (les délais de grâce ne se transforment pas en suspensions tant que la licence n’est pas revenue). Les webhooks des abonnés existants sont toujours traités, et un paiement terminé entre-temps attend le retour de la licence. Rien n’est supprimé.

Connexion de Stripe

Ouvrez System > Cashier. Dans la carte Stripe :

Dans votre Stripe Dashboard, créez une restricted key (Developers > API keys > Create restricted key) avec un accès en écriture à Customers, Checkout Sessions, Customer portal, Products, Prices, Subscriptions, Subscription items et Webhook Endpoints, et en lecture à Invoices. Une clé secrète (sk_…) fonctionne aussi, mais une restricted key (rk_…) est plus sûre.
Collez la Publishable key (pk_test_… ou pk_live_…) et la Secret / restricted key ; les deux doivent être des clés de test ou des clés live. Cashier les vérifie auprès de Stripe et affiche le compte et le mode. La clé secrète est stockée chiffrée et n’est plus jamais affichée (laissez le champ vide pour la conserver).
Appuyez sur Create the webhook. Cashier enregistre https://<mail host>/mlw-cashier/webhook.php dans votre compte Stripe avec les événements dont il a besoin et enregistre son secret de signature. Si un proxy réécrit le nom d’hôte, définissez d’abord Public webhook address sous Rules. Un webhook ajouté à la main dans Stripe fonctionne aussi : collez son Signing secret.
Last event affiche le dernier événement envoyé par Stripe ; utilisez-le pour vérifier que le webhook arrive.

Disconnect retire les clés du serveur (votre compte Stripe n’est pas modifié). Pour passer du mode test au mode live, connectez les clés live et créez à nouveau le webhook.

Formules

Dans Plans, appuyez sur New plan :

Kind : mailbox (une boîte aux lettres avec son quota) ou domain package (pour les administrateurs de domaine : Domains (package), Mailboxes / domain, Aliases / domain, Quota (MB; package: per domain), Default quota / mailbox (MB)).
Name (English), Name (Romanian) et les descriptions dans les deux langues, affichées sur la page d’inscription dans la langue du visiteur.
Monthly price et/ou Yearly price, dans la devise de votre compte Stripe. Cashier crée le produit et les prix dans votre compte Stripe.
Trial days (0 = aucun) : l’essai de votre formule, pour vos clients.
Visible on the registration page : décochez-la pour une formule cachée, accessible uniquement via son lien direct (/mlw-signup/?plan=<token>) ou un code d’invitation lié à la formule.

Edit modifie une formule : un montant modifié crée un nouveau prix dans Stripe et désactive l’ancien, que les abonnés existants conservent. Archive retire la formule de la vente (ses prix sont désactivés dans Stripe) ; les abonnés existants la conservent.

Options

Dans Add-ons, une option s’achète en quantité sur l’abonnement : des boîtes aux lettres supplémentaires sur chaque domaine du paquet, ou du stockage supplémentaire (Mo par domaine ; sur une formule de boîte aux lettres, par boîte aux lettres). Définissez Unit (mailboxes / MB), les noms, les prix mensuel et annuel et Visible. Les clients les ajoutent sur My account ; Stripe calcule le prix au prorata et les nouvelles limites sont appliquées à mailcow aussitôt.

Règles

Grace period after a failed payment (days, 0–90) : le compte continue de fonctionner pendant que le client paie (7 jours par défaut).
After the grace period the account is suspended : no sign-in: mail is still received (par défaut) ou inactive: mailboxes, domain administrator and domains. Rien n’est jamais supprimé ; un paiement rétablit le compte immédiatement.
E-mail the subscribers about invoices and receipts.
Public webhook address (empty = automatic), Stripe product tax code (avec la valeur par défaut, le code recommandé avec la licence est utilisé ; none l’omet), Stripe name prefix (quand plusieurs serveurs mailcow partagent un compte Stripe).

Ce que vos clients voient

Sur la page d’inscription, ils choisissent une formule (mensuelle ou annuelle), confirment leur adresse et paient sur la page de paiement de Stripe. Le compte est créé quand Stripe confirme le paiement.
Sur My account : la formule, la date du prochain paiement, les options, Change plan (au prorata ; une formule inférieure à l’usage actuel est refusée) et Card, invoices and cancellation (Stripe), le portail client de Stripe.
Un paiement en échec envoie un e-mail avec le lien pour payer et la date de la suspension. Un client suspendu qui ne peut pas se connecter obtient le lien de paiement depuis /mlw-cashier/billing.php en saisissant l’adresse e-mail du compte.
Une résiliation prend effet à la fin de la période payée.

Abonnés et accords gratuits

Subscribers liste chaque abonnement avec son état (active, grace, suspended, ended), la formule, le montant et le lien vers Stripe, ainsi que les revenus mensuels. Grant a plan for free donne une formule à un compte (boîte aux lettres ou administrateur de domaine) pour un nombre de jours, sans Stripe ; un accord peut être terminé en avance. Recent Stripe events affiche ce que le webhook a reçu.

Données et sauvegardes

Les formules, les clients et les abonnements se trouvent dans la base de données de mailcow (tables mlw_ca_*), donc dans les sauvegardes de mailcow. Les clés et le secret du webhook sont dans le dossier partagé du Toolkit, chiffrés avec AES-256-GCM ; la clé de chiffrement est conservée à part, dans le redis de mailcow. uninstall.sh retire Cashier avec le Toolkit mais conserve les tables et chaque compte ; les clés chiffrées partent avec le dossier partagé, il faudrait donc reconnecter Stripe après une réinstallation.

Problèmes courants

Stripe a refusé la clé. Vérifiez que les deux clés sont du même mode (test ou live) et que la restricted key a chaque permission listée ci-dessus ; le message de Stripe est affiché sur la page.

Les paiements réussissent mais aucun compte n’apparaît. Le webhook n’arrive pas : vérifiez Last event, les livraisons du webhook dans le Stripe Dashboard et que l’interface mailcow est accessible depuis Internet en HTTPS. Puis appuyez à nouveau sur Create the webhook.

La page d’inscription n’affiche aucune formule payante. La formule est cachée, n’a pas de prix, Stripe n’est pas connecté, ou la licence de Cashier ou de Sign-up n’est pas valide.

Un client ne peut pas passer à une formule inférieure. Le compte utilise plus que ce que la nouvelle formule permet (domaines, boîtes aux lettres, alias ou quota) ; le message indique quoi réduire.