Stripe

Stripe

💡

Follow this guide to get Stripe subscriptions setup in your Divjoy codebase. If anything is confusing please reach out.

Basic Setup

  • Create an account on stripe.com
  • Install the Stripe command line tool as described in the Stripe CLI docs.
  • Create your products/plans in Stripe as described in step 3 of this guide. Note: You'll only need to follow step 3, as all code has already been setup for you by Divjoy.
  • Open your codebase .env file and fill in your Stripe "Publishable Key", "Secret Key", and the "Price IDs" you created in the above step. Feel free to change the environment variables names (such as "DEMO_STRIPE_PRICE_PRO") to a different name that better matches your intended plan name (such as "DEMO_STRIPE_PRICE_MEGA"). Just remember to do a codebase search for the changed name so you can update the name anywhere else it's used.
  • If you did change the environment variables names, make sure to also go to src/util/prices.js in your codebase and update the stripePriceIds object so that the object keys and values correctly mirror those changes. They keys will also need to be updated in src/components/PricingSection.js where they are passed in the <Pricing> component.

Customer Portal

  • Your codebase integrates with the Stripe customer portal to enable your users to easily change plans and payment methods.
  • You can follow step 1 of this guide to setup the portal for your Stripe account.
  • After that's setup you should be able to view your customer portal by going to /settings/billing within your web app. Divjoy gives you a dedicated page in your web app that automatically redirects to the portal so that you can share this URL with your users.

Webhooks

  • The last step is to getting Stripe payments fully working is to setup a webhook. A webhook is an API endpoint in your codebase that Stripe will make a request to whenever an event happens, such as a successful payment.
  • For local development simply run npm run stripe-webhook in its own terminal window. This calls the Stripe command line tool (which you should have already installed in a previous step) and tells it to forward all Stripe events to your locally running codebase at localhost:3000/api/stripe-webhook. You'll need to copy the webhook secret that this command outputs, paste it into your .env file as the value for STRIPE_WEBHOOK_SECRET, and then restart your development server (if running already). You can see this npm script in your package.json file.
  • After completing all the above steps and running your app you should be able to successful subscribe to a plan within your app, see your plan data on the /dashboard page, as well as use the customer portal to change plans and billing methods.
  • Later when running your app in production you'll want to make sure you setup a webhook in Stripe webhook settings for the URL mydomain.com/api/stripe-webhook and have it listen for the following events: checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted, customer.subscription.trial_will_end. After creating this webhook, you'll want to make sure to use its "Signing secret" as the value for the STRIPE_WEBHOOK_SECRET environment variable you've set for your production host (as opposed to the value that npm run stripe-webhook gives you for local development).

With Cloud Firestore

  • Skip this step if not using Cloud Firestore
  • If you're using Stripe with Cloud Firestore then you'll also want to add your Stripe "Price IDs" to your firestore.rules file so that you have the ability to control what fields can be updated based on Stripe plan. Search your firestore.rules file for "Add your Stripe plans here", fill in your Stripe "Price IDs", then uncomment the line that calls validateWriteForPlan. By default this ensures that users need the "Pro" or "Business" plan to update the item.featured field, but you can tweak this logic to your needs as you build out your app. If you've already set your rules within the Firebase console remember to do that again with this updated file. Otherwise, we'll walk you through that when you go through Firestore setup.

Troubleshooting

If your running into any issues after completing the above steps here are a few things to check on:

  • Make sure you've also updated the Stripe environment variables in .env starting with REACT_APP_ (or if you're using Next.js NEXT_APP_).
  • Make sure you the port number your app is running on is the same port number as defined in your package.json stripe-webhook script. If not, update the script to point to the correct URL.
  • Depending on your stack, your .env may contain a STRIPE_DOMAIN variable. If this is present, make sure it references the correct localhost port. When this environment variable is added to your host, make sure it references the correct production domain.
  • Make sure Stripe is pinging your webhook by viewing the output in the terminal window where you ran npm run stripe-webhook. You should also see an output in the terminal window where you are running your app (your Stripe webhook endpoint file will log the event name). If not, then ensure you've following the instructions above in the webhook section.
  • Make sure the plan value passed to your purchase/:plan route matches one of the keys in src/util/prices.jsstripePriceIds object. It should be a human readable value, such as "starter". The actual Stripe priceId will be looked up by this key in the stripePriceIds object.