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

API подписок

Методы API подписок АТОЛ Pay - планы подписок, создание, отмена и получение списка подписок.

Подписки строятся на двух сущностях: план подписки (шаблон: период, пробный период, сумма, чек) и подписка покупателя (экземпляр плана, привязанный к клиенту). Общий сценарий описан на странице Сценарий работы с подпиской.

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

http
POST /v1/ecom/subscription-plans
ПараметрОписаниеОбяз.Формат
nameНазвание плана подпискиДаstring(255)
externalPlanIdВнешний ID плана (цифры, латиница и символы :, +, -, _, .)Нетstring(255)
descriptionОписание планаНетstring(255)
periodПериод подписки - должно быть передано одно из значенийДаobject
period.years / period.months / period.daysПериод в годах / месяцах / дняхНетnumber
period.minutes / period.secondsПериод в минутах / секундах - только на тестовых средахНетnumber
trialPeriodПробный период - та же структура, что periodНетobject
dataДанные для формирования заказаДаobject
data.amountСумма платежа в копейках (1…2000000000)Нет, если передан userDefinedProps.costnumber
data.returnUrlURL для кнопок «Вернуться в магазин» на платежной формеДаstring(255)
data.appReturnUrlURL для кнопки «Вернуться в приложение» (только в режиме tp=app)Нетstring(255)
data.receipt.providerIdID провайдера фискализации: 100 - АТОЛ ОнлайнДа (в блоке receipt)number
data.receipt.snoСистема налогообложения (0…5)Да (в блоке receipt)number
data.merchant.nameНазвание магазинаНетstring(255)
data.items[]Список позиций: name, price (копейки), quantity (тысячные), measure - обязательны; вложенный receipt (paymentMethod, paymentSubject, tax - обязательны в нем; isAgent, agentId, supplierId)Нетarray
data.paymentMethods[]Методы оплаты подписки: paymentType - только card, bankId - только 100 (Альфа-Банк) или 700 (Т-Банк). Если не передан - из настроек ЛКНетarray
data.userDefinedPropsДоп. параметры заказа: cost.min / cost.max (копейки), fields[].nameНетobject

В подписках доступен только paymentType: "card" - набор методов уже, чем в обычном платеже.

json
{
  "name": "Подписка Премиум",
  "externalPlanId": "premium-monthly",
  "description": "Ежемесячный доступ к премиум-функциям",
  "period": { "months": 1 },
  "trialPeriod": { "days": 7 },
  "data": {
    "amount": 49900,
    "returnUrl": "https://example.com/subscription/return",
    "receipt": { "providerId": 100, "sno": 1 },
    "merchant": { "name": "ООО Пример" },
    "items": [
      {
        "name": "Подписка Премиум, 1 месяц",
        "price": 49900,
        "quantity": 1000,
        "measure": 0,
        "receipt": { "paymentMethod": 0, "paymentSubject": 4, "tax": 6 }
      }
    ],
    "paymentMethods": [ { "paymentType": "card", "bankId": 100 } ]
  }
}

Ответ - { "status": "success", "data": { ... } }, где data содержит id плана, externalPlanId, name, amount, description, isActive, paymentUrl, period, trialPeriod, createdAt и исходный блок data.

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

http
PATCH /v1/ecom/subscription-plans

Все параметры передаются в теле запроса (query-параметров у метода нет).

ПараметрОписаниеОбяз.Формат
subscriptionPlanIdID плана подписки - используется для поиска планаОдно из двухstring
externalPlanIdВнешний ID плана - используется для поиска планаОдно из двухstring(255)
nameНовое название плана подпискиНетstring(255)
descriptionНовое описание плана. Значение null очищает полеНетstring | null
json
{
  "externalPlanId": "premium-monthly",
  "name": "Подписка Премиум+",
  "description": "Ежемесячный доступ ко всем функциям"
}
json
{
  "status": "success",
  "data": {
    "id": "8460382f-f3fc-49ae-9f37-e353d18fa4a5",
    "externalPlanId": "premium-monthly",
    "name": "Подписка Премиум+",
    "amount": 49900,
    "description": "Ежемесячный доступ ко всем функциям",
    "isActive": true,
    "paymentUrl": "https://atolpay.ru/subscription/8460382f",
    "period": { "months": 1 },
    "trialPeriod": { "days": 7 },
    "data": { "returnUrl": "https://example.com/subscription/return" },
    "createdAt": "2025-06-04T13:21:00+03:00",
    "updatedAt": "2025-06-05T09:10:00+03:00"
  }
}

