Skip to main content

Stripe Integration Operations

Integration Shape​

  • Miru uses the official stripe Ruby gem (Gemfile) with API key setup in config/initializers/stripe.rb.
  • Stripe is used in two flows:
  • Invoice collection via Stripe Checkout (InvoicePayment::Checkout) and webhook fulfillment (Webhooks::StripeController + HandleStripeCheckoutEventService).
  • Subscription billing via Stripe Checkout/Billing Portal (Api::V1::SubscriptionsController) and webhook-driven sync (Subscriptions::StripeSyncService).
  • Stripe Connect onboarding is handled by StripeConnectedAccount and exposed from Payment Settings APIs.

Required Local Secrets​

Add these to your local env file (or shell profile) before starting the app:

  • STRIPE_SECRET_KEY (required)
  • STRIPE_PUBLISHABLE_KEY (required for frontend/public usage)
  • STRIPE_WEBHOOK_ENDPOINT_SECRET (required to validate webhook signatures)
  • APP_BASE_URL (required for Stripe Connect refresh/return URLs; local value: http://127.0.0.1:3000)
  • STRIPE_SUBSCRIPTION_PRICE_ID_MONTHLY (recommended for subscriptions)
  • STRIPE_SUBSCRIPTION_PRICE_ID_YEARLY (recommended for subscriptions)
  • STRIPE_SUBSCRIPTION_PRICE_ID (fallback if interval-specific IDs are not set)

Notes:

  • Use Stripe test-mode keys locally.
  • Never commit keys or webhook secrets.

Create a New Stripe Test Account​

  1. Sign up at Stripe Dashboard in test mode.
  2. Copy test API keys from Developers > API keys.
  3. Create test prices for subscriptions and copy price IDs:
  4. Monthly recurring price -> STRIPE_SUBSCRIPTION_PRICE_ID_MONTHLY
  5. Yearly recurring price -> STRIPE_SUBSCRIPTION_PRICE_ID_YEARLY
  6. If you use a single fallback price, set STRIPE_SUBSCRIPTION_PRICE_ID.

Stripe Signup Wizard Choice (Important)​

When Stripe asks how you want to accept recurring payments, choose:

  • Pre-built checkout form

Why this is the correct choice for Miru:

  • Miru already creates Stripe Checkout Sessions server-side for subscriptions:
  • Api::V1::SubscriptionsController#checkout
  • Miru also uses Stripe Checkout for invoice payment collection:
  • InvoicePayment::Checkout
  • Current architecture is hosted Stripe Checkout + webhook fulfillment, not embedded Elements.

How each wizard option maps to Miru:

  • Pre-built checkout form:
  • Matches current Miru implementation and should be used by default.
  • Shareable payment links:
  • Not used by billing checkout, because hosted links bypass managed-session deduplication.
  • Embedded components:
  • Not used in current Miru implementation; requires separate frontend integration work.

Miru pricing alignment:

  • Free: no Stripe checkout needed.
  • Pro (monthly/yearly): configure recurring Stripe Prices and set:
  • STRIPE_SUBSCRIPTION_PRICE_ID_MONTHLY
  • STRIPE_SUBSCRIPTION_PRICE_ID_YEARLY
  • Enterprise/Hosted Enterprise: keep contact-sales/manual flow unless product explicitly moves them to self-serve Stripe checkout.

Stripe Dashboard Field Checklist (What To Enter)​

For Miru Pro in Stripe Dashboard:

  1. Product:
  • Name: Miru Pro
  • Pricing model: Standard
  1. Monthly price:
  • Type: Recurring
  • Billing period: Monthly
  • Usage model: Licensed (per seat)
  • Amount: your monthly per-seat amount
  1. Yearly price:
  • Type: Recurring
  • Billing period: Yearly
  • Usage model: Licensed (per seat)
  • Amount: your yearly per-seat amount

Do not use:

  • One-time price (not compatible with Miru subscription checkout flow)
  • Metered usage (Miru currently sends explicit seat quantity)

Where To Copy Env Var Values In Stripe​

  • STRIPE_SECRET_KEY:

  • Stripe Dashboard -> Developers -> API keys -> Secret key (<stripe_secret_key>)

  • STRIPE_PUBLISHABLE_KEY:

  • Stripe Dashboard -> Developers -> API keys -> Publishable key (<stripe_publishable_key>)

  • STRIPE_SUBSCRIPTION_PRICE_ID_MONTHLY:

  • Stripe Dashboard -> Product catalog -> Miru Pro -> select monthly recurring price -> copy <monthly_price_id> value

  • STRIPE_SUBSCRIPTION_PRICE_ID_YEARLY:

  • Stripe Dashboard -> Product catalog -> Miru Pro -> select yearly recurring price -> copy <yearly_price_id> value

  • STRIPE_SUBSCRIPTION_PRICE_ID (optional fallback):

  • Set to either monthly or yearly price ID if you want a default fallback

  • STRIPE_WEBHOOK_ENDPOINT_SECRET:

  • If using Stripe CLI locally: value printed by stripe listen (<webhook_signing_secret>)

  • If using Dashboard webhook endpoint: Developers -> Webhooks -> select endpoint -> Reveal signing secret (<webhook_signing_secret>)

Purchase Announcements​

The transition to paid writes one SubscriptionPurchaseEvent for each company and Stripe subscription, in the same transaction as the plan change. The delivery job is queued only after every enclosing transaction commits. If queueing fails or the process dies first, SubscriptionPurchaseDeliveryRecoveryJob queues pending events again, oldest first and at most 100 per run, every 10 minutes. An event becomes due 15 minutes after its last queueing, doubling up to 16 hours while it keeps failing.

  • subscription_purchased analytics are recorded exactly once, because the Ahoy row and tracked_at commit together. The stored converted_at, interval and seats come from the purchase; the Ahoy time column is the delivery time.
  • The PLAN_PURCHASE_ALERT_EMAIL alert is sent at least once. A worker that dies after the mail provider accepts the message but before notified_at commits sends it again, because no provider idempotency key is used.
  • A failed send stays pending, including a Postmark inactive recipient. Reactivate the address or change PLAN_PURCHASE_ALERT_EMAIL, and the next attempt delivers it. Check for failed SubscriptionPurchaseDeliveryJob executions and reported errors. List stuck work with SubscriptionPurchaseEvent.pending. After fixing the cause, SubscriptionPurchaseEvent.find(id).enqueue_delivery retries immediately instead of waiting for backoff.
  • A subscription the company already had in a status other than incomplete or incomplete_expired is not a new purchase when it regains access. A new Stripe subscription after cancellation is. A first purchase that started incomplete is.
  • A generic Stripe event that activates the plan records analytics only. A later checkout.session.completed for that subscription, while it is still paid, requests the alert.
  • If PLAN_PURCHASE_ALERT_EMAIL is unset at delivery, the alert is logged as skipped and stops being pending. Only a later replayed checkout.session.completed can request it again.

Local Webhook Setup (Stripe CLI)​

  1. Install Stripe CLI and authenticate:
stripe login
  1. Forward Stripe events to local Miru webhook:
stripe listen --forward-to http://127.0.0.1:3000/webhooks/stripe/checkout/fulfillment
  1. Copy the signing secret printed by Stripe CLI and set it as STRIPE_WEBHOOK_ENDPOINT_SECRET.
  2. Restart web/worker processes after changing env vars.

Start Miru Locally​

Run app stack using repo-preferred runtime wrapper:

rtk mise exec -- bundle exec foreman start -f Procfile.dev

Primary local URL:

  • http://127.0.0.1:3000

End-to-End Verification Checklist​

A) Stripe Connect (Payment Settings)​

  1. Log in as an owner/admin user.
  2. Open Payment Settings and click Connect Stripe.
  3. Complete Stripe onboarding in test mode.
  4. Confirm provider status returns connected from:
  • GET /api/v1/payments/settings

