Skip to content

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.

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:

  • buildCheckoutUrl never 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> forwards code to the provider (Polar discount id, Lemon Squeezy checkout[discount_code], Stripe prefilled_promo_code) and ref to Lemon Squeezy aff or 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 as discount_id. Create the coupon in the provider dashboard. Tokens that are not [A-Za-z0-9_-] are ignored.
  • parseWebhook verifies the raw request body before parsing it, using each provider’s documented scheme:
    • Polar follows Standard Webhooks: webhook-id, webhook-timestamp and webhook-signature, signing id.timestamp.body with a base64 secret, v1,<base64> in the header.
    • Stripe sends Stripe-Signature: t=…,v1=…, signing t.body as hex. Non-v1 schemes are ignored so a downgrade cannot verify.
    • Lemon Squeezy sends X-Signature: a hex HMAC of the raw body, with the event name at meta.event_name.
  • Comparison is constant-time by construction — crypto.subtle.verify does 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. Only bad-signature and unparseable return 400.

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.

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.

/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.