southseact-3d/shopify-ai-backup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Restore to commit 74e578279624c6045ca440a3459ebfa1f8d54191

Browse Source
This commit is contained in:
southseact-3d
2026-02-07 20:32:41 +00:00
commit ed67b7741b
252 changed files with 99814 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

465
stripe.md Normal file
View File

@@ -0,0 +1,465 @@
# 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.