Cashier for mailcow — Anleitung

Bevor du beginnst

Das mailcow Toolkit-Paket 0.4.0 oder neuer, installiert mit install.sh wie in der Anleitung zum mailcow Toolkit beschrieben. Cashier for mailcow ist Teil des Pakets.
Sign-up for mailcow mit seiner eigenen gültigen Lizenz, eingerichtet (siehe die Anleitung zu Sign-up): Kostenpflichtige Konten werden über seine Registrierungsseite angelegt.
Dein Lizenzschlüssel für Cashier for mailcow (ein Schlüssel des mailcow-Pakets funktioniert auch) oder eine E-Mail-Adresse für den kostenlosen 30-tägigen Test.
Dein eigenes Stripe-Konto. Zahlungen gehen direkt darauf ein; MediaLab Works ist an deinem Verkauf nicht beteiligt.
Die mailcow-Oberfläche aus dem Internet über HTTPS erreichbar (Stripe ruft dort den Webhook an) und ausgehendes HTTPS zu api.stripe.com und medialab.works.

Lizenz und kostenloser Test

Öffne System > Updates (Toolkit) und nutze die Karte License · Cashier for mailcow: Gib den Schlüssel ein und drücke Activate, oder starte den kostenlosen 30-tägigen Test mit deiner E-Mail-Adresse (die Karte wird auf der Stripe-Bezahlseite von medialab.works abgefragt und in den 30 Tagen nicht belastet). Jedes mailcow-Tool hat seinen eigenen Test, einmal pro Server und pro E-Mail-Adresse. Mit einem Paket-Schlüssel des mailcow-Pakets gib denselben Schlüssel in jeder Produktkarte ein. Auf der Shell: docker compose exec -u www-data php-fpm-mailcow php /web/mlw-toolkit/cli.php activate mailcow-cashier <KEY> aus dem mailcow-Ordner.

Die Lizenz wird beim Start des Servers und einmal am Tag geprüft; ohne Internet funktioniert Cashier noch 7 Tage nach der letzten erfolgreichen Prüfung. Ohne gültige Lizenz startet kein neuer Bezahlvorgang und die Timer-Jobs stoppen für Cashier (aus Kulanzfristen werden erst wieder Sperrungen, wenn die Lizenz zurück ist). Die Webhooks bestehender Abonnenten werden weiter verarbeitet, und ein in der Zwischenzeit abgeschlossener Bezahlvorgang wartet, bis die Lizenz zurück ist. Es wird nichts gelöscht.

Stripe verbinden

Öffne System > Cashier. In der Karte Stripe:

Erstelle in deinem Stripe-Dashboard einen eingeschränkten Schlüssel (Developers > API keys > Create restricted key) mit Schreibzugriff auf Customers, Checkout Sessions, Customer portal, Products, Prices, Subscriptions, Subscription items und Webhook Endpoints sowie Lesezugriff auf Invoices. Ein geheimer Schlüssel (sk_…) funktioniert auch, aber ein eingeschränkter Schlüssel (rk_…) ist sicherer.
Füge den Publishable key (pk_test_… oder pk_live_…) und den Secret / restricted key ein; beide müssen Testschlüssel oder beide Live-Schlüssel sein. Cashier prüft sie bei Stripe und zeigt das Konto und den Modus an. Der geheime Schlüssel wird verschlüsselt gespeichert und nie wieder angezeigt (das Feld leer lassen, um ihn zu behalten).
Drücke Create the webhook. Cashier registriert https://<mail host>/mlw-cashier/webhook.php in deinem Stripe-Konto mit den Ereignissen, die es braucht, und speichert sein Signier-Geheimnis. Wenn ein Proxy den Hostnamen umschreibt, setze zuerst Public webhook address unter Rules. Ein von Hand in Stripe hinzugefügter Webhook funktioniert auch: Füge sein Signing secret ein.
Last event zeigt das letzte Ereignis, das Stripe gesendet hat; nutze es, um zu prüfen, dass der Webhook ankommt.

Disconnect entfernt die Schlüssel vom Server (dein Stripe-Konto wird nicht geändert). Um vom Testmodus in den Livemodus zu wechseln, verbinde die Live-Schlüssel und erstelle den Webhook erneut.

Tarife

In Plans drücke New plan:

Kind: mailbox (ein Postfach mit seinem Kontingent) oder domain package (für Domain-Administratoren: Domains (package), Mailboxes / domain, Aliases / domain, Quota (MB; package: per domain), Default quota / mailbox (MB)).
Name (English), Name (Romanian) und die Beschreibungen in beiden Sprachen, auf der Registrierungsseite in der Sprache des Besuchers angezeigt.
Monthly price und/oder Yearly price, in der Währung deines Stripe-Kontos. Cashier erstellt das Produkt und die Preise in deinem Stripe-Konto.
Trial days (0 = keiner) — der Test deines Tarifs, für deine Kunden.
Visible on the registration page — Häkchen weg für einen versteckten Tarif, der nur über seinen direct link (/mlw-signup/?plan=<token>) oder einen an den Tarif gebundenen Einladungscode erreichbar ist.

