Payments

Selling something is mostly bookkeeping that's easy to get subtly wrong. A price typed as 9.99 rounds badly. A button that marks the user as paid when they click it gives Pro to anyone who opens the console. A webhook handler that doesn't check signatures accepts forged events, and one that isn't idempotent grants twice when the provider retries.

weft's answer is a plugin, @weft-js/pay. It's a plugin in the plain sense: nothing in weft names it, and an app that doesn't use it carries none of its code. It owns one ledger of purchases, verifies every event from the payment provider, and turns what's in the ledger into entitlements: short names like 'pro' that your server functions check. The provider is a rail, and today's rail is Stripe.

Adding payments

Payments need a database and sign-in, so add those first (Database, Auth). Then:

weft add pay

That adds the Stripe rail to plugins and writes five files, which this page walks through:

Then run weft db generate for the two tables, put your Stripe test keys in .env, and give Stripe the webhook URL https://<your app>/_weft/x/pay/stripe, subscribed to customer.subscription.*, checkout.session.*, charge.refunded and charge.dispute.*. Nothing calls Stripe until a user checks out, and no page loads Stripe.js.

What you sell: the catalog

App code names products, never a provider's ids. A product says how it's paid for, what it is, what it costs and which entitlements it grants:

// src/pay/catalog.tsimport { product } from '@weft-js/pay'export const pro = product({  id: 'pro',  kind: 'subscription',  use: 'digital',  name: 'Pro',  plans: { month: { usd: 999 }, year: { usd: 7999, trialDays: 7 } },  grants: ['pro'],})export const credits = product({  id: 'credits',  kind: 'consumable',  use: 'digital',  name: '100 credits',  price: { usd: 500, eur: 450 },})

• kind is 'subscription' (priced per plan in plans), 'one-time' or 'consumable' (priced with price).
• use is 'digital', 'physical' or 'service'; shipping: true collects an address for physical goods.
• Amounts are whole minor units with a lowercase currency: { usd: 999 } is $9.99, and JPY has no minor unit at all. A float or an amount with no currency is PAY008, both in weft check and when the module loads.
• A plan named month or year is its own interval; any other name needs interval.
• grants lists the entitlements a live purchase gives.

