Перейти к содержимому

Подробно

Оплата за пользователя в Stripe и вебхуки, которые переживают повторы

Опубликовано · 6 мин чтения·

Другие языки: العربية, Deutsch, English, Español, Français, 日本語, Português (Brasil) и 简体中文

Ряд фиолетовых театральных кресел, в каждом стоит растение в горшке, а в ещё одно кресло на нитке опускают новый росток.

Коротко

  • В Seed количество в подписке Stripe равно числу участников группы, вместе с владельцем. Перерасчёт делает Stripe, приложение деньги не считает.
  • Сначала человек вступает в группу, потом меняется счёт: задача воркера сообщает Stripe новое число и повторяет запрос с тем же ключом идемпотентности, пока Stripe недоступен.
  • Id каждого события Stripe сохраняется в той же транзакции, что его применяет: повтор ничего не меняет, а сбой откатывает и то и другое, и Stripe пришлёт событие снова.
  • Старое событие никогда не откатывает план, а ночная задача исправляет число мест, если оно разошлось.

Как сделать в SaaS оплату за каждого пользователя через Stripe, чтобы счёт не расходился с командой? В Seed количество в подписке просто равно числу участников группы, и приложение не полагается ни на один отдельный запрос или вебхук. Изменение состава сохраняется первым; затем повторяемая задача сообщает Stripe новое число; каждый вебхук записывается по id события в той же транзакции, что его применяет; а ночная задача исправляет всё, что проскочило.

Статья для разработчиков, которые добавляют командную оплату в свой SaaS, и для всех, у кого обработчик вебхуков работал, пока Stripe не прислал событие повторно. Всё описанное есть в коде Seed под лицензией MIT, и я цитирую настоящие строки.

Что значит оплата за пользователя в Seed?

Оплата принадлежит группе, то есть команде в Seed. У каждой группы одна подписка, её оплачивает владелец. В каталоге два плана (PLANS):

План Цена Участники Пробный период
Free 0 до 3 нет
Pro 9,00 € за участника в месяц до 50 14 дней

«За участника» значит, что количество в подписке Stripe равно числу участников группы, включая владельца. Это то же число, что проверяет лимит в 50 человек, так что место определено один раз, а не двумя расходящимися способами. Приглашение, которое ещё не приняли, места не занимает; принятое занимает.

Сколько это стоит команде, показывает калькулятор с ценами демо. Подвигайте ползунок:

Сколько стоит тариф Pro из демо для вашей команды

Pro оплачивается за каждого участника. Укажите размер команды.

Вся команда, в месяц
45,00 €
За участника, в месяц
9,00 €
Цены тарифов демо, без налогов.

Пятеро на Pro платят 45 € в месяц. Владелец видит цену ещё одного места до того, как кого-то пригласить: форма приглашения показывает, сколько добавит новый участник, и просит это принять. API отклоняет приглашение без такого согласия (SEAT_PRICE_NOT_ACCEPTED), так что правило действует, даже если форму отправили без JavaScript.

Почему участник вступает раньше, чем об этом узнаёт Stripe?

Потому что медленный Stripe не должен мешать человеку вступить в команду. Очевидный код вызывает Stripe прямо в запросе «принять приглашение». Если Stripe не ответил, человек либо не может вступить, либо вступает, а счёт навсегда остаётся неверным. Плохо и то и другое, а второе ещё и незаметно.

Seed сначала сохраняет изменение состава в отдельной транзакции. Её коммит пишет строку в outbox, и воркер превращает каждое изменение (вступил, удалён, вышел) в задачу синхронизации мест. Задача читает число участников в момент запуска и обращается к Stripe, только если оно отличается от сохранённого (seat-sync.ts):

const members = await new PostgresInvitationRepository(sql).countMembers(groupId)
if (members < 1 || row.quantity === members) return
const result = await provider.updateQuantity({
  subscriptionId: row.providerSubscriptionId,
  quantity: members,
  // A retry of this row asks for the same count with the same key; a later count gets its own.
  idempotencyKey: `seats:${event.id}:${members}`,
})
if (!result.ok) {
  throw new Error(`seat sync of group ${groupId} failed: ${result.error.code} ...`)
}

Всё держится на трёх деталях:

  1. Число читается, когда задача выполняется, а не когда её поставили в очередь. Пятеро вступили за минуту — нужен один верный запрос, а не пять наперегонки.
  2. Ключ идемпотентности содержит задачу и число. Если Stripe изменение применил, а ответ потерялся, повтор отправит тот же ключ, и Stripe вернёт первый результат, а не применит изменение дважды.
  3. Сбой бросает исключение. Система задач повторяет через 1 с, 2 с, 4 с и так далее, с паузой до 15 минут, всего 20 попыток, около двух с половиной часов (jobs.md).

Изменение количества просит у Stripe proration_behavior=create_prorations, это значение по умолчанию: остаток периода добавляется к следующему счёту или вычитается из него. Приложение само не считает ни одного евро перерасчёта. Денежную арифметику, которую я не пишу, я не могу написать с ошибкой.

А если синхронизация так и не прошла?

