Take test payments with a hosted checkout and webhook

Context: this project is the online store "Thread & Needle", a fashion e-commerce store selling women's and men's clothing, shoes and accessories in United States and charging in USD. Checkout already saves pending orders (Episode 12). The stack is Next.js, TypeScript, PostgreSQL with Drizzle (local database shop_local) and Zod.

Goal: connect Stripe in TEST MODE using this pattern: the customer is sent to the gateway's own hosted checkout page, the gateway tells our server the result through a signed webhook, and only that webhook can mark an order paid. The default gateway is Stripe, using Checkout Sessions. If Stripe is a different gateway, follow the same pattern with its official documentation and tell me where it differs. Before writing code, read the official docs for the gateway and the Next.js version in this project, because details change.

Plan first: show me your plan (files, new tables, environment variable names, events you will handle) and wait for my OK before changing anything. Explain webhooks and idempotency in a few plain words.

Tasks, after I approve:
1. Ask me to add the test secret key and the webhook signing secret to .env.local. Add only the variable names to .env.example. Never print, log or commit their values.
2. Server action or route that creates a hosted checkout session for one pending order. Build the line items, currency and amounts from the order saved in the database, never from the browser. Put the order id in the session metadata and set success and cancel URLs. Redirect the customer to the gateway's page.
3. Success page: it only shows "We are confirming your payment" and reads the order status from our database. It must never mark an order paid.
4. Webhook route at /api/webhooks/stripe (or the matching name for the gateway): read the raw request body, verify the signature, reject anything unverified with an error status, and return quickly. Handle: payment completed (check the paid status, and that amount and currency match the order), delayed payment succeeded or failed if the gateway supports them, session expired, and refund events.
5. Idempotency: add a table that stores every processed event id with a unique constraint. If the same event arrives twice, do nothing the second time. Apply order changes and the event record in one database transaction.
6. Order status rules in one place: pending can become paid, failed or expired; paid can become refunded or partly refunded; paid orders never go back to pending. Reject impossible changes and log them without personal data.
7. On payment, reduce stock for each item inside the same transaction and empty that customer's cart.

Security rules: never see, store or log card numbers, expiry dates or security codes; keep keys only in .env.local and the host's settings; keep test and live keys clearly separate; return generic errors to callers.

Verify yourself and show results: write Vitest tests for the status rules and for duplicate events. Then run the gateway's CLI to forward test webhooks to localhost and complete one successful test payment, one declined test payment and one refund in the gateway's dashboard. Show the order status after each step. Run the type check and linter.

Commit to a branch named feature/payments-test-mode with a clear message.

Report back in this format: 1) What was done. 2) What I should check in the gateway dashboard and in the browser. 3) Anything that needs my decision.

Review the prompt, then copy it. Never paste real passwords or API keys into a chat.