Stripe Integration Summary

Quick Reference Guide for Issue #202 and #216

🎯 Key Decision: Credit Burndown Model

Answer to your question: Stripe integration happens ONLY during balance top-up, NOT during balance consumption.

Why?

Balance Top-Up (Stripe API):
User clicks "Add $50" → Stripe processes payment → Balance updated in Firestore
Frequency: Low (maybe once per month)
Stripe Cost: ~2.9% + $0.30 per transaction

Balance Consumption (Local Only):
User runs task → Check local balance → Deduct from Firestore → No Stripe API
Frequency: High (100s per day)
Stripe Cost: $0 (all local)

Result: Simple, fast, cheap! 🚀

📊 Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         USER ACTIONS                            │
└─────────────────────────────────────────────────────────────────┘
                    │                              │
              [Top Up $50]                   [Run Task $2.50]
                    │                              │
                    ▼                              ▼
┌──────────────────────────────┐   ┌──────────────────────────────┐
│    TOP-UP FLOW               │   │   CONSUMPTION FLOW           │
│    (Stripe Integration)      │   │   (Local Only)               │
└──────────────────────────────┘   └──────────────────────────────┘
         │                                      │
         │ 1. Create PaymentIntent              │ 1. Check balance
         ├────────► Stripe API                  ├────────► Firestore
         │                                      │
         │ 2. Confirm payment (frontend)        │ 2. Deduct amount
         ├────────► Stripe.js                   ├────────► Firestore
         │                                      │
         │ 3. Webhook: payment_succeeded        │ 3. Create transaction
         ◄────────┤ Stripe                      ├────────► Firestore
         │                                      │
         │ 4. Update balance                    │ 4. Return new balance
         ├────────► Firestore                   ◄────────┤ Firestore
         │                                      │
         │ 5. Create CREDIT transaction         │ (Done - no more API calls)
         └────────► Firestore                   │

┌─────────────────────────────────────────────────────────────────┐
│                    FIRESTORE COLLECTIONS                         │
├──────────────────────────────┬──────────────────────────────────┤
│  billing_profiles            │  billing_transactions            │
│  - user@example.com          │  - txn_123 (CREDIT: +$50)       │
│    - available_balance: $300 │  - txn_124 (DEBIT: -$2.50)      │
│    - stripe_customer_id      │  - txn_125 (DEBIT: -$1.20)      │
│    - complimentary_credits   │  - ...                           │
└──────────────────────────────┴──────────────────────────────────┘

✅ What You Already Have

Backend:

✅ billing.proto - Complete schema
✅ BillingServiceImpl - Fully implemented (mock mode)
✅ StripeService - Ready for real mode
✅ Firestore collections - Set up and working
✅ Transaction tracking - Working
✅ Balance deduction - Atomic and safe

Frontend:

✅ Billing page UI
✅ Balance display in top bar
✅ Transaction history
✅ Expense tracking by project

Dependencies:

✅ Stripe Java SDK (v29.5.0) in pom.xml

🚀 What You Need to Do

Phase 1: Development Setup (This Week)

1. Create Stripe Test Account

# Visit: https://dashboard.stripe.com/register
# Complete signup
# Toggle to "Test mode"

2. Get API Keys

# From Stripe Dashboard → Developers → API keys
STRIPE_PUBLISHABLE_KEY=pk_test_51xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
STRIPE_SECRET_KEY=sk_test_51xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

🔐 Security Note: Test vs. Production Keys

Key Type	Prefix	Can Process Real Payments?	Safe to Commit?	Storage
Test Secret	`sk_test_`	❌ No (test mode only)	⚠️ Not recommended	Use Secret Manager
Test Publishable	`pk_test_`	❌ No (test mode only)	⚠️ Not recommended	Use Secret Manager
Prod Secret	`sk_live_`	✅ YES! Real money!	❌ NEVER!	MUST use Secret Manager
Prod Publishable	`pk_live_`	Used with secret key	✅ Safe (client-side)	Can commit (domain-restricted)

