mufassall

Шпаргалка · Бизнес-процессы

Биллинг подписок

14 мин · Средний · mufassall.dtwin.uz/ru/l/subscription-billing/

← Открыть урок

Проблема

SaaS-продукт продаёт месячные тарифы и каждую ночь списывает деньги с карт. Две копии джоба списывают с одного клиента дважды, карты отклоняются, клиенты меняют тариф посреди месяца, месяцы разной длины, а провайдер сообщает результат позже вебхуком. У каждой проблемы есть конкретное решение, которое держит деньги верными, а клиентов — на месте.

Чему вы научитесь

  • Подписка, тариф, расчётный период и строка счёта за каждым списанием
  • Пересекающиеся запуски биллинга: ключ идемпотентности на счёт и лиз на каждую строку
  • Даннинг после отказа и прорейт при смене тарифа посреди периода
  • Концы месяцев и часовые пояса, вебхуки провайдера, отмена в конце периода
Итоговая сцена

Диаграмма как код

Итоговая схема урока в виде текста: вставьте её в Jira, GitLab, GitHub, Notion или документацию, там Mermaid рисуется сам. Есть варианты для D2 и PlantUML (Confluence, IntelliJ).

Mermaid: схема

flowchart LR
  n_customer(["Клиент"])
  n_api["Billing API"]
  n_invoices[("Счета")]
  n_job("Биллинг-джоб")
  n_provider>"Платёжный провайдер"]
  n_job2("Биллинг-джоб №2")
  n_mailer>"Почтовый сервис"]
  n_customer --> n_api
  n_api --> n_invoices
  n_job --> n_invoices
  n_job -->|"вызов"| n_provider
  n_job2 --> n_invoices
  n_job --> n_mailer
  n_provider -.->|"асинхронно"| n_api

Mermaid: последовательность запросов

sequenceDiagram
  participant n_api as Billing API
  participant n_invoices as Счета
  participant n_job as Биллинг-джоб
  participant n_job2 as Биллинг-джоб №2
  participant n_provider as Платёжный провайдер
  Note over n_api,n_invoices: Подписка — это тариф плюс расчётный период
  n_api->>n_invoices: invoices: new row
  Note over n_job,n_invoices: Каждую ночь джоб продлевает то, что пора
  n_job->>n_invoices: SELECT s.id, s.plan, s.current_period_end
  n_invoices-->>n_job: 18 412 rows
  Note over n_job2,n_provider: Две копии джоба списывают с одних и тех же клиентов
  n_job2->>n_provider: 02:00 cron billing-run started on node-a
  Note over n_job,n_provider: Лиз на счёт и ключ идемпотентности на списание
  n_job->>n_provider: POST /v1/charges HTTP/1.1
  n_provider-->>n_job: HTTP/1.1 200 OK
  Note over n_job,n_provider: Карта отклонена
  n_job->>n_provider: POST /v1/charges HTTP/1.1
  n_provider-->>n_job: HTTP/1.1 402 Payment Required
  Note over n_job,n_invoices: Даннинг: попытки несколько дней, льготный период, затем приостановка
  n_job->>n_invoices: dunning: row for in_7188
  Note over n_api,n_invoices: Апгрейд посреди периода: кредит за неиспользованное, списание за новое
  n_api->>n_invoices: upgrade sub_42 basic -#62; pro at 2026-11-16T00:00Z
  Note over n_job,n_invoices: Концы месяцев и часовые пояса
  n_job->>n_invoices: sub_77 anchor 2026-01-31T00:00 +05:00, anchor_day 31
  Note over n_provider,n_api: Провайдер подтверждает оплату позже вебхуком
  n_provider->>n_api: POST /billing/webhooks HTTP/1.1
  n_api-->>n_provider: HTTP/1.1 200 OK
  Note over n_job,n_invoices: Отмена в конце периода или сейчас с возвратом
  n_job->>n_invoices: UPDATE subscriptions SET status = 'canceled'
  n_invoices-->>n_job: UPDATE 312

D2

direction: right

n_customer: "Клиент" {
  shape: rectangle
}
n_api: "Billing API" {
  shape: rectangle
}
n_invoices: "Счета" {
  shape: cylinder
}
n_job: "Биллинг-джоб" {
  shape: rectangle
  style.multiple: true
}
n_provider: "Платёжный провайдер" {
  shape: cloud
}
n_job2: "Биллинг-джоб №2" {
  shape: rectangle
  style.multiple: true
}
n_mailer: "Почтовый сервис" {
  shape: cloud
}

n_customer -> n_api
n_api -> n_invoices
n_job -> n_invoices
n_job -> n_provider: "вызов"
n_job2 -> n_invoices
n_job -> n_mailer
n_provider -> n_api: "асинхронно" {
  style.stroke-dash: 3
}

PlantUML: последовательность запросов

