Setup guide

Know the work before you buy.

Pagemage gives you the source for a working storefront. You still need to adapt it to your product, configure your accounts, and test the purchase. Here is what that involves.

1. Buy and download

Check the starter's availability. After a completed payment, the confirmation page unlocks your ZIP. Save the archive and confirmation link.

2. Unzip and install

Extract the download and open the folder containing package.json in your terminal.

npm ci

Edit the copy in index.html, the themes in styles.css, and your business details in the legal pages.

3. Create your product in Stripe

Use a separate Stripe sandbox for a new integration, or keep an existing test-mode setup for rehearsal. Create an active, fixed, per-unit USD price and copy its price_... ID. Standard, Pro, Agency, Agency Pack, and marketplace downloads require one-time prices. Care tiers require licensed monthly or yearly subscription prices with an interval count of one. Keys and prices must come from the same account and environment; each tier needs a separate price ID. Match the advertised amount and provide a cancellation path for recurring offers.

4. Add your keys

Put local values in .env.local. Set deployment values in your Vercel project's environment variables. Never commit secret keys. Customize the Stripe-hosted Checkout name, colors, and square icon in CHECKOUT_BRANDING in catalog.js; the override applies to this storefront's sessions and leaves shared account branding alone. Use a public PNG or JPG icon at least 128×128 and under 512 KB.

5. Test locally

npm run check
npm run smoke
npx vercel dev

Use Stripe test credentials for every test purchase. The public page hides purchase buttons for test-mode prices. To exercise the checkout in your local environment, request a session from the API:

curl -X POST http://localhost:3000/api/create-checkout-session \
  -H 'Content-Type: application/json' \
  -d '{"tier":"standard"}'

Open the returned Stripe URL and use test card 4242 4242 4242 4242, a future expiry, and any CVC. Confirm the download contains your product. Test an unpaid session too, and confirm the server refuses the download.

Complete a second test without opening the success page. Verify the signed event records the correct order in your private register. Replay it and confirm there is one order and one delivery notice. If you accept delayed payment methods, check that pending and failed payments stay locked and a later paid event unlocks only the purchased product. Use the app's own test Checkout Sessions; a synthetic event without its metadata does not prove delivery works.

6. Deploy

After adapting the build for your product, deploy to your own Vercel project:

npx vercel --prod

Review the deployment before sharing it. The security headers live in vercel.json. The public build must exclude api/assets/ so buyers can only download through the payment-checked function.

7. Go-live checklist

Troubleshooting

Checkout is not configured

Check the environment variable names, the selected Vercel environment, and whether you redeployed after changing them.

The page shows no price

Check that the Stripe key can read Prices and the price is active. Test-mode prices do not enable public checkout.

The payment has not completed

Check the session in Stripe. It may still be pending, or the lookup may be using a key from the wrong account or mode.

Local API requests return 404

Run npx vercel dev. The static preview server does not run payment functions.

For setup help, email hello@pagemage.tech with the error and the step you were following. Keep keys and customer details out of the message.