По любому вопросу мы в одном клике

Задать вопрос
Поиск по ключевым словам
/

Подписки

Подписки позволяют организовать регулярные списания средств с карты клиента по заранее заданной сумме и периодичности.

При создании подписки регистрируется заказ для первичной оплаты и возвращается ссылка на платежную страницу. После успешной первичной оплаты подписка становится активной, а последующие платежи выполняются автоматически с периодичностью, заданной в параметрах billingIntervalValue и billingIntervalUnit.

В этом разделе описаны методы создания подписки, получения списка подписок и детальной информации о подписке, отмены подписки и обновления параметров регулярных списаний.

Описание процесса


Group 2

  1. Клиент выбирает подписку в интернет-магазине и нажимает кнопку Подписаться.

  2. Сервер интернет-магазина получает запрос на подписку.

  3. Сервер интернет-магазина запрашивает регистрацию подписки, отправляя вызов API POST /v1/subscriptions в сервис подписок.

  4. Сервис подписок создает новую подписку и отправляет ответ на сервер интернет-магазина. Ответ содержит параметр checkoutUrl (URL-адрес оплаты, на который интернет-магазин должен перенаправить клиента на шаге 5) и параметр subscriptionId (уникальный номер подписки).

  5. Интернет-магазин перенаправляет клиента на URL, полученный в параметре checkoutUrl. Перенаправление может выполняться как в текущем окне, так и в новом.

  6. Сервис подписок отображает платежную страницу.

  7. Клиент вводит номер своей карты, срок ее действия и CVV/CVC и нажимает Оформить подписку.

  8. Сервис подписок обрабатывает запрос на оплату.

  9. Клиент перенаправляется на финишную страницу.

  10. Интернет-магазин отправляет запрос POST /v1/subscriptions/details в сервис подписок, чтобы проверить статус подписки и убедиться, что первичный платеж прошел успешно. Запрос содержит параметр subscriptionId, полученный на шаге 4.

  11. Сервис подписок по расписанию, указанному при создании подписки, проверяет для каких подписок нужно произвести повторные списания.

  12. Повторные списания производятся с платежного средства, привязанного на шаге 7.

О том, как просматривать подписки в Личном кабинете, читайте здесь.

Базовый URL:

При выполнении запроса необходимо использовать заголовок: Content-Type: application/json;charset=UTF-8, метод POST.

Статусы подписки

СтатусОписание
INITIATEDСоздана, ожидает первичной оплаты
ACTIVEАктивна, рекуррентные платежи выполняются
UNPAIDПлатёж не прошёл, ожидается повтор
PAYMENT_FAILEDПервый платёж завершился неудачей
CANCELLEDОтменена (терминальный статус)

Создание подписки

Для создания подписки используется метод POST /v1/subscriptions. Регистрируется заказ, создаётся подписка в статусе INITIATED и возвращается ссылка на платежную страницу для первичной оплаты.

Тело запроса

usernamestringrequired
Логин учетной записи API продавца.
passwordstringrequired
Пароль учетной записи API продавца.
customerIdstringrequired
Номер клиента (ID) в системе мерчанта.
amountnumberrequired
Сумма платежа в минимальных единицах валюты (например, в копейках).
currencynumberrequired
Числовой код ISO 4217 (например, 643 — RUB)
billingIntervalValuenumberrequired
Интервал между регулярными списаниями в единицах, указанных в billingIntervalUnit. Должен быть целым числом больше 0.
billingIntervalUnitstringrequired
Одно из: DAYS / WEEKS / MONTHS / YEARS
successUrlstringrequired
Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол.
failUrlstringrequired
Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол.
emailstringrequired*
Обязателен, если не указан phone
phonestringrequired*
+?[0-9\\s\\-()]{7,20}. Обязателен, если не указан email.
orderNumberstringoptional
Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.
descriptionstringoptional
Описание подписки в любом формате. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется.

Пример запроса создания подписки

curl --request POST \
  --url https://sandbox.rbsuat.com/wheel/v1/subscriptions \
  --header 'content-type: application/json;charset=UTF-8' \
  --data '{
    "username": "merchant_login",
    "password": "merchant_password",
    "customerId": "customer-123",
    "email": "customer@example.com",
    "phone": "+79001234567",
    "amount": 10000,
    "currency": 643,
    "billingIntervalValue": 1,
    "billingIntervalUnit": "MONTHS",
    "description": "Ежемесячная подписка",
    "successUrl": "https://example.com/success",
    "failUrl": "https://example.com/fail"
  }'

Пример успешного ответа

