Cashier for mailcow — ghid

Înainte de a începe

Pachetul mailcow Toolkit 0.4.0 sau mai nou, instalat cu install.sh cum scrie în ghidul mailcow Toolkit. Cashier for mailcow face parte din pachet.
Sign-up for mailcow cu licența lui validă și configurat (vezi ghidul Sign-up): conturile plătite se creează prin pagina lui de înregistrare.
Cheia de licență Cashier for mailcow (merge și o cheie de pachet mailcow) sau o adresă de e-mail pentru perioada de probă gratuită de 30 de zile.
Propriul tău cont Stripe. Plățile ajung direct în el; MediaLab Works nu are niciun rol în vânzările tale.
Interfața mailcow accesibilă din internet prin HTTPS (Stripe apelează acolo webhook-ul) și acces HTTPS spre api.stripe.com și medialab.works.

Licență și perioada de probă gratuită

Deschide System > Actualizări (Toolkit) și folosește cardul Licență · Cashier for mailcow: introdu cheia și apasă Activează sau pornește perioada de probă gratuită de 30 de zile cu adresa ta de e-mail (cardul se cere pe pagina de plată Stripe a medialab.works și nu se debitează în cele 30 de zile). Fiecare unealtă mailcow are propria perioadă de probă, o dată pe server și pe adresă de e-mail. Cu o cheie de pachet mailcow, introdu aceeași cheie în cardul fiecărui produs. Din terminal, în folderul mailcow: docker compose exec -u www-data php-fpm-mailcow php /web/mlw-toolkit/cli.php activate mailcow-cashier <CHEIE>.

Licența se verifică la pornirea serverului și o dată pe zi; fără internet, Cashier funcționează 7 zile de la ultima verificare reușită. Fără o licență validă nu pornește nicio plată nouă, iar sarcinile temporizatorului se opresc pentru Cashier (perioadele de grație nu se transformă în suspendări până revine licența). Webhook-urile abonaților existenți se procesează în continuare, iar o plată încheiată între timp așteaptă până revine licența. Nu se șterge nimic.

Conectarea Stripe

Deschide System > Cashier. În cardul Stripe:

În Stripe Dashboard creează o cheie restricționată (Developers > API keys > Create restricted key) cu drept de scriere pe Customers, Checkout Sessions, Customer portal, Products, Prices, Subscriptions, Subscription items și Webhook Endpoints și drept de citire pe Invoices. Merge și o cheie secretă (sk_…), dar o cheie restricționată (rk_…) e mai sigură.
Lipește Cheia publicabilă (pk_test_… sau pk_live_…) și Cheia secretă / restricționată; ambele trebuie să fie de test sau ambele live. Cashier le verifică la Stripe și arată contul și modul. Cheia secretă se păstrează criptat și nu mai e afișată niciodată (lasă câmpul gol ca s-o păstrezi).
Apasă Creează webhook-ul. Cashier înregistrează https://<server de e-mail>/mlw-cashier/webhook.php în contul tău Stripe, cu evenimentele de care are nevoie, și îi salvează secretul de semnare. Dacă un proxy rescrie numele de gazdă, completează întâi Adresa publică a webhook-ului din Reguli. Merge și un webhook adăugat manual în Stripe: lipește-i Secretul de semnare.
Ultimul eveniment arată ultimul eveniment trimis de Stripe; după el vezi dacă webhook-ul ajunge.

Deconectează scoate cheile de pe server (contul tău Stripe nu se schimbă). Ca să treci din modul de test în modul live, conectează cheile live și creează din nou webhook-ul.

Planuri

În Planuri apasă Plan nou:

Tip: cutie poștală (o cutie cu spațiul ei) sau pachet de domenii (pentru administratorii de domeniu: Domenii (pachet), Cutii / domeniu, Aliasuri / domeniu, Cotă (MB; pachet: per domeniu), Cotă implicită / cutie (MB)).
Nume (engleză), Nume (română) și descrierile în ambele limbi, afișate pe pagina de înregistrare în limba vizitatorului.
Preț lunar și/sau Preț anual, în moneda contului tău Stripe. Cashier creează produsul și prețurile în contul tău Stripe.
Zile probă (0 = fără) — perioada de probă a planului tău, pentru clienții tăi.
Vizibil pe pagina de înregistrare — debifează pentru un plan ascuns, disponibil doar prin linkul direct (/mlw-signup/?plan=<token>) sau printr-un cod de invitație legat de plan.

