Фиксированные тарифы
Эта страница для касс, которым раньше подключили тарифы с фиксированной ценой и автоматическим списанием по расписанию. Они работают как прежде.
Новым кассам этот режим не подключается. Для них действует более простой способ: вы сами списываете любую сумму в пределах лимита и не согласовываете тарифы, см. Регулярные платежи по СБП.
Выбор плана
Получите GET /api/v1/subscription-plans?terminal_id=.... План определяет условия подписки:
| Данные плана | Режим | Параметры создания |
|---|---|---|
billing_mode: fixed, указан payer_amount_rub, нет cap_amount_rub | Фиксированный тариф | plan_id и payer_id; сумму не передавайте |
billing_mode: fixed, указан cap_amount_rub | Сумма в пределах лимита | plan_id и amount; payer_id и description не передавайте |
Используйте только UUID плана из ответа API. Режим и периоды доступны после подключения соответствующих условий к вашей кассе. Пустой items означает, что доступных планов пока нет.
Подтвердите с RollyPay готовность кассы и тарифов, условия согласия плательщика и обработку платежей. Активная привязка не заменяет подтверждение оплаты.
Как это работает
- Получите доступные тарифы вашей кассы и выберите
idнужного плана. - Создайте подписку с
plan_id,payer_idи ключом ид емпотентности. - Сохраните
idподписки вместе с вашим идентификатором клиента. - Направьте клиента по
pay_url. Он принимает условия регулярных списаний и подтверждает привязку в банковском приложении. - Проверяйте состояние подписки через API. Выдавайте оплаченный доступ только по подтверждённому платежу
paid. - Списания выполняются автоматически по условиям подписки. По успешному платежу RollyPay отправляет колбэк на сервер мерчанта.
- При отказе клиента от автопродления вызовите остановку и проверьте её результат.
Активная привязка не доказывает оплату. state: active, возврат клиента из банка и успешное открытие платёжной страницы не заменяют подтверждение платежа.
Что настроить заранее
Для каждого тарифа согласуются сумма списания с клиента, комиссия и сторона, которая её оплачивает, период, ограничения по числу циклов и отказов, условия согласия. Настройку выполняет RollyPay; мерчант не создаёт планы через этот API.
| Идентификатор | Где используется |
|---|---|
terminal_id | UUID вашей кассы RollyPay |
plan_id | UUID из GET /api/v1/subscription-plans; определяет конкретный тариф |
payer_id | Ваш стабильный идентификатор плательщика, например tg_123456789 |
merchant_subscription_ref | Необязательная ссылка на подписку в вашей системе |
id подписки | Возвращает RollyPay; нужен для проверки, истории и остановки |
Одна касса может иметь несколько тарифов с одинаковым периодом и разными суммами. Выбирайте по id, а не только по interval.
Периоды
Период определяется подключённым планом. Для тарифов с периодичностью в днях используйте согласованное количество дней: 30 дней не равны календарному месяцу, 365 дней не всегда равны календарному году.
| Код API | Период для планов с фиксированным числом дней |
|---|---|
day | 1 день |
month | 30 дней |
quarter | 90 дней |
half_year | 180 дней |
year | 365 дней |
Для фиксированного режима точное время первого списания, повторы после отказа и расписание следующих списаний подтверждаются при подключении сервиса. next_charge_at — расчётная дата в RollyPay, а не подтверждение будущего платежа. Продлевайте доступ по факту оплаченного цикла; не запускайте собственное списание по этой дате.
Аутентификация и повтор запросов
Во всех запросах нужны X-API-Key вашей кассы и новый X-Nonce; см. аутентификацию. Ключ храните на сервере мерчанта.
При создании подписки также обязателен Idempotency-Key длиной до 128 байт. Если ответ потерялся или запрос завершился сетевой ошибкой, повторите то же тело и тот же Idempotency-Key, но с новым X-Nonce. Новым клю чом создаётся новая подписка: не меняйте его автоматически после тайм-аута.
merchant_subscription_ref не заменяет ключ идемпотентности. Смена плательщика или тарифа при повторе того же ключа приводит к конфликту 409.
1. Получить тарифы
curl 'https://rollypay.io/api/v1/subscription-plans?terminal_id=TERMINAL_UUID' \
-H 'X-API-Key: YOUR_ROLLYPAY_API_KEY' \
-H "X-Nonce: $(uuidgen)"
Пример ответа 200 (идентификаторы условные):
{
"items": [
{
"id": "8f1c0b6e-2a44-4f0f-9d1b-6d2f9a3c7b10",
"code": "vpn_30_days",
"name": "VPN — 30 дней",
"version": 1,
"billing_mode": "fixed",
"merchant_amount_rub": "150.00",
"payer_amount_rub": "150.00",
"interval": "month"
}
]
}
Для фиксированного режима payer_amount_rub — окончательная сумма списания с клиента; merchant_amount_rub — сумма заказа, которая может отличаться при комиссии на клиенте. Не вычисляйте итоговое списание самостоятельно. max_cycles, если присутствует, задаёт предел успешных циклов; отсутствие этого поля означает отсутствие такого предела в плане. Отмена остаётся возможной.
Если items пуст, тарифы не доступны для создания подписок. Используйте только UUID из ответа API.