CloudPOS Documentation

# Payment Gateway Setup

CloudPOS supports Stripe for subscription payments. This guide covers setting up Stripe integration.

# Overview

Stripe integration allows tenants to:

  • Subscribe to plans via Stripe Checkout
  • Pay monthly or yearly
  • Automatically renew subscriptions
  • Manage subscriptions via Stripe Customer Portal

# Step 1: Create Stripe Account

  1. Go to: https://stripe.com
  2. Sign up for an account
  3. Complete account verification
  4. Access Stripe Dashboard

# Step 2: Get Stripe API Keys

# Test Mode (Development)

  1. Stripe Dashboard → Developers → API keys
  2. Copy:
    • Publishable key: pk_test_...
    • Secret key: sk_test_...

# Live Mode (Production)

  1. Toggle Test mode off in Stripe Dashboard
  2. Copy:
    • Publishable key: pk_live_...
    • Secret key: sk_live_...

⚠️ Never share your secret keys!

# Step 3: Create Products and Prices in Stripe

For each subscription plan, create a product in Stripe:

# Create Product

  1. Stripe Dashboard → Products → Add product
  2. Fill in:
    • Name: Plan name (e.g., "Basic Plan")
    • Description: Plan description
  3. Click Save

# Create Prices

For each product, create two prices (monthly and yearly):

Monthly Price:

  1. Click Add price
  2. Set:
    • Price: Monthly amount (e.g., 29.99)
    • Billing period: Recurring → Monthly
    • Currency: USD (or your currency)
  3. Click Save
  4. Copy Price ID (e.g., price_1234567890)

Yearly Price:

  1. Click Add price again
  2. Set:
    • Price: Yearly amount (e.g., 299.99)
    • Billing period: Recurring → Yearly
    • Currency: USD
  3. Click Save
  4. Copy Price ID

Repeat for each plan (Trial, Basic, Pro, Enterprise).

# Step 4: Configure Payment Gateway in Admin Panel

  1. Login to Admin Panel: http://localhost:5173/admin/login

  2. Navigate to Settings → Payment Gateways

  3. Click Create or Edit Stripe gateway

  4. Fill in:

    Test Mode:

    • Publishable Key (Test): pk_test_...
    • Secret Key (Test): sk_test_...
    • Webhook Secret (Test): whsec_... (get from Step 5)

    Live Mode:

    • Publishable Key (Live): pk_live_...
    • Secret Key (Live): sk_live_...
    • Webhook Secret (Live): whsec_... (get from Step 5)

  5. Toggle Test Mode on/off as needed

  6. Toggle Is Active to enable gateway

  7. Click Save

# Method 2: Via Environment Variables (Legacy)

Add to .env file:

STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key_here
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here

Note: Admin Panel method is recommended as it supports test/live mode switching.

# Step 5: Configure Stripe Webhooks

Webhooks notify CloudPOS when payments succeed or fail.

# Create Webhook Endpoint

  1. Stripe Dashboard → Developers → Webhooks
  2. Click Add endpoint
  3. Set Endpoint URL:
    • Development: http://localhost:3000/api/subscriptions/webhook
    • Production: https://yourdomain.com/api/subscriptions/webhook
  4. Click Add endpoint

# Select Events

Select these events to listen to:

  • ✅ checkout.session.completed
  • ✅ customer.subscription.created
  • ✅ customer.subscription.updated
  • ✅ customer.subscription.deleted
  • ✅ invoice.payment_succeeded
  • ✅ invoice.payment_failed

Click Add events.

# Get Webhook Secret

  1. After creating webhook, click on it
  2. Find Signing secret
  3. Click Reveal and copy the secret (starts with whsec_)
  4. Add to Admin Panel → Payment Gateways → Webhook Secret

# Step 6: Configure Plan Price IDs

Link Stripe prices to CloudPOS plans:

  1. Admin Panel → Plans → Select a plan
  2. Fill in:
    • Stripe Price ID (Monthly): price_xxxxx (from Step 3)
    • Stripe Yearly Price ID: price_xxxxx (from Step 3)
  3. Click Save

Repeat for each plan.

# Step 7: Test Payment Flow

