Document external DashCaddy billing architecture
This commit is contained in:
Krystie
148
STRIPE_SETUP.md
148
STRIPE_SETUP.md
@@ -1,83 +1,65 @@
|
||||
# Stripe Setup Guide for DashCaddy.net
|
||||
|
||||
## 1. Create a Stripe Account
|
||||
|
||||
Go to [stripe.com](https://stripe.com) and create an account (or log in).
|
||||
|
||||
## 2. Create Your Product and Prices
|
||||
|
||||
In the Stripe Dashboard:
|
||||
|
||||
1. Go to **Products** > **Add Product**
|
||||
2. Name: `DashCaddy Premium`
|
||||
3. Description: `Premium license for DashCaddy - Self-hosting dashboard`
|
||||
4. Create two prices:
|
||||
- **Monthly**: $20.00 USD / month (recurring)
|
||||
- **Yearly**: $99.00 USD / year (recurring)
|
||||
5. Note down both **Price IDs** (they look like `price_1234...`)
|
||||
|
||||
## 3. Get Your API Keys
|
||||
|
||||
1. Go to **Developers** > **API Keys**
|
||||
2. Copy your **Publishable key** (`pk_test_...` or `pk_live_...`)
|
||||
3. Copy your **Secret key** (`sk_test_...` or `sk_live_...`)
|
||||
|
||||
## 4. Set Up Webhooks
|
||||
|
||||
1. Go to **Developers** > **Webhooks**
|
||||
2. Click **Add endpoint**
|
||||
3. URL: `https://dashcaddy.net/api/webhooks/stripe`
|
||||
4. Select these events:
|
||||
- `checkout.session.completed`
|
||||
- `customer.subscription.updated`
|
||||
- `customer.subscription.deleted`
|
||||
- `invoice.payment_failed`
|
||||
5. Copy the **Webhook signing secret** (`whsec_...`)
|
||||
|
||||
## 5. Configure Environment Variables
|
||||
|
||||
Copy `.env.example` to `.env.local` and fill in your values:
|
||||
|
||||
```bash
|
||||
cp .env.example .env.local
|
||||
```
|
||||
|
||||
Edit `.env.local`:
|
||||
|
||||
```env
|
||||
STRIPE_SECRET_KEY=sk_live_your_actual_secret_key
|
||||
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_your_actual_publishable_key
|
||||
STRIPE_WEBHOOK_SECRET=whsec_your_actual_webhook_secret
|
||||
STRIPE_PRICE_MONTHLY=price_your_monthly_price_id
|
||||
STRIPE_PRICE_YEARLY=price_your_yearly_price_id
|
||||
NEXT_PUBLIC_APP_URL=https://dashcaddy.net
|
||||
```
|
||||
|
||||
## 6. Test with Stripe CLI (Optional)
|
||||
|
||||
For local development, use Stripe CLI to forward webhooks:
|
||||
|
||||
```bash
|
||||
stripe listen --forward-to localhost:3000/api/webhooks/stripe
|
||||
```
|
||||
|
||||
Use test card `4242 4242 4242 4242` with any future date and any CVC.
|
||||
|
||||
## 7. License Key Delivery
|
||||
|
||||
The webhook handler at `src/app/api/webhooks/stripe/route.ts` has TODO comments
|
||||
where you need to implement:
|
||||
|
||||
1. **Generate license key** using the same format as DashCaddy's license-keygen
|
||||
(DC-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX)
|
||||
2. **Store it** in a database (Stripe metadata can also hold it)
|
||||
3. **Email it** to the customer (use Stripe's receipt email or a service like
|
||||
SendGrid/Resend)
|
||||
4. **Link it** to the Stripe subscription ID so you can manage renewals/cancellations
|
||||
|
||||
## Pricing Strategy Notes
|
||||
|
||||
- **Monthly ($20/mo)**: Positioned as the flexibility option
|
||||
- **Yearly ($99/yr)**: ~$8.25/mo — 58% savings, this will be the primary seller
|
||||
- **14-day free trial**: Enabled on both plans via `trial_period_days: 14`
|
||||
- **Promotion codes**: Enabled via `allow_promotion_codes: true`
|
||||
# DashCaddy Billing Setup
|
||||
|
||||
DashCaddy website no longer processes Stripe webhooks locally.
|
||||
|
||||
Current architecture:
|
||||
- `dashcaddy.net` handles pricing UI and starts checkout by calling the external license server
|
||||
- `dashcaddy-license-server` owns Stripe secret usage, webhook handling, subscription state, and license generation
|
||||
- DashCaddy app instances validate/deactivate against the external license server
|
||||
|
||||
## Required website environment
|
||||
|
||||
```env
|
||||
NEXT_PUBLIC_APP_URL=https://dashcaddy.net
|
||||
NEXT_PUBLIC_LICENSE_SERVER_URL=https://licenses.dashcaddy.net
|
||||
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_your_publishable_key_here
|
||||
```
|
||||
|
||||
## Required license server environment
|
||||
|
||||
```env
|
||||
PORT=3010
|
||||
APP_BASE_URL=https://licenses.dashcaddy.net
|
||||
DASHCADDY_WEBSITE_URL=https://dashcaddy.net
|
||||
STRIPE_SECRET_KEY=sk_live_...
|
||||
STRIPE_PUBLISHABLE_KEY=pk_live_...
|
||||
STRIPE_WEBHOOK_SECRET=whsec_...
|
||||
```
|
||||
|
||||
## Stripe product model
|
||||
|
||||
One Premium tier, four subscription cadences:
|
||||
- 1 month — $25
|
||||
- 3 months — $50
|
||||
- 6 months — $65
|
||||
- 12 months — $99
|
||||
|
||||
No free trial.
|
||||
7-day grace period.
|
||||
Cancel at period end.
|
||||
One active machine at a time.
|
||||
Premium features only: `sso`, `recipes`, `swarm`.
|
||||
|
||||
## Stripe webhook target
|
||||
|
||||
Configure Stripe to send events to the license server, not the website.
|
||||
|
||||
Recommended webhook endpoint:
|
||||
|
||||
```text
|
||||
https://licenses.dashcaddy.net/api/stripe/webhook
|
||||
```
|
||||
|
||||
Recommended events:
|
||||
- `checkout.session.completed`
|
||||
- `customer.subscription.created`
|
||||
- `customer.subscription.updated`
|
||||
- `customer.subscription.deleted`
|
||||
- `invoice.payment_failed`
|
||||
|
||||
## Website behavior
|
||||
|
||||
The website pricing page should start checkout via:
|
||||
- `POST /api/checkout/session` on the external license server
|
||||
|
||||
The website-local routes under `src/app/api/checkout` and `src/app/api/webhooks/stripe` are intentionally disabled compatibility stubs and should not be used for production billing.
|
||||
|
||||
Reference in New Issue
Block a user