To show a price, never type it into the page (that's PAY005): ask the catalog. price(product, plan) formats it for the reader's locale, by the currency's own number of decimals:

import { price } from '@weft-js/pay'import { pro } from '#/pay/catalog'export function Plans() {  const year = price(pro, 'year')  return (    <p>      {price(pro, 'month').display} a month, or {year.display} a year      {year.trialDays ? ` with ${year.trialDays} days free` : ''}    </p>  )}

The ledger and the server functions

src/pay.server.ts is the one ledger of the app. Here it is as weft add pay writes it for a Drizzle app:

// src/db/pay.schema.tsimport { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'export const purchases = sqliteTable('purchases', {  id: text().primaryKey(),  rail: text().notNull(),  user: text(),  product: text(),  plan: text(),  state: text().notNull(),  at: integer().notNull(),  expires: integer(),  customer: text(),})export const payEvents = sqliteTable('pay_events', {  id: text().primaryKey(),  at: integer().notNull(),})

// src/pay.server.tsimport { drizzlePayStore } from '@weft-js/pay/drizzle'import { definePay } from '@weft-js/pay/server'import { db } from '#/db/index.server'import { payEvents, purchases } from '#/db/pay.schema'import * as catalog from './pay/catalog'export default definePay({ catalog, store: drizzlePayStore(db, { purchases, payEvents }), urls: { success: '/', cancel: '/' } })

(weft add pay imports the tables from #/db/schema, which re-exports them; either path works.)

urls are where a buyer comes back to after paying or giving up. They're set here, on the server, and never come from the client. definePay also takes leeway (how long access lasts past a paid period while a late renewal arrives, 3 days by default), origin for absolute URLs behind a proxy, and user if your user id isn't ctx.user.id.

Pages don't import the ledger. They call three server functions:

// src/server/pay.tsimport { entitlementTag } from '@weft-js/pay'import { mutation, query, redirect } from '@weft-js/start'import pay from '../pay.server'export const entitlements = query({  auth: 'user',  tags: (_, ctx) => [entitlementTag(ctx.user.id)],  run: ({ ctx }) => ctx.entitlements.list(),})export const checkout = mutation({  auth: 'user',  input: pay.input,  run: async ({ input, ctx }) => redirect(await pay.checkout(ctx, input), 303),})export const portal = mutation({  auth: 'user',  run: async ({ ctx }) => redirect(await pay.portal(ctx), 303),})

pay.input is a schema built from the catalog: the client may send a product id, a plan, a currency and a quantity, and every amount comes from the catalog on the server. A checkout mutation without auth: 'user' is PAY010, because a purchase has to belong to someone.

Checkout grants nothing

Here's a pricing page. The buttons call the mutations, and what the page shows comes from entitlements:

// src/routes/pricing.tsximport { price } from '@weft-js/pay'import type { Meta } from '@weft-js/start'import { pro } from '#/pay/catalog'import { checkout, entitlements, portal } from '#/server/pay'export const meta: Meta = { title: 'Pricing', description: 'Pro unlocks reports and exports, billed monthly or yearly.' }export default function Pricing() {  const mine = entitlements.live()  return (    <section>      <h1>Pricing</h1>      {mine.value?.includes('pro') ? (        <>          <p aria-label="plan">Pro</p>          <button type="button" onClick={() => portal()}>Manage your plan</button>        </>      ) : (        <button type="button" onClick={() => checkout({ product: 'pro', plan: 'year' })}>          Go Pro · {price(pro, 'year').display}        </button>      )}    </section>  )}

checkout sends the buyer to the provider's hosted page, and that's all it does. When they finish paying, the provider posts an event to /_weft/x/pay/stripe, and that is what grants Pro:

1. The event is verified against the exact bytes received, with STRIPE_WEBHOOK_SECRET. A bad signature answers 400.
2. It's applied to the purchase in the ledger.
3. It pokes the tag entitlements:<user>, so every .live() reader of entitlements for that user refetches, on every tab. The page above flips to "Pro" by itself, a moment after the buyer comes back.

Providers deliver at least once and in any order. A repeated event changes nothing, and an older event than the one already applied changes nothing, by the provider's own clock. If applying fails, the webhook answers 500 so the event is sent again.

Enforce on the server

What the client shows is decoration. Anyone can call a server function directly, so the server decides. There are two ways, and you'll use both.

requires on a query or mutation refuses the call unless the user holds every entitlement listed. The client gets a typed 403 with the code ENTITLEMENT_REQUIRED:

// src/server/reports.tsimport { query } from '@weft-js/start'import { eq } from 'drizzle-orm'import { todos } from '#/db/schema'export const report = query({  tags: ['todos'],  auth: 'user',  requires: ['pro'],  run: async ({ ctx }) => {    const rows = await ctx.db.select().from(todos).where(eq(todos.userId, ctx.user.id))    return { total: rows.length, done: rows.filter(t => t.done).length }  },})

ctx.entitlements works in any query, mutation or load, for decisions that aren't a plain yes or no. In a layout's load it guards a whole section:

// src/routes/reports/_layout.tsximport { redirect, type LoadArgs } from '@weft-js/start'export const load = async ({ ctx }: LoadArgs) => {  if (!ctx.user) redirect('/login')  if (!(await ctx.entitlements.has('pro'))) redirect('/pricing')  return {}}export default function ReportsLayout(props: { children?: unknown }) {  return <section>{props.children}</section>}

An entitlement checked only on the client, with nothing on the server enforcing it, is PAY013.

A query with cache: { life } shares its value across users, so it can't read ctx.entitlements unless it also says scope: 'user'. And a query's tags can take ctx, which is how entitlements above gets one tag per user.

Purchase states

Every rail's events land on the same states:

Access also ends leeway (3 days) after a paid period if no renewal came, so a missed event can't keep someone on Pro forever. A refund or a revoke is final, and wins a tie with a renewal in the same second.

Test mode

Two kinds of testing, for two jobs.

Stripe's test mode, for trying the real flow in a browser. Put your sk_test_… key and the test webhook secret in .env, run the app, and pay with Stripe's test cards. To reach your machine from Stripe, use the Stripe CLI's forwarding to localhost:<port>/_weft/x/pay/stripe and use the signing secret it prints as STRIPE_WEBHOOK_SECRET.

fakePay, for automated tests. It's a rail with no key and no network. Its events are signed and go through your own webhook and ledger, so a test sees exactly what a user would. net.context sets who the test's requests come from:

import { net, render, screen, user } from '@weft-js/core/test'import { fakePay } from '@weft-js/pay/test'import { expect, test } from 'vitest'import pay from '#/pay.server'import Pricing from '#/routes/pricing'test('Pro arrives with the event, not the click', async () => {  const fake = fakePay(pay)  net.context({ user: { id: 'u1' } })  render(Pricing)  await user.click(await screen.findByRole('button', { name: /Go Pro/ }))  expect(screen.queryByLabelText('plan')).toBeNull()  await fake.complete()  expect((await screen.findByLabelText('plan')).textContent).toBe('Pro')  await fake.simulate('refund')  expect(await screen.findByRole('button', { name: /Go Pro/ })).toBeTruthy()})

fake.complete() is the buyer finishing the hosted page; fake.abandon() is them closing it. fake.simulate(…) plays what a rail does later: renewal, renewal-failed, recovered, grace-expired, cancel, pause, resume, refund and revoke. fake.redeliver() and fake.deliver(event, { forged: true }) check that a repeat is harmless and a forgery is refused. The Testing page covers render, user and the fake network.

A live key in a test is PAY031: tests never touch real money. And memoryPayStore() is for tests only; a production server refuses to start with it (PAY016).

Another provider

The catalog, the server functions and your pages never name Stripe, so another provider is one line: replace stripe() in plugins with any plugin for the pay.rail slot. A rail implements PayRail from @weft-js/pay (checkout, portal, verify, and optionally refund) and passes payRailSuite from @weft-js/pay/test. verify gets the exact bytes received and throws PayError('PAY011', …) for anything it can't prove.

Stripe is the only rail that ships today. App-store rails, store policy and a weft pay sync command aren't built.

Recap

• weft add pay writes a catalog, a ledger, three server functions and two tables. Keys live in the server's environment, never in source.
• Products are whole minor units with a currency. Show prices with price(product, plan), never typed into the page.
• checkout only opens the provider's page. A verified event at /_weft/x/pay/<rail> is the only grant, and it pokes entitlements:<user>, so .live() readers update by themselves.
• Enforce on the server: requires: ['pro'] on a function, or await ctx.entitlements.has('pro') in a load.
• Try the real flow with Stripe's test keys; test it automatically with fakePay, which runs your real webhook and ledger with no network.

Try it