Skip to main content

​
Overview

Support Unicorn uses a credit-based billing system:
  • 1 credit = 1 AI message (configurable)
  • Organizations start with 50 free credits/month
  • AI responses are blocked when credits run out (no negative balance)
  • Monthly subscriptions with included credits + ability to purchase additional credits
  • Only AI chat responses consume credits (embeddings are bundled)

​
Architecture

​
Database Schema

  • Organizations: Extended with billing fields (stripe_customer_id, credits_balance, subscription_status)
  • CreditTransactions: Audit log of all credit movements (usage, purchase, refund, renewal)
  • StripeSubscriptions: Monthly subscription tracking
  • StripeCharges: One-time credit purchases
  • PaymentMethods: Stored payment cards
  • Messages: Links to credit transactions

​
Services

  • StripeService: HTTParty-based API client for Stripe
  • BillingService: Core credit management logic
  • CreditTrackingService: Tracks AI message usage

​
Background Jobs

  • TrackAiMessageUsageJob: Async credit deduction after AI messages
  • LowCreditsNotificationJob: Sends Slack alerts when credits exhausted
  • MonthlySubscriptionRenewalJob: Handles monthly subscription renewals

​
Setup Instructions

​
Step 1: Create Stripe Account

  1. Go to stripe.com and sign up
  2. Complete account verification
  3. Switch to Test Mode (toggle in top right) for development

​
Step 2: Get API Keys

​
Development Keys (Test Mode)

  1. In Stripe Dashboard, ensure you’re in Test mode
  2. Navigate to Developers → API keys
  3. Copy:
    • Publishable key: pk_test_... (safe to expose in frontend)
    • Secret key: sk_test_... (keep secret, server-side only)

​
Production Keys (Live Mode)

  1. Switch to Live mode in Stripe Dashboard
  2. Navigate to Developers → API keys
  3. Copy the live keys

​
Step 3: Create Subscription Products

Create Products and Prices in Stripe for subscription plans: Starter Plan:
  • Name: Support Unicorn - Starter
  • Price: $29.00 USD/month
  • Credits: 1,500 per month
  • Copy the Price ID (starts with price_)
Professional Plan:
  • Name: Support Unicorn - Professional
  • Price: $99.00 USD/month
  • Credits: 10,000 per month
  • Copy the Price ID

​
Step 4: Configure Environment Variables

​
Development

Add to .env.development: 
# Stripe Test Keys
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Stripe Price IDs
STRIPE_PRICE_STARTER=price_test_...
STRIPE_PRICE_PROFESSIONAL=price_test_...

# Billing Configuration
CREDITS_PER_MESSAGE=1
PRICE_PER_CREDIT=0.05
FREE_CREDITS_PER_MONTH=50

# Application URL
APP_URL=http://localhost:3000

​
Production

Set via Fly.io secrets: 
fly secrets set STRIPE_SECRET_KEY=sk_live_...
fly secrets set STRIPE_PUBLISHABLE_KEY=pk_live_...
fly secrets set STRIPE_WEBHOOK_SECRET=whsec_...
fly secrets set STRIPE_PRICE_STARTER=price_live_...
fly secrets set STRIPE_PRICE_PROFESSIONAL=price_live_...
fly secrets set CREDITS_PER_MESSAGE=1
fly secrets set PRICE_PER_CREDIT=0.05
fly secrets set FREE_CREDITS_PER_MONTH=50
fly secrets set APP_URL=https://your-app.fly.dev

​
Step 5: Get Webhook Signing Secret

​
Development: Using Stripe CLI

# Install Stripe CLI
brew install stripe/stripe-cli/stripe

# Login
stripe login

# Forward webhooks
stripe listen --forward-to localhost:3000/stripe/webhook
Copy the whsec_... value and add to .env.development.

​
Production: Stripe Dashboard

  1. Go to dashboard.stripe.com/webhooks
  2. Click ”+ Add endpoint”
  3. Set Endpoint URL: https://your-app.fly.dev/stripe/webhook
  4. Select events:
    • checkout.session.completed
    • invoice.paid
    • invoice.payment_failed
    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
    • charge.refunded
  5. Copy the signing secret (whsec_...)

​
Testing

​
Test Stripe Integration

Use Stripe test cards:
  • Success: 4242 4242 4242 4242
  • Decline: 4000 0000 0000 0002

​
Configuration Options

VariableDefaultDescription
STRIPE_SECRET_KEYrequiredStripe API secret key
STRIPE_PUBLISHABLE_KEYrequiredStripe publishable key
STRIPE_WEBHOOK_SECRETrequiredWebhook signing secret
CREDITS_PER_MESSAGE1Credits charged per AI message
PRICE_PER_CREDIT0.05Dollar amount per credit
FREE_CREDITS_PER_MONTH50Monthly free tier allocation
APP_URLhttp://localhost:3000Base URL for Stripe redirects

​
Troubleshooting

​
Webhook signature verification failed

  • Ensure STRIPE_WEBHOOK_SECRET matches the secret from stripe listen
  • Restart stripe listen and copy the new secret

​
Credits not deducting

  • Check Solid Queue is running: bin/rails solid_queue:start
  • Check job dashboard: http://localhost:3000/jobs
  • Review logs for errors in TrackAiMessageUsageJob

​
AI still works with 0 credits

  • Verify organization.can_use_ai? returns false
  • Check organization.subscription_status is 'active'
  • Ensure credit checks are in place

​
Next Steps

File Processing Setup

Configure automated file processing