@lunora/payment — Stripe

Stripe is the default provider for @lunora/payment. This page is a standalone, copy-pasteable walkthrough: install the adapter, wire it onto ctx.payments, run your first checkout, gate features and meter usage, and verify inbound webhooks. Every API detail below maps to a real method on the adapter — nothing is invented. For the provider-agnostic concepts (ctx.payments surface, the state machine, the store, reconcile) read the package overview first.

Stripe is a PSP — you are the merchant of record

Stripe is a payment service provider, not a Merchant-of-Record. That is the one fact that shapes everything else: you are the merchant of record, so you own tax calculation, invoicing, and remittance (Stripe Tax and Invoicing are add-on products you enable on your own account — the adapter does not do this for you). This is the opposite of Polar, Dodo Payments, and Creem, where the provider is the legal seller and owns tax/invoices.

The adapter advertises this in its capabilities:

Choose Stripe when you want the broadest payment-method and pricing coverage, direct control of the money flow (including manual authorize/capture), and you are prepared to handle tax/invoicing yourself. If you would rather offload tax and sales-of-record liability, reach for a Merchant-of-Record provider (Polar / Dodo Payments / Creem) — same ctx.payments API, different adapter.

Because Stripe is a PSP, manual authorize/capture is available: a checkout in mode: "payment" can hold funds (requires_capture) and you capture later. The Merchant-of-Record providers don't expose this.

Prerequisites

Lunora scaffolds the two secrets into your .dev.vars automatically when it detects @lunora/payment:

# .dev.vars
STRIPE_SECRET_KEY=sk_test_...       # Developers → API keys
STRIPE_WEBHOOK_SECRET=whsec_...     # Developers → Webhooks (endpoint signing secret)

Install

The Stripe adapter uses the real stripe SDK — the adapter types its client as a Stripe instance and verifies webhooks with the SDK's own verifier. stripe is an optional peer dependency (the adapter tree-shakes away when unused), so install it alongside the package:

pnpm add @lunora/payment stripe

npm install @lunora/payment stripe

yarn add @lunora/payment stripe

bun add @lunora/payment stripe

Configure

ctx.payments is wired by codegen onto ActionCtx whenever a lunora/ source imports @lunora/payment or reads ctx.payments. The Stripe adapter — which carries your secret key — comes from a config.payment(env) thunk you pass to createShardDO().

import Stripe from "stripe";

const stripe = new Stripe(env.STRIPE_SECRET_KEY, { httpClient: Stripe.createFetchHttpClient() });

import { createStripeAdapter } from "@lunora/payment/stripe";

const adapter = createStripeAdapter({
    client: stripe,
    webhookSecret: env.STRIPE_WEBHOOK_SECRET,
    webhookToleranceSeconds: 300, // optional; default 300 (five minutes)
});

import { createStripeAdapter } from "@lunora/payment/stripe";
import { createShardDO } from "./_generated/shard";
import Stripe from "stripe";

export const ShardDO = createShardDO({
    payment: (env) => ({
        adapter: createStripeAdapter({
            client: new Stripe(env.STRIPE_SECRET_KEY, { httpClient: Stripe.createFetchHttpClient() }),
            webhookSecret: env.STRIPE_WEBHOOK_SECRET,
        }),
        // Override the default "caller owns the referenceId" rule for org/workspace keys.
        // authorize: (referenceId) => referenceId === ctx.auth.orgId,
        entitlements: {
            plans: {
                pro: { features: ["export"], limits: { api_calls: 1000 }, priceIds: ["price_123"] },
            },
        },
        observability: (event) => console.log("[payment]", event.type, event),
    }),
});

The adapter options:

First checkout / subscription

Call the facade from an action. createCheckout returns a hosted Stripe Checkout URL to redirect the browser to. Use mode: "subscription" for recurring plans and mode: "payment" for one-time charges. attach is the plan-oriented alias with mode defaulting to "subscription", so a subscription is just { referenceId, priceId, successUrl, cancelUrl }:

import { action, v } from "./_generated/server";

export const subscribe = action.input({ priceId: v.string() }).action(async ({ ctx, args: { priceId } }): Promise<{ url: string }> => {
    const { url } = await ctx.payments.attach({
        referenceId: ctx.auth.userId,
        priceId, // e.g. "price_123"
        successUrl: "https://app.test/done",
        cancelUrl: "https://app.test/cancel",
    });

    return { url };
});

Under the hood the adapter calls Stripe's Create Checkout Session with line_items: [{ price, quantity }], client_reference_id, and the framework-controlled referenceId pinned into both the session and the subscription metadata. The facade reuses a reference's stored Stripe customer — minting a new one via Create Customer only on first checkout — and attaches an outbound idempotency key automatically (override via input.idempotencyKey), so a double-submit never double-charges.

The subscription only becomes active in your store once Stripe confirms payment through a webhook (see below) — createCheckout just starts the flow.

Entitlements and metered usage

Once a subscription is synced, entitlements are derived in-Worker from stored subscription state — no extra call to Stripe. A plan is granted when an active (or genuine trialing) subscription holds one of its configured priceIds.

Gate a feature with check — pass a featureId (feature grant/allowance) or a priceId (active product access):

export const apiCallsRemaining = action.action(async ({ ctx }): Promise<{ allowed: boolean; balance?: number }> => {
    const result = await ctx.payments.check({ referenceId: ctx.auth.userId, featureId: "api_calls" });

    return { allowed: result.allowed, balance: result.balance };
});