{
  "checkoutUrl": "https://sandbox.rbsuat.com/payment/merchants/ecom2/payment.html?mdOrder=02ea2f54-96a1-7ba5-8cfd-c56c026fc629&language=ru&subscription=true",
  "subscription": {
    "subscriptionId": "fe10e4c1-015d-4762-8309-89713438e78a",
    "merchantLogin": "merchant_login",
    "customerId": "customer-123",
    "amount": 10000,
    "currency": 643,
    "email": "customer@example.com",
    "phone": "+79001234567",
    "billingIntervalValue": 1,
    "billingIntervalUnit": "MONTHS",
    "description": "Ежемесячная подписка",
    "status": "INITIATED",
    "mdOrder": "02ea2f54-96a1-7ba5-8cfd-c56c026fc629",
    "bindingId": null,
    "activeTill": null,
    "nextChargeAt": null,
    "created": "2026-07-13T15:37:45.359553+03:00"
  }
}

Примеры ответов с ошибкой

400 Bad Request — ошибка валидации или сбой регистрации в шлюзе

{ "error": "Either email or phone is required" }
{ "error": "Amount must be greater than zero" }
{ "error": "Payment Gateway registration failed: ..." }

500 Internal Server Error

{ "error": "Internal server error" }

Список подписок

Для получения списка подписок используется метод POST /v1/subscriptions/list. Метод возвращает постраничный список подписок мерчанта с фильтрацией и сортировкой.

Тело запроса

usernamestringrequired
Логин учетной записи API продавца.
passwordstringrequired
Пароль учетной записи API продавца.
statusesstring[]optional
Список статусов подписок для фильтрации. Возможные значения перечислены в разделе Статусы подписки.
customerIdstringoptional
Номер клиента (ID) в системе мерчанта, по которому требуется отфильтровать подписки.
amountFromnumberoptional
Минимальная сумма подписки в минимальных единицах валюты. Граница включается в результат.
amountTonumberoptional
Максимальная сумма подписки в минимальных единицах валюты. Граница включается в результат.
createdFromstringoptional
Дата и время создания подписки, начиная с которых требуется вернуть записи. Указывается в формате ISO 8601.
createdTostringoptional
Дата и время создания подписки, до которых требуется вернуть записи. Указывается в формате ISO 8601.
sortFieldstringoptional
Поле для сортировки списка. Возможные значения: CUSTOMER_ID, SUBSCRIPTION_ID, CREATED, UPDATED, AMOUNT, STATUS, NEXT_CHARGE_AT. Значение по умолчанию: CREATED.
sortDirectionstringoptional
Направление сортировки. Возможные значения: ASC, DESC. Значение по умолчанию: DESC.
pagenumberoptional
Номер страницы, начиная с 0. Значение по умолчанию: 0.
sizenumberoptional
Количество записей на странице. Значение по умолчанию: 20.

Пример запроса списка подписок

curl --request POST \
  --url https://sandbox.rbsuat.com/wheel/v1/subscriptions/list \
  --header 'content-type: application/json;charset=UTF-8' \
  --data '{
    "username": "merchant_login",
    "password": "merchant_password",
    "statuses": ["ACTIVE", "UNPAID"],
    "customerId": null,
    "amountFrom": 5000,
    "amountTo": null,
    "createdFrom": "2026-01-01T00:00:00+03:00",
    "createdTo": null,
    "sortField": "CREATED",
    "sortDirection": "DESC",
    "page": 0,
    "size": 20
  }'

Пример успешного ответа

