Technical Documentation

No error handling shown for Stripe API failures during signup - developer doesn't know how to handle carddeclined, insufficientfunds, or network errors

Wrap Stripe calls in rescue block:

begin
customer = Stripe::Customer.create(...)
subscription = Stripe::Subscription.create(...)
rescue Stripe::CardError => e
# Card declined: carddeclined, insufficientfunds, etc.
render json: { error: e.message }, status: :unprocessableentity
rescue Stripe::RateLimitError => e
# Too many requests to Stripe API
render json: { error: 'Service temporarily unavailable. Please try again.' }, status: :serviceunavailable
rescue Stripe::InvalidRequestError => e
# Invalid parameters (bad priceid, etc.)
Rails.logger.error "Stripe invalid request: #{e.message}"
render json: { error: 'Configuration error. Please contact support.' }, status: :internalservererror
rescue Stripe::StripeError => e
# Generic Stripe error
Rails.logger.error "Stripe error: #{e.message}"
render json: { error: 'Payment processing failed. Please try again.' }, status: :internalserver_error
end

Stripe API calls can fail in multiple ways. Without explicit error handling, signup will crash with 500 errors. Specific rescue blocks let developer show appropriate user messages and prevent partial account creation.

Webhook handler doesn't show idempotency handling or what to do if database update fails mid-processing

Add idempotency and transaction handling:

def create
payload = request.body.read
sigheader = request.env['HTTPSTRIPE_SIGNATURE']

begin
event = Stripe::Webhook.constructevent(payload, sigheader, ENV['STRIPEWEBHOOKSECRET'])
rescue JSON::ParserError => e
render json: { error: 'Invalid payload' }, status: :badrequest and return
rescue Stripe::SignatureVerificationError => e
render json: { error: 'Invalid signature' }, status: :badrequest and return
end

# Idempotency: Check if already processed
if WebhookEvent.exists?(stripeeventid: event.id)
head :ok and return
end

ActiveRecord::Base.transaction do
case event.type
when 'invoice.paymentsucceeded'
handlesuccessfulpayment(event)
when 'invoice.paymentfailed'
handlefailedpayment(event)
when 'customer.subscription.deleted'
handlesubscriptiondeleted(event)
end

# Record that we processed this webhook
WebhookEvent.create!(stripe_event_id: event.id, event_type: event.type, processed_at: Time.current)

end

head :ok
rescue => e
Rails.logger.error "Webhook processing failed: #{e.message}"
# Return 500 so Stripe retries
head :internalservererror
end

Stripe retries webhooks if they fail. Without idempotency checks, you'll double-credit users or send duplicate emails. Transaction ensures atomic updates. Proper error responses tell Stripe whether to retry.

Says 'Stripe will retry automatically' but doesn't specify what developer should do if ALL retries fail, or how to detect retry vs first failure

Add to Edge Case 1:

Handling retry attempts:
- First failure (attempt 1): Set subscriptionstatus = 'pastdue', send email 'Payment failed - we\'ll retry in 3 days'
- Second failure (attempt 2, ~3 days later): Send email 'Second payment attempt failed - update card to avoid service interruption'
- Third failure (attempt 3, ~5 days later): Send email 'Final payment attempt failed - update card within 48 hours'
- Final failure (attempt 4, ~7 days later): Stripe fires customer.subscription.deleted webhook → Set subscription_status = 'cancelled', block all access, send 'Subscription cancelled due to payment failure' email

Detecting retry attempt number:
Check invoice.attemptcount in webhook payload:
if invoice.attemptcount == 1
# First failure - gentle reminder
elsif invoice.attempt_count >= 3
# Multiple failures - urgent action needed
end

Stripe's retry logic is complex and varies by settings. Developer needs to know exact retry sequence to send appropriate user communications and take correct actions at each stage. Attempt count determines message urgency.

Checklist items aren't specific enough to write actual test cases - 'Trial credits decrement' doesn't specify assertions or edge cases to test

Replace generic checklist with specific test scenarios:

Trial Signup & Credit Usage:
- [ ] Valid card creates user with subscriptionstatus='trial', trialcreditsremaining=15, trialendsat=7.days.fromnow
- [ ] Declined card (use Stripe test card 4000000000000002) shows error, does NOT create user record
- [ ] Analysis decrements trialcreditsremaining from 15→14, does NOT touch plancreditsremaining
- [ ] cananalyze? returns true when trialcredits_remaining > 0, false when = 0
- [ ] Attempting analysis with 0 trial credits shows 'Upgrade Now' modal, does NOT process analysis

Auto-upgrade on Day 8:
- [ ] ConvertTrialsJob finds users where trialendsat <= Time.current
- [ ] After job runs: subscriptionstatus='active', plancreditsremaining=75 (for Pro), trialcreditsremaining=0
- [ ] Stripe subscription.status='active' and first invoice is paid
- [ ] currentperiodstart = today, currentperiodend = 30.days.fromnow

Early upgrade:
- [ ] Clicking 'Upgrade Now' immediately charges card (verify Stripe invoice created)
- [ ] After upgrade: subscriptionstatus='active', plancreditsremaining=75, upgradedearly=true
- [ ] Billing cycle starts from upgrade date: currentperiodend = 30.days from upgrade, NOT from trial start
- [ ] Unused trial credits (e.g., 10 remaining) are discarded, NOT added to plan credits

Payment failures:
- [ ] invoice.paymentfailed webhook sets subscriptionstatus='pastdue'
- [ ] cananalyze? returns false when subscriptionstatus='pastdue'
- [ ] Dashboard shows 'Update Payment Method' banner when pastdue
- [ ] After 7 days pastdue with no payment, subscription_status='cancelled'

Webhook idempotency:
- [ ] Receiving same webhook event twice (same event.id) only processes once
- [ ] WebhookEvent record created with stripeeventid after processing
- [ ] Second delivery of same event returns 200 OK but doesn't modify user

Generic checklists don't prevent bugs. Specific test scenarios with exact assertions (subscription_status='trial', credits=15) and Stripe test card numbers give QA and developers concrete, reproducible test cases.