Схема интеграции
- Создайте подписку методом POST /integration/subscriptions. По умолчанию используется h2h с email; в режиме hosted email необязателен
- Перенаправьте клиента на полученный
confirmation_url. Подписка не активируется без подтверждения клиента на стороне платёжного провайдера - Дождитесь вебхука
subscription.status_updatedсо статусомactive - Каждое автоматическое списание создаёт обычную транзакцию. Результат приходит событием
transaction.status_updatedи доступен в истории списаний - Когда подписка больше не нужна, вызовите метод отмены
Для подписок используется sbp_recurring. Он должен быть подключён к мерчанту Cashera. Передавать этот код в обычный POST /integration/transactions нельзя - подписка создаётся только через POST /integration/subscriptions.
Интервалы списаний
interval задаёт единицу периода, а необязательный interval_count — сколько таких единиц проходит между списаниями. По умолчанию используется 1, поэтому запросы существующих интеграций продолжают работать без изменений.
| interval | Допустимый interval_count | Единица периода |
|---|---|---|
daily | 1–31 | День |
weekly | 1–4 | Неделя |
monthly | 1–12 | Месяц |
yearly | 1–3 | Год |
Для 3, 6 или 9 месяцев передавайте monthly и соответствующий interval_count. Для 24 месяцев — yearly и 2. Готовые тела запросов приведены в примерах создания. Сумму, интервал и ближайшую дату действующей подписки можно изменить отдельным запросом update. Числовые значения 1–4 вместо строки interval не поддерживаются.
Период не гарантирует бесплатного времени до первого списания. Расписание задаёт провайдер; следующее списание отражается в next_charge_at. Создание и подтверждение подписки сами по себе не подтверждают оплату первого периода.
Суммы и зачисление
Все суммы API передаются целыми числами в копейках. amount — сумма одного списания; interval_count не умножает её или комиссию. Каждое успешное списание проходит как обычный RUB-платёж: применяются сохранённые при создании подписки комиссия и холд, после чего средства зачисляются через стандартный ledger Cashera. Неуспешное списание баланс не увеличивает.
Статус active означает только то, что подписка действует. Товар или услугу за конкретный период выдавайте исключительно после transaction.status_updated со статусомpaid, предварительно сверив сумму, валюту и идентификатор подписки.
Управление действующей подпиской
| Нужно | Метод | Деньги |
|---|---|---|
| Проверить доступность изменения | GET update-supported | Ничего не списывает |
| Изменить цену, ближайшую дату или период | POST update | Ничего не списывает |
| Запустить отдельную попытку сейчас | POST charge-now | Оплата подтверждается отдельно; основное расписание сохраняется |
| Прекратить будущие списания | POST cancel | Не возвращает прошлые оплаты |
Для update и charge-now обязателен Idempotency-Key. Сохраните ключ и параметры до отправки; при сетевом сбое используйте их повторно. Создание подписки по-прежнему защищается через external_id, менять существующую интеграцию для обычных регулярных оплат не требуется. Все URL принимают UUID Cashera; провайдерские ID и ключи клиенту не нужны.
Сценарий «19 ₽ на пять дней, затем 290 ₽ ежемесячно» подробно разобран в инструкции по триалу. Изменение тарифа организует ваш сервер, встроенных полей тарифных этапов нет. Новые методы требуют версии Cashera с поддержкой управления подписками; перед запуском интеграции согласуйте их доступность для вашей кассы. Для ошибок и повторов используйте отдельную инструкцию.
Неудачное списание и отмена
Одна неудачная попытка не отменяет подписку. У платежа может бытьcanceled или failed, а у подписки past_due. Отмена подписки обозначается cancelled. Фиксированного срока автоматической отмены или гарантированного графика повторов API не задаёт. Не показывайте следующую попытку, если next_charge_at отсутствует.