Why NOT commit even test keys?

Someone could spam your Stripe test account
Leaked patterns help attackers
Accidentally promoting test→prod with keys in code
Best practice: No secrets in git, ever

3. Configure Environment

⚠️ IMPORTANT: Secret Storage Strategy

Even for test/dev environments, use Google Secret Manager (not vars.yaml):

# DO NOT add Stripe keys to vars.yaml (it's committed to git!)
# Instead, use Secret Manager for ALL environments:

# Development environment
ENV=dev
GCP_PROJECT_ID="construction-code-expert-${ENV}"

# Create secrets (test keys for dev)
echo -n "sk_test_51xxxxx" | gcloud secrets create stripe-secret-key \
  --data-file=- \
  --project=${GCP_PROJECT_ID}

# NOTE: Get webhook secret AFTER creating webhook endpoint (see step 3a below)
echo -n "whsec_xxxxx" | gcloud secrets create stripe-webhook-secret \
  --data-file=- \
  --project=${GCP_PROJECT_ID}

echo -n "pk_test_51xxxxx" | gcloud secrets create stripe-publishable-key \
  --data-file=- \
  --project=${GCP_PROJECT_ID}

3a. How to Get Webhook Secret:

The webhook secret is NOT in your API keys - you get it when creating a webhook endpoint:

For Local Development (using Stripe CLI):

# Run Stripe CLI webhook forwarding
stripe listen --forward-to localhost:8080/v1/billing/webhook

# This outputs a webhook signing secret like:
# > Ready! Your webhook signing secret is whsec_1234567890abcdef...
# Copy this secret and use it in the command above

For Cloud Run (deployed environments):

Deploy your backend first (so you have a webhook URL)
Go to Stripe Dashboard → Developers → Webhooks
Click "Add endpoint"
Enter webhook URL: https://your-app.run.app/v1/billing/webhook
Click "Select events" and choose:
- payment_intent.succeeded
- payment_intent.payment_failed
Click "Add endpoint"
On the endpoint details page, click "Reveal" next to "Signing secret"
Copy the secret (starts with whsec_)
Store it in Secret Manager using the command above

Order of operations:

✅ Get API keys from Stripe Dashboard (available immediately)
✅ Store API keys in Secret Manager
✅ Deploy backend to get webhook URL
✅ Create webhook endpoint in Stripe Dashboard
✅ Get webhook secret from webhook endpoint details
✅ Store webhook secret in Secret Manager
✅ Redeploy backend with webhook secret mounted

Update vars.yaml to enable Stripe (but NOT store keys):

# env/dev/gcp/cloud-run/grpc/vars.yaml
STRIPE_ENABLED: "true"  # Enable Stripe integration
# Note: Actual keys loaded from Secret Manager, not here!

Update deployment to mount secrets:

# When deploying, mount secrets as environment variables
gcloud run deploy construction-code-expert-grpc \
  --set-env-vars-file=env/dev/gcp/cloud-run/grpc/vars.yaml \
  --set-secrets="STRIPE_SECRET_KEY=stripe-secret-key:latest,STRIPE_WEBHOOK_SECRET=stripe-webhook-secret:latest" \
  --project=construction-code-expert-dev

Why use Secret Manager even for test keys?

✅ Practice good habits in all environments
✅ Prevents accidental exposure in public repos
✅ Easy to rotate keys without changing code
✅ Audit trail of who accessed secrets
✅ Same pattern for dev, test, and prod

Frontend publishable key (exception):

The STRIPE_PUBLISHABLE_KEY for frontend can go in setvars.sh:

# env/dev/firebase/m3/setvars.sh
export STRIPE_PUBLISHABLE_KEY=pk_test_51xxxxx

This is acceptable because:

✅ Publishable keys are meant to be public (used in browser JavaScript)
✅ They can't process payments without the secret key
✅ You can restrict them to specific domains in Stripe Dashboard
✅ Frontend environment files are typically committed