Editează schimbă 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ă. Arhivează scoate planul de la vânzare (prețurile lui se dezactivează în Stripe); abonații existenți îl păstrează.

Suplimente

În Suplimente, un supliment se cumpără cu o cantitate pe abonament: cutii poștale în plus pe fiecare domeniu al pachetului sau spațiu în plus (MB pe domeniu; la un plan de cutie poștală, pe cutie). Setează Unitate (cutii / MB), numele, prețurile lunar și anual și Vizibil. Clienții le adaugă din Contul meu; Stripe calculează proporțional prețul, iar limitele noi se aplică imediat în mailcow.

Reguli

Perioadă de grație după o plată eșuată (zile, 0–90) — contul funcționează cât timp clientul plătește (implicit 7 zile).
După perioada de grație contul se suspendă — fără conectare: e-mailurile se primesc în continuare (implicit) sau inactiv: cutii, administrator de domeniu și domenii. Nu se șterge niciodată nimic; o plată reactivează contul imediat.
Trimite abonaților e-mailuri despre facturi și chitanțe.
Adresa publică a webhook-ului (gol = automat), Cod fiscal Stripe al produselor (cu valoarea implicită se folosește codul recomandat odată cu licența; none îl omite), Prefix în Stripe (când mai multe servere mailcow folosesc același cont Stripe).

Ce văd clienții tăi

Pe pagina de înregistrare aleg un plan (lunar sau anual), își confirmă adresa și plătesc pe pagina de plată Stripe. Contul se creează când Stripe confirmă plata.
În Contul meu: planul, data următoarei plăți, suplimentele, Schimbă planul (calculat proporțional; un plan mai mic decât ce folosesc acum e refuzat) și Card, facturi și anulare (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 primește linkul de plată din /mlw-cashier/billing.php, introducând adresa de e-mail a contului.
O anulare intră în vigoare la sfârșitul perioadei plătite.

Abonați și planuri oferite gratuit

Abonați arată fiecare abonament cu starea lui (activ, în grație, suspendat, încheiat), planul, suma și linkul spre Stripe, plus Venitul lunar. Oferă un plan gratuit dă un plan unui cont (cutie poștală sau administrator de domeniu) pentru un număr de Zile, fără Stripe; o ofertă poate fi încheiată mai devreme. Evenimente Stripe recente arată ce a primit webhook-ul.

Date și copii de rezervă

Planurile, clienții și abonamentele sunt în baza de date a mailcow (tabelele mlw_ca_*), deci în copiile de rezervă ale mailcow. Cheile și secretul webhook-ului sunt în folderul comun al Toolkit-ului, criptate cu AES-256-GCM; cheia de criptare stă separat, în redis-ul mailcow. uninstall.sh dezinstalează Cashier odată cu Toolkit-ul, dar păstrează tabelele și fiecare cont; cheile criptate pleacă odată cu folderul comun, deci după o reinstalare conectezi din nou Stripe.

Probleme frecvente

Stripe a refuzat cheia. Verifică dacă ambele chei sunt din același mod (test sau live) și dacă cheia restricționată are toate drepturile de mai sus; mesajul Stripe apare pe pagină.

Plățile reușesc, dar nu apare niciun cont. Webhook-ul nu ajunge: verifică Ultimul eveniment, livrările webhook-ului în Stripe Dashboard și dacă interfața mailcow e accesibilă din internet prin HTTPS. Apoi apasă Recreează webhook-ul.

Pagina de înregistrare nu arată planuri plătite. Planul e ascuns, nu are preț, Stripe nu e conectat sau licența Cashier ori Sign-up nu e validă.

Un client nu poate trece la un plan mai mic. Contul folosește mai mult decât permite noul plan (domenii, cutii poștale, aliasuri sau spațiu); mesajul spune ce trebuie redus.