{
  "items": [
    {
      "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
      "merchantLogin": "merchant_login",
      "customerId": "customer-123",
      "amount": 10000,
      "currency": 643,
      "email": "customer@example.com",
      "status": "ACTIVE",
      "billingIntervalValue": 1,
      "billingIntervalUnit": "MONTHS",
      "activeTill": "2026-12-31T23:59:59+03:00",
      "created": "2026-01-01T10:00:00+03:00"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "page": 0,
  "size": 20
}

Примеры ответов с ошибкой

500 Internal Server Error

{ "error": "Internal server error" }

Детали подписки

Для получения полной информации о подписке используется метод POST /v1/subscriptions/details. Метод возвращает параметры подписки и список связанных платежей.

Для активной подписки первым элементом в payments возвращается платёж активации (первичная оплата). Последующие элементы — рекуррентные списания.

Тело запроса

usernamestringrequired
Логин учетной записи API продавца.
passwordstringrequired
Пароль учетной записи API продавца.
subscriptionUuidstringrequired
UUID подписки, полученный при создании подписки.

Пример запроса деталей подписки

curl --request POST \
  --url https://sandbox.rbsuat.com/wheel/v1/subscriptions/details \
  --header 'content-type: application/json;charset=UTF-8' \
  --data '{
    "username": "merchant_login",
    "password": "merchant_password",
    "subscriptionUuid": "550e8400-e29b-41d4-a716-446655440000"
  }'

Пример успешного ответа

{
  "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
  "merchantLogin": "merchant_login",
  "customerId": "customer-123",
  "amount": 10000,
  "currency": 643,
  "email": "customer@example.com",
  "phone": "+79001234567",
  "billingIntervalValue": 1,
  "billingIntervalUnit": "MONTHS",
  "description": "Ежемесячная подписка",
  "status": "ACTIVE",
  "mdOrder": "abc12345-0000-0000-0000-000000000000",
  "bindingId": "binding-id-12345",
  "activeTill": "2026-12-31T23:59:59+03:00",
  "nextChargeAt": "2026-07-01T10:00:00+03:00",
  "created": "2026-01-01T10:00:00+03:00"
}

Примеры ответов с ошибкой

404 Not Found — подписка не найдена или принадлежит другому мерчанту

{ "error": "Subscription not found: 550e8400-e29b-41d4-a716-446655440000" }

500 Internal Server Error

{ "error": "Internal server error" }

Отмена подписки

Для отмены подписки используется метод POST /v1/subscriptions/deactivate. Метод переводит подписку в статус CANCELLED и завершает связанный рекуррентный процесс.

Повторная отмена уже отменённой подписки возвращает ошибку 422.

Тело запроса

usernamestringrequired
Логин учетной записи API продавца.
passwordstringrequired
Пароль учетной записи API продавца.
subscriptionIdstringrequired
UUID подписки, которую требуется отменить.
forcebooleanoptional
Способ отмены подписки. false — дождаться конца текущего расчетного периода; true — отменить немедленно. Значение по умолчанию: false.

Пример запроса отмены подписки

curl --request POST \
  --url https://sandbox.rbsuat.com/wheel/v1/subscriptions/deactivate \
  --header 'content-type: application/json;charset=UTF-8' \
  --data '{
    "username": "merchant_login",
    "password": "merchant_password",
    "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
    "force": false
  }'

Пример успешного ответа

{
  "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CANCELLED"
}

Примеры ответов с ошибкой

404 Not Found

{ "error": "Subscription not found: 550e8400-e29b-41d4-a716-446655440000" }

422 Unprocessable Entity — подписка уже отменена

{ "error": "Subscription already cancelled: 550e8400-e29b-41d4-a716-446655440000" }

500 Internal Server Error

{ "error": "Internal server error" }

Обновление подписки

Для обновления подписки используется метод POST /v1/subscriptions/update. Метод изменяет сумму и/или интервал списания. Если опциональное поле не передано, текущее значение этого поля сохраняется.

Подписка в статусе CANCELLED не может быть обновлена.

Тело запроса

usernamestringrequired
Логин учетной записи API продавца.
passwordstringrequired
Пароль учетной записи API продавца.
subscriptionIdstringrequired
UUID подписки, которую требуется обновить.
amountnumberoptional
Новая сумма регулярного списания в минимальных единицах валюты. Должна быть целым числом больше 0.
billingIntervalValuenumberoptional
Новый интервал между регулярными списаниями в единицах, указанных в billingIntervalUnit. Должен быть целым числом больше 0.
billingIntervalUnitstringoptional
Новая единица интервала регулярных списаний. Возможные значения: DAYS, WEEKS, MONTHS, YEARS.

Пример запроса обновления подписки

curl --request POST \
  --url https://sandbox.rbsuat.com/wheel/v1/subscriptions/update \
  --header 'content-type: application/json;charset=UTF-8' \
  --data '{
    "username": "merchant_login",
    "password": "merchant_password",
    "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 15000,
    "billingIntervalValue": 1,
    "billingIntervalUnit": "MONTHS"
  }'

Пример успешного ответа

{
  "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ACTIVE",
  "amount": 15000,
  "billingIntervalValue": 1,
  "billingIntervalUnit": "MONTHS"
}

Примеры ответов с ошибкой

404 Not Found

{ "error": "Subscription not found: 550e8400-e29b-41d4-a716-446655440000" }

422 Unprocessable Entity — подписка отменена

{ "error": "Cannot update cancelled subscription: 550e8400-e29b-41d4-a716-446655440000" }

500 Internal Server Error

{ "error": "Internal server error" }
Категории:
SubscriptionsAPI V1
Beta
Категории
Результаты поиска
Навигация
Перейти
Закрыть
Beta
Категории
Результаты поиска