Vinde cutii poștale și pachete de domenii pe mailcow, prin propriul cont Stripe

Dacă rulezi deja mailcow pentru tine, probabil ai primit de mai multe ori aceeași întrebare: ai putea găzdui mail și pentru altcineva? Partea tehnică este jumătatea ușoară. Jumătatea grea este facturarea: cine este pe ce plan, ce se întâmplă când un card este refuzat și cum oprești un cont fără să-l distrugi.

Cashier for mailcow este construit exact pentru această jumătate. Vinde planuri de cutii poștale și pachete de domenii pe mailcow-ul tău, plătite lunar sau anual cu cardul prin propriul tău cont Stripe, și aplică fiecare schimbare în mailcow imediat ce plata este confirmată. Conturile neplătite se suspendă după o perioadă de grație pe care o alegi tu, nu se șterg niciodată. Acest tutorial parcurge configurarea lui ca mică afacere de mail găzduit.

Cerințe preliminare

Înainte să începi, asigură-te că ai:

• Pachetul mailcow Toolkit 0.4.0 sau mai nou pe mailcow-dockerized (Linux, docker compose, systemd). Cashier vine în pachet și se instalează cu install.sh ca root pe host.
• Sign-up for mailcow cu licență proprie validă și configurat, pentru că conturile plătite sunt create prin pagina lui de înregistrare.
• O cheie de licență Cashier for mailcow (merge și o cheie din pachetul mailcow) sau o adresă de e-mail pentru perioada de probă gratuită de 30 de zile.
• Propriul tău cont Stripe într-o țară acceptată de Stripe. Banii, facturile și datele clienților rămân în contul tău; MediaLab Works nu este parte în vânzările tale.
• Interfața mailcow accesibilă din internet prin HTTPS, ca Stripe să poată apela webhook-ul, plus HTTPS către api.stripe.com și medialab.works pentru verificarea licenței.

Pasul 1 — Activează licența

Deschide System > Updates (Toolkit) și caută cardul License · Cashier for mailcow. Introdu cheia și apasă Activate, sau începe perioada de probă gratuită de 30 de zile cu adresa ta de e-mail. În shell, același lucru este:

docker compose exec -u www-data php-fpm-mailcow php /web/mlw-toolkit/cli.php activate mailcow-cashier <KEY>

Rulează comanda din folderul mailcow. Licența este verificată la pornire și o dată pe zi; fără internet, Cashier continuă să funcționeze 7 zile după ultima verificare reușită. Fără o licență validă nu pornește nicio plată nouă, dar webhook-urile abonaților existenți sunt în continuare procesate și nimic nu este șters.

Pasul 2 — Conectează Stripe

Deschide System > Cashier și parcurge cardul Stripe:

1. În Stripe Dashboard, creează o cheie restricționată (Developers > API keys > Create restricted key) cu acces de scriere la Customers, Checkout Sessions, Customer portal, Products, Prices, Subscriptions, Subscription items și Webhook Endpoints, și acces de citire la Invoices. Merge și o cheie secretă, dar o cheie restricționată este mai sigură.
2. Lipește Publishable key și Secret / restricted key. Ambele trebuie să fie chei de test sau ambele chei live; Cashier le verifică la Stripe și afișează contul și modul. Cheia secretă se păstrează criptată și nu mai este afișată niciodată, așa că lasă câmpul gol mai târziu ca să o păstrezi.
3. Apasă Create the webhook. Cashier înregistrează https://<mail host>/mlw-cashier/webhook.php în contul tău Stripe cu evenimentele de care are nevoie și salvează secretul de semnare. Dacă un proxy rescrie numele de host, setează mai întâi Public webhook address la Rules.
4. Verifică Last event ca să confirmi că evenimentele chiar ajung.

Ca să treci mai târziu din modul test în modul live, conectează cheile live și creează din nou webhook-ul.

Pasul 3 — Definește planurile

La Plans, apasă New plan. Alege Kind:

• mailbox — o cutie poștală cu cota ei, pentru cei care vor doar o adresă.
• domain package — pentru administratorii de domenii: Domains (package), Mailboxes / domain, Aliases / domain, Quota (MB; package: per domain) și Default quota / mailbox (MB).

Apoi completează numele și descrierile în engleză și română (apar pe pagina de înregistrare în limba vizitatorului), un preț lunar și/sau un preț anual în moneda contului tău Stripe, și zile de probă (0 = niciuna). Cashier creează produsul și prețurile în contul tău Stripe pentru tine. Lasă bifat Visible on the registration page pentru planurile publice; debifează-l pentru un plan ascuns, accesibil doar prin linkul direct (/mlw-signup/?plan=<token>) sau printr-un cod de invitație legat de plan.

Edit modifică un plan: o sumă schimbată creează un preț nou în Stripe și îl dezactivează pe cel vechi, pe care abonații existenți îl păstrează. Archive scoate un plan din vânzare fără să atingă abonații lui.