Meter usage with track. Because Stripe advertises usageMetering, track writes the durable local ledger and forwards the event to Stripe's Meter Events API (event_name = your featureId, payload.stripe_customer_id = the stored Stripe customer, payload.value = the quantity, identifier = the idempotency key that dedupes within Stripe's aggregation window). Upstream metering is best-effort: a reporting failure is observed, never thrown, and the local ledger check reads is always updated.

export const recordApiCall = action.action(async ({ ctx }): Promise<{ recorded: boolean }> => {
    // `mode: "add"` (default) increments; `"set"` reconciles the period total.
    const result = await ctx.payments.track({ referenceId: ctx.auth.userId, featureId: "api_calls" });

    return { recorded: result.recorded };
});

For track to feed a Stripe meter, create the meter in the dashboard (Product catalog → Meters) with an event_name matching your featureId, and attach it to a usage-based Price. A metered check subtracts usage tracked this period ({ allowed, balance, limit, used }) — the period window comes from the synced subscription's current billing period, so webhook sync (next) must be working for the window to be correct.

Webhooks

Stripe delivers state changes as webhooks. Signature verification needs the raw request body, so the endpoint runs at the Worker edge via httpAction (no ctx.db) and forwards the raw body + signature into the shard, where ctx.payments and its store exist. Note the header is stripe-signature:

// lunora/http.ts
import { httpAction, httpRouter } from "lunorash/server";
import { processWebhook } from "./billing";

export const app = httpRouter();

app.post(
    "/payment/webhook",
    httpAction(async (ctx, request) => {
        const body = await request.text();
        const signature = request.headers.get("stripe-signature") ?? "";

        return Response.json(await ctx.runAction(processWebhook, { body, signature }));
    }),
);

// lunora/billing.ts
import { internalAction, v } from "./_generated/server";

export const processWebhook = internalAction
    .input({ body: v.string(), signature: v.string() })
    .action(async ({ ctx, args: { body, signature } }): Promise<{ applied: boolean; status: number }> => {
        const request = new Request("https://internal/payment/webhook", {
            body,
            headers: { "stripe-signature": signature },
            method: "POST",
        });
        const response = await ctx.payments.handleWebhook(request);
        const result = (await response.json()) as { applied?: boolean };

        return { applied: result.applied ?? false, status: response.status };
    });

Register the endpoint

In the Stripe dashboard → Developers → Webhooks → Add endpoint, set the URL to your deployed route (e.g. https://your-worker.example.com/payment/webhook), then copy the endpoint's Signing secret (whsec_…) into STRIPE_WEBHOOK_SECRET. Locally, stripe listen --forward-to localhost:8787/payment/webhook prints a signing secret and streams events to your dev worker.

Select at least these events when creating the endpoint:

• checkout.session.completed
• customer.subscription.created, customer.subscription.updated, customer.subscription.deleted
• payment_intent.succeeded, payment_intent.payment_failed, payment_intent.amount_capturable_updated
• charge.refunded

The signature scheme + tolerance

Stripe signs each delivery with the Stripe-Signature header — t=<unix-seconds>,v1=<hex-hmac>. The adapter verifies it with the SDK's own webhooks.constructEventAsync(rawBody, header, secret, tolerance) — no explicit crypto provider: the stripe SDK's platform build selects the right implementation (WebCrypto on workerd, Node's crypto on Node). It rejects any delivery whose signed timestamp is more than webhookToleranceSeconds (default 300s) from now — Stripe's replay-window default — and a failed check surfaces as a WEBHOOK_SIGNATURE_INVALID error (a 400). Verification runs over the raw body; never re-serialize the JSON before verifying.

Events → normalized transitions

handleWebhook verifies, normalizes each event into a WebhookAction, and applies it through the state machine. Once verified it always returns 200 so Stripe stops retrying — a duplicate or no-op is acknowledged, not re-applied (the Stripe event id keys an append-only events log for idempotency and audit).

Refunds, portal, and manual capture

Refunds are first-class. refundPayment (exposed via the adapter) calls Stripe Create Refund against the payment intent — omit amount for a full refund, pass a Money for a partial one — then re-reads the intent to resolve partially_refunded vs refunded. The charge.refunded webhook keeps the store in sync afterward.

Customer portal. capabilities.portal is true, so createPortalSession opens Stripe's hosted Billing Portal where customers manage payment methods, invoices, and cancellations. The customer is derived from the store (never a caller-supplied id — no IDOR):

export const openPortal = action.action(async ({ ctx }): Promise<{ url: string }> => {
    return ctx.payments.createPortalSession(ctx.auth.userId, "https://app.test/account");
});

Enable and configure the portal once in the dashboard under Settings → Billing → Customer portal.

Manual authorize/capture. Because Stripe is a PSP, a mode: "payment" checkout can authorize-only (requires_capture) and you capture later — the adapter exposes capturePayment (optional partial amount) and cancelPayment over Stripe's PaymentIntent capture / cancel endpoints.

Limitations

• You own tax and invoicing. Stripe Tax and Invoicing are separate products you enable on your own account; the adapter does not compute or file tax.
• Metering is best-effort upstream. A failed forward to Stripe Meter Events is observed, not thrown — the local ledger stays authoritative for check until reconcile reconciles.
• Out-of-band cancellations of one-time payments (payment_intent.canceled) are not mapped — they arrive as unhandled. Subscriptions handle cancellation via customer.subscription.deleted.

Troubleshooting

See also

• @lunora/payment — the provider-agnostic overview and ctx.payments surface
• @lunora/scheduler — drive the reconcile sweep
• Studio — the Payments panel (synced customers, subscriptions, webhook events)
• Stripe API reference · Stripe webhooks