Stripe Checkout в Next.js — интеграция шаг за шагом

Кратко: эта статья пошагово объясняет, как добавить Stripe Checkout в приложение Next.js: регистрация в Stripe, получение API-ключей, серверный API-роут для создания сессии, фронтенд-компонент для перенаправления на Checkout, обработка success/cancel страниц и варианты кастомизации. Включены чек-листы, сценарии отказа и рекомендации по безопасности.

Человек держит дебетовую карту

Введение

Stripe — платформа для приёма онлайн‑платежей. Она предоставляет готовую страницу Checkout, инструменты для работы с подписками, выставления счетов, локальными методами оплаты, предотвращения мошенничества и гибкой настройки внешнего вида. Для большинства проектов использование Stripe сокращает время разработки и помогает соответствовать требованиям PCI.

Кому полезна инструкция: фронтенд‑ и бэкенд‑разработчикам, создающим e‑commerce на Next.js и желающим быстро подключить безопасную оплату.

Важно: в примерах используется режим тестирования (test mode). Перед выходом в продакшен активируйте аккаунт и поменяйте ключи на live.

Основные термины (одной строкой)

Checkout Session: объект Stripe, который управляет одноразовой или подписной оплатой и перенаправлением пользователя.
Publishable key: публичный ключ для клиента (NEXTPUBLIC*), безопасен для браузера.
Secret key: секретный ключ для сервера, храните в .env и не публикуйте.

Что понадобится (проверить перед началом)

Next.js проект (npm/yarn).
Stripe аккаунт (test mode для разработки).
Доступ к средам переменных окружения (.env.local).
Базовые знания JavaScript/React и серверных API в Next.js.

1. Создание аккаунта Stripe и получение API‑ключей

Откройте сайт Stripe и нажмите кнопку “Зарегистрироваться” (Sign up).
Введите email, имя, страну и пароль; нажмите «Создать аккаунт» (Create account).
Подтвердите email согласно инструкции в письме от Stripe.
На Dashboard нажмите “Activate payments” и ответьте на вопросы (название бизнеса, адрес, банковские реквизиты). Для разработки оставайтесь в test mode.
Перейдите на вкладку “Developers” → “API keys” и скопируйте Publishable key и Secret key. Поместите их в файл .env.local вашего проекта.

Пример .env.local (не коммитить в git):

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...

Важно: SECRET_KEY должен быть доступен только на сервере.

2. Установка npm пакетов

Установите серверную библиотеку Stripe и клиентскую утилиту для загрузки Stripe.js:

npm install stripe
npm install @stripe/stripe-js
npm install axios

(axios используется в примере для отправки запроса к API‑роуту).

3. Серверный API‑роут: создание Checkout Session

В папке /pages/api создайте файл checkout-session.js. Инициализируйте Stripe с секретным ключом из переменных окружения:

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

export default async function handler(req, res) {
  if (req.method === 'POST') {
    const { cart } = req.body;

    try {
      const session = await stripe.checkout.sessions.create({
        payment_method_types: ['card'],
        line_items: [
          ...cart
        ],
        mode: 'payment',
        success_url: `${req.headers.origin}/success`,
        cancel_url: `${req.headers.origin}/cancel`,
      });

      res.status(200).json({ id: session.id, url: session.url });
    } catch (err) {
      res.status(err.statusCode || 500).json({ error: err.message });
    }
  } else {
    res.setHeader('Allow', 'POST');
    res.status(405).end('Method Not Allowed');
  }
}

Пояснения к полям:

payment_method_types: какие методы оплаты разрешены (например, [‘card’, ‘alipay’]). Список в документации Stripe.
line_items: массив товаров; каждый элемент — описание товара/цен и количества. В простом случае можно передать объект из корзины.
mode: ‘payment’ для одноразовой оплаты, ‘subscription’ для подписок.
success_url / cancel_url: куда перенаправить пользователя.

Пример объекта line_item (рекомендуемая структура):

{
  price_data: {
    currency: 'usd',
    product_data: { name: 'T‑shirt' },
    unit_amount: 2000
  },
  quantity: 1
}

Совет: используйте price_id (из Stripe Dashboard) для повторного использования цен вместо передачи price_data каждый раз.

4. Фронтенд: компонент Checkout

Создайте /components/checkout.js и подключите загрузчик Stripe.js:

import { loadStripe } from '@stripe/stripe-js';
import axios from 'axios';

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY);

export default function Checkout({ cart }) {
  const handleCheckout = async () => {
    try {
      const stripe = await stripePromise;

      const checkoutSession = await axios.post('/api/checkout-session', { cart });

      // Рекомендуемый способ: redirectToCheckout с sessionId или редирект на session.url
      if (checkoutSession.data.url) {
        window.location = checkoutSession.data.url;
        return;
      }

      const result = await stripe.redirectToCheckout({
        sessionId: checkoutSession.data.id,
      });

      if (result.error) {
        alert(result.error.message);
      }
    } catch (error) {
      console.error('Checkout error:', error);
    }
  };

  return (
    
      
    
  );
}

Примечание: Stripe рекомендует использовать session.url (HTTP 303 redirect) для надёжного перенаправления, особенно для SSR/CSR различий.

5. Обработка редиректов: страницы success и cancel

В /pages создайте success.js и cancel.js:

// pages/success.js
export default function Success() {
  return Оплата прошла успешно. Спасибо за покупку!;
}

// pages/cancel.js
export default function Cancel() {
  return Оплата была отменена или возникла ошибка.;
}

Можно добавить в success отображение информации о заказе, номера транзакции, отправку письма и т.д. Для получения полной информации о платеже используйте Stripe Webhooks (ниже указания).

