Skip to content

Latest commit

 

History

History
205 lines (148 loc) · 10.1 KB

Stripe Subscription.md

File metadata and controls

205 lines (148 loc) · 10.1 KB
Raw

Apollo Universal Starter Kit Payments Module with Stripe

The Apollo Universal Starter Kit payments module is a great starting point when you want to charge users for access to paid features or services available through your application. With the starter kit payments module, you can develop the recurring billing functionality more rapidly than if you would have started from scratch.

The payment module is based on a popular payment processor Stripe, and the module provides an example of using Stripe subscriptions in a real production application.

The payments module code is located under the packages/server/src/modules/payments/stripe/ directory. (When talking about the payments module files, we'll omit the long packages/server/src/modules/payments/ part for brevity, and will simply start the path with stripe/. If a path doesn't start with stripe/, you should look for a respective file or directory from the project root.)

Running the App in Development Mode

  1. Sign in to Stripe Dashboard.

  2. Enable the subscription module in config/stripe/subscription.js by setting the stripe.subscription.enable property to true:

export default {
  enabled: true,
  // other code is omitted for brevity
};
  1. Replace process.env.STRIPE_PUBLIC_KEY with your Stripe publishable key for development mode in config/stripe/subscription.js:
export default {
   enabled: true,
   publicKey: process.env.STRIPE_PUBLIC_KEY, // Set to your 'Stripe_publishable_key' for development mode
};
  1. Add your [Stripe secret key] into the packages/server/.env file:
# Stripe
STRIPE_SECRET_KEY="your_Stripe_secret_key"

NOTE: In packages/server/.env, you'll also see the STRIPE_ENDPOINT_SECRET environment variable. You don't need to set this variable to run the application in development mode. You need to specify STRIPE_ENDPOINT_SECRET only when you're deploying your Apollo Starter Kit-based application. For more information about deployment, consult the deployment section.

  1. Run yarn stripe:setup from the root project directory.

This command will create a product and plan using the Stripe API according to the default subscription plan and product configured in the config/stripe/subscription.js file.

  1. Start the application:
yarn seed && yarn watch

NOTE: If you're already using Apollo Universal Starter Kit, we recommend that you run yarn migrate instead of yarn seed. Otherwise, the data that's already stored in the database will be overwritten.

  1. Sign in to the application with the email user@example.com and password user1234.

(Apollo Universal Starter Kit provides two demo users; their login details can be found on the /login page in the application. You can also create a new user to subscribe.)

  1. Visit the /subscriber-page page and subscribe. The subscription page provides a few test credit cards that you can use to test Stripe subscription.

  2. Once the payment is processed, visit /subscriber-page again to view the secret number. The subscription information is available on the /profile page.

Implemented Stripe Subscription Features

The payments module in Apollo Universal Starter Kit provides a few features to help you build your specific payments functionality upon them for your particular application.

Currently, Apollo Universal Starter Kit includes the following payments features:

  • Subscription cancellation
  • A default monthly subscription plan
  • Editing credit card details in the user profile
  • Authentication of subscription endpoints on the server
  • Notification functionality for canceled or failed payments
  • Integration with Stripe Elements in React for the web application
  • Integration with React Native Credit Card Input for the mobile app
  • Creation of subscriptions products and plans from the command line with yarn stripe:setup
  • Protection of application routes with SubscriptionRoute (non-subscribers are redirected to the subscription page)

Webhook

The Apollo Starter Kit payments module uses our custom webhook middleware for Express to handle requests from Stripe and to notify users about any changes to their subscription. You can have a look at the stripe/subscription/webhook.ts file for the code that manages requests and notifies users about subscription changes.

Currently, Apollo Universal Starter Kit supports two Stripe events:

  • customer.subscription.deleted. If the user exists in the database, then the application deletes the source from Stripe and updates the database. After that, an email is sent to the user to confirm the cancellation.
  • invoice.payment_failed. An email will be sent to the user if their payment failed.

Simulation of Full Subscription Functionality in Development Mode

If you've already used Stripe, you might know that Stripe doesn't allow you to get subscription information if you're running the application in development mode.

In a production application, upon any changes of the subscription status, Stripe sends requests to the endpoint – a webhook – that you registered with Stripe. These requests typically contain data about the subscription cancellation or payment failure, and you need to handle these events in your production application.

The described flow, however, is only possible in a production application with a real domain.

When you work on your application in development mode, Stripe simply can't send any data to localhost:port (in fact, Stripe still sends requests to the webhook that you registered, but the requests will never reach your application).

Subscription Module Settings

To use the payments module, you need to add your Stripe keys into the packages/server/.env file and configure the module in the config/stripe/subscription.js file.

First, add your Stripe secret and endpoint keys to the packages/server/.env file:

# Stripe API keys
STRIPE_SECRET_KEY=
STRIPE_ENDPOINT_SECRET=

To configure the payments module, you can change the settings listed in the table below in config/stripe/subscription.js:

Property Value Purpose
enabled Boolean Enables or disables the payments module. Defaults to false
webhookUrl String Stores the URL for the webhook that you registered with Stripe
publicKey String Stores the publishable key generated by Stripe for your application
product Object Stores the product properties. Consult Stripe documentation for product
plan Object Stores the subscription plan. Consult Stripe documentation for plan

Deployment with Apollo Starter Kit Payments Module

  1. Create a webhook endpoint in the Stripe dashboard. The webhook URLs that are set in the Stripe dashboard and in the config/stripe/subscription.js file must be the same.

By default, webhookUrl is set to /stripe/webhook in config/stripe/subscription.js, therefore, in the Stripe dashboard you need to set the webhook endpoint to https://your-website-name.com/stripe/webhook. Otherwise, use your own URLs.

  1. Add your live publishable key from Stripe into config/stripe/subscription.js.

  2. Add your live secret key from Stripe into packages/server/.env.

  3. Add the Stripe secret endpoint key from your Stripe webhook (webhook signatures) in packages/server/.env to prevent fraudulent webhooks from being processed.

  4. Run yarn stripe:setup from the root directory of Apollo Starter kit to create a subscription plan and product. The default plan and product are configured in the config/stripe/subscription.js file.

  5. Deploy your application.

Deployment to Heroku

  1. Create a webhook endpoint in Stripe Dashboard. The webhook URLs that are set in the Stripe dashboard and the config/stripe/subscription.js file must be the same.

By default, webhookUrl is set to /stripe/webhook in config/stripe/subscription.js. Therefore, in the Stripe dashboard you need to set the webhook endpoint to https://your-website-name.com/stripe/webhook. Otherwise, use your own URLs.

  1. Add your live publishable key, secret key, and secret endpoint key from Stripe to your deployment configuration variables in Heroku Dashboard.
Variable Value
STRIPE_PUBLIC_KEY 'your_public_key'
STRIPE_SECRET_KEY 'your_secret_key'
STRIPE_ENDPOINT_SECRET 'your_secret_endpoint_key'

STRIPE_ENDPOINT_SECRET is the secret endpoint key that's necessary to prevent fraudulent webhooks from being processed. You can consult webhook signatures for more information about the secret endpoint key.

NOTE: The command yarn stripe:setup will be run automatically by Heroku to create a subscription plan and product using the Stripe API. The default plan and product are configured in the config/stripe/subscription.js file.

  1. Deploy your application.