How to Add Stripe to Next.js: A Comprehensive Guide

Introduction

Integrating a payment solution is crucial for any SaaS application, and Stripe stands out as one of the best options available. It offers a robust and secure platform that allows developers to handle payments with ease. In this guide, we’ll walk through the process of integrating Stripe into a Next.js application, ensuring you have a comprehensive understanding of how to set up payment processing efficiently.

Setting Up Your Next.js Project

Creating a New Next.js Application

If you haven't already created a Next.js application, you can do so by running the following command in your terminal:

npx create-next-app@latest my-saas-app
cd my-saas-app

This command creates a new directory named my-saas-app with a fresh Next.js application set up.

Installing Required Dependencies

To work with Stripe, you'll need to install the Stripe SDK. Run the following command:

npm install stripe

For the frontend, we’ll also need the Stripe.js library. To include it, you can add it directly to your project using a script tag or install it via npm:

npm install @stripe/react-stripe-js @stripe/stripe-js

Configuring TypeScript (if applicable)

If you're using TypeScript, ensure that your tsconfig.json is set up correctly. It should look something like this:

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "commonjs",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

Creating a Stripe Account

Signing Up for Stripe

To get started, you'll need an account with Stripe. Go to the Stripe sign-up page and create your account.

Accessing API Keys

Once your account is set up, navigate to the Developers section in the Stripe dashboard. Here, you'll find your Publishable Key and Secret Key under the API keys section. Make sure to keep your secret key safe, as it is sensitive information.

Understanding Stripe Dashboard Features

Familiarize yourself with the Stripe dashboard features, including the ability to manage payments, view your transaction history, and handle disputes. This is crucial for monitoring your application's financial health.

Installing Stripe SDK

Adding Stripe to Your Project

We already installed the Stripe SDK in the previous steps. Now, let’s set up our environment variables to securely store your API keys.

Configuring Environment Variables

Create a .env.local file in your project root and add your Stripe API keys:

STRIPE_SECRET_KEY=your_secret_key
STRIPE_PUBLISHABLE_KEY=your_publishable_key

Make sure to replace your_secret_key and your_publishable_key with the actual keys from your Stripe dashboard.

Setting Up API Routes

Next, we'll create an API route for handling payments. Create a new file at pages/api/checkout_sessions.ts:

import { NextApiRequest, NextApiResponse } from 'next';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string, {
  apiVersion: '2022-08-01',
});

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'POST') {
    try {
      const session = await stripe.checkout.sessions.create({
        payment_method_types: ['card'],
        line_items: req.body.items,
        mode: 'payment',
        success_url: `${req.headers.origin}/success`,
        cancel_url: `${req.headers.origin}/cancel`,
      });
      res.status(200).json({ id: session.id });
    } catch (err) {
      res.status(500).json({ error: 'Internal Server Error' });
    }
  } else {
    res.setHeader('Allow', ['POST']);
    res.status(405).end(`Method ${req.method} Not Allowed`);
  }
}

This code sets up an API route that creates a new checkout session when a POST request is made.

Implementing Payment Processing

Creating a Checkout Session

To create a checkout session, you'll need to set up a function on the frontend to make a request to your API route. In a suitable component, implement the following:

const handleCheckout = async () => {
  const response = await fetch('/api/checkout_sessions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      items: [
        {
          price_data: {
            currency: 'usd',
            product_data: {
              name: 'Test Product',
            },
            unit_amount: 2000, // $20.00
          },
          quantity: 1,
        },
      ],
    }),
  });

  const session = await response.json();
  const stripe = await getStripe();
  await stripe.redirectToCheckout({ sessionId: session.id });
};

Handling Webhooks for Payment Events

Set up a webhook to listen for events from Stripe, such as successful payments. Create another API route at pages/api/webhooks.ts:

import { NextApiRequest, NextApiResponse } from 'next';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string, {
  apiVersion: '2022-08-01',
});

export const config = {
  api: {
    bodyParser: false,
  },
};