However, backend secret keys (sk_test_, sk_live_) MUST use Secret Manager!

4. Update BillingServiceImpl

// Change from:
this.stripeService = new StripeService();  // Mock mode

// To:
String secretKey = System.getenv("STRIPE_SECRET_KEY");
String webhookSecret = System.getenv("STRIPE_WEBHOOK_SECRET");
boolean enabled = "true".equals(System.getenv("STRIPE_ENABLED"));

if (enabled && secretKey != null) {
    this.stripeService = new StripeService(secretKey, webhookSecret, false);
} else {
    this.stripeService = new StripeService();  // Mock mode
}

5. Install Stripe.js in Frontend

cd web-ng-m3
npm install @stripe/stripe-js

6. Test Payment Flow

Load billing page
Click "Add Funds"
Enter: $25
Card: 4242 4242 4242 4242
Verify: Balance updates to $325

📋 Implementation Checklist

Backend

Update BillingServiceImpl to read env vars
Test Stripe customer creation
Test PaymentIntent creation
Implement webhook endpoint
Test webhook signature verification
Test balance update on webhook

Frontend

Add Stripe.js package
Add publishable key to environment
Create payment dialog component
Add Stripe Elements (card input)
Implement payment confirmation
Handle 3D Secure authentication
Add error handling

Testing

Test with test card 4242...
Test with 3D Secure card 4000 0027 6000 3184
Test with declined card 4000 0000 0000 0002
Test webhook locally with Stripe CLI
Test concurrent payments
Test balance reconciliation

Production

🔐 Security Best Practices

✅ DO:

Store secret keys in Google Secret Manager
Validate webhook signatures
Use HTTPS everywhere
Log payment events (without sensitive data)
Implement rate limiting
Use atomic Firestore transactions

❌ DON'T:

Commit secret keys to git
Log card numbers or CVV
Skip webhook signature verification
Allow negative balances
Process payments without authentication
Store unnecessary PII

📞 Support & Troubleshooting

Common Issues

"Payment processing failed"

Check Stripe Dashboard → Logs
Verify API keys are correct
Check card details are valid

"Webhook not received"

Check webhook URL is publicly accessible
Verify webhook secret matches
Check Stripe Dashboard → Webhooks → Recent deliveries

"Balance not updating"

Check webhook processed successfully
Look for errors in Cloud Run logs
Verify Firestore transaction completed

Useful Commands

# Test Stripe connectivity
stripe customers list --limit 1

# Forward webhooks locally
stripe listen --forward-to localhost:8080/v1/billing/webhook

# Trigger test webhook
stripe trigger payment_intent.succeeded

# Check Cloud Run logs
gcloud logging read "resource.type=cloud_run_revision" \
  --project=construction-code-expert-dev \
  --limit=20 | grep -i stripe

📚 Resources

Documentation:

Full Stripe Integration Plan ← Complete guide
Billing TDD ← Architecture details
Stripe API Reference
Credit Burndown Model

Support:

Stripe Support: https://support.stripe.com
Stripe Status: https://status.stripe.com
GitHub Issues: #202, #216

💡 Key Takeaways

Stripe is ONLY for payments - Not for tracking usage
Top-up is the only Stripe API call - Everything else is local
Test mode first - Use test cards, no real money
Webhooks are critical - They update the balance
Security matters - Never commit secrets, always validate signatures

Ready to start? Follow the Full Stripe Integration Plan!

🎯 Key Decision: Credit Burndown Model​

Why?​

📊 Architecture Diagram​

✅ What You Already Have​

🚀 What You Need to Do​

Phase 1: Development Setup (This Week)​

📋 Implementation Checklist​

Backend​

Frontend​

Testing​

Production​

🔐 Security Best Practices​

📞 Support & Troubleshooting​

Common Issues​

Useful Commands​

📚 Resources​

💡 Key Takeaways​