Skip to content
Early bird + Black Friday · 73% off

Get ZeroDirs for $179 $49

Claim $49 deal

Plans and payments

tiers in site.config.ts defines the plans a submitter can pick. features.payments: true with providers.payment: 'stripe' sells a priced tier through Stripe Checkout; the shipped config has both.

  1. An enabled priced tier needs both switches on.

    site.config.ts
    tiers: [
    { id: 'free', name: 'Free', description: 'Reviewed in order.', kind: 'queue', priceCents: 0, currency: 'usd' },
    { id: 'express', name: 'Express', description: 'Reviewed first.', kind: 'express', priceCents: 4900, currency: 'usd', slaHours: 48 },
    ],
    features: { payments: true },
    providers: { payment: 'stripe' },
    Terminal
    pnpm check:config

    site.config.ts OK — <your site name> (https://your-domain.com). Payments off with a priced tier enabled: site.config.ts › tiers[1].priceCents: must be 0 when features.payments is false.

  2. Stripe → Developers → API keys → Create restricted key with only Checkout Sessions: Write, in test mode; the key begins rk_test_.

    Terminal
    pnpm cf:secrets STRIPE_SECRET_KEY

    The value comes from .env.prod; the script refuses a whsec_ value or a publishable key, and never echoes it.

  3. Stripe → Developers → Webhooks → Add destination: the URL https://<your site>/api/stripe/webhook/ (keep the trailing slash), the events checkout.session.completed and checkout.session.async_payment_succeeded, test mode, API version matching the installed stripe package. The signing secret (whsec_…) is on the endpoint’s page after saving.

    Terminal
    pnpm cf:secrets STRIPE_WEBHOOK_SECRET
    curl -s -o /dev/null -w '%{http_code}\n' https://<your site>/api/stripe/webhook/

    405: the route exists and takes only POST. Without the slash it prints a redirect code, and Stripe fails the delivery instead of following it.

  4. Deploy the config change with pnpm deploy or a push; secrets need no deploy. /admin/ stops listing the two keys.

One test-mode checkout on the deployed site:

Check Where You should see
The plans are offered /submit/, step 2 the priced tiers next to the free one
Checkout starts submit on a priced tier a redirect to Stripe; the row is pending, payment unpaid
The payment lands pay with card 4242 4242 4242 4242, any future expiry, any CVC and postcode /submit/status/<token>/?paid=1 with “Payment received.”; on reload the “Not completed yet” line and the “Complete payment” button are gone
The webhook wrote it pnpm exec wrangler d1 execute DB --remote --command "SELECT id, status, event_id FROM payments ORDER BY created_at DESC LIMIT 1" status paid, an event_id beginning evt_
It is in the queue /admin/ the listing under “Waiting for review”, not under “Awaiting payment”
Stripe agrees the endpoint’s recent deliveries in Stripe 200. A redirect code: the slash is missing. 400: the wrong secret, or the two values swapped. No deliveries: the events were not selected
  • The checkout URL /api/checkout/<id>/?t=<token> has no login: the signed 24-hour token in ?t= is the whole credential, and a bad token, an unknown listing or a free tier all answer 404. ?tier=<id> on that URL upgrades a pending free listing, from its status page or its receipt.
  • A tier with featuredDays writes featured_until when its payment lands; a renewal overwrites that window rather than extending it.
  • Featured is decided at build time, so a placement lapses at the next build. The hourly job demotes lapsed rows, requests a rebuild and deletes unpaid listings past limits.unpaidTtlDays; Extend, Remove and Demote now are at /admin/featured/.
  • A priced or featured tier forces rel="sponsored noopener", whatever listing.outboundRel says.
  • A recording that fails after a valid signature still answers 200, logged as PAYMENT_RECORDING_FAILED; Stripe will not retry, so record the money with “Mark as paid by hand” on the listing’s admin page.
Configuration A visitor sees /admin/ reports Fix
features.payments: false, or providers.payment: 'none' only free tiers on the form; checkout and the webhook answer 404 nothing leave it, or turn both on
Payments on, a Stripe secret missing the priced tiers, then a 503 at checkout: “Payment is temporarily unavailable. Nothing has been charged — please try this link again in a few minutes.” The webhook answers 503 too Missing secret STRIPE_SECRET_KEY — run: wrangler secret put STRIPE_SECRET_KEY (local: add to .env). Paid tiers cannot complete a checkout. — one line per key pnpm cf:secrets STRIPE_SECRET_KEY STRIPE_WEBHOOK_SECRET
TOKEN_SECRET missing a 503 at checkout Missing secret TOKEN_SECRET … pnpm cf:secrets TOKEN_SECRET
Endpoint without the slash, or the wrong signing secret “Payment received.” on the status page, but the listing stays unpaid and out of the queue “Awaiting payment”, and after an hour a checkout “created over an hour ago and never completed” fix the endpoint or the secret; Stripe redelivers. For money already taken, “Mark as paid by hand”

Each entry in tiers carries id, name, description, kind, priceCents, currency, featuredDays, slaHours, features and enabled. Two catch people out: featuredDays is required for kind: 'featured' and rejected on any other kind, and enabled: false hides a tier from the form while listings already on it keep their price and stay sponsored. Elsewhere: features.payments, providers.payment, limits.unpaidTtlDays, and listing.outboundRel, which priced tiers override.

  • site.config.ts tiers, features.payments, providers.payment
  • .env.example the two Stripe keys and their instructions
  • Directorysrc/
    • Directoryconfig/
      • schema.ts the rule tying priced tiers to payments
    • Directorypages/api/
      • Directorycheckout/
        • [id].ts the redirect to Stripe
      • Directorystripe/
        • webhook.ts the endpoint; 405 for anything but POST
    • Directoryserver/
      • Directorypayments/
        • checkout.ts the checks before the redirect; the created row
        • stripe.ts the Checkout Session and the signature check
        • webhook.ts the status codes it answers
        • fulfill.ts the idempotent write, upgrades, the receipt
        • index.ts the provider selector; both secrets or none
      • jobs.ts expireFeatured, purgeUnpaid
      • queries.ts featureListing, unfeatureListing, markPaid
      • secrets.ts the messages /admin/ shows
    • Directorylib/
      • listing.ts isFeatured, the sort order, outboundRel
    • Directorypages/admin/
      • featured.astro /admin/featured/
    • Directorypages/submit/status/
      • [token].astro “Complete payment” and the upgrade buttons