Её подстрахуют ещё два пути, ведь два с половиной часа повторов — это не «навсегда»:

  • Вебхук тоже проверяет. Когда Stripe сообщает о подписке, количество в которой не совпадает с числом участников, та же транзакция, что сохраняет событие, ставит синхронизацию мест. Так исправляется оплата, открытая до того, как кто-то вступил.
  • Ночная задача сверяет все платные группы. В 03:00 очистка находит каждую подписку за участника, в которой сохранённое количество отличается от числа людей в группе, и ставит для неё синхронизацию. Это покрывает долгий сбой Stripe и число, которое изменилось без события группы, например, когда участник удалил свой аккаунт.

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

Как сделать вебхук Stripe безопасным для повторов?

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

Вебхук Seed делает три вещи в строгом порядке. Сначала подпись: адаптер @spy4x/billing проверяет заголовок Stripe-Signature по сырому телу запроса, с окном в пять минут, до того как разобрать хоть байт JSON. Неверная подпись получает 400. Дальше всё происходит в одной транзакции Postgres, которая начинается с записи id события (postgres-billing-repository.ts):

return await this.sql.begin(async (transaction) => {
  const stored = await transaction`
    INSERT INTO billing_events (id, event_type) VALUES (${event.id}, ${event.type})
    ON CONFLICT (id) DO NOTHING
    RETURNING id
  `
  if (stored.length === 0) return "duplicate"
  // ... apply the subscription, queue mails and seat syncs, record the plan change
})

billing_events.id — первичный ключ, поэтому вторая доставка ничего не вставляет и выходит, не трогая подписку. А раз id сохраняется внутри транзакции, безопасен и обратный случай: если что-то после него упало, id откатывается вместе с остальным, маршрут отвечает 500, и повтор Stripe получает чистую вторую попытку. Если записать id отдельно, а применить потом, в два шага, событие потеряется при первом же перезапуске API между ними во время деплоя.

Письма владельцу (платёж не прошёл, пробный период заканчивается, план заканчивается) ставятся в outbox в той же транзакции, поэтому повторное событие второе письмо не поставит. Событие, которое Seed не обрабатывает, получает 200, и Stripe перестаёт его слать.

А если события пришли не по порядку?

Stripe не гарантирует порядок событий. Опоздавший customer.subscription.updated со статусом «trialing» не должен отменить active, пришедший раньше. Seed записывает подписку запросом upsert, который двигается только вперёд:

ON CONFLICT (group_id) DO UPDATE SET ...
WHERE (subscriptions.provider_event_at, subscriptions.provider_event_rank)
    <= (EXCLUDED.provider_event_at, EXCLUDED.provider_event_rank)

Сначала сравнивается время события, при равенстве — его вид: создание, затем изменение, затем удаление. Старое событие не совпадает ни с одной строкой и ничего не меняет. Второе условие в том же WHERE не даёт новой неоплаченной подписке (скажем, с запоздавшим неудачным списанием) заменить оплаченную.

Скажу прямо об ограничении. Документация Stripe советует не упорядочивать события по created, потому что там целые секунды. Seed использует его только как защиту от отката и никогда — для поиска дублей: для этого есть id события. Два события одного вида в одну секунду, пришедшие в обратном порядке, всё ещё оставят сохранённым старое, пока его не исправит следующее событие или изменение в портале. Этот случай описан в документации по оплате, а исправление ждёт spy4x/ts-libs#380. Лучше я расскажу сам, чем вы найдёте это в продакшене.

Подтверждают ли это тесты?

Они работают с настоящим Postgres. Среди 26 шагов набора вебхука (tests/integration/billing.integration.test.ts) есть «повторная доставка того же события ничего не меняет» и «событие старше сохранённого никогда не откатывает план». У мест свой набор (tests/integration/seat-billing.integration.test.ts), с шагами вроде «удалённый и вышедший участник уменьшают число на один» и «ночная задача ставит изменение мест для каждой разошедшейся группы».

Чего Seed не делает?

Чтобы вы знали заранее:

  • Один платный план, помесячно, за участника. Нет оплаты по потреблению или по счётчику, нет ступеней. Новый план добавляется за пять шагов в Plans and limits.
  • Только Stripe. Код обращается к интерфейсу провайдера, но адаптер пока один — Stripe. Оплату можно и выключить, тогда каждая группа получает все возможности.
  • invoice.paid и invoice.payment_failed сохраняются, но пока ничего не меняют. План следует за статусом самой подписки.
  • Деньги остаются в Stripe. Приложение хранит то, что сообщают вебхуки, и никогда не решает про план само.

Попробуйте

Откройте демо, создайте группу и загляните во вкладку «Оплата»; пригласите кого-нибудь, и увидите цену места до отправки. Коротко об этом — на странице оплаты, Set up billing проведёт от выключенной оплаты до настоящего Stripe, сначала в тестовом режиме, а о группах — на странице групп. Если ваш обработчик вебхуков сохраняет id события одним шагом, а применяет другим, эту строку я бы изменил сегодня.

Следующий пост — на почту

Короткое письмо, когда выходит новый пост или что-то запускается. Подписка подтверждается один раз по почте, отписаться можно в один клик.

Все посты