Получение списка планов подписок

http
GET /v1/ecom/subscription-plans

Необязательные query-параметры - subscriptionPlanIds и externalPlanIds (списки ID через запятую). Без них возвращаются все планы.

Возвращает массив data.plans[]: id, externalPlanId, name, amount, description, paymentUrl, isActive, period, trialPeriod, createdAt, updatedAt и вложенный data с параметрами заказа (returnUrl, receipt, merchant, items с sum, paymentMethods, userDefinedProps).

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

http
POST /v1/ecom/buyer-subscriptions/order

Создает подписку и возвращает ссылку на оплату первого платежа. План указывается одним из способов:

  1. subscriptionPlanId или externalPlanId - ID существующего плана; любой из них имеет приоритет над subscriptionPlan. Не передавайте оба ID одновременно;
  2. subscriptionPlan - полные данные плана (та же структура, что при создании плана), если ID не переданы.
ПараметрОписаниеОбяз.Формат
subscriptionPlanIdID плана подпискиНетstring
externalPlanIdВнешний ID планаНетstring
subscriptionPlanПолные данные плана подпискиНетobject
orderIdВнешний ID заказа (цифры, латиница и :, +, -, _, .)Нетstring(255)
notificationUrlURL для уведомлений о статусе. Приоритет над настройками ЛК (Настройки > Настройки заказов > Настройки колбэков)Нетstring(255)
sourceNameИсточник создания платежа (для CMS-модулей). По умолчанию apiНетstring
sourceVersionВерсия источника создания платежа (для CMS-модулей)Нетstring(32)
buyerДанные покупателяНетobject
buyer.idID конечного покупателя в системе мерчанта. К нему привязываются сохраненные карты; по нему же определяется право на пробный периодНетstring(255)
buyer.emailEmail покупателя - подставляется на форме оплатыНетstring(64)
buyer.inn / buyer.kppИНН / КПП покупателяНетstring(255)
Поле ответа (data)Описание
subscriptionIdID созданной подписки
subscriptionPlanIdID плана подписки
orderIdВнешний ID заказа первого платежа
amountСумма платежа в копейках
paymentUrls.mainСсылка на оплату первого платежа (плюс mainFrame, mainApp, direct)
paymentUrlУстарело - используйте paymentUrls.main
positions[]Позиции заказа
json
{
  "status": "success",
  "data": {
    "subscriptionId": "8460382f-f3fc-49ae-9f37-e353d18fa4a5",
    "subscriptionPlanId": "7813357e-0f79-469b-9b10-289e848df225",
    "orderId": "sub-1001",
    "amount": 49900,
    "paymentUrls": { "main": "https://atolpay.ru/8460382f-f3fc-49ae-9f37-e353d18fa4a5" },
    "positions": []
  }
}

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

http
POST /v1/ecom/buyer-subscriptions/{subscriptionId}/cancel
json
{ "status": "success", "data": {} }

После отмены придет callback с subscriptionStatus: "canceled".

Получение списка подписок

http
GET /v1/ecom/buyer-subscriptions?subscriptionIds={id1},{id2}

Query-параметр subscriptionIds (список ID через запятую) обязателен.

Поле ответа (data.subscriptions[])Описание
idВнутренний ID подписки
createdAtДата создания подписки
nextPaymentAtДата следующего платежа
canceledAtДата отмены подписки
statusСтатус: paid, error, canceled, trial, processing, paused
amountСумма подписки в копейках
isTrialAcceptedБыл ли использован пробный период (учитываются предыдущие подписки пользователя)
buyerДанные покупателя (id, email)
planПлан подписки: id, externalPlanId, name, description, isActive, period, trialPeriod
json
GET /v1/ecom/buyer-subscriptions?subscriptionIds=8460382f-f3fc-49ae-9f37-e353d18fa4a5,7813357e-0f79-469b-9b10-289e848df225

Callback подписок

Уведомления о жизненном цикле подписки приходят с type: "subscription" - см. Callback-уведомления.