const webhook = async (req: NextApiRequest, res: NextApiResponse) => {
  const buf = await buffer(req);
  const signature = req.headers['stripe-signature'];

  let event;

  try {
    event = stripe.webhooks.constructEvent(buf, signature, process.env.STRIPE_WEBHOOK_SECRET as string);
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Handle successful payment here
  if (event.type === 'checkout.session.completed') {
    const session = event.data.object;
    // Fulfill the purchase
  }

  res.json({ received: true });
};

export default webhook;

Redirecting Users After Payment

After the checkout session is created, users will be redirected to the success or cancel URL you defined earlier. Make sure to create pages at /success and /cancel to handle these routes.

Building the Frontend Payment Form

Using Stripe Elements for Secure Payments

For handling sensitive card details, utilize Stripe Elements. In your payment component, import the necessary components:

import { CardElement, useStripe, useElements } from '@stripe/react-stripe-js';

// Inside your component
const stripe = useStripe();
const elements = useElements();

const handleSubmit = async (event: React.FormEvent) => {
  event.preventDefault();

  if (!stripe || !elements) return;

  const cardElement = elements.getElement(CardElement);
  const { error, paymentMethod } = await stripe.createPaymentMethod({
    type: 'card',
    card: cardElement,
  });

  if (error) {
    console.error(error);
  } else {
    console.log('Received Stripe PaymentMethod:', paymentMethod);
  }
};

Validating User Input

Ensure you validate user inputs before submission. You can do this within the handleSubmit function, checking for any errors returned by Stripe.

Styling the Payment Form

You can style your payment form using CSS or any styling library of your choice. Here’s a quick example using basic CSS:

.card-input {
  border: 1px solid #ced4da;
  border-radius: 4px;
  padding: 10px;
  margin: 10px 0;
}

Testing Your Integration

Using Stripe Test Cards

Stripe provides several test card numbers that you can use to simulate transactions. Use these in your payment form to test different scenarios without real transactions.

Monitoring Transactions in the Dashboard

Check the Stripe dashboard to monitor your transactions. This will help you confirm that payments are being processed correctly.

Debugging Common Issues

Common issues might include incorrect API keys, misconfigured webhooks, or issues with the card details. Check the console logs in your application and the Stripe dashboard for any error messages.

Deploying Your Next.js Application

Preparing for Production

Before deploying, ensure your .env.local file is configured with production keys. Also, review your code to remove any debug statements and improve performance.

Configuring Stripe in Production

Make sure to set your production API keys in your hosting environment. If you're using Vercel, you can easily add them through the dashboard.

Deploying with Vercel or Other Hosting Services

Deploy your Next.js application using Vercel, which provides seamless integration. You can deploy by running:

vercel

Follow the prompts to complete the deployment process.

Conclusion

Recap of Key Steps

In this guide, we covered the essential steps to integrate Stripe into your Next.js application, including setting up your project, creating a Stripe account, implementing payment processing, and deploying your application.

Encouragement to Explore More Features

Don't stop here! Explore additional features offered by Stripe and consider implementing subscriptions, coupons, and more to enhance your SaaS application. Check out BuilderHack features for more insights.

Links to Further Resources

For further learning, explore our guides on Next.js and payment processing.

FAQ

What is Stripe and why should I use it in my Next.js application?

Stripe is a leading payment processing platform that allows businesses to accept payments online and in mobile apps. Its flexibility and robust features make it ideal for SaaS applications.

Can I test Stripe integration without real money transactions?

Yes! Stripe provides a test mode with test card numbers that you can use to simulate transactions without real money.

How do I secure my Stripe API keys?

Always store your API keys in environment variables and never expose them in your frontend code. Use server-side code to handle sensitive operations.

What are the common errors when integrating Stripe with Next.js?

Common errors include incorrect API keys, misconfigured webhooks, and issues with the card details entered by users.

Where can I find more information on Next.js and payment processing?

Visit BuilderHack for a wealth of resources, including comparisons, pricing, and ideas for your next project.