Edit ändert einen Tarif: Ein geänderter Betrag erstellt einen neuen Preis in Stripe und deaktiviert den alten, den bestehende Abonnenten behalten. Archive nimmt den Tarif vom Verkauf (seine Preise werden in Stripe deaktiviert); bestehende Abonnenten behalten ihn.

Zusatzoptionen

In Add-ons wird eine Zusatzoption mit einer Menge auf dem Abonnement gekauft: extra mailboxes auf jeder Domain des Pakets oder extra storage (MB pro Domain; bei einem Postfach-Tarif pro Postfach). Lege die Unit (mailboxes / MB), die Namen, die monatlichen und jährlichen Preise und Visible fest. Kunden fügen sie unter My account hinzu; Stripe berechnet den Preis anteilig, und die neuen Limits werden sofort in mailcow angewendet.

Regeln

Grace period after a failed payment (days, 0–90) — das Konto funktioniert weiter, während der Kunde zahlt (Standard 7 Tage).
After the grace period the account is suspended — no sign-in: mail is still received (Standard) oder inactive: mailboxes, domain administrator and domains. Es wird nie etwas gelöscht; eine Zahlung stellt das Konto sofort wieder her.
E-mail the subscribers about invoices and receipts.
Public webhook address (empty = automatic), Stripe product tax code (mit dem Standard wird der mit der Lizenz empfohlene Code verwendet; none lässt ihn weg), Stripe name prefix (wenn mehrere mailcow-Server ein Stripe-Konto teilen).

Was deine Kunden sehen

Auf der Registrierungsseite wählen sie einen Tarif (monatlich oder jährlich), bestätigen ihre Adresse und zahlen auf der Stripe-Bezahlseite. Das Konto wird erstellt, wenn Stripe die Zahlung bestätigt.
Unter My account: der Tarif, das nächste Zahlungsdatum, die Zusatzoptionen, Change plan (anteilig; ein kleinerer Tarif als der aktuell genutzte wird abgelehnt) und Card, invoices and cancellation (Stripe), Stripes Kundenportal.
Eine fehlgeschlagene Zahlung sendet eine E-Mail mit dem Link zum Bezahlen und dem Datum der Sperrung. Ein gesperrter Kunde, der sich nicht anmelden kann, bekommt den Bezahllink von /mlw-cashier/billing.php, indem er die E-Mail-Adresse des Kontos eingibt.
Eine Kündigung wird am Ende des bezahlten Zeitraums wirksam.

Abonnenten und kostenlose Freischaltungen

Subscribers listet jedes Abonnement mit seinem Zustand (active, grace, suspended, ended), dem Tarif, dem Betrag und dem Link zu Stripe sowie den monatlichen Umsatz. Grant a plan for free gibt einem Konto (Postfach oder Domain-Administrator) für eine Anzahl von Tagen einen Tarif, ohne Stripe; eine Freischaltung kann vorzeitig beendet werden. Recent Stripe events zeigt, was der Webhook empfangen hat.

Daten und Backups

Tarife, Kunden und Abonnements liegen in mailcows Datenbank (Tabellen mlw_ca_*), Teil von mailcows Backups. Die Schlüssel und das Webhook-Geheimnis liegen im gemeinsamen Ordner des Toolkits, verschlüsselt mit AES-256-GCM; der Verschlüsselungsschlüssel wird getrennt aufbewahrt, in mailcows Redis. uninstall.sh entfernt Cashier mit dem Toolkit, behält aber die Tabellen und jedes Konto; die verschlüsselten Schlüssel gehen mit dem gemeinsamen Ordner, du müsstest also nach einer Neuinstallation Stripe erneut verbinden.

Häufige Probleme

Stripe hat den Schlüssel abgelehnt. Prüfe, dass beide Schlüssel denselben Modus haben (Test oder Live) und dass der eingeschränkte Schlüssel jede oben genannte Berechtigung hat; Stripes Meldung wird auf der Seite angezeigt.

Zahlungen gelingen, aber es erscheint kein Konto. Der Webhook kommt nicht an: Prüfe Last event, die Zustellungen des Webhooks im Stripe-Dashboard und dass die mailcow-Oberfläche aus dem Internet über HTTPS erreichbar ist. Drücke dann Create the webhook again.

Die Registrierungsseite zeigt keine kostenpflichtigen Tarife. Der Tarif ist versteckt, hat keinen Preis, Stripe ist nicht verbunden, oder die Lizenz von Cashier oder Sign-up ist nicht gültig.

Ein Kunde kann nicht auf einen kleineren Tarif wechseln. Das Konto nutzt mehr, als der neue Tarif erlaubt (Domains, Postfächer, Aliasse oder Kontingent); die Meldung sagt, was verkleinert werden muss.