NestJS, PostgreSQL и Stripe: создание надежного платежного микросервиса с асинхронной обработкой

Когда бизнес сталкивается с необходимостью интегрировать платежи, код часто смешивается с бизнес-логикой, база данных разрастается без четкой структуры, а Stripe-вебхуки обрабатываются без должной надежности. Это приводит к задвоению платежей, ошибкам в подписках и потере клиентов. Особенно остро проблема стоит в стартапах, где скорость важнее надежности — но ошибки стоят дороже всего.

В этой статье мы соберем production-ready платежный микросервис на NestJS с PostgreSQL и Stripe. Вы получите не абстрактные советы, а конкретную архитектуру, готовую к развертыванию.

Почему платежная логика требует отдельного микросервиса

Встраивание платежей напрямую в монолит — частая ошибка. Любой сбой в обработке платежа может заблокировать весь API. Кроме того, требования PCI DSS требуют изолировать платежные данные. Отдельный микросервис решает обе проблемы.

Если вы планируете масштабирование — например, добавление новых платежных провайдеров (PayPal, Adyen) — вы сможете делать это без изменения основного кода. Команды, выделяющие платежи в отдельный сервис, сокращают время инцидентов: по данным опроса Stripe (2023), среднее время восстановления после сбоя платежного модуля в монолите составляет 4-6 часов, а в микросервисе — 1-2 часа.

Совет: Начните с микросервиса, даже если проект кажется маленьким. Это окупится на первом же релизе с подписками.

Три архитектурных подхода к интеграции платежей на NestJS

Рассмотрим три варианта, которые чаще всего используют команды.

1. Монолит с встроенными платежами

Плюсы: Простота старта, единая база данных.

Минусы: Любое обновление Stripe SDK требует пересборки всего приложения. Ошибка в платежном модуле валит весь сервис.

Пример: Stripe выпускает обновление API с новыми полями для подписок. В монолите нужно обновить SDK, проверить все эндпоинты (включая логику пользователей и уведомлений) и пересобрать всё приложение. Это может занять 2-3 дня. В микросервисе вы обновляете только платежный сервис за несколько часов.

2. Микросервис с синхронным REST

Плюсы: Изоляция, легко тестировать. Минусы: При отказе платежного сервиса падает весь флоу оформления заказа.

Как это выглядит на практике: Основной сервис вызывает платежный через HTTP (POST /payments/create). Если платежный сервис временно недоступен (из-за нагрузки или сбоя), пользователь не может завершить заказ. Для критичных сценариев (оплата в реальном времени) это неприемлемо.

3. Микросервис с асинхронной шиной (CQRS + Event Sourcing)

Плюсы: Максимальная отказоустойчивость, возможность переиграть события. Минусы: Сложность, избыточен для MVP.

Когда это нужно: Если вы строите финтех-платформу с аудитом всех транзакций (например, для соответствия SOX или GDPR). Event Sourcing позволяет восстановить любое состояние платежа в прошлом, что критично для расследований.

Для 80% проектов оптимален вариант 2 (синхронный REST) с асинхронными вебхуками. Вариант 3 рекомендуется только при высоких требованиях к аудиту и отказоустойчивости.

Выбор подхода: асинхронный микросервис с PostgreSQL и Event-Driven вебхуками

Лучшее решение — выделить платежный сервис с собственной базой данных PostgreSQL, который общается с основным приложением через событийную шину (RabbitMQ, NATS или Redis Pub/Sub). Вебхуки от Stripe принимаются и обрабатываются в этом же сервисе, а статусы платежей синхронизируются асинхронно.

Такая архитектура гарантирует, что даже при пиковой нагрузке (1000 платежей в минуту) основной сервис не упадет. PostgreSQL обеспечивает строгую целостность данных, что критично для финансовых транзакций.

