1. Что это и зачем нужна

Stripe — это ведущая платёжная платформа, которая позволяет интернет-магазинам, SaaS-сервисам и любым другим веб-приложениям принимать платежи от клиентов по всему миру. Официальная библиотека stripe для Node.js предоставляет разработчикам полный набор инструментов для интеграции платёжного API Stripe в серверную часть приложения. Она абстрагирует сложность прямых HTTP-запросов к API Stripe, предлагая удобный, типизированный и предсказуемый интерфейс на JavaScript.

Зачем нужна эта библиотека? В современной веб-разработке безопасная обработка платежей — одна из самых критичных задач. Stripe берёт на себя соблюдение стандартов PCI DSS, обработку чувствительных данных (номера карт, CVV) и управление сложными сценариями (подписки, возвраты, споры). Библиотека для Node.js позволяет легко создавать платёжные формы, управлять клиентами, создавать подписки, обрабатывать вебхуки и генерировать отчёты — и всё это с использованием асинхронного кода на основе промисов.

Благодаря этой библиотеке вы можете сосредоточиться на бизнес-логике вашего приложения, а не на низкоуровневых деталях платёжных протоколов. Она идеально подходит для Node.js-приложений, работающих на Express, Koa, Fastify или любом другом фреймворке. Библиотека активно поддерживается компанией Stripe, регулярно обновляется и имеет огромное сообщество.

2. Установка

Для установки библиотеки Stripe в ваш проект Node.js используйте менеджер пакетов npm или yarn. Выполните одну из следующих команд в корневой директории проекта:

# Используя npm
npm install stripe

# Используя yarn
yarn add stripe

После установки вы можете импортировать библиотеку в свой код:

// Современный синтаксис (ES Modules)
import Stripe from 'stripe';

// Или CommonJS (Node.js по умолчанию)
const Stripe = require('stripe');

Важно: Для работы с библиотекой вам понадобится секретный ключ (sk_test_... для тестового режима или sk_live_... для продакшена). Ключ можно получить в панели управления Stripe.

3. Быстрый старт — минимальный рабочий пример

Давайте создадим простой скрипт, который создаёт платёжное намерение (PaymentIntent) — это стандартный способ принять разовый платёж.

// Импортируем библиотеку
const Stripe = require('stripe');
// Инициализируем с секретным ключом (замените на ваш тестовый ключ)
const stripe = Stripe('sk_test_XXXXXXXXXXXXXXXXXXXXXXXX');

async function createPayment() {
    try {
        // Создаём PaymentIntent на сумму 2000 центов (20 USD)
        const paymentIntent = await stripe.paymentIntents.create({
            amount: 2000,
            currency: 'usd',
            // Описание платежа (опционально)
            description: 'Тестовый платёж из Node.js',
            // Автоматически захватывать платеж (true) или только авторизовать (false)
            capture_method: 'automatic',
        });

        console.log('PaymentIntent успешно создан:');
        console.log(`ID: ${paymentIntent.id}`);
        console.log(`Статус: ${paymentIntent.status}`);
        console.log(`Сумма: ${paymentIntent.amount} ${paymentIntent.currency.toUpperCase()}`);
    } catch (error) {
        console.error('Ошибка при создании PaymentIntent:', error.message);
    }
}

createPayment();

Этот код создаёт платёжное намерение. На фронтенде вам нужно будет использовать client_secret из объекта paymentIntent, чтобы подтвердить платёж с помощью Stripe Elements или Stripe.js.

4. Основные методы/функции/классы

Библиотека Stripe для Node.js предоставляет множество сервисов (например, stripe.customers, stripe.paymentIntents). Ниже приведены 8 ключевых методов с примерами.

const paymentIntent = await stripe.paymentIntents.create({
    amount: 1500, // 15.00 USD
    currency: 'eur',
    payment_method_types: ['card'],
    metadata: { order_id: '12345' }
});
console.log(paymentIntent.id); // pi_xxx

const paymentIntent = await stripe.paymentIntents.retrieve('pi_xxx');
console.log(`Статус: ${paymentIntent.status}`); // 'succeeded', 'requires_payment_method' и т.д.

