Payment Flow Scenarios

in this section, we will outlines the key components and functions involved in the payment flow architecture of your SAAS boilerplate. It covers essential concepts and details two major payment flow scenarios.

Important Definitions and Functions

Stripe Webhook

A Stripe webhook is a mechanism for Stripe to notify your server about events in your Stripe account, such as successful payments or subscription updates. It sends an HTTP POST request to a specified URL, allowing you to automate responses to these events.

SubscriptionId

• Context: Recurring payments (subscriptions).

• Description: Represents the ID of the subscription object received with the subscription event. This ID is stored in our database to keep track of all payments.

PaymentIntentId

• Context: One-time payments (lifetime subscriptions).

• Description: Represents the ID of the payment intent object received with the triggered Stripe event. This ID is stored in our database to keep track of all one-time payments.

ClientConversion Table

• Purpose: Keeps track of client conversions (sales) when clients subscribe to or upgrade to a paid plan.

• Usage: Useful for the Admin dashboard to show sales statistics.

PreClientPlan Table

• Purpose: Temporarily stores client plan data (with a specific token) for users who have subscribed to a paid plan without having an account beforehand (missing userId).

• Function: Once the ClientPlan record is set up, the PreClientPlan is removed.

Important Functions

GeneratePreClientPlan()

Location: actions/auth/tokens.ts Description: Responsible for creating a PreClientPlan table.

sendAccountCreationLink()

Location: app/api/stripe-webhook/route.ts Description: Sends account creation link emails to users who have subscribed to a paid plan without having an account beforehand (missing userId). Clients will use a link in the format /auth/sign-up?token=token_code to create their account and set up their ClientPlan record using the specific token generated.

HandleAfterSubscriptionTasks()

Location: app/api/stripe-webhook/route.ts Purpose: Handles various post-subscription tasks:

• Sends receipt email to the client.

• Sends new subscription email to the admin.

• Adds a new conversion record (useful for the admin dashboard and statistics).

• Handles affiliate commissions if required via the processAffiliateCommission() function.

setupUserAccount()

Location: actions/setup-account.ts Purpose: Sets up the user account by:

• Assigning the user role.

• Creating the ClientPlan record.

• Calling handleAfterSignupTasks().

handleAfterSignupTasks()

Location: actions/setup-account.ts Purpose: Handles additional tasks post-signup:

• Adds the email to the audience list (on Resend).

• Sends a welcome email to the client.

• Sets up the NotificationPreferences table.

• Assigns a country to the user.

• Adds contact to the Affiliates database (if it’s an affiliate).

• Sends a welcome email to the affiliate (if applicable).

We have two major payment flow scenarios that culminate in creating a user account with a CLIENT role and an associated ClientPlan table populated with appropriate data.