Payment Authorization Tutorial

Overview

ZapStart comes with a powerful subscription-based access control system that allows you to limit features based on a user's plan. This tutorial explains how to use the planAuth middleware to create paywalled features and manage user access to different subscription tiers.

The previous tutorial was about user authentication and authorization (how to protect routes from unauthenticated users), this tutorial is about how to protect routes from users with the wrong plan.

Plan-Based Access [Frontend]

Check if a user has access to your product, using the user.plan.hasAccess property, the has access property is not restricted to the paid plans, it can be used to check if the user has access to any plan, whether free or paid, because you may don't want to the user to have access to a free product unless they click on (try for free) button for example, and this is automatically handled for you by default in the boilerplate:

import { useAuth } from "@/context/AuthContext";

function DashboardPage() {
  const { user } = useAuth();
  
  // Check if user has access to this feature
  const hasAccess = user?.plan?.hasAccess;

  if (!user) {
    return router.push('/login');
  }

  return (
    <div>
      {hasAccess ? (
        <div>Dashboard Page Content</div>
    ) : (
        <div>Choose a plan first to get access to the product</div>
      )}
    </div>
  );
}

One-time vs Subscription Payment

ZapStart supports both one-time payments and recurring subscriptions through configuration.

Managing User Access

When a user makes a payment, you'll need to update their plan information in the database. The webhook handler in the subscription controller is where this happens automatically.

// This code is simplified for demonstration
// Real implementation is in your subscriptionController.js

// When a successful payment is detected in the webhook:
user.plan = {
  ...user.plan,
  currentPlanName: plan.name,  // e.g., 'Pro'
  priceId: plan.priceId,       // Stripe price ID
  hasAccess: true,             // Grant access
  // Other plan details...
};

Adding a new plan

To add a new plan, you need to make a few updates:

• First add the plan to the backend/src/models/userModel.js file in the currentPlanName array.
• Then add the plan to the backend/configBack.js file in the plans array with its name and priceId.
• Then add the plan to the frontend/configFront.js file in the stripe.plans array with its priceId.
• Create features in the backend and limit access to the new plan using the planAuth middleware. Also make changes in the frontend code to use the new plan.
If you have more than one paid plan, you may need to handle the plan upgrade (switching between plans) in the frontend and backend. Becuase each plan according to stripe will be treated as a new product and upgrading to a new plan should mean cancelling the old plan and creating a new one, but this won't be handled automatically and that may cause issues. In other words each plan will trigger webhooks and cause unexpected behavior.

Start simple to speed up your product launch, and then add more plans later if needed.

Best Practices

• Require Authentication First: Always use authenticateJWT before planAuth to ensure the user is logged in before checking their subscription status.
• Start Simple: Consider beginning with one-time payments which are simpler to implement and manage. This works well for digital products, courses, or tools that don't have significant ongoing server costs.
• Clear Upgrades: Provide clear upgrade paths when users hit paywall restrictions.
• Graceful Failures: When users try to access premium features without the right plan, show helpful messages rather than generic errors.
• Test Payment Flows: Thoroughly test the complete payment and access control flow using Stripe's test mode.

With ZapStart's payment system, you can have subscription or one-time payment features up and running in minutes instead of weeks. Let us see your app in action!