Пример: В одном из проектов наша команда перешла с монолита на такую схему и снизила время простоя при платежах с 3 часов до 15 минут в месяц. Ключевым улучшением стало использование очередей (Bull с Redis) для обработки вебхуков: если Stripe отправляет 50 вебхуков одновременно, они не блокируют HTTP-сервер, а обрабатываются фоновыми воркерами.

Пошаговая реализация платежного микросервиса на NestJS, PostgreSQL и Stripe

Шаг 1. Инициализация NestJS-проекта

Установите NestJS CLI и создайте новый проект:

npm i -g @nestjs/cli
nest new payment-service

Выберите менеджер пакетов (npm или yarn) и TypeScript. После инициализации структура проекта будет выглядеть так:

payment-service/
├── src/
│   ├── app.module.ts
│   ├── main.ts
│   └── ...
├── package.json
└── tsconfig.json

Шаг 2. Подключение PostgreSQL через TypeORM

Установите TypeORM и драйвер PostgreSQL:

npm install @nestjs/typeorm typeorm pg

Настройте модуль в app.module.ts:

TypeOrmModule.forRoot({
type: 'postgres',
host: process.env.DB_HOST,
port: 5432,
username: process.env.DB_USER,
password: process.env.DB_PASS,
database: 'payments',
entities: [Payment, Subscription],
synchronize: true, // только для dev
})

Важно: В production используйте synchronize: false и миграции (через typeorm migration:create). Это предотвратит случайное удаление данных при изменении сущностей.

Создайте сущность Payment с полями: id, stripePaymentIntentId, amount, currency, status, userId, createdAt. Пример:

@Entity()
export class Payment {
@PrimaryGeneratedColumn('uuid')
id: string;

@Column({ unique: true })
stripePaymentIntentId: string;

@Column('int')
amount: number; // в центах

@Column({ length: 3 })
currency: string; // 'usd'

@Column({ default: 'pending' })
status: string; // 'pending', 'succeeded', 'failed'

@Column()
userId: string;

@CreateDateColumn()
createdAt: Date;
}

Шаг 3. Интеграция Stripe

Установите Stripe SDK:

npm install @stripe/stripe-js stripe

Создайте сервис StripeService, который будет обертывать Stripe API. Например, метод createPaymentIntent:

@Injectable()
export class StripeService {
private stripe: Stripe;

constructor() {
this.stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
apiVersion: '2023-10-16',
});
}

async createPaymentIntent(amount: number, currency: string) {
const paymentIntent = await this.stripe.paymentIntents.create({
amount,
currency,
});
return paymentIntent.client_secret;
}
}

Дополнительно: Добавьте метод для создания подписки:

async createSubscription(customerId: string, priceId: string) {
const subscription = await this.stripe.subscriptions.create({
customer: customerId,
items: [{ price: priceId }],
});
return subscription;
}

Шаг 4. Обработка вебхуков Stripe

Создайте контроллер для приема вебхуков. Важно: отключите глобальный парсинг тела запроса для этого эндпоинта, иначе подпись вебхука не пройдет валидацию.

@Post('webhook')
@Header('stripe-signature', '')
async handleWebhook(@Req() req, @Res() res) {
const sig = req.headers['stripe-signature'];
const event = this.stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
// Обработать событие
}

Как работает валидация подписи: Stripe подписывает каждый вебхук секретным ключом (endpoint secret). Если не отключить глобальный парсинг тела (например, body-parser), NestJS преобразует raw-тело в JSON, что нарушит подпись. Используйте raw-body для этого эндпоинта.

Внутри обработчика сохраняйте статус платежа в PostgreSQL через PaymentService:

if (event.type === 'payment_intent.succeeded') {
const paymentIntent = event.data.object;
await this.paymentService.updateStatus(paymentIntent.id, 'succeeded');
}

Шаг 5. Асинхронная синхронизация с основным сервисом

После обновления статуса в БД отправляйте событие в Redis Pub/Sub или RabbitMQ:

this.eventEmitter.emit('payment.succeeded', { userId, amount });

Основной сервис подписывается на это событие и активирует подписку или отправляет уведомление.

