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.
-
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:configsite.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. -
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_KEYThe value comes from
.env.prod; the script refuses awhsec_value or a publishable key, and never echoes it. -
Stripe → Developers → Webhooks → Add destination: the URL
https://<your site>/api/stripe/webhook/(keep the trailing slash), the eventscheckout.session.completedandcheckout.session.async_payment_succeeded, test mode, API version matching the installedstripepackage. The signing secret (whsec_…) is on the endpoint’s page after saving.Terminal pnpm cf:secrets STRIPE_WEBHOOK_SECRETcurl -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. -
Deploy the config change with
pnpm deployor a push; secrets need no deploy./admin/stops listing the two keys.
Verify
Section titled “Verify”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 |
Worth knowing
Section titled “Worth knowing”- 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
featuredDayswritesfeatured_untilwhen 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
unpaidlistings pastlimits.unpaidTtlDays; Extend, Remove and Demote now are at/admin/featured/. - A priced or featured tier forces
rel="sponsored noopener", whateverlisting.outboundRelsays. - 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.
When it is off or degraded
Section titled “When it is off or degraded”| 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” |
Configuration
Section titled “Configuration”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
createdrow - 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
- checkout.ts the checks before the redirect; the
- jobs.ts
expireFeatured,purgeUnpaid - queries.ts
featureListing,unfeatureListing,markPaid - secrets.ts the messages
/admin/shows
Directorylib/
- listing.ts
isFeatured, the sort order,outboundRel
- listing.ts
Directorypages/admin/
- featured.astro
/admin/featured/
- featured.astro
Directorypages/submit/status/
- [token].astro “Complete payment” and the upgrade buttons