Шпаргалка · Бизнес-процессы
Биллинг подписок
Проблема
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_apiMermaid: последовательность запросов
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 312D2
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
@endumlPlantUML: компоненты
@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% |
Шаги
- Кейс Подписка — это тариф плюс расчётный период
Клиент выбирает тариф Basic за $20.00 в месяц.
- Кейс Каждую ночь джоб продлевает то, что пора
В 02:00 UTC биллинг-джоб выбирает все активные подписки с закончившимся периодом.
- Проблема Две копии джоба списывают с одних и тех же клиентов
Деплой поднял новый экземпляр биллинга, пока старый ещё работал.
- Решение Лиз на счёт и ключ идемпотентности на списание
Воркер забирает пачку счетов через
FOR UPDATE SKIP LOCKEDи пишетlease_until = now() + 10 min. - Проблема Карта отклонена
Каждую ночь около 4% продлений не проходят.
- Решение Даннинг: попытки несколько дней, льготный период, затем приостановка
Каждый неоплаченный счёт получает запись даннинга: повтор на 1, 3, 5 и 7 день, ближе к полудню, когда пришла зарплата, а не в 02:00.
- Кейс Апгрейд посреди периода: кредит за неиспользованное, списание за новое
16 ноября клиент переходит с Basic ($20) на Pro ($50).
- Кейс Концы месяцев и часовые пояса
Клиент в UTC+5 подписался 31 января в полночь по своему времени.
- Решение Провайдер подтверждает оплату позже вебхуком
Часть списаний не завершается внутри вызова: банк просит дополнительное подтверждение или проводит платёж позже.
- Решение Отмена в конце периода или сейчас с возвратом
Большинство отменивших уже заплатили за этот месяц, поэтому доступ сохраняется до конца периода.
- Итоги Итог
Шесть правил регулярного биллинга.