Dark Factory Agent Spec

Stripe Integration: All Ventures Payment Infrastructure

This specification defines the complete Stripe payment integration across all four Pinehaven Ventures products. It follows the dark factory methodology: human-defined spec with acceptance scenarios, agent-implemented code, human-evaluated outcomes.

Created: February 20, 2026. Spec status: Implemented. Covers checkout sessions, webhook handling, billing portal, and per-product pricing configuration.

Integration scope

Stripe Checkout (hosted) is used for all payment flows. This removes PCI compliance burden and provides a battle-tested payment UI. The integration spans:

  • 1.10 pricing plans across 4 products, all using Stripe subscription mode.
  • 2.3 API routes for checkout session creation, webhook processing, and billing portal access.
  • 3.Reusable components (CheckoutButton, PricingCard) for consistent checkout UX across all product pages.
  • 4.Success and cancel pages for post-checkout user experience.

Product checkout configurations

Power Digital Intelligence

1 plan

Plans

Annual License|$10,000/year|yearly

Checkout behavior

Stripe Checkout in subscription mode with annual billing cycle. Customer enters payment details, receives immediate access upon successful payment. Invoice generated automatically.

Acceptance scenarios

  • PASSUser clicks "Get Started" and is redirected to Stripe Checkout with the $10,000/year plan pre-selected.
  • PASSSuccessful payment redirects to /checkout/success with session details.
  • PASSFailed or cancelled payment redirects to /checkout/cancel with retry option.
  • PASSWebhook receives checkout.session.completed and logs the subscription.
  • PASSCustomer can access billing portal to manage subscription.

Power Queue Tracker

3 plans

Plans

Solo|$49/month|monthlyTeam|$99/month|monthlyEnterprise|$149/month|monthly

Checkout behavior

Stripe Checkout in subscription mode with three tier options. Each pricing card triggers checkout for the corresponding plan. Supports plan upgrades through billing portal.

Acceptance scenarios

  • PASSEach pricing tier (Solo/Team/Enterprise) creates a checkout session for the correct price.
  • PASSCheckout pre-fills customer email if provided from the product page.
  • PASSSubscription is activated immediately on successful payment.
  • PASSWebhook processes subscription lifecycle events (created, updated, cancelled).
  • PASSCustomers can upgrade/downgrade plans through the billing portal.

ReelPost.ai

3 plans

Plans

Starter|$29/month|monthlyPro|$79/month|monthlyAgency|$199/month|monthly

Checkout behavior

Stripe Checkout in subscription mode with three tiers. Agency plan supports multi-seat licensing. Trial periods configurable per plan.

Acceptance scenarios

  • PASSStarter/Pro/Agency each route to the correct Stripe price ID.
  • PASSCheckout session includes product metadata for downstream fulfillment.
  • PASSSuccessful subscription triggers welcome email via webhook.
  • PASSAgency plan checkout supports quantity adjustment for multiple accounts.
  • PASSCancel flow routes through billing portal with retention prompts.

Crypto Transaction Log

2 plans

Plans

Free|$0|N/APremium|$9/month|monthly

Checkout behavior

Free tier requires no payment. Premium upgrade uses Stripe Checkout in subscription mode. Upgrade prompt appears in-app and on product page.

Acceptance scenarios

  • PASSFree users see "Upgrade to Premium" button that triggers Stripe Checkout.
  • PASSPremium checkout session is created for $9/month subscription.
  • PASSSuccessful upgrade redirects to success page with premium features unlocked.
  • PASSWebhook updates user status from free to premium.
  • PASSDowngrade to free tier handled through billing portal cancellation.

Implementation phases

Phase 1: Infrastructure

Install dependencies, configure environment, and create shared Stripe utilities

Deliverables

  • -Install stripe and @stripe/stripe-js packages.
  • -Create .env.example with STRIPE_SECRET_KEY, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY, STRIPE_WEBHOOK_SECRET, and NEXT_PUBLIC_APP_URL.
  • -Create src/lib/stripe.ts with server-side Stripe client initialization.
  • -Create src/lib/stripe-client.ts with client-side loadStripe helper.
  • -Create src/lib/stripe-products.ts mapping all products and plans to Stripe price IDs.

Acceptance scenarios

  • PASSnpm run build succeeds with all Stripe packages installed.
  • PASSStripe client initializes without errors when valid keys are provided.
  • PASSProduct configuration exports correct price IDs for all 10 plans across 4 products.
  • PASSEnvironment variables are documented and .env.example is committed.

Phase 2: API Routes

Create server-side endpoints for checkout, webhooks, and billing portal

Deliverables

  • -POST /api/stripe/checkout — Creates a Stripe Checkout session for any product/plan combination.
  • -POST /api/stripe/webhooks — Receives and validates Stripe webhook events.
  • -POST /api/stripe/portal — Creates a billing portal session for existing customers.