6. Вебхуки (рекомендация)

Для автоматической обработки событий (успешная оплата, возврат, статус подписки) подключите Stripe Webhooks на сервере. Создайте защищённый роут, проверьте подпись событий с помощью STRIPE_WEBHOOK_SECRET и обрабатывайте события server‑side.

Пример проверки подписи (Node.js):

const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;

export default async function handler(req, res) {
  const sig = req.headers['stripe-signature'];
  let event;
  try {
    event = stripe.webhooks.constructEvent(req.rawBody, sig, endpointSecret);
  } catch (err) {
    res.status(400).send(`Webhook Error: ${err.message}`);
    return;
  }
  // handle event
}

Важно: Next.js требует правильной настройки body parsing для роутов webhooks (raw body).

7. Дополнительные настройки внешнего вида и локализации

Через Dashboard Stripe → Branding вы можете задать логотип, основной цвет, домен и язык страницы Checkout. В параметрах создания сессии можно указать preferred_locales для принудительного языка.

8. Безопасность и соответствие

Не храните секретные ключи в клиентском коде.
Используйте HTTPS в продакшене.
Проводите тесты на уязвимости цепочки платежей и проверяйте логирование ошибок.
Включите и проверяйте настройки PCI в Dashboard (Stripe облегчает соответствие).

Когда этот подход не подходит (контрпримеры)

Если вы нуждаетесь в полностью кастомной UX с контролем полей ввода карты и сохранением карт на стороне клиента — возможно, придётся реализовать Elements или собрать собственный платежный модуль.
Большие маркетплейсы с разделением комиссий между множеством получателей могут требовать Connect или кастомную архитектуру, а не простую Checkout сессии.
Проекты, где политика безопасности запрещает внешние перенаправления — нужна серверная интеграция с Elements.

Альтернативные подходы

Stripe Elements — для встраивания форм ввода карты прямо на сайт.
PayPal Checkout или Braintree — альтернативы для регионов/бизнес‑моделей.
Adyen, Mollie, или локальные PSP — если нужен специфичный локальный метод оплаты.

Руководство по интеграции — мини‑методология (шаги)

Подготовка: зарегистрировать Stripe, определить методы оплаты и валюты.
Настройка окружения: добавить ключи в .env.local.
Сервер: реализовать API‑роут для создания сессий и вебхуков.
Фронтенд: компонент для вызова API и перенаправления на Checkout.
Тестирование: пройти тестовые платежи, проверить webhooks и страницы success/cancel.
Продакшен: сменить ключи на live, активировать аккаунт и проверить логирование.

Ролевые чек‑листы

Разработчик фронтенда:
- Подключить loadStripe с публичным ключом.
- Реализовать компонент кнопки Checkout.
- Обработать ошибки клиента и состояние загрузки.
Разработчик бэкенда:
- Хранить STRIPE_SECRET_KEY в безопасном месте.
- Создать API‑роуты и обработчики webhooks.
- Логировать ошибки и проводить ретраи в случае временных сбоев.
Продукт/QA:
- Пройти тестовые транзакции (успешные / отмены / ошибка карты).
- Проверить различные методы оплаты и валюты.

Критерии приёмки

Кнопка “Оформить заказ” запускает создание сессии и перенаправляет на Stripe Checkout.
После успешной оплаты пользователь попадает на /success и получает подтверждение.
В случае отмены — на /cancel с возможностью повторить оплату.
Webhook обрабатывается сервером и обновляет статус заказа в БД.
Секретные ключи не попадают в клиентский бандл.

Сниппет: шаблон тела запроса для line_items

const cart = [
  {
    price_data: {
      currency: 'usd',
      product_data: { name: 'T-shirt' },
      unit_amount: 2000
    },
    quantity: 2
  }
];

Или с использованием price_id:

const cart = [
  { price: 'price_1Hh1XYZ...', quantity: 2 }
];

Возможные ошибки и пути их решения

400 Bad Request — проверьте структуру line_items и правильность unit_amount (в центах).
401 Unauthorized — проверьте, что SECRET_KEY корректен и доступен на сервере.
Webhook signature verification failed — убедитесь, что используете raw body и правильный STRIPE_WEBHOOK_SECRET.

Матрица рисков и смягчения

Утечка секретных ключей → хранить в CI/CD секретах и .env, ограничить доступ.
Ошибки в редиректах → логирование и fallback на страницу с инструкциями по оплате.
Проблемы с локальными методами оплаты → тестирование региональных методов и документация для пользователей.

Короткая релиз‑анонс (для маркетинга, 100–200 слов)

Подключили Stripe Checkout: теперь пользователи могут быстро и безопасно оплачивать заказы на нашем сайте. Мы интегрировали защищённую платежную форму Stripe Checkout, поддерживающую карты, Apple Pay/Google Pay и локальные способы оплаты. Процесс оформления прост: пользователь нажимает “Оформить заказ”, проходит через защищённую страницу оплаты и автоматически получает подтверждение на сайте. Для команды это означает меньше времени на поддержку PCI и больше возможностей по настройке подписок, скидок и международных платежей.

Ключевые рекомендации перед запуском в продакшен

Проведите полную проверку в test mode.
Активируйте аккаунт Stripe и замените ключи на live.
Настройте и проверьте webhooks.
Документируйте потоки ошибок и поведение страницы success.

Сводка

Использование Stripe Checkout в Next.js — один из самых быстрых и безопасных способов начать принимать онлайн‑платежи. Решение минимизирует объём работы с платёжными данными и упрощает соответствие требованиям безопасности. В статье приведены рабочие примеры кода, чек‑листы, рекомендации по тестированию и список типичных проблем с путями их решения.