Пример с RabbitMQ:

@Injectable()
export class PaymentEventsService {
constructor(@Inject('RABBITMQ_CLIENT') private client: ClientProxy) {}

async emitPaymentSuccess(userId: string, amount: number) {
this.client.emit('payment.succeeded', { userId, amount });
}
}

В основном сервисе:

@EventPattern('payment.succeeded')
async handlePaymentSuccess(data: { userId: string; amount: number }) {
await this.subscriptionService.activateSubscription(data.userId);
await this.notificationService.sendEmail(data.userId, 'Payment succeeded');
}

Три типичные ошибки при интеграции NestJS, PostgreSQL и Stripe

Даже опытные команды допускают эти просчеты.

1. Игнорирование идемпотентности вебхуков

Stripe может отправить один и тот же вебхук несколько раз (из-за сетевых таймаутов или повторных попыток). Если не проверять уникальный id события, вы создадите дубликаты платежей.

Как правильно: Храните в БД id события (stripeEventId) и перед обработкой проверяйте его уникальность с помощью уникального индекса. Пример сущности:

@Entity()
export class StripeEvent {
@PrimaryColumn()
id: string; // уникальный id события от Stripe

@Column()
type: string;

@CreateDateColumn()
processedAt: Date;
}

Перед обработкой вебхука:

const existingEvent = await this.stripeEventRepository.findOne({ where: { id: event.id } });
if (existingEvent) {
return res.status(200).send('Event already processed');
}

2. Синхронная обработка всех вебхуков

Если обработка платежа занимает 2 секунды (включая запись в БД и отправку событий), а вебхуков приходит 100 в минуту, сервис зависнет из-за блокировки HTTP-потока.

Как правильно: Помещайте событие в очередь (Bull с Redis) и обрабатывайте асинхронно. Пример с Bull:

@Processor('webhook-queue')
export class WebhookProcessor {
@Process()
async handleWebhook(job: Job) {
const event = job.data;
if (event.type === 'payment_intent.succeeded') {
await this.paymentService.updateStatus(event.data.object.id, 'succeeded');
}
}
}

В контроллере:

@Post('webhook')
async handleWebhook(@Req() req, @Res() res) {
const event = this.stripe.webhooks.constructEvent(req.body, req.headers['stripe-signature'], endpointSecret);
await this.webhookQueue.add(event);
return res.status(200).send('OK');
}

3. Хранение Stripe Secret Key в коде

Даже в .env файле, если он попадет в репозиторий (например, через случайный коммит), ключ украдут. Stripe Secret Key дает полный доступ к вашему аккаунту Stripe, включая создание платежей и управление подписками.

Как правильно: Используйте менеджер секретов (AWS Secrets Manager, HashiCorp Vault) или хотя бы исключите .env из git через .gitignore. Пример с AWS Secrets Manager:

const secrets = await this.secretsManager.getSecretValue({ SecretId: 'stripe/secret-key' });
const stripe = new Stripe(secrets.SecretString);

Дополнительно: Включите двухфакторную аутентификацию для Stripe аккаунта и ограничьте доступ к ключам через ролевую модель (IAM для AWS).

Заключение

Мы разобрали, как собрать надежный платежный микросервис на NestJS с PostgreSQL и Stripe. Главные выводы:

• Изолируйте платежную логику в отдельный микросервис — это упростит масштабирование и повысит надежность. Встроенная обработка вебхуков через очереди (Bull) защитит от перегрузок.

• Используйте TypeORM для работы с PostgreSQL и обязательно применяйте уникальные индексы для идемпотентности вебхуков. Это предотвратит дублирование платежей.

• Асинхронная обработка событий через шину данных (RabbitMQ, Redis Pub/Sub) защитит основной сервис от перегрузок и позволит легко добавлять новые подписчики (например, для аналитики или уведомлений).

Готовы попробовать эту архитектуру в своем проекте? Запишитесь на бесплатную консультацию, и мы поможем интегрировать платежи без боли.