Pasul 4 — Adaugă suplimente

La Add-ons, creează extraopțiunile pe care clienții le pot cumpăra cu o cantitate: cutii poștale în plus pe fiecare domeniu al pachetului, sau spațiu în plus (MB pe domeniu; pe un plan de cutie poștală, pe cutie). Setează Unit, numele, prețurile lunare și anuale și Visible. Clienții le adaugă la My account; Stripe calculează prețul proporțional, iar noile limite se aplică imediat în mailcow.

Pasul 5 — Setează regulile: perioada de grație și suspendarea

La Rules, decide cât de strict vrei să fii:

• Grace period after a failed payment (days, 0–90) — implicit 7 zile, timp în care contul funcționează în continuare în timp ce clientul plătește.
• After the grace period the account is suspended — alege no sign-in: mail is still received (implicit) sau inactive: mailboxes, domain administrator and domains. Nimic nu este șters niciodată, iar o plată restaurează contul imediat.
• E-mail the subscribers about invoices and receipts.
• Public webhook address (empty = automatic), Stripe product tax code și Stripe name prefix — ultimul contează când mai multe servere mailcow împart un singur cont Stripe.

Pentru o mică afacere de găzduire, modul implicit fără conectare este un punct de plecare bun: un client care nu mai plătește nu mai folosește serviciul, dar e-mailurile continuă să sosească, așa că nimic nu se pierde și o plată pornește totul la loc.

Pasul 6 — Află ce văd clienții

Pe pagina de înregistrare, un vizitator alege un plan (lunar sau anual), își confirmă adresa și plătește pe pagina de checkout a Stripe. Contul este creat când Stripe confirmă plata. La My account văd planul, data următoarei plăți și suplimentele, pot folosi Change plan (proporțional; un plan mai mic decât ce se folosește acum e refuzat, cu ce trebuie redus mai întâi) și pot deschide Card, invoices and cancellation (Stripe), portalul de client Stripe.

O plată eșuată trimite un e-mail cu linkul de plată și data suspendării. Un client suspendat care nu se poate conecta poate cere linkul de plată de pe pagina publică /mlw-cashier/billing.php, introducând adresa de e-mail a contului. O anulare produce efecte la sfârșitul perioadei plătite, iar un cont creat de abonament rămâne apoi suspendat.

Pasul 7 — Administrează partea de admin

Subscribers listează fiecare abonament cu starea lui (active, grace, suspended, ended), planul, suma, linkul către Stripe și Monthly revenue, plus Recent Stripe events primite de webhook. Grant a plan for free oferă un plan unui cont pentru un număr de zile fără Stripe, iar un grant poate fi încheiat mai devreme — util pentru teste sau pentru un favor făcut unui prieten.

Planurile, clienții și abonamentele stau în baza de date a mailcow (tabelele mlw_ca_*), deci fac parte din backup-urile mailcow. Cheile și secretul webhook-ului se află în folderul partajat al Toolkit-ului, criptate cu AES-256-GCM, cu cheia de criptare păstrată separat în redis-ul mailcow.

Sfaturi și depanare

• Webhook-ul nu ajunge? Verifică Last event în cardul Stripe. Dacă un reverse proxy rescrie numele de host, setează Public webhook address la Rules și creează din nou webhook-ul.
• Chei respinse? Asigură-te că ambele chei sunt de test sau ambele live; amestecarea lor face verificarea să eșueze.
• Clientul vrea un plan mai mic, dar e refuzat. Este intenționat: nimic nu este șters ca să încapă. Cere-i să elimine mai întâi cutii poștale sau spațiu.
• Un eveniment Stripe repetat. Evenimentele sunt verificate prin semnătură și procesate o singură dată, așa că un duplicat nu schimbă nimic.
• Verificarea licenței eșuează. Serverul trebuie să ajungă la medialab.works prin HTTPS; Cashier continuă să funcționeze 7 zile după ultima verificare reușită.
• Mutarea pe alt server. uninstall.sh elimină Cashier împreună cu Toolkit-ul, dar păstrează tabelele și fiecare cont; cheile criptate pleacă împreună cu folderul partajat, așa că planifică o reconectare a Stripe după aceea.

Concluzie

Cashier for mailcow nu încearcă să fie o platformă completă de facturare. Face bine un singur lucru: vinde cutii poștale și pachete de domenii pe propriul tău mailcow, prin propriul tău cont Stripe, cu schimbări proporționale, o perioadă de grație pe care o controlezi și o suspendare care nu șterge niciodată date. Citește ghidul de utilizare pentru fiecare câmp, verifică changelog-ul înainte de actualizare și folosește Bază de cunoștințe sau FAQ când ceva nu este clar. Întrebările despre configurarea ta sunt binevenite prin contact.