@startuml
participant "Billing API" as n_api
database "Счета" as n_invoices
participant "Биллинг-джоб" as n_job
participant "Биллинг-джоб №2" as n_job2
boundary "Платёжный провайдер" as n_provider
note over n_api, n_invoices : Подписка — это тариф плюс расчётный период
n_api -> n_invoices : invoices: new row
note over n_job, n_invoices : Каждую ночь джоб продлевает то, что пора
n_job -> n_invoices : SELECT s.id, s.plan, s.current_period_end
n_invoices --> n_job : 18 412 rows
note over n_job2, n_provider : Две копии джоба списывают с одних и тех же клиентов
n_job2 -> n_provider : [дубль] 02:00 cron billing-run started on node-a
note over n_job, n_provider : Лиз на счёт и ключ идемпотентности на списание
n_job -> n_provider : POST /v1/charges HTTP/1.1
n_provider --> n_job : HTTP/1.1 200 OK
note over n_job, n_provider : Карта отклонена
n_job -> n_provider : POST /v1/charges HTTP/1.1
n_provider --> n_job : HTTP/1.1 402 Payment Required
note over n_job, n_invoices : Даннинг: попытки несколько дней, льготный период, затем приостановка
n_job -> n_invoices : dunning: row for in_7188
note over n_api, n_invoices : Апгрейд посреди периода: кредит за неиспользованное, списание за новое
n_api -> n_invoices : upgrade sub_42 basic -> pro at 2026-11-16T00:00Z
note over n_job, n_invoices : Концы месяцев и часовые пояса
n_job -> n_invoices : sub_77 anchor 2026-01-31T00:00 +05:00, anchor_day 31
note over n_provider, n_api : Провайдер подтверждает оплату позже вебхуком
n_provider ->> n_api : POST /billing/webhooks HTTP/1.1
n_api -->> n_provider : HTTP/1.1 200 OK
note over n_job, n_invoices : Отмена в конце периода или сейчас с возвратом
n_job -> n_invoices : UPDATE subscriptions SET status = 'canceled'
n_invoices --> n_job : UPDATE 312
@enduml

PlantUML: компоненты

@startuml
left to right direction
agent "Клиент" as n_customer
component "Billing API" as n_api
database "Счета" as n_invoices
collections "Биллинг-джоб" as n_job
cloud "Платёжный провайдер" as n_provider
collections "Биллинг-джоб №2" as n_job2
cloud "Почтовый сервис" as n_mailer
n_customer --> n_api
n_api --> n_invoices
n_job --> n_invoices
n_job --> n_provider : вызов
n_job2 --> n_invoices
n_job --> n_mailer
n_provider ..> n_api : асинхронно
@enduml

Итог

Шесть правил регулярного биллинга.

1) Каждое списание принадлежит одному счёту за один полуоткрытый период. 2) Считайте, что джоб запустится дважды: лиз на каждый счёт и ключ идемпотентности из счёта и попытки на каждое списание. 3) После мягкого отказа — даннинг: попытки несколько дней, письма, льготный период, затем приостановка. 4) Прорейт смены тарифа — строками счёта с одним правилом округления. 5) Храните якорный день и часовой пояс клиента; моменты — в UTC. 6) Пусть оплату завершают подписанные вебхуки без дублей, зависшие счета сверяйте с провайдером, а отменяйте в конце периода, если клиент не просит сейчас.

Показатели: в начале и в конце

ПоказательВ началеВ конце
Двойные списания0/день0/день
Неоплаченные счета0 $4 700 $
Спасено после отказа0%71%
Вынужденный отток0%1%

Шаги

  1. Кейс Подписка — это тариф плюс расчётный период

    Клиент выбирает тариф Basic за $20.00 в месяц.

  2. Кейс Каждую ночь джоб продлевает то, что пора

    В 02:00 UTC биллинг-джоб выбирает все активные подписки с закончившимся периодом.

  3. Проблема Две копии джоба списывают с одних и тех же клиентов

    Деплой поднял новый экземпляр биллинга, пока старый ещё работал.

  4. Решение Лиз на счёт и ключ идемпотентности на списание

    Воркер забирает пачку счетов через FOR UPDATE SKIP LOCKED и пишет lease_until = now() + 10 min.

  5. Проблема Карта отклонена

    Каждую ночь около 4% продлений не проходят.

  6. Решение Даннинг: попытки несколько дней, льготный период, затем приостановка

    Каждый неоплаченный счёт получает запись даннинга: повтор на 1, 3, 5 и 7 день, ближе к полудню, когда пришла зарплата, а не в 02:00.

  7. Кейс Апгрейд посреди периода: кредит за неиспользованное, списание за новое

    16 ноября клиент переходит с Basic ($20) на Pro ($50).

  8. Кейс Концы месяцев и часовые пояса

    Клиент в UTC+5 подписался 31 января в полночь по своему времени.

  9. Решение Провайдер подтверждает оплату позже вебхуком

    Часть списаний не завершается внутри вызова: банк просит дополнительное подтверждение или проводит платёж позже.

  10. Решение Отмена в конце периода или сейчас с возвратом

    Большинство отменивших уже заплатили за этот месяц, поэтому доступ сохраняется до конца периода.

  11. Итоги Итог

    Шесть правил регулярного биллинга.

Термины

Даннинг
Повтор неудавшегося продления в течение нескольких дней, уведомления клиенту и приостановка после льготного периода.
Прорейт
При смене тарифа посреди периода: кредит за неиспользованную часть старого и списание за остаток нового.