const customer = await stripe.customers.create({
    email: 'user@example.com',
    name: 'Иван Иванов',
    description: 'VIP клиент'
});
console.log(customer.id); // cus_xxx

const subscription = await stripe.subscriptions.create({
    customer: 'cus_xxx',
    items: [{ price: 'price_xxx' }], // Price ID из каталога
    trial_period_days: 7, // Бесплатный пробный период
});
console.log(`Подписка создана: ${subscription.id}`);

const product = await stripe.products.create({
    name: 'Премиум-доступ',
    description: 'Доступ ко всем функциям на 1 месяц',
    active: true,
});
console.log(`Товар создан: ${product.id}`); // prod_xxx

const price = await stripe.prices.create({
    product: 'prod_xxx',
    unit_amount: 999, // 9.99 USD
    currency: 'usd',
    recurring: { interval: 'month' }, // Для подписки
});
console.log(`Цена создана: ${price.id}`); // price_xxx

const session = await stripe.checkout.sessions.create({
    success_url: 'https://example.com/success',
    cancel_url: 'https://example.com/cancel',
    line_items: [{ price: 'price_xxx', quantity: 1 }],
    mode: 'payment', // или 'subscription'
});
console.log(`URL для оплаты: ${session.url}`); // Переадресуйте пользователя сюда

// Пример в Express
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
    const sig = req.headers['stripe-signature'];
    let event;
    try {
        event = stripe.webhooks.constructEvent(req.body, sig, 'whsec_xxx');
    } catch (err) {
        return res.status(400).send(`Webhook Error: ${err.message}`);
    }
    // Обработка события
    if (event.type === 'payment_intent.succeeded') {
        console.log('Платёж успешен!');
    }
    res.json({received: true});
});

5. Реальный практический пример (100-200 строк кода)

В этом примере мы создадим простой REST API на Express, который принимает платежи через Stripe Checkout, обрабатывает вебхуки и управляет подписками.

const express = require('express');
const Stripe = require('stripe');
const app = express();

// Инициализация Stripe
const stripe = Stripe(process.env.STRIPE_SECRET_KEY);

// Middleware для парсинга JSON (для API)
app.use(express.json());

// Middleware для парсинга raw body (для вебхуков)
app.use('/webhook', express.raw({ type: 'application/json' }));

// --- Эндпоинты API ---

// 1. Создание сессии Checkout для разового платежа
app.post('/api/create-checkout-session', async (req, res) => {
    try {
        const { priceId, customerId } = req.body; // priceId и опционально customerId
        const session = await stripe.checkout.sessions.create({
            customer: customerId || undefined,
            line_items: [{ price: priceId, quantity: 1 }],
            mode: 'payment',
            success_url: `${process.env.DOMAIN}/success?session_id={CHECKOUT_SESSION_ID}`,
            cancel_url: `${process.env.DOMAIN}/cancel`,
        });
        res.json({ url: session.url });
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

// 2. Создание подписки (создаём клиента, если его нет)
app.post('/api/create-subscription', async (req, res) => {
    try {
        const { email, priceId } = req.body;
        // Создаём или находим клиента (упрощённо)
        const customer = await stripe.customers.create({ email });
        const subscription = await stripe.subscriptions.create({
            customer: customer.id,
            items: [{ price: priceId }],
            payment_behavior: 'default_incomplete', // Не списывать сразу
            expand: ['latest_invoice.payment_intent'],
        });
        res.json({
            subscriptionId: subscription.id,
            clientSecret: subscription.latest_invoice.payment_intent.client_secret,
        });
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

// 3. Получение информации о клиенте
app.get('/api/customer/:id', async (req, res) => {
    try {
        const customer = await stripe.customers.retrieve(req.params.id);
        res.json(customer);
    } catch (error) {
        res.status(404).json({ error: 'Customer not found' });
    }
});

// --- Вебхук ---
app.post('/webhook', async (req, res) => {
    const sig = req.headers['stripe-signature'];
    let event;
    try {
        event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET);
    } catch (err) {
        console.error('Webhook signature verification failed.', err.message);
        return res.status(400).send(`Webhook Error: ${err.message}`);
    }

    // Обрабатываем события
    switch (event.type) {
        case 'checkout.session.completed':
            const session = event.data.object;
            console.log(`Плат