# Test Mode Setup

  1. Ensure Test Mode is enabled in Admin Panel
  2. Use Stripe test card numbers:
    • Success: 4242 4242 4242 4242
    • Decline: 4000 0000 0000 0002
    • 3D Secure: 4000 0025 0000 3155
  3. Use any future expiry date (e.g., 12/34)
  4. Use any 3-digit CVC

# Test Subscription

  1. Login as tenant (or register new tenant)
  2. Navigate to Subscription → Plans
  3. Select a plan
  4. Click Subscribe
  5. Complete Stripe Checkout with test card
  6. Verify:
    • Payment succeeds
    • Plan is assigned to tenant
    • Subscription status is ACTIVE

# Verify Webhook

  1. Stripe Dashboard → Developers → Webhooks
  2. Click on your webhook
  3. View Events tab
  4. Check recent events:
    • checkout.session.completed should be successful
    • Check response (should be 200 OK)

# Production Checklist

Before going live:

  • [ ] Switch to Live Mode in Admin Panel
  • [ ] Add Live API keys (not test keys)
  • [ ] Configure Production webhook URL
  • [ ] Get Production webhook secret
  • [ ] Test with real card (small amount)
  • [ ] Verify webhook events are received
  • [ ] Monitor webhook logs in Stripe Dashboard

# Local Webhook Testing (Development)

For local development, use Stripe CLI to forward webhooks:

# Install Stripe CLI

# macOS
brew install stripe/stripe-cli/stripe

# Windows
# Download from: https://github.com/stripe/stripe-cli/releases

# Linux
# Download from: https://github.com/stripe/stripe-cli/releases

# Forward Webhooks

# Login to Stripe
stripe login

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

This will:

  • Show webhook secret (use this in Admin Panel)
  • Forward all webhook events to your local server

# Trigger Test Events

# Trigger checkout completion
stripe trigger checkout.session.completed

# Trigger subscription creation
stripe trigger customer.subscription.created

# Troubleshooting

# Payment Succeeds But Plan Not Assigned

Issue: Stripe payment completes but tenant doesn't get plan

Solutions:

  1. Check webhook configuration:

    • Verify webhook URL is correct
    • Check webhook secret matches
    • View webhook events in Stripe Dashboard

  2. Check webhook logs:

    • Stripe Dashboard → Webhooks → Select webhook → Events
    • Look for failed events
    • Check error messages

  3. Check application logs:

    # PM2 logs
pm2 logs cloudpos

# Or server logs
tail -f logs/pm2-error.log

  4. Manually assign plan:

    • Admin Panel → Tenants → Select tenant
    • Manually assign plan

# Webhook Not Receiving Events

Issue: Webhook endpoint not receiving events from Stripe

Solutions:

  1. Verify webhook URL:

    • Must be publicly accessible (not localhost in production)
    • Must use HTTPS in production
    • Must be exactly: https://yourdomain.com/api/subscriptions/webhook

  2. Check firewall/security:

    • Allow Stripe IPs (see Stripe docs)
    • Check server firewall rules

  3. Test webhook manually:

    • Stripe Dashboard → Webhooks → Select webhook
    • Click Send test webhook
    • Check if received

# Invalid Webhook Secret

Error: No signatures found matching the expected signature

Solutions:

  1. Verify webhook secret:

    • Get secret from Stripe Dashboard → Webhooks → Signing secret
    • Must match exactly (no spaces, correct test/live mode)

  2. Check test/live mode:

    • Test mode webhook secret ≠ Live mode webhook secret
    • Use correct secret for current mode

# CORS Errors

Issue: Frontend can't connect to Stripe

Solutions:

  1. Check CORS settings:

    • Verify CORS_ORIGIN in .env matches frontend URL
    • Restart API server after changes

  2. Check Stripe keys:

    • Use publishable key in frontend (not secret key)
    • Verify keys match test/live mode

# Disabling Payments

If you want to disable payments and use manual plan assignment:

  1. Admin Panel → Payment Gateways
  2. Toggle Is Active to OFF for Stripe
  3. Or remove Stripe configuration

Tenants can still be assigned plans manually via Admin Panel.

Next: See Email Notifications to configure email sending.

← Email Notifications →