- PCI DSS и 3‑D Secure: выполните требования безопасности и настройте SCA/3‑DS обходы там, где это допустимо по правилам. Подробности — в разделе Безопасность и SCA.
- Удержание карты (hold): предварительная авторизация для проверки карты или обеспечения баланса. Полезно для постоплатных сценариев. Не забывайте про своевременный capture или reversal.
- Явный мандат на MIT: храните согласие клиента, дату и параметры расписания.
Архитектура подписок в API: сущности и модель данных
Чтобы подписки API были устойчивыми, задайте четкую модель:
- Customer (покупатель) — аккаунт клиента.
- Payment Method Token — токенизированная карта/кошелек, связанный с клиентом.
- Mandate/Agreement — согласие на MIT и параметры автосписаний.
- Plan — тариф (цена, период, пробный период, ограничения).
- Subscription — экземпляр подписки клиента с состояниями: active, past_due, paused, canceled.
- Invoice — счет на период; может агрегировать несколько позиций.
- Charge — фактическое списание по invoice.
Минимальные жизненные циклы: создание (trial/active), продление, приостановка, возобновление, смена тарифа (с возможной пропорциональной корректировкой), отмена и архивирование. Используйте идемпотентные ключи при создании invoice/charge, чтобы исключить дубли на повторах запросов и сетевых таймаутах.
Типовые потоки оплаты и UX‑сценарии
Ниже — частые паттерны UX для рекуррентных платежей API:
- One‑click/COF: клиент сохраняет карту в первом платеже (CIT + 3‑DS), дальше списания идут по токену (MIT) без участия пользователя.
- Trial + автопродление: нулевой или сниженный тариф на период теста, затем автоматическое списание полной суммы. Своевременно отправляйте «уведомления подписки» перед продлением.
- Freemium с апгрейдом: бесплатная базовая версия + переход на платный план.
- Постоплата с удержанием: вы делаете удержание карты (auth hold) на предсказанную сумму, по факту — capture частично/полностью или reversal.
Tokenized payments: как работает токенизация
Tokenized payments — это механика, при которой провайдер возвращает безопасный токен взамен чувствительных данных карты. Ключевые моменты:
- Токены не раскрывают PAN и срок действия, снижая требования к вашей инфраструктуре.
- Обновление токенов: некоторые провайдеры автоматически актуализируют карточные реквизиты (network updates).
- Несколько токенов на клиента: полезно для резервного метода на случай отказов.
Чтобы стартовать, следуйте базовому гайду интеграции и сохранения методов оплаты — см. Базовая интеграция.
Webhooks и идемпотентность: надежная доставка событий
При подписках ядро логики держится на событиях: invoice.created, charge.succeeded, charge.failed, subscription.canceled и др. Правила надежности:
- Обрабатывайте вебхуки идемпотентно, храните last processed event id.
- Подтверждайте получение 2xx‑кодом; на ретраях не создавайте дубликаты документов.
- Подписывайте и верифицируйте payload, ограничьте источники.
Подробные рекомендации по гарантиям доставки, ретраям и уникальности операций — в разделе Вебхуки и идемпотентность.
Retry strategy и dunning: как снижать неуспешные списания
Даже с идеальным UX часть платежей будет отклоняться: недостаточно средств, 3‑DS/СА отказ, фрод‑фильтры, неверные реквизиты. Нужна правильно настроенная retry strategy:
- План повтора: 0‑й день (немедленно), затем D+2, D+4, D+7, D+14. Регулируйте частоту по бизнес‑модели.
- Причины отказов: разделяйте soft decline (временные) и hard decline (постоянные). Софт‑отказы — повторять, хард — переводить в past_due и просить обновить метод оплаты.
- Умные окна: повтор ночью/утром в банковские «пиковые окна» поступления зарплат.
- Переключение на резервный токен/кошелек.
Таблица ориентировочных реакций:
| Причина отказа |
Класс |
Рекомендация |
| Insufficient funds |
Soft |
Повтор через 24–72 часа, уведомление клиенту |
| 3‑DS/SCA required |
Soft |
Попросить клиент‑action: оплатить invoice в кабинете |
| Stolen/Lost card |
Hard |
Остановить автосписания, запросить новый метод |
| Do not honor |
Soft/Hard |
1–2 повтора, затем эскалация в поддержку |
Коммуникации дунк‑цикла (dunning) связывайте с «уведомлениями подписки»: письмо о проблеме оплаты, кнопка «обновить карту», дедлайн блокировки доступа.
Уведомления подписки и коммуникации
«Уведомления подписки» — фундамент доверия и соответствия ожиданиям клиента:
- Предпродление: за 3–7 дней до списания — сумма, дата, тариф, способ оплаты.
- Неуспешный платеж: причина (по возможности), быстрый линк на обновление карты.
- Изменение плана/цены: заранее и с подтверждением.
- Квитанции/чеки: после успешного списания — автопочта/мессенджер.
Эти письма снижают отток, помогают пройти SCA, уменьшают нагрузку на поддержку и повышают NPS.
Интеграции с провайдерами: что учесть
Провайдеры по‑разному реализуют токенизацию, подписи вебхуков и статусы MIT. Ознакомьтесь с особыми требованиями в разделах провайдеров:
| Провайдер |
Токенизация |
Подписки «из коробки» |
3‑D Secure |
Материалы |
| YooMoney |
Да |
Ограниченно |
Поддерживается |
YooMoney API |
| СберБанк |
Да |
Через рекуррентные платежи |
Поддерживается |
Сбербанк Эквайринг API |
| Т‑Банк (эквайринг) |
Да |
По COF/MIT |
Поддерживается |
T‑Bank API |
| Беларусбанк |
Да |
По согласованию |
Поддерживается |
Беларусбанк API |
Сравнить подходы банков и агрегаторов можно в разделе Банки vs агрегаторы.
Мобильные сценарии и SDK
На мобильных платформах используйте SDK для безопасного ввода карт и токенизации, а также нативные кошельки:
- Apple Pay / Google Pay токены конвертируйте в постоянный COF‑токен (если провайдер поддерживает) для последующих MIT.
- Утечки фокуса/сети на мобиле — частая причина дубликатов: строго применяйте идемпотентность.
Готовые компоненты описаны в разделе Мобильная SDK‑интеграция.
Тестирование, мониторинг и обработка ошибок
Подписки — это марафон, а не спринт. Важно обеспечить стабильность:
- Покрыть e2e‑кейсы в песочнице: первый платеж, продление, неуспехи, отмена, возвраты, смена тарифа — см. Песочница и тестовые данные.
- Централизованный мониторинг ошибок и алерты по SLA renewal job — см. Ошибки и мониторинг.
- Идемпотентные ключи на каждый charge/invoice generation, корреляция по request‑id.
Возвраты, реверсалы и отмена удержаний
При рекуррентных платежах важно корректно обрабатывать обратные операции:
- Полные/частичные возвраты за неполный период или даунгрейд плана.
- Реверсал удержания (void) при неиспользовании услуги.
- Налоговые документы и чек коррекции после refund.
Методики и варианты — в разделе Возвраты и реверсалы.
Сверка платежей и аналитика подписок
Сверяйте внутреннюю бухгалтерию с провайдером, чтобы находить рассинхронизации:
- Автосверка по выпискам и webhook‑событиям.
- Метрики подписок: MRR, churn, ARPU, dunning success rate, доля soft/hard declines.
Практики и схемы — в разделе Сверка и аналитика.
Банк vs агрегатор: что выбрать
- Банк: ниже комиссия, но больше интеграционной работы, меньше готовых подписочных функций.
- Агрегатор: быстрее выход на рынок, готовые токенизированные потоки и инструменты dunning, но зачастую выше стоимость.
Сравнение факторов — в гайде Банки vs агрегаторы.
Частые ошибки и быстрый чек‑лист
Ошибки, которые бьют по доходу и UX:
- Нет идемпотентности при продлениях — дублирующиеся списания.
- Отсутствуют «уведомления подписки» перед продлением — жалобы и чарджбеки.
- Неправильная retry strategy — слишком частые или редкие попытки.
- Не обрабатываются reason codes — одинаковая реакция на soft/hard declines.
- Привязка одного токена на всех клиентов (антипаттерн) — риски безопасности.
- Нет резервного метода оплаты — высокий churn при отказах.
- Отсутствуют SLA‑алерты на очереди продления.
Быстрый чек‑лист внедрения:
- Первый платеж как CIT с 3‑DS, создание mandate и токена.
- Надежные webhooks с подписью + идемпотентность — см. паттерн.
- Плановая retry strategy и dunning‑коммуникации.
- Оповещения о продлении и изменениях.
- Поддержка возвратов/реверсалов — см. гайд.
- Сверка и метрики MRR/churn — см. аналитику.
- Мониторинг ошибок и алерты — см. раздел.
Вывод и следующий шаг
Рекуррентные платежи API и подписки API — это не только про автосписания, но и про безопасную токенизацию, корректную модель данных, надежные вебхуки, продуманную retry strategy и своевременные «уведомления подписки». Настроив эти компоненты, вы снизите отказные платежи, уменьшите отток и сделаете выручку предсказуемой.
Готовы внедрять? Начните с базы и по шагам подключайте нужные паттерны — пройдите через Базовую интеграцию, затем настройте безопасность в PCI/3‑DS и провайдера из списка выше. Если нужна мобилка — смотрите SDK‑интеграцию.