@pylonsync/stripe

@pylonsync/stripe replaces the ~400 lines every Pylon app rewrites when it adds Stripe billing: customer creation, checkout session creation, billing portal, webhook signature verification, plan derivation, and subscription state. One stripe({plans, hooks}) block returns a manifest fragment and handler factories.

Install

bun add @pylonsync/stripe

Config

import { buildManifest, app, entity, field } from "@pylonsync/sdk";
import { stripe } from "@pylonsync/stripe";

export const Org = entity("Org", {
  name: field.string(),
  slug: field.string().unique(),
  createdBy: field.id("User"),
  createdAt: field.string(),
  stripeCustomerId: field.string().optional(),
});

export const billing = stripe({
  referenceType: "org", // or "user"
  plans: [
    { name: "starter", priceId: process.env.STRIPE_PRICE_STARTER!, limits: { recordings: 50 } },
    { name: "pro",     priceId: process.env.STRIPE_PRICE_PRO!,     limits: { recordings: 500 } },
    { name: "scale",   priceId: process.env.STRIPE_PRICE_SCALE!,   limits: { recordings: -1 } },
  ],
  hooks: {
    onSubscriptionActivate: async (ctx, { referenceId, plan }) => {
      // analytics, welcome email
    },
    onInvoice: async (ctx, { eventType, invoice }) => {
      // record audit, slack alert on payment_failed
    },
  },
});

export default app({
  name: "myapp",
  entities: [Org /* + your entities */, ...billing.manifest.entities],
  actions:  [...billing.manifest.actions],
  queries:  [...billing.manifest.queries],
  policies: [...billing.manifest.policies],
});

Wrapper files

Pylon loads function handlers by file. Create one-line wrappers under functions/:

// functions/createCheckoutSession.ts
export { createCheckoutSession as default } from "../billing";

// functions/createBillingPortalSession.ts
export { createBillingPortalSession as default } from "../billing";

Create one more wrapper per handler key exposed by billing.handlers (cancelSubscription, restoreSubscription, stripeWebhook, plus the _pylonStripe* internals).

Required env

Variable	Purpose
`STRIPE_SECRET_KEY`	API requests (set per Stack0 Cloud project’s Secrets UI).
`STRIPE_WEBHOOK_SECRET`	Signature verification on `/api/webhooks/stripeWebhook`.
`PYLON_PUBLIC_URL`	Auto-set by Stack0 Cloud. Drives URL allowlist for `success_url`/`cancel_url`.

Webhook endpoint

Configure in Stripe Dashboard → Developers → Webhooks → Add endpoint:

URL:    https://api.<your-app>.com/api/webhooks/stripeWebhook
Events: customer.subscription.created
        customer.subscription.updated
        customer.subscription.deleted
        invoice.created
        invoice.finalized
        invoice.paid
        invoice.payment_failed
        invoice.voided

Copy the signing secret (whsec_...). Set it as STRIPE_WEBHOOK_SECRET on your Pylon machine.

Lifecycle hooks

Hook	Fires
`onCustomerCreate`	After a Stripe customer is created (first checkout).
`onSubscriptionActivate`	`customer.subscription.created` event.
`onSubscriptionUpdate`	`customer.subscription.updated` event.
`onSubscriptionCancel`	`customer.subscription.deleted` event.
`onInvoice`	Any invoice event.
`onEvent`	Catch-all for unhandled Stripe events.
`getCheckoutSessionParams`	Inject tax/promo/idempotency-key params into checkout creation.

RBAC

The authorizeReference hook gates subscription mutations. Defaults:

referenceType: "org": the caller must be the org’s owner or admin.
referenceType: "user": the caller must be the user.
referenceType: "custom": you must supply your own resolveCustomer hook, which maps referenceId to a Stripe customer ID and creates one if needed. custom has no default authorization, so supply authorizeReference too.

Security

Constant-time signature verification with a 5-minute replay window. The Stripe-Signature header can carry multiple v1= signatures (Stripe emits several during a signing-secret rotation). The verifier accepts a match against any of them.
URL allowlist derived automatically from PYLON_PUBLIC_URL and PYLON_CORS_ORIGIN. No hardcoded host strings.
Three-signal plan resolver: it matches on lookup_key, then nickname, then price ID match. Stripe sometimes omits the first two on webhook payloads.
Double-trial guard: a prior Subscription row for the same reference disables the trial period, regardless of plan config.
Idempotent webhook upsert via stripeSubscriptionId lookup, so Stripe retries produce the same state.

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Migrate

@pylonsync/stripe

Install

Config

Wrapper files

Required env

Webhook endpoint

Lifecycle hooks

RBAC

Security

​Install

​Config

​Wrapper files

​Required env

​Webhook endpoint

​Lifecycle hooks

​RBAC

​Security

Install

Config

Wrapper files

Required env

Webhook endpoint

Lifecycle hooks

RBAC

Security