Перейти к основному содержимому

Регулярные платежи по СБП

Клиент один раз привязывает счёт в своём банке. После этого ваш сервер списывает нужную сумму, когда приходит время: за месяц, за год, за разовый заказ.

Тарифы создавать и согласовывать не нужно. Цену и период вы называете сами, когда создаёте подписку. Ограничений два: одно списание не больше лимита кассы, а всего за период — не больше трёх цен, которые видел клиент (подробнее в шаге 3).

Как это выглядит целиком:

  1. Вы создаёте подписку и отправляете клиенту ссылку.
  2. Клиент подтверждает привязку счёта в банке. Это бесплатно.
  3. Вы запрашиваете списание на нужную сумму.
  4. Приходит уведомление payment.paid, и вы выдаёте доступ.

Расписания на нашей стороне нет: каждое списание запускаете вы. Нужна оплата раз в месяц, значит ваш сервер раз в месяц отправляет запрос из шага 3.

Понадобятся API-ключ кассы и её terminal_id. Регулярные платежи для кассы включает менеджер RollyPay. Проверить, включены ли они, и узнать лимит можно в кабинете, в разделе «Подписки».

1. Создайте подписку​

curl -X POST 'https://rollypay.io/api/v1/subscriptions' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_ROLLYPAY_API_KEY' \
-H "X-Nonce: $(uuidgen)" \
-H 'Idempotency-Key: bind-customer-123' \
-d '{
"terminal_id": "TERMINAL_UUID",
"payer_id": "customer_123",
"display_amount_rub": "299.00",
"display_interval": "month"
}'
ПолеЧто это
payer_idВаш идентификатор клиента, например tg_123456789. Телефон и email не нужны
display_amount_rubЦена, которую клиент увидит на странице подтверждения: «299 ₽ раз в месяц»
display_intervalПериод для этой подписи: month, quarter, half_year или year. Без него цена показывается «за заказ»

display_amount_rub и display_interval только показывают клиенту ваши условия. Они ничего не списывают и не задают расписание.

В ответе придут id подписки и pay_url. Сохраните id рядом с клиентом и отправьте ему pay_url как есть.

{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"state": "new",
"billing_status": "consent_pending",
"max_charge_amount_rub": "5000.00",
"pay_url": "https://pay.rollypay.io/pay/recurring/SIGNED_TOKEN"
}

max_charge_amount_rub — лимит одного списания для вашей кассы. В примере это 5 000 ₽; свой берите из ответа.

2. Дождитесь привязки​

Клиент открывает ссылку, принимает условия и подтверждает привязку в банковском приложении. Проверяйте подписку запросом:

curl 'https://rollypay.io/api/v1/subscriptions/SUBSCRIPTION_UUID' \
-H 'X-API-Key: YOUR_ROLLYPAY_API_KEY' \
-H "X-Nonce: $(uuidgen)"

Подписка готова к списаниям, когда одновременно state: "active" и billing_status: "enabled". Отдельного уведомления о привязке нет. Если клиент закрыл страницу, тот же запрос вернёт актуальный pay_url: новую подписку создавать не нужно.

Привязка ещё не оплата. Деньги списываются только на следующем шаге.

3. Спишите сумму​

curl -X POST 'https://rollypay.io/api/v1/subscriptions/SUBSCRIPTION_UUID/debits' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_ROLLYPAY_API_KEY' \
-H "X-Nonce: $(uuidgen)" \
-H 'Idempotency-Key: customer-123-2026-12' \
-d '{"amount":"299.00"}'

Сумма — строка в рублях с двумя знаками после точки, не больше лимита. В следующий раз можно списать другую сумму, например 349 ₽ вместо 299 ₽: новая подписка для этого не нужна.

Клиент защищён от лишних списаний

Клиент соглашался на цену, которую видел при привязке. Поэтому всего за период по подписке можно списать не больше трёх таких цен: при «299 ₽ раз в месяц» это 897 ₽ за 30 дней. Обычному продлению и небольшой смене цены это не мешает. Точные правила — в справочнике.

У каждого списания свой Idempotency-Key. Удобно собирать его из клиента и периода, как в примере: тогда повтор запроса за тот же месяц не спишет деньги второй раз.

Ответ 200 или 201 значит, что запрос принят. Это ещё не подтверждение оплаты.

4. Выдайте доступ по уведомлению​

На callback_url кассы придёт обычное уведомление payment.paid. Проверьте подпись, запросите платёж GET /api/v1/payments/PAYMENT_UUID и убедитесь, что у него status: "paid" и ваш subscription_id. После этого продлевайте доступ.

Одно уведомление может прийти дважды. Запоминайте обработанный payment_id и не выдавайте доступ повторно.

Результат конкретного списания виден в истории:

curl 'https://rollypay.io/api/v1/subscriptions/SUBSCRIPTION_UUID/debits' \
-H 'X-API-Key: YOUR_ROLLYPAY_API_KEY' \
-H "X-Nonce: $(uuidgen)"
Статус списанияЧто делать
requested, pendingПодождать. Новое списание вместо этого не создавать
succeededОплачено. Выдать доступ один раз
failedБанк отказал. Сообщить клиенту; следующая попытка идёт с новым ключом
reviewМы проверяем операцию. Не повторять, написать в поддержку

Отмена​

Когда клиент отказывается от автопродления:

curl -X POST 'https://rollypay.io/api/v1/subscriptions/SUBSCRIPTION_UUID/stop' \
-H 'X-API-Key: YOUR_ROLLYPAY_API_KEY' \
-H "X-Nonce: $(uuidgen)"

Отмена подтверждена, когда у подписки state: "stop" и billing_status: "stopped". Она не возвращает прошлые платежи. Списание, отправленное до отмены, может завершиться после неё.

Частые вопросы​

Как сделать подписку «раз в месяц»? Храните у себя дату следующего списания и в этот день отправляйте запрос из шага 3. Мы сами по расписанию ничего не списываем.

Клиент сменил тариф. Что делать? Если новая цена близка к прежней, просто спишите новую сумму. Если она заметно выше (был месяц за 299 ₽, стал год за 1 990 ₽), создайте новую подписку с новой ценой: клиент подтвердит её в банке, а старую отмените.

Нужно ли согласовывать цены? Нет. Цену вы называете сами при создании подписки, в пределах лимита кассы. Если лимита не хватает, напишите менеджеру.

Списание вернуло 422. Что это? Сработала защита клиента: сумма или частота списаний выходит за то, на что он соглашался. Деньги не списаны. Причина написана в ответе.

Запрос завис или вернул ошибку сети. Повторять? Да, с тем же телом и тем же Idempotency-Key, но новым X-Nonce. С новым ключом получится второе списание.

Что если банк несколько раз подряд отказал? Подписка остановится. Клиенту нужно привязать счёт заново.

Есть ли тестовый режим? Нет. Проверяйте на своём счёте и небольшой сумме: это настоящие деньги.

Все поля, статусы и ошибки собраны в справочнике.