Stripe i tryb testowy

Jak WolfieAuth obsługuje Stripe pod hood, jak testować billing end-to-end z fake-cardami, i checklist na przejście na żywe pieniądze.

Stripe i tryb testowy — testowanie billingu przed wejściem na żywo

TL;DR: WolfieAuth używa Stripe Connect, więc pieniądze płyną do Twojego konta Stripe orgi, nie do platform pool. Najpierw uruchom flow billingu apki w trybie testowym Stripe (test cards działają, brak realnych pieniędzy), zweryfikuj cały lifecycle (checkout → webhook → aktywna subskrypcja → faktura → maile), potem przełącz konto Connect na live keys gdy jesteś pewien. Ta strona prowadzi przez cały flow.

Jak faktycznie płyną pieniądze

Gdy klient subskrybuje plan Twojej apki:

Klient hituje Twoją /pricing page albo picker @wolfieauth/sdk-paywall
     │
     ▼
WolfieAuth tworzy Stripe Checkout session przeciwko TWOJEMU kontu Connect
(używa Stripe key Twojego konta, nie platformy)
     │
     ▼
Klient płaci kartą / SEPA / etc — pieniądze lądują bezpośrednio w TWOIM Stripe balance
     │
     ▼
Stripe wysyła webhook do WolfieAuth → tworzy subscription row → zaktualizowany wolfieauth_plans claim
     │
     ▼
Przy następnym mint OIDC tokenu klienta, Twoja apka widzi nowy plan w claim
     │
     ▼
Raz na miesiąc: WolfieAuth wystawia małą fakturę platform-fee Twojej orgi osobno

Sam nigdy nie piszesz Stripe code-u. WolfieAuth ogarnia checkout, webhooki, stan subskrypcji, proracje, retry, refundy — wszystko siedzące na wierzchu TWOJEGO konta Connect żebyś zachował ownership relacji z klientem i funduszy.

Dwie strony test/live

WolfieAuth sam siedzi na infrze Wolfie z platform-side Stripe keys (mechanika platform-fee). Co Ty kontrolujesz jako app owner to swoje własne konto Stripe Connect — i tam test mode ma znaczenie dla Ciebie.

Konto Stripe Connect jest albo w trybie test albo trybie live. Te dwa to całkowicie osobne światy — osobne balansy, osobni klienci, osobne webhooki. Nie da się zmigrować danych między nimi. Więc: zrób całe testowanie na test-mode Connect, potem onboarduj live-mode gdy gotowy na realne pieniądze.

Tryb testowy: end-to-end walkthrough

1. Podłącz test-mode konto Stripe

W admin WolfieAuth → /admin/organizations/<twoja-org> → zakładka Stripe → Connect Stripe account.

Gdy klikasz przez onboarding Stripe, upewnij się że jesteś przełączony w tryb test w Stripe dashboard (prawy górny róg). Account-link który Stripe tworzy dziedziczy mode w którym jesteś. Onboarding w trybie test pomija KYC verification — możesz dokończyć go z śmieciowymi danymi w sekundach.

Gdy wrócisz, zobaczysz chargesEnabled: true (test) przy orgi. Od tego punktu każdy checkout który WolfieAuth tworzy przeciwko tej orgi idzie przez Stripe test mode.

2. Stwórz plany i ceny

/admin/clients/<twoja-apka>/plans → + Nowy plan. Nazwij, daj slug, opcjonalnie tagnij features:

Nazwa:      Pro
Slug:       pro          (auto-derived z nazwy)
Features:   ["ksef_enabled", "advanced_reports"]

Dodaj cenę (jedną albo wiele — możesz mieć monthly + annual + per-currency):

Kwota:      99.00
Waluta:     PLN
Interval:   month
Per-seat:   off

Klik Sync to Stripe — WolfieAuth provisionuje Product + Price na Twoim test Connect. Powinieneś zobaczyć Stripe Price ID przy row-ie ceny.

3. Uruchom test checkout

Dwa sposoby:

Hostowana pricing page:

https://auth.wolfieguard.com/billing/<twoja-apka-clientId>

Publiczny URL — bez login. Wybierz plan, klik “Subscribe.”

Embedded w apce przez paywall SDK:

// hooks.server.ts (SvelteKit) — patrz /sdks/ dla innych stacków
import { createWolfieAuthHandle } from '@wolfieauth/sdk-sveltekit/server';

export const handle = createWolfieAuthHandle({
  paywall: {
    enabled: true,
    plans: await fetch(`${ISSUER}/api/billing/${CLIENT_ID}/plans`).then(r => r.json()),
    allowSkip: false,
  },
});

Na Stripe Checkout page użyj test card:

Pełna lista: https://stripe.com/docs/testing#cards.

4. Zweryfikuj że webhook wylądował

Po opłaceniu Stripe odpala checkout.session.completed i (kilka sekund później) customer.subscription.created do WolfieAuth. Subskrypcja klienta powinna pojawić się w /admin/clients/<twoja-apka>/users ze status ACTIVE.

Żeby zobaczyć co Stripe faktycznie wysłał:

• Stripe dashboard → Developers → Events (test mode) — pełen payload + delivery log.
• WolfieAuth admin → /admin/clients/<twoja-apka> → recent activity panel.

Jeśli webhook nie dotarł, najczęstszą przyczyną jest że currentPlanSlug klienta w OrgCustomer jest dalej empty po 30 sekundach. Sprawdź Stripe “Events” log dla delivery errors i porównaj z URL webhooka WolfieAuth zarejestrowanym w settings Twojego konta Connect.

5. Zasymuluj resztę lifecycle

Stripe CLI pozwala odpalić dowolny webhook event bez czekania na realny billing cycle:

stripe login                                          # raz, otwiera browser
stripe trigger invoice.payment_succeeded              # mintuje opłaconą fakturę
stripe trigger invoice.payment_failed                 # → subskrypcja idzie PAST_DUE
stripe trigger customer.subscription.deleted         # → cancellation cascade
stripe trigger customer.subscription.updated \
  --override "items[0].price=<twoj-test-price-id>"   # plan switch / upgrade

Każdy odpala przeciwko Twojemu test-mode kontu i ćwiczy webhook handler WolfieAuth. Możesz zweryfikować rezultujący stan w /admin/clients/<twoja-apka> albo czytając OIDC claims user-a:

curl -H "Authorization: Bearer <user-access-token>" \
     https://auth.wolfieguard.com/me | jq .wolfieauth_plans

6. Test path email + faktura

Gdy invoice.payment_succeeded odpala, WolfieAuth woła Twój CRM tooling (jeśli wpięte) żeby wystawić customer-facing fakturę. W trybie test:

• Jeśli Twoje CRM jest też w trybie test, dostajesz test faktury. Numery mogą używać osobnej sekwencji (TEST/2026/…) żeby nie zaśmiecać live numeracji.
• Jeśli Twoje CRM jest w live mode, dostaniesz warning w logach WolfieAuth i invoice step jest pomijany — best-effort, nie psuje przetwarzania płatności.

Email notyfikacje idą tą samą zasadą: w test deployment wskaż swój SMTP host na sink (Mailpit, MailHog) i obserwuj co byłoby wysłane bez dostarczania do realnych skrzynek.

Wejście na żywo — checklist

Gdy test-mode end-to-end działa, przełączenie na live jest mechaniczne:

1. Powtórz Stripe Connect onboarding w live mode. Przełącz Stripe dashboard w live mode i klik Connect z admin WolfieAuth. To tworzy zupełnie nowe live Connect konto — Twoje test konto pozostaje nietknięte i użyteczne do dalszego testowania.
2. Stwórz ponownie plany i ceny na live koncie. Button “Sync to Stripe” WolfieAuth tworzy Stripe Products + Prices na którym aktualnie podlinkowanym Connect koncie. Uruchom ponownie na live. Slugi i feature tagi przenoszą się automatycznie (siedzą w DB WolfieAuth, nie Stripe).
3. Zweryfikuj URL webhooka. Connect konta dziedziczą webhook config WolfieAuth — nie ma nic do ręcznego rejestrowania po Twojej stronie. Po prostu potwierdź że org pokazuje teraz chargesEnabled: true (live) w admin panel.
4. Test realną kartą za 1 zł. Wystaw sobie refund tuż po — udowadnia end-to-end bez realnej ekspozycji.
5. Zaktualizuj apkę by wskazywała live pricing page. Jeśli zhardkodowałeś https://auth.wolfieguard.com/billing/<twoja-apka>?mode=test gdzieś, drop param.

Możesz zostawić test Connect konto na zawsze — to właściwy dom dla eksploracyjnej pracy, demo data dla sales calls i pre-production validation nowych planów przed ich sync-iem na live.

Rzeczy które NIE zmieniają się między test a live

Nie powinieneś musieć dotykać żadnej z tych:

• Twoje OidcClient client_id i client_secret — to samo w obu trybach. WolfieAuth sam nie ma osobnych test/live modes per-app.
• OIDC scopes, redirect URI, claim shapes — identyczne.
• Plan slugs, feature flags, role mappings — siedzą w DB WolfieAuth, nie Stripe.
• Code Twojej apki — bez if (testMode) branchów; SDK nie wie i nie obchodzi go.

Gdy coś wygląda źle

Czytaj dalej

• Plany & Billing overview — modele cenowe, per-seat, comp overrides
• SDKs — paywall — embedded checkout w apce
• SSO & Sesje — jak plan claim płynie z powrotem do tokenu user-a

Ostatnia aktualizacja: 2026-05-03