Stripe, payments & plans

Once your Stripe credentials are configured (like we did in the quickstart), setting up payments and pricing plans in your app is quite straightforward.

Install the Stripe CLI

The first thing you're gonna want to do is install the Stripe CLI and configure it with your Stripe Sandbox, so you can receive Stripe webhooks in development.

Once installed, log in to your Stripe account from the CLI:

stripe login

And then forward all development webhooks to your local dev server:

stripe listen --forward-to localhost:3000/pay/webhooks/stripe

You'll get a development Stripe webhook signing secret, which you need to add to your development credentials so that Stripe webhooks get processed.

With that, your development RailsFast app is now fully wired to Stripe, and reacting + processing all webhooks!

NOTE

For Stripe webhooks to get processed, solid_queue needs to be running. This is handled automatically by RailsFast when you run bin/dev to start your development server, but if you're doing something else like starting your server with rails s, you need to launch solid_queue like this: bundle exec rake solid_queue:start

Add and define your pricing plans

The next thing you're going to do is add your subscription options (your pricing plans) to your railsfast.yml file. There's a placeholder there, you need to fill it up with your actual Stripe price IDs you've created in your Stripe dashboard:

development:
  <<: *default
  # Stripe pricing configuration
  # Define your Stripe Price IDs for each environment
  # These will be used by both pricing_plans and usage_credits gems
  # Use Sandbox / testing mode in Stripe to get test IDs in development
  stripe:
    plans:
      basic_plan:
        monthly: "price_REPLACE_ME"
        yearly: "price_REPLACE_ME"
      pro_plan:
        monthly: "price_REPLACE_ME"
        yearly: "price_REPLACE_ME"
      advanced_plan:
        monthly: "price_REPLACE_ME"
        yearly: "price_REPLACE_ME"

IMPORTANT

Make sure you use Stripe Sandbox price IDs for your development environment, and live price IDs for your production environment.

This is the single source of Stripe price IDs for your entire app: everything draws from here.

To have these subscription plans show up in your pricing page, edit the pricing_plans.rb file. It will look something like this:

  stripe_config = Rails.configuration.x.railsfast.dig(:stripe, :plans) || {}

  plan :basic_plan do
    stripe_price    month: stripe_config.dig(:basic_plan, :monthly), year: stripe_config.dig(:basic_plan, :yearly)

    allows          :api_access
    limits          :projects, to: 5

    description     "Your basic plan description"
    bullets         "API Access", "Up to 5 projects"
  end

RailsFast uses the pricing_plans gem to define pricing plans. The first thing you get automatically is your users can purchase whatever plans you define (with monthly and yearly pricing) from your /pricing page – try it out after defining your plans! On top of having checkout and billing already configured, whatever you define in each of your pricing plans is automatically enforceable anywhere else in your app. In the example above, we give users on the basic_plan API access and up to 5 projects. You can enforce these limits easily throughout your app with methods and helpers like these:

@user.plan_allows_api_access?  # => true / false
@user.projects_remaining       # => 2

Read the pricing_plans gem docs to learn everything you can do with it (which is a lot!)

RailsFast pricing cards with automatic pricing plan limits and entitlements enforcement

And with that, you're pretty much ready to start charging and providing a fully functional service! Both in development and production! Try it out!

If you want to tweak how the pricing page is rendered (toggle, accent color, scalable plans, etc.), see Pricing page.

Handle plan upgrades and downgrades

RailsFast uses the Stripe Customer Portal integration to offload everything billing-related to Stripe. This includes handling plan upgrades and downgrades, which Stripe does beautifully. To get started, go to your Stripe dashboard and configure your plan upgrade and downgrade options in: https://dashboard.stripe.com/settings/billing/portal

With that, your users will be able to upgrade or downgrade their subscription at any time through the Stripe Customer Portal link we provide with RailsFast. Everything else is automatically handled: whenever a user upgrades or downgrades, your app gets the webhook and your user gets moved to the corresponding plan, with its corresponding limits and enabled features.

One-time payments

TODO: PayChargeExtension

Invoices

TODO: receipts gem

Adding a production Stripe webhook

Don't forget to add a production Stripe webhook for your payments to work in production too!

Go to your Stripe Dashboard - Webhooks (make sure it's in live mode, and not in Sandbox!)
Click "Add endpoint"
Enter your webhook URL: https://YOURDOMAIN.COM/pay/webhooks/stripe
Select events to listen to (at minimum: customer, charge, invoice, and payment_intent, or select "receive all events")
Copy the signing secret and add it to your production credentials

RailsFast uses the pay gem to handle everything Stripe-related, check out the Pay Docs for guidance on how to use it if what you want to do is not covered in the RailsFast docs!