466 lines
14 KiB
Markdown
466 lines
14 KiB
Markdown
# Stripe Setup Guide for Plugin Compass
|
|
|
|
This guide will walk you through setting up Stripe for Plugin Compass to process payments and manage subscriptions for the Professional and Agency plans.
|
|
|
|
## Table of Contents
|
|
|
|
1. [Prerequisites](#prerequisites)
|
|
2. [Create a Stripe Account](#create-a-stripe-account)
|
|
3. [Get Your API Keys](#get-your-api-keys)
|
|
4. [Configure Environment Variables](#configure-environment-variables)
|
|
5. [Create Products and Prices](#create-products-and-prices)
|
|
6. [Set Up Webhooks](#set-up-webhooks)
|
|
7. [Testing with Stripe Test Mode](#testing-with-stripe-test-mode)
|
|
8. [Going Live](#going-live)
|
|
9. [Troubleshooting](#troubleshooting)
|
|
|
|
## Prerequisites
|
|
|
|
Before you begin, ensure you have:
|
|
- Access to your server's environment variables
|
|
- Admin/root access to the Plugin Compass deployment
|
|
- A verified business email address
|
|
- Business registration details (for live mode)
|
|
|
|
## Create a Stripe Account
|
|
|
|
1. Go to [https://dashboard.stripe.com/register](https://dashboard.stripe.com/register)
|
|
2. Sign up with your business email
|
|
3. Verify your email address
|
|
4. Complete your business profile:
|
|
- Business name: "Plugin Compass" (or your business name)
|
|
- Business type
|
|
- Industry: "Software as a Service (SaaS)"
|
|
- Website URL
|
|
- Support email
|
|
|
|
## Get Your API Keys
|
|
|
|
### Test Mode Keys (for development)
|
|
|
|
1. Log into your Stripe Dashboard
|
|
2. Ensure you're in **Test mode** (toggle in the top right)
|
|
3. Navigate to **Developers** → **API keys**
|
|
4. You'll see two keys:
|
|
- **Publishable key** (starts with `pk_test_`)
|
|
- **Secret key** (starts with `sk_test_`) - Click "Reveal test key"
|
|
5. Keep these keys secure - you'll need them for configuration
|
|
|
|
### Live Mode Keys (for production)
|
|
|
|
1. Complete Stripe account verification first
|
|
2. Toggle to **Live mode** in the top right
|
|
3. Navigate to **Developers** → **API keys**
|
|
4. You'll see:
|
|
- **Publishable key** (starts with `pk_live_`)
|
|
- **Secret key** (starts with `sk_live_`) - Click "Reveal live key"
|
|
|
|
## Configure Environment Variables
|
|
|
|
Add these environment variables to your deployment:
|
|
|
|
```bash
|
|
# Test mode (for development)
|
|
STRIPE_SECRET_KEY=sk_test_your_secret_key_here
|
|
STRIPE_PUBLISHABLE_KEY=pk_test_your_publishable_key_here
|
|
# One-off top-up price IDs (one-time prices)
|
|
STRIPE_TOPUP_PRICE_FREE=price_test_free_topup
|
|
STRIPE_TOPUP_PRICE_PLUS=price_test_plus_topup
|
|
STRIPE_TOPUP_PRICE_PRO=price_test_pro_topup
|
|
|
|
# Live mode (for production)
|
|
STRIPE_SECRET_KEY=sk_live_your_secret_key_here
|
|
STRIPE_PUBLISHABLE_KEY=pk_live_your_publishable_key_here
|
|
# One-off top-up price IDs (one-time prices)
|
|
STRIPE_TOPUP_PRICE_FREE=price_live_free_topup
|
|
STRIPE_TOPUP_PRICE_PLUS=price_live_plus_topup
|
|
STRIPE_TOPUP_PRICE_PRO=price_live_pro_topup
|
|
```
|
|
|
|
### Docker/Docker Compose
|
|
|
|
Add to your `.env` file or `docker-compose.yml`:
|
|
|
|
```yaml
|
|
environment:
|
|
- STRIPE_SECRET_KEY=sk_test_your_key
|
|
- STRIPE_PUBLISHABLE_KEY=pk_test_your_key
|
|
```
|
|
|
|
### Kubernetes
|
|
|
|
Create a secret:
|
|
|
|
```bash
|
|
kubectl create secret generic stripe-keys \
|
|
--from-literal=STRIPE_SECRET_KEY=sk_test_your_key \
|
|
--from-literal=STRIPE_PUBLISHABLE_KEY=pk_test_your_key
|
|
```
|
|
|
|
### Environment Variable File
|
|
|
|
Or add to your `.env` file:
|
|
|
|
```
|
|
STRIPE_SECRET_KEY=sk_test_your_secret_key
|
|
STRIPE_PUBLISHABLE_KEY=pk_test_your_publishable_key
|
|
```
|
|
|
|
## Create Products and Prices
|
|
|
|
You need to create Products and Prices in Stripe for each plan and currency.
|
|
|
|
### Option 1: Using Stripe Dashboard (Recommended for beginners)
|
|
|
|
#### Create Professional Plan
|
|
|
|
1. Go to **Products** in the Stripe Dashboard
|
|
2. Click **+ Add product**
|
|
3. Fill in the details:
|
|
- **Name**: Professional Plan
|
|
- **Description**: For serious WordPress plugin developers
|
|
- **Image**: (optional) Upload your plan icon/image
|
|
|
|
4. **Create USD Price**:
|
|
- **Pricing model**: Standard pricing
|
|
- **Price**: $25.00
|
|
- **Billing period**: Monthly
|
|
- **Currency**: USD
|
|
- Click **Add another price** to add yearly: $20.00/month (billed annually as $240)
|
|
|
|
5. **Create GBP Price**:
|
|
- Click **Add price** on the product page
|
|
- **Price**: £20.00
|
|
- **Billing period**: Monthly
|
|
- **Currency**: GBP
|
|
- Add yearly: £16.00/month (billed annually as £192)
|
|
|
|
6. **Create EUR Price**:
|
|
- Click **Add price** on the product page
|
|
- **Price**: €25.00
|
|
- **Billing period**: Monthly
|
|
- **Currency**: EUR
|
|
- Add yearly: €20.00/month (billed annually as €240)
|
|
|
|
#### Create Agency Plan
|
|
|
|
Repeat the same process with these prices:
|
|
|
|
- **USD**: $99/month, $79/month (yearly)
|
|
- **GBP**: £79/month, £63/month (yearly)
|
|
- **EUR**: €99/month, €79/month (yearly)
|
|
|
|
### Create Token Top-up Products
|
|
|
|
Create three one-time products to power the `/topup` purchase page:
|
|
|
|
1. Add a **Free/Starter Top-up** product (one-time) with a single price (e.g., $15 for 500k credits).
|
|
2. Add a **Plus Top-up** product (one-time) with a single price (e.g., $25 for 1M credits).
|
|
3. Add a **Pro Top-up** product (one-time) with a single price (e.g., $40 for 1M pro-tier credits).
|
|
|
|
Copy the resulting Price IDs into the environment variables:
|
|
|
|
- `STRIPE_TOPUP_PRICE_FREE`
|
|
- `STRIPE_TOPUP_PRICE_PLUS`
|
|
- `STRIPE_TOPUP_PRICE_PRO`
|
|
|
|
The app automatically applies a 2.5% discount for Business plans and a 5% discount for Enterprise plans during checkout. Successful payments redirect back to `/topup`, confirm the Stripe session, and immediately add the purchased credits to the user's balance.
|
|
|
|
### Option 2: Using Stripe CLI (Advanced)
|
|
|
|
Install the [Stripe CLI](https://stripe.com/docs/stripe-cli) and run:
|
|
|
|
```bash
|
|
# Professional Plan - USD
|
|
stripe products create \
|
|
--name="Professional Plan" \
|
|
--description="For serious WordPress plugin developers"
|
|
|
|
# Get the product ID (e.g., prod_xxxxx) and create prices:
|
|
stripe prices create \
|
|
--product=prod_xxxxx \
|
|
--unit-amount=2500 \
|
|
--currency=usd \
|
|
--recurring[interval]=month
|
|
|
|
stripe prices create \
|
|
--product=prod_xxxxx \
|
|
--unit-amount=24000 \
|
|
--currency=usd \
|
|
--recurring[interval]=year
|
|
|
|
# Repeat for GBP (2000 pence = £20) and EUR (2500 cents = €25)
|
|
```
|
|
|
|
### Copy Price IDs
|
|
|
|
After creating prices, you'll see Price IDs like `price_xxxxx`. You'll need these for:
|
|
- Checkout page integration
|
|
- Subscription management
|
|
- Webhook handling
|
|
|
|
Store them in your environment variables if needed:
|
|
|
|
```bash
|
|
STRIPE_PRICE_PROFESSIONAL_USD_MONTHLY=price_xxxxx
|
|
STRIPE_PRICE_PROFESSIONAL_USD_YEARLY=price_xxxxx
|
|
STRIPE_PRICE_PROFESSIONAL_GBP_MONTHLY=price_xxxxx
|
|
# ... etc
|
|
```
|
|
|
|
## Set Up Webhooks
|
|
|
|
Webhooks allow Stripe to notify your application about payment events.
|
|
|
|
### Configure Webhook Endpoint
|
|
|
|
1. Go to **Developers** → **Webhooks**
|
|
2. Click **+ Add endpoint**
|
|
3. Enter your endpoint URL:
|
|
- Test: `https://your-test-domain.com/api/stripe/webhook`
|
|
- Live: `https://plugincompass.com/api/stripe/webhook`
|
|
4. Select events to listen to:
|
|
- `customer.subscription.created`
|
|
- `customer.subscription.updated`
|
|
- `customer.subscription.deleted`
|
|
- `invoice.payment_succeeded`
|
|
- `invoice.payment_failed`
|
|
- `payment_method.attached`
|
|
- `payment_method.detached`
|
|
5. Click **Add endpoint**
|
|
6. Copy the **Signing secret** (starts with `whsec_`)
|
|
|
|
### Add Webhook Secret to Environment
|
|
|
|
```bash
|
|
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
|
|
```
|
|
|
|
### Test Webhook Locally
|
|
|
|
Using Stripe CLI:
|
|
|
|
```bash
|
|
stripe listen --forward-to localhost:4000/api/stripe/webhook
|
|
```
|
|
|
|
This will give you a webhook signing secret for local testing.
|
|
|
|
## Testing with Stripe Test Mode
|
|
|
|
Stripe provides test card numbers for testing payments:
|
|
|
|
### Test Cards
|
|
|
|
| Card Number | Scenario |
|
|
|---------------------|-----------------------------------|
|
|
| 4242 4242 4242 4242 | Successful payment |
|
|
| 4000 0027 6000 3184 | Requires 3D Secure authentication |
|
|
| 4000 0000 0000 9995 | Declined card |
|
|
| 4000 0000 0000 0341 | Attaching card fails |
|
|
|
|
**For all test cards:**
|
|
- Use any future expiration date (e.g., 12/34)
|
|
- Use any 3-digit CVC (e.g., 123)
|
|
- Use any 5-digit ZIP code (e.g., 12345)
|
|
|
|
### Test the Payment Flow
|
|
|
|
1. Go to your pricing page
|
|
2. Select a plan (Professional or Agency)
|
|
3. Enter test card details
|
|
4. Complete the payment
|
|
5. Verify in Stripe Dashboard:
|
|
- Go to **Payments** to see the test payment
|
|
- Go to **Customers** to see the test customer
|
|
- Go to **Subscriptions** to see active test subscriptions
|
|
|
|
## Going Live
|
|
|
|
### Before Going Live Checklist
|
|
|
|
- [ ] Complete Stripe account verification (identity, business, banking)
|
|
- [ ] Add payout/bank account information
|
|
- [ ] Test all payment flows in test mode
|
|
- [ ] Test webhook handling
|
|
- [ ] Set up email notifications
|
|
- [ ] Configure tax settings (if applicable)
|
|
- [ ] Review pricing and product descriptions
|
|
- [ ] Set up dispute handling process
|
|
- [ ] Configure automatic subscription management
|
|
- [ ] Test cancellation and refund flows
|
|
|
|
### Activate Live Mode
|
|
|
|
1. Complete all required verification steps in Stripe Dashboard
|
|
2. Submit your application for review (may take 1-2 business days)
|
|
3. Once approved, toggle to **Live mode**
|
|
4. Update environment variables with live API keys:
|
|
```bash
|
|
STRIPE_SECRET_KEY=sk_live_your_live_key
|
|
STRIPE_PUBLISHABLE_KEY=pk_live_your_live_key
|
|
```
|
|
5. Recreate products and prices in Live mode (or copy from test mode)
|
|
6. Create a new webhook endpoint for live mode
|
|
7. Update webhook secret in environment variables
|
|
8. Deploy the changes to production
|
|
9. Test with a real card (or your own card) to verify
|
|
|
|
### Security Recommendations
|
|
|
|
1. **Never commit API keys to version control**
|
|
2. **Use environment variables** for all keys
|
|
3. **Rotate keys periodically** (every 90 days recommended)
|
|
4. **Set up Stripe Radar** for fraud prevention
|
|
5. **Enable 3D Secure** for European customers (PSD2 compliance)
|
|
6. **Log all payment events** for audit trails
|
|
7. **Monitor webhook delivery** in Stripe Dashboard
|
|
8. **Set up alerts** for failed payments and disputes
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### 1. "No such customer" error
|
|
|
|
**Solution**: Ensure the customer is created before attempting to create/attach payment methods:
|
|
|
|
```javascript
|
|
// First check if customer exists
|
|
let customer;
|
|
if (user.stripeCustomerId) {
|
|
try {
|
|
customer = await stripe.customers.retrieve(user.stripeCustomerId);
|
|
} catch (err) {
|
|
customer = null;
|
|
}
|
|
}
|
|
|
|
// Create if doesn't exist
|
|
if (!customer) {
|
|
customer = await stripe.customers.create({
|
|
email: user.email,
|
|
metadata: { userId: user.id }
|
|
});
|
|
}
|
|
```
|
|
|
|
#### 2. Webhook signature verification fails
|
|
|
|
**Causes**:
|
|
- Wrong webhook secret in environment variables
|
|
- Request body was modified before verification
|
|
- Using test secret with live mode (or vice versa)
|
|
|
|
**Solution**: Verify webhook secret matches the endpoint, and raw request body is used for verification.
|
|
|
|
#### 3. "Invalid API Key" error
|
|
|
|
**Solution**:
|
|
- Check you're using the correct key for the mode (test vs live)
|
|
- Verify no extra spaces or quotes in environment variables
|
|
- Check key hasn't been rolled/revoked in Stripe Dashboard
|
|
|
|
#### 4. Payment method attachment fails
|
|
|
|
**Solution**: Ensure you're passing the payment method ID (starts with `pm_`), not the card token.
|
|
|
|
#### 5. Currency mismatch errors
|
|
|
|
**Solution**: When creating a subscription, ensure the price ID matches the customer's selected currency.
|
|
|
|
### Debug Mode
|
|
|
|
Enable Stripe debug logging:
|
|
|
|
```javascript
|
|
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY, {
|
|
apiVersion: '2024-06-20',
|
|
maxNetworkRetries: 2,
|
|
telemetry: false, // Disable telemetry in production
|
|
appInfo: {
|
|
name: 'Plugin Compass',
|
|
version: '1.0.0',
|
|
}
|
|
});
|
|
|
|
// Log all requests (development only)
|
|
if (process.env.NODE_ENV === 'development') {
|
|
stripe._emitter.on('request', (request) => {
|
|
console.log('Stripe request:', request);
|
|
});
|
|
}
|
|
```
|
|
|
|
### Support Resources
|
|
|
|
- **Stripe Documentation**: https://stripe.com/docs
|
|
- **Stripe Support**: https://support.stripe.com
|
|
- **Stripe Discord**: https://stripe.com/discord
|
|
- **Stripe API Reference**: https://stripe.com/docs/api
|
|
- **Test Card Numbers**: https://stripe.com/docs/testing
|
|
|
|
## Additional Configuration
|
|
|
|
### Subscription Management
|
|
|
|
The application automatically handles:
|
|
- Payment method storage (encrypted in Stripe)
|
|
- Subscription creation and updates
|
|
- Plan upgrades/downgrades
|
|
- Cancellations and pause/resume
|
|
- Failed payment retry logic
|
|
|
|
### Plan Comparison
|
|
|
|
| Plan | USD/month | GBP/month | EUR/month | Apps | Features |
|
|
|--------------|-----------|-----------|-----------|------|--------------------------|
|
|
| Hobby | Free | Free | Free | 3 | Basic features |
|
|
| Professional | $25 | £20 | €25 | 20 | All features + priority |
|
|
| Agency | $99 | £79 | €99 | ∞ | Everything + white-label |
|
|
|
|
### Currency Detection
|
|
|
|
The app automatically detects user currency based on:
|
|
1. Previously saved preference (localStorage)
|
|
2. Browser language/region (navigator.languages)
|
|
3. Timezone (Intl.DateTimeFormat)
|
|
4. Fallback to USD if detection fails
|
|
|
|
Users can manually change currency using the dropdown on pricing pages.
|
|
|
|
## Compliance
|
|
|
|
### GDPR (Europe)
|
|
|
|
- Stripe is GDPR compliant
|
|
- Customer data is stored securely
|
|
- Users can request data deletion
|
|
- Cookie consent required for tracking
|
|
|
|
### PSD2 (Europe)
|
|
|
|
- 3D Secure authentication required for European cards
|
|
- Automatically handled by Stripe Elements
|
|
- No additional code needed
|
|
|
|
### PCI DSS
|
|
|
|
- Never store raw card numbers
|
|
- Use Stripe Elements for card input
|
|
- Stripe handles PCI compliance
|
|
- Annual compliance verification required
|
|
|
|
## Next Steps
|
|
|
|
1. ✅ Complete Stripe account setup
|
|
2. ✅ Configure environment variables
|
|
3. ✅ Create products and prices
|
|
4. ✅ Set up webhooks
|
|
5. ✅ Test in test mode
|
|
6. ✅ Go live with real payments
|
|
7. ✅ Monitor payments and subscriptions
|
|
8. ✅ Set up customer support for billing issues
|
|
|
|
For technical support or questions about the Plugin Compass Stripe integration, please refer to the main documentation or contact support.
|