Accept payments with Stripe in DaloyJS

STRIPE_SECRET_KEY=sk_test_replace_me
STRIPE_WEBHOOK_SECRET=whsec_replace_me
STRIPE_SUCCESS_URL=https://your-app.example.com/checkout/success?session_id={CHECKOUT_SESSION_ID}
STRIPE_CANCEL_URL=https://your-app.example.com/cart

import Stripe from "stripe";
import type { App } from "@daloyjs/core";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  // Pin the API version your code was written against; upgrade deliberately.
  apiVersion: "2026-09-30.endive",
  maxNetworkRetries: 2,
  timeout: 20_000,
  // Cloudflare Workers / other fetch-only runtimes:
  // httpClient: Stripe.createFetchHttpClient(),
});

// WebCrypto-based verifier: works on Node 24+, Deno, Bun, and Workers.
const cryptoProvider = Stripe.createSubtleCryptoProvider();

export interface StripeClient {
  raw: Stripe;
  createCheckoutSession(input: {
    lineItems: Stripe.Checkout.SessionCreateParams.LineItem[];
    orderId: string;
    customerEmail?: string;
    idempotencyKey: string;
  }): Promise<{ id: string; url: string }>;
  retrieveCheckoutSession(sessionId: string): Promise<Stripe.Checkout.Session>;
  refund(input: {
    paymentIntent: string;
    amount?: number;
    idempotencyKey: string;
  }): Promise<{ id: string; status: string | null }>;
  constructWebhookEvent(rawBody: Uint8Array, signature: string | null): Promise<Stripe.Event>;
}

// Exported so job handlers (which run outside a request) can use it too.
export const stripeClient: StripeClient = {
  raw: stripe,

  async createCheckoutSession({ lineItems, orderId, customerEmail, idempotencyKey }) {
    const session = await stripe.checkout.sessions.create(
      {
        mode: "payment",
        line_items: lineItems,
        success_url: process.env.STRIPE_SUCCESS_URL!,
        cancel_url: process.env.STRIPE_CANCEL_URL!,
        customer_email: customerEmail,
        client_reference_id: orderId,
        metadata: { orderId },
      },
      { idempotencyKey },
    );
    if (!session.url) throw new Error("Stripe returned a Checkout Session without a URL");
    return { id: session.id, url: session.url };
  },

  retrieveCheckoutSession(sessionId) {
    return stripe.checkout.sessions.retrieve(sessionId);
  },

  async refund({ paymentIntent, amount, idempotencyKey }) {
    const refund = await stripe.refunds.create(
      { payment_intent: paymentIntent, amount },
      { idempotencyKey },
    );
    return { id: refund.id, status: refund.status };
  },

  async constructWebhookEvent(rawBody, signature) {
    if (!signature) throw new Error("Missing Stripe-Signature header");
    return stripe.webhooks.constructEventAsync(
      Buffer.from(rawBody), // on Workers, pass new TextDecoder().decode(rawBody)
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!,
      undefined, // default 300 s tolerance; never pass 0
      cryptoProvider,
    );
  },
};

// Call with the root app, not through app.register(): a decoration made
// inside a registered plugin is visible only to that plugin's own routes.
export function stripePlugin(app: App) {
  app.decorate("stripe", stripeClient);
}

declare module "@daloyjs/core" {
  interface AppState {
    stripe: StripeClient;
  }
}

import { z } from "zod";
import { idempotency } from "@daloyjs/core";
import { stripePlugin } from "../plugins/stripe.ts";
import { orders } from "../orders.ts";

stripePlugin(app);

app.post(
  "/checkout/stripe",
  {
    operationId: "createStripeCheckoutSession",
    // Safe client retries of this POST (scoped per signed-in user).
    hooks: idempotency({ scope: (ctx) => ctx.state.session.get<string>("userId") }),
    request: {
      body: z.object({ orderId: z.string().min(1).max(80) }).strict(),
    },
    responses: {
      200: { description: "checkout session", body: z.object({ url: z.url() }) },
    },
  },
  async ({ body, state }) => {
    const order = await orders.forCheckout(body.orderId, state.session.get<string>("userId"));

    const session = await state.stripe.createCheckoutSession({
      orderId: order.id,
      // Price IDs, never client-supplied amounts.
      lineItems: order.lines.map((line) => ({ price: line.stripePriceId!, quantity: line.quantity })),
      // The cart version makes a changed cart a new logical request.
      idempotencyKey: `checkout:${order.id}:v${order.version}`,
    });

    return { status: 200, body: { url: session.url } };
  },
);

export async function startCheckout(orderId: string, csrfToken: string) {
  const res = await fetch("/checkout/stripe", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-csrf-token": csrfToken,
      "idempotency-key": `checkout-${orderId}`,
    },
    body: JSON.stringify({ orderId }),
  });
  if (!res.ok) throw new Error("Could not start checkout");
  const { url } = (await res.json()) as { url: string };
  window.location.assign(url);
}

import { z } from "zod";
import type Stripe from "stripe";
import { readBodyLimited, jobIdempotencyKey } from "@daloyjs/core";

app.post(
  "/webhooks/stripe",
  {
    operationId: "stripeWebhook",
    // No request.body schema: the raw bytes stay readable for verification.
    responses: {
      200: { description: "ack", body: z.object({ ok: z.literal(true) }) },
      400: { description: "bad signature", body: z.object({ error: z.string() }) },
    },
  },
  async ({ request, state }) => {
    const raw = await readBodyLimited(request, 1_048_576);

    let event: Stripe.Event;
    try {
      event = await state.stripe.constructWebhookEvent(raw, request.headers.get("stripe-signature"));
    } catch {
      return { status: 400, body: { error: "invalid signature" } };
    }

    if (event.type === "checkout.session.completed" || event.type === "checkout.session.async_payment_succeeded") {
      await app.jobs!.enqueue({
        name: "stripe.checkout_paid",
        payload: { eventId: event.id, sessionId: event.data.object.id },
        idempotencyKey: jobIdempotencyKey({ name: "stripe.checkout_paid", key: event.id }),
      });
    }
    // Ack every verified event, including types you do not handle.
    return { status: 200, body: { ok: true as const } };
  },
);

import type { JobHandler } from "@daloyjs/core";
import { stripeClient } from "../plugins/stripe.ts";
import { orders } from "../orders.ts";

export const handleStripeCheckoutPaid: JobHandler<{ eventId: string; sessionId: string }> = async ({ job }) => {
  const session = await stripeClient.retrieveCheckoutSession(job.payload.sessionId);
  if (session.payment_status !== "paid") return; // async methods: wait for async_payment_succeeded
  await orders.markPaid(session.metadata!.orderId!, {
    amountMinor: session.amount_total!,
    currency: session.currency!,
    providerRef: String(session.payment_intent),
  });
};

// One useJobs() per app; jobStore is your durable JobStore (MemoryJobStore in dev).
app.useJobs({ store: jobStore, startWorker: true, handlers: { "stripe.checkout_paid": handleStripeCheckoutPaid } });

stripe listen --forward-to localhost:3000/webhooks/stripe
stripe trigger checkout.session.completed

// Partial refund, amount in the smallest currency unit.
await state.stripe.refund({
  paymentIntent: order.providerRef!,
  amount: 250, // 2.50 USD
  idempotencyKey: `refund:${order.id}:${order.refundedMinor}:250`,
});