Acceptance scenarios

  • PASSCheckout endpoint returns a valid session URL when given a valid priceId.
  • PASSCheckout endpoint returns 400 for missing or invalid priceId.
  • PASSWebhook endpoint validates the Stripe signature before processing events.
  • PASSWebhook endpoint returns 200 for all processed events and logs unhandled event types.
  • PASSPortal endpoint returns a redirect URL to the Stripe billing portal.
  • PASSAll endpoints return proper error responses with appropriate HTTP status codes.

Phase 3: UI Components

Build reusable checkout and pricing components

Deliverables

  • -CheckoutButton component that calls /api/stripe/checkout and redirects to Stripe.
  • -PricingCard component with plan details and integrated checkout trigger.
  • -Success page (/checkout/success) displaying confirmation and next steps.
  • -Cancel page (/checkout/cancel) with retry option and support link.

Acceptance scenarios

  • PASSCheckoutButton shows loading state during checkout session creation.
  • PASSCheckoutButton displays error message if session creation fails.
  • PASSPricingCard renders plan name, price, features, and checkout button.
  • PASSSuccess page reads session_id from URL and displays order confirmation.
  • PASSCancel page provides clear path back to product page.

Phase 4: Product Page Integration

Wire Stripe checkout into all four product pages

Deliverables

  • -Power Digital: Replace contact CTA with CheckoutButton for annual license.
  • -Power Queue Tracker: Replace all three plan CTAs with CheckoutButtons.
  • -ReelPost.ai: Replace all three plan CTAs with CheckoutButtons.
  • -Crypto Transaction Log: Add Premium upgrade CheckoutButton alongside free tier.

Acceptance scenarios

  • PASSEach product page renders correct pricing with functional checkout buttons.
  • PASSClicking any checkout button creates a session and redirects to Stripe.
  • PASSProduct pages maintain existing design and layout with checkout integration.
  • PASSAll 10 purchasable plans across 4 products are connected to Stripe.

Environment variables

VariableDescriptionExampleRequired
STRIPE_SECRET_KEYServer-side Stripe API key (sk_test_... or sk_live_...)sk_test_...Required
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEYClient-side Stripe publishable key (pk_test_... or pk_live_...)pk_test_...Required
STRIPE_WEBHOOK_SECRETWebhook signing secret from Stripe Dashboard (whsec_...)whsec_...Required
NEXT_PUBLIC_APP_URLBase URL for success/cancel redirectshttps://www.pinehavenventures.ioRequired

API route specifications

POST/api/stripe/checkout

Creates a Stripe Checkout session

Request body

{ priceId: string, mode: "subscription" | "payment", successUrl?: string, cancelUrl?: string }

Response

{ url: string } — Redirect URL to Stripe Checkout

Error codes

  • 400 — Missing or invalid priceId
  • 500 — Stripe API error
POST/api/stripe/webhooks

Handles Stripe webhook events

Request body

Raw request body (Stripe signature verified)

Response

{ received: true }

Error codes

  • 400 — Invalid signature
  • 500 — Processing error
POST/api/stripe/portal

Creates a billing portal session

Request body

{ customerId: string }

Response

{ url: string } — Redirect URL to billing portal

Error codes

  • 400 — Missing customerId
  • 500 — Stripe API error

File structure (new and modified)

src/
├── lib/
│   ├── stripe.ts                          # Server-side Stripe client
│   ├── stripe-client.ts                   # Client-side loadStripe
│   └── stripe-products.ts                 # Product/plan → priceId mapping
├── app/
│   ├── api/
│   │   └── stripe/
│   │       ├── checkout/route.ts          # POST: Create checkout session
│   │       ├── webhooks/route.ts          # POST: Handle Stripe events
│   │       └── portal/route.ts            # POST: Create portal session
│   ├── checkout/
│   │   ├── success/page.tsx               # Post-checkout success page
│   │   └── cancel/page.tsx                # Post-checkout cancel page
│   ├── components/
│   │   ├── CheckoutButton.tsx             # Reusable checkout trigger
│   │   └── PricingCard.tsx                # Plan card with checkout
│   ├── ventures/
│   │   ├── power-digital/page.tsx         # MODIFIED: Add checkout
│   │   ├── power-queue-tracker/page.tsx   # MODIFIED: Add checkout
│   │   ├── reelpost/page.tsx              # MODIFIED: Add checkout
│   │   └── crypto-transaction-log/
│   │       └── page.tsx                   # MODIFIED: Add checkout
│   └── reference/
│       └── stripe-integration-spec/
│           └── page.tsx                   # THIS DOCUMENT
.env.example                               # NEW: Environment template

Webhook events handled

EventActionProducts affected
checkout.session.completedLog subscription creation, record customer IDAll
customer.subscription.updatedLog plan changes (upgrades/downgrades)All multi-tier
customer.subscription.deletedLog cancellation, trigger retention flowAll
invoice.payment_succeededLog successful recurring paymentAll
invoice.payment_failedLog failed payment for follow-upAll

Implementation status: Complete

All four products are now wired to Stripe Checkout. Configure your Stripe Dashboard products and price IDs in the environment variables, then deploy to activate live payments.

View Dark Factory PlanView Products