Skip to main content
This guide walks you through cloning the project, configuring your Stripe account, and running the full subscription flow end to end.

​
Prerequisites

Before you begin, make sure you have the following:
  • Node.js 20 or later — the app uses React Router v7, which requires Node 20+
  • A Stripe account — sign up at stripe.com if you don’t have one
  • Stripe CLI — used to forward webhooks to your local server during development
Install the Stripe CLI with brew install stripe/stripe-cli/stripe on macOS, or follow the official installation guide for Linux and Windows.

​
Setup

1

Clone the repository

Clone the project and move into the directory:
git clone https://github.com/Tsirimaholy/stripe-payment.git
cd stripe-payment
npm install
2

Set environment variables

Create a .env file in the project root and set your Stripe secret key:
.env
STRIPE_SECRET_KEY=sk_test_...
Never commit your .env file or expose your secret key publicly. Use test-mode keys (prefixed with sk_test_) during development — they are safe to use and will not charge real cards.
You can find your API keys in the Stripe Dashboard under Developers → API keys.
3

Start the Stripe CLI webhook listener

In a separate terminal, authenticate the Stripe CLI and forward webhook events to your local server:
stripe login
stripe listen --forward-to localhost:5173/webhook
The CLI will print a webhook signing secret that starts with whsec_. Copy this value — you will need it in your configuration.
Keep this terminal running while you develop. The CLI forwards Stripe billing events (such as invoice.paid and invoice.payment_failed) to your local app.
4

Run the development server

Start the app:
npm run dev
The app runs at http://localhost:5173. The dev server supports hot module replacement, so changes to your files are reflected instantly.

​
User flow walkthrough

Once the app is running, follow this flow to test the full subscription experience:
1

Register an account

The home route (/) redirects automatically to /register. Enter your email address to create a Stripe customer account. No password is required — the app uses a session cookie to keep you logged in.
2

Choose a plan

After registration you are redirected to /prices, which lists the available subscription plans fetched from your Stripe account. Each plan shows its name, price, and billing interval.
If no plans appear, make sure you have created products and prices in your Stripe Dashboard. The app reads prices directly from the Stripe API using your secret key.
3

Subscribe

Select a plan to proceed to /subscribe. The subscribe page renders a Stripe Elements card form (CardElement). Enter a test card number to complete the subscription:
Card numberScenario
4242 4242 4242 4242Successful payment, no authentication required
4000 0025 0000 3155Requires SCA (3D Secure) authentication
Use any future expiry date, any 3-digit CVC, and any billing postal code.
Use the SCA card (4000 0025 0000 3155) to test that your webhook handler correctly activates the subscription after the authentication challenge is completed.
4

View your account

After a successful payment you are redirected to /account, which displays your active subscription, plan details, and renewal date. This data is retrieved from Stripe using the customer ID stored in your session.

​
Available scripts

ScriptCommandDescription
Development servernpm run devStarts the React Router dev server with HMR at localhost:5173
Production buildnpm run buildCompiles the app to ./build/
Production servernpm run startServes the production build using react-router-serve

​
Next steps

Configuration

Review all environment variables, session settings, and Stripe webhook configuration.

Registration

Learn how user accounts are created and stored in the session.

Plans

Understand how subscription plans are fetched from the Stripe API.

Webhooks

See how the app handles Stripe webhook events to activate subscriptions.

Build docs developers (and LLMs) love

Get started for freeTalk to us