Przepis: subskrypcja SaaS

Kryptowaluty nie da się pobrać z portfela, więc subskrypcja odnawia się fakturą: przed końcem okresu kupujący dostaje następną, potem przypomnienia, dopóki nie zostanie opłacona. Nie ma automatycznego pobierania. Aplikacja nie liczy dni sama — pyta entitlements.check.

Jak to działa

1. 1

   Plan

   Produkt i cena z model: "subscription" oraz recurring.interval (month, year…), opcjonalnie dni próbne i dni karencji.

2. 2

   Subskrypcja

   Faktura na tę cenę z użytkownikiem jako klientem otwiera subskrypcję i jej pierwszą fakturę. Jej opłacenie aktywuje plan.

3. 3

   Dostęp do funkcji

   entitlements.check({ customer_external_id, product }) → has_access i ends_at, na serwerze, przy każdej wizycie lub z krótkim cache.

4. 4

   Nasłuchuj

   invoice.fulfilled — pierwsza płatność i każde odnowienie; subscription.past_due, subscription.unpaid i subscription.ended — żeby ostrzec i zamknąć.

5. 5

   Zarządzanie dla kupującego

   Link do portalu klienta (portalSessions.create): opłacić otwarte odnowienie, zapłacić z góry albo anulować.

const invoice = await pay.invoices.create(
  { line_items: [{ price: PRO_MONTHLY }], customer: customer.id, metadata: { user: userId }, return_url },
  { idempotencyKey: `subscribe-${userId}-${today}` },
);
redirect(invoice.url); // invoice.subscription is the new subscription

const { has_access } = await pay.entitlements.check({ customer_external_id: userId, product: PRO });

Dni karencji, zmianę planu i statusy opisano w Subscriptions and reminders.

Uruchom przykład

1. 1

   Zainstaluj

   npm install w examples/saas-subscription (Node 20.12+).

2. 2

   Klucz

   Skopiuj .env.example do .env i wpisz klucz testowy (sk_test_…) w PERLY_PAY_SECRET_KEY.

3. 3

   Przygotuj

   npm run setup tworzy produkt i cenę Twoim kluczem i drukuje ich identyfikatory do .env.

4. 4

   Uruchom

   npm start (lub npm run dev), jak mówi jego README.

5. 5

   Zapłać bez portfela

   Zasubskrybuj na stronie głównej, kliknij Simulate payment na fakturze, potem otwórz /pro?user=you@example.com: Pro jest otwarte do końca okresu.

Pułapki

• Obiecywanie „sami pobierzemy z Twojego portfela”. Nic nie jest pobierane; mów „odnawia się fakturą”.
• Brak lub zmyślony e-mail klienta: faktury za odnowienie i przypomnienia idą właśnie tam.
• Zamykanie dostępu w pierwszej minucie spóźnienia. Zdecyduj, co znaczy past_due (w ramach dni karencji).
• Otwieranie dostępu, gdy kupujący wrócił z płatności. „Opłacone” znaczy tylko zweryfikowany webhook invoice.fulfilled albo entitlements.check z Twojego serwera.