ForgeScan Monetization Setup

This document outlines the setup and deployment process for the ForgeScan monetization flow using Stripe Checkout.

Overview

The monetization flow allows users to purchase a detailed PDF fix guide for £9.99 when their domain scan reveals security issues. The flow includes:

  1. Conditional CTA display when issues are detected
  2. Stripe Checkout integration
  3. PDF generation with @react-pdf/renderer
  4. Email delivery via Resend/Postmark
  5. Secure download links with 24-hour expiry

Environment Setup

1. Environment Variables

Create a .env.local file (for local development) and set the following Cloudflare secrets:

# Stripe Configuration
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_PRICE_ID=price_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

# Site Configuration
PUBLIC_BASE_URL=https://www.domainforge.co.uk
PRICE_GBP=9.99

# Email Configuration
EMAIL_PROVIDER=resend
RESEND_API_KEY=re_xxx
POSTMARK_TOKEN=xxx

# Storage Configuration
DOWNLOAD_TOKEN_TTL_SECONDS=86400

# Brand Colors
BRAND_PRIMARY_HEX=#FF7A00
BRAND_BG_DARK_HEX=#0B1220

2. Cloudflare Setup

KV Namespaces

Create two KV namespaces:

# Scan data storage
wrangler kv:namespace create "SCAN_DATA"
wrangler kv:namespace create "SCAN_DATA" --preview

# Download tokens storage
wrangler kv:namespace create "DOWNLOAD_TOKENS"
wrangler kv:namespace create "DOWNLOAD_TOKENS" --preview

R2 Bucket

Create an R2 bucket for PDF storage:

wrangler r2 bucket create domainforge-pdfs

Update wrangler.toml

Replace the placeholder IDs in wrangler.toml with your actual KV and R2 IDs.

3. Stripe Setup

Create Product and Price

  1. Go to Stripe Dashboard > Products
  2. Create a new product: "ForgeScan Fix Guide"
  3. Add a price: £9.99 GBP, one-time payment
  4. Copy the price ID (starts with price_)

Webhook Configuration

  1. Go to Stripe Dashboard > Webhooks
  2. Add endpoint: https://your-domain.com/api/stripe-webhook
  3. Select events: checkout.session.completed
  4. Copy the webhook signing secret (starts with whsec_)

4. Email Provider Setup

Resend (Recommended)

  1. Sign up at resend.com
  2. Verify your domain
  3. Create an API key
  4. Set EMAIL_PROVIDER=resend and RESEND_API_KEY=re_xxx

Postmark (Alternative)

  1. Sign up at postmarkapp.com
  2. Create a server
  3. Get the API token
  4. Set EMAIL_PROVIDER=postmark and POSTMARK_TOKEN=xxx

Local Development

1. Install Dependencies

npm install

2. Set Environment Variables

Copy env.example to .env.local and fill in your test values.

3. Start Development Server

npm start

4. Test Stripe Webhooks

Local Development

# Install Stripe CLI
brew install stripe/stripe-cli/stripe

# Forward webhooks to local server
stripe listen --forward-to localhost:8788/api/stripe-webhook

# Copy the webhook secret from CLI output and add to .dev.vars
STRIPE_WEBHOOK_SECRET=whsec_xxx_from_cli_output

Production Setup

  1. Go to Stripe Dashboard > Webhooks
  2. Click "Add endpoint"
  3. Set endpoint URL: https://www.domainforge.co.uk/api/stripe-webhook
  4. Select events: checkout.session.completed
  5. Copy the webhook signing secret (starts with whsec_)
  6. Set the secret in Cloudflare Pages:
    wrangler pages secret put STRIPE_WEBHOOK_SECRET --project-name=domain-forge-site

Test Webhook Secret

# Test if webhook secret is configured (DELETE BEFORE PRODUCTION)
curl http://localhost:8788/api/webhook-test

Testing

Test Card Numbers

Use these Stripe test cards:

Test Flow

  1. Run a scan with a domain that has issues
  2. Verify CTA appears
  3. Click "Fix it for £9.99"
  4. Complete payment with test card
  5. Check email delivery
  6. Verify download link works
  7. Test link expiry (24 hours)

Deployment

1. Build and Deploy

npm run build
wrangler pages deploy dist

2. Set Production Secrets

wrangler secret put STRIPE_SECRET_KEY
wrangler secret put STRIPE_PRICE_ID
wrangler secret put STRIPE_WEBHOOK_SECRET
wrangler secret put RESEND_API_KEY
wrangler secret put PUBLIC_BASE_URL
wrangler secret put EMAIL_PROVIDER
wrangler secret put PRICE_GBP
wrangler secret put DOWNLOAD_TOKEN_TTL_SECONDS

3. Update Webhook URL

Update your Stripe webhook endpoint to point to your production domain.

API Endpoints

POST /api/checkout

Creates a Stripe checkout session.

Request:

{
  "email": "[email protected]",
  "scanKey": "scan_1234567890_abc123"
}

Response:

{
  "url": "https://checkout.stripe.com/pay/cs_test_..."
}

POST /api/stripe-webhook

Handles Stripe webhook events (internal use only).

Features:

Security:

GET /api/session-status?session_id=cs_xxx

Returns session status for the thanks page.

Response:

{
  "status": "completed",
  "downloadUrl": "https://domain.com/api/download/token123"
}

GET /api/download/:token

Serves the PDF file with proper headers.

Security Considerations

  1. Webhook Verification: All Stripe webhooks are verified using the signing secret
  2. Token Expiry: Download tokens expire after 24 hours
  3. No Client Trust: Scan data is stored server-side and never trusted from client
  4. Secure Headers: PDFs are served with no-cache headers
  5. Rate Limiting: Consider adding rate limiting to prevent abuse

Monitoring

Cloudflare Analytics

Monitor API usage and errors in Cloudflare Analytics.

Stripe Dashboard

Track payments, webhook deliveries, and customer data in Stripe Dashboard.

Email Provider Dashboard

Monitor email delivery rates and bounces.

Troubleshooting

Common Issues

  1. Webhook Not Receiving Events

  2. PDF Not Generating

  3. Email Not Sending

  4. Download Link Expired

Debug Mode

Enable debug logging by setting DEBUG=true in environment variables.

Future Enhancements

  1. A/B Testing: Test different price points
  2. Bulk Discounts: Offer discounts for multiple domains
  3. Subscription Model: Monthly domain monitoring
  4. White-label: Allow custom branding
  5. Analytics: Track conversion rates and user behavior

Support

For issues or questions:

  1. Check Cloudflare function logs
  2. Review Stripe webhook delivery logs
  3. Test with Stripe test mode
  4. Contact development team