Expected outcome:

  • stripe.connected is true.

B) Invoice Payment Checkout + Webhook​

  1. Create a client + invoice with Stripe enabled.
  2. Open client invoice payment URL (/invoices/:id/payments/new flow) and choose Stripe.
  3. Complete checkout using Stripe test card 4242 4242 4242 4242.
  4. In Stripe CLI terminal, verify checkout.session.completed is delivered.
  5. In Miru UI/API, verify invoice moved to paid and payment entry is created.

Expected webhook/event handling:

  • Endpoint: POST /webhooks/stripe/checkout/fulfillment
  • Service: HandleStripeCheckoutEventService -> InvoicePayment::StripeCheckoutFulfillment

C) Subscription Checkout + Sync​

  1. Open billing settings in app.
  2. Trigger upgrade checkout (monthly/yearly).
  3. Complete test checkout in Stripe.
  4. Verify webhook events are forwarded and processed:
  • checkout.session.completed
  • customer.subscription.created / updated
  • invoice.paid (on invoice cycles)
  1. Verify company billing fields are updated (stripe_customer_id, stripe_subscription_id) and plan status in billing UI changes.

Expected service path:

  • Api::V1::SubscriptionsController#checkout
  • HandleStripeCheckoutEventService -> Subscriptions::StripeSyncService

API/Flow Smoke Tests​

Use these as focused checks during integration work:

  • GET /api/v1/subscription
  • POST /api/v1/subscription/checkout?interval=monthly
  • POST /api/v1/subscription/portal
  • POST /api/v1/payments/settings/stripe/connect
  • DELETE /api/v1/payments/settings/stripe/disconnect

Common Failure Modes​

  • Invalid signature! on webhook:
  • STRIPE_WEBHOOK_ENDPOINT_SECRET does not match the current Stripe signing secret.
  • Stripe checkout session creation fails:
  • Missing/invalid STRIPE_SECRET_KEY or missing subscription price env var.
  • Stripe Connect refresh/return links are wrong:
  • APP_BASE_URL is missing or not set to the active local host.
  • Billing checkout returns pricing error:
  • Missing STRIPE_SUBSCRIPTION_PRICE_ID_MONTHLY / YEARLY and no fallback STRIPE_SUBSCRIPTION_PRICE_ID.

Focused Test Commands​

Run focused specs first when changing Stripe flows:

rtk mise exec -- bundle exec rspec spec/requests/webhooks/stripe_controller_spec.rb
rtk mise exec -- bundle exec rspec spec/services/subscriptions/stripe_sync_service_spec.rb
rtk mise exec -- bundle exec rspec spec/requests/api/v1/subscriptions_controller_spec.rb

If JavaScript or TypeScript files are changed as part of Stripe work, run:

rtk mise exec -- timeout 30 bin/vite build