Payments
Polar and Lemon Squeezy act as merchants of record for their supported sales. StratoLMS’s Stripe adapter uses ordinary Stripe checkout, where you manage seller and applicable tax obligations. Review the provider’s current terms, supported countries, fees, and tax responsibilities before choosing a provider: Polar, Lemon Squeezy, and Stripe Tax.
PAYMENT_PROVIDER defaults to polar. Choosing stripe is deliberate and
reachable, not the first thing the scaffolder offers.
What the adapters do
Section titled “What the adapters do”Polar with licence-key benefits provides the built-in returning-buyer recovery flow. Test purchases, delivery, recovery, and refunds in your chosen provider’s sandbox before taking payments, and account for the session-expiry behavior below.
These are adapter capabilities, reflected in PaymentProvider.capabilities:
| Capability | Polar | Stripe | Lemon Squeezy |
|---|---|---|---|
| Checkout and signed webhook grant | Yes | Yes | Yes |
| Returning-buyer licence recovery | Yes, with organization and benefit mapping | Unimplemented | Unimplemented |
| Delayed payment | Grants on order.paid |
Checks paid status, handles async success | Grants on order_created; payment status is not checked, so delayed payments are unqualified |
| Subscription access | Unsupported | Unsupported | Unsupported |
| Refund invalidates issued cookie | No | No | No |
Stripe and Lemon Squeezy buyers receive a seven-day access link from the paid
webhook. An issued session lasts 30 days. After link/session expiry, a returning
buyer needs the site owner’s support; this kit has no automatic email lookup or
link reissue endpoint. Do not promise licence recovery for those adapters.
Set site.contactEmail in src/consts.ts to a monitored support address.
Mixed-provider sites can use each published course’s pricing.provider for
checkout and webhook grants. Only published paid Polar courses with
pricing.licenseBenefitId participate in recovery, regardless of the global
PAYMENT_PROVIDER checkout default. Polar validation cannot grant a Stripe or
Lemon Squeezy course even when its benefit mapping matches. Recovery for other
providers needs separate implementation and qualification.
Each provider implements one interface (PaymentProvider), and all three run the
same conformance suite, so none of them can quietly skip a check:
buildCheckoutUrlnever accepts an amount. The price lives at the provider. A checkout URL carrying a price is a coupon for anyone who can edit a query string.- Coupons and referrals are provider tokens. A course sales page is static,
so
?code=and?ref=on that page are copied onto the buy link in the browser. The listed price stays the provider’s price./checkout?course=<slug>&code=<token>&ref=<token>forwardscodeto the provider (Polar discount id, Lemon Squeezycheckout[discount_code], Stripeprefilled_promo_code) andrefto Lemon Squeezyaffor Polar checkout metadata. A human Polar code is not priced here: Polar’s checkout collects it (allow_discount_codes). A Polar discount UUID is sent asdiscount_id. Create the coupon in the provider dashboard. Tokens that are not[A-Za-z0-9_-]are ignored. parseWebhookverifies the raw request body before parsing it, using each provider’s documented scheme:- Polar follows Standard Webhooks:
webhook-id,webhook-timestampandwebhook-signature, signingid.timestamp.bodywith a base64 secret,v1,<base64>in the header. - Stripe sends
Stripe-Signature: t=…,v1=…, signingt.bodyas hex. Non-v1schemes are ignored so a downgrade cannot verify. - Lemon Squeezy sends
X-Signature: a hex HMAC of the raw body, with the event name atmeta.event_name.
- Polar follows Standard Webhooks:
- Comparison is constant-time by construction —
crypto.subtle.verifydoes it, so no hand-rolled equality check can leak the expected signature. - Replay protection is not optional. An event more than five minutes old is
stale. Where the timestamp is inside the signed content (Polar, Stripe) it cannot be moved; Lemon Squeezy signs only the body, so its window comes from the payload timestamp. A timestamp we cannot read is treated as stale, never as fresh. - An unrecognised event returns
ignored, and the route answers 200. A 500 on an event we simply do not handle triggers exponential retries and, at the provider’s end, a disabled webhook. Onlybad-signatureandunparseablereturn 400.
How a grant works with no database
Section titled “How a grant works with no database”On order.paid the webhook does exactly two things: it emails the buyer a
signed access link valid for seven days, and nothing else. The provider is the
database. The buyer’s orders live there; Polar recovery validates a licence
key. Anonymous email lookup is unimplemented. There is no row to write, no
backup to take and nothing to migrate.
A refund produces action: 'revoke' and sends no link. Existing sessions expire on their own —
with no storage there is nothing to revoke, so residual access can last for the 30-day session
window. V1 does not support subscriptions. Paid recovery uses a validated Polar licence key;
free courses are public and the anonymous email-signin endpoint is disabled.
For each paid Polar course, configure both identifiers. pricing.productId is the checkout product
ID. pricing.licenseBenefitId is the licence-key benefit ID returned by Polar validation; the two
are intentionally never treated as interchangeable. Set POLAR_ORGANIZATION_ID to the organization
that issued those keys.
POLAR_SERVER selects sandbox or production for both checkout and recovery.
Recovery retains the current public organization-scoped validation endpoint;
verify it against your sandbox before launch. Polar’s current documentation
recommends its authenticated endpoint for server use.
Changing authority or credentials needs separate review; these local repairs
do not establish provider production support.
Account recovery and sign-out
Section titled “Account recovery and sign-out”The account form posts to /api/redeem/. With JavaScript, errors stay inline and
the key stays only in the current form. A native form works without JavaScript:
success returns a 303 to /account/ (or an exact owned course route), and errors
redirect with an allowlisted error code. After a page reload the buyer re-enters
the key. Keys never enter URLs or browser storage.
API clients requesting Accept: application/json retain JSON responses:
{ ok: true, courses, redirect } or { ok: false, error }. Invalid, expired,
revoked or unrelated keys return 403; a provider outage or missing recovery
configuration returns 503. The default response for clients without an HTML
Accept header is also JSON. Optional returnTo accepts only /account/ and
exact /learn/<owned-course>/ or /courses/<owned-course>/ paths. Other values
fall back to the account page.
/api/logout/ clears the learner cookie and returns to /account/ with 303.
Both POST routes reject foreign origins. The account document uses
Referrer-Policy: same-origin so native form POSTs carry their origin; external
referrers are suppressed. API and token callback responses use no-referrer.
Account documents and responses produced by these API handlers remain no-store.
Idempotency without storage: the access token is derived from the event, not from the wall clock, so a replayed webhook re-sends a byte-identical link instead of granting twice.
Deployment note
Section titled “Deployment note”/api/webhook/[provider] must be publicly reachable. On Vercel, put it outside
deployment protection — protection returns 401 to the provider, the webhook
retries, and you see purchases with no access granted and no obvious cause.