Flat-rate

Payment Structure

If you're using the Vercel Monorepo template, the @workspace-apps/web app defines a flat-rate subscription plan out of the box.

Payments are structured as follows:

1. Free trial for 7 days
2. Paid subscription for fixed price per month
   • e.g. $10/month

Note that if you need to change the pricing structure (e.g. add another tier), you will need to make revisions to the @workspace-apps/web app in the following locations:

1. /apps/web/src/server/router/payment/router.ts.
2. /apps/web/src/server/router/plans/router.ts.

Setup

Create a new Stripe account and activate payments.

Business settings

Set up your business details so that you can start accepting payments.

1. Go to the Settings of the Stripe dashboard
2. Click on the Business section.
3. Click on the Account details tab and fill out the form as needed.
4. Click on the Business details tab and fill out the form as needed.
   • You can do this later when you need to start accepting payments (i.e. are ready to switch off Stripe's test mode).
5. Click on the Branding tab, and add your icon, logo, and colors.
6. Click on the Customer emails tab and enable emails "Successful payments" and "Refunds".

Payment settings

Recommendations to avoid potential abuse and fraud.

1. Go back to the Settings page.
2. Click on the Payments section.
3. Click on the Checkout and Payment Links tab, and enable "Limit customers to 1 subscription".
   • This will help prevent potential race conditions, where users might subscribe multiple times on accident.
4. Click on the Payment methods tab, and enable only the payment methods you want to offer.
   • We recommend disabling "Cash App Pay" to mitigate abuse and fraud. Many customers using it tend to cancel transactions.

Billing settings

Recommendations for avoiding failed payments.

1. Go back to the Settings page.
2. Click on the Billing section.
3. Click on the Subscriptions and emails tab.
4. Enable the following Customer emails:
   • Send a reminder email 7 days before a free trial ends
   • Send emails about upcoming renewals
   • Send emails about expiring cards
   • Send emails when card payments fail
   • Send emails when bank debit payments fail
5. Within the "Payment method updates" section, select "Link to a Stripe-hosted page"
6. Within the "Subscription management" section, select "Include a link for customers to manage their subscriptions"
7. In the "Manage free trial messaging" section, enable the "Statement descriptor" option.

API keys

Connect your Stripe account to your project.

1. Go to the API keys page. You can find this by clicking on the "Developers" link at the bottom of the left sidebar.

2. Create a "Secret key", and copy values for STRIPE_SECRET_KEY and STRIPE_PUBLISHABLE_KEY.

3. Add these values to your .env file in /apps/web/.env.

   STRIPE_SECRET_KEY="sk_test_..."
   STRIPE_PUBLISHABLE_KEY="pk_test_..."

4. Go to the Webhooks page. You can find this by clicking on the "Developers" link at the bottom of the left sidebar.

5. Click on "Add destination" and set the "Endpoint URL" to point to a URL that you want to receive webhooks from Stripe.

   • Note that if you are running the project locally, you will need to tunnel your selected Endpoint URL to your local machine. This is because Stripe is unable to access localhost origins.

6. Enable the following events:

   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.deleted
   • customer.subscription.paused
   • customer.subscription.pending_update_applied
   • customer.subscription.pending_update_expired
   • customer.subscription.resumed
   • customer.subscription.trial_will_end
   • customer.subscription.updated
   • invoice.marked_uncollectible
   • invoice.paid
   • invoice.payment_failed
   • invoice.payment_succeeded

7. Click on "Create destination", and copy the "Signing secret" value.

8. Add this value to your .env file in /apps/web/.env as STRIPE_WEBHOOK_SECRET.

   STRIPE_WEBHOOK_SECRET="whsec_..."

Product and prices

Create your product and prices to offer to your customers.

1. Go to the Products catalog page.

2. Click on "Create product" and fill out the name, description and image.

3. In the pricing section of the product

   • Ensure "Recurring" is selected.
   • Select a "Monthly" billing period, and set the price to your desired price.
   • Click "Add product" to finish creating the product.

4. Copy the "Product ID" and "Price ID" and add them to your .env file at /apps/web/.env

   STRIPE_PRICE_ID: "price_...",
   STRIPE_PRODUCT_ID: "prod_...",

Set Product metadata

We assume that you may want to potentially use the same Stripe business account for multiple products, each with different Stripe webhooks and settings. Unfortunately, Stripe does not allow partitioning webhooks by product, so we use Stripe metadata to differentiate between products.

1. On your newly created product, click on the "Edit" button within the "Metadata" section.
   • Create a key-value pair with the key appId and the value of your appId that you have chosen for your project in /packages/configs/appConfig.js under stripe.appId.
2. Click on your flat-rate price, and add the same appId key-value pair to the "Metadata" section.