API подписок
Методы API подписок АТОЛ Pay - планы подписок, создание, отмена и получение списка подписок.
Подписки строятся на двух сущностях: план подписки (шаблон: период, пробный период, сумма, чек) и подписка покупателя (экземпляр плана, привязанный к клиенту). Общий сценарий описан на странице Сценарий работы с подпиской.
Создание плана подписки
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.cost | number |
data.returnUrl | URL для кнопок «Вернуться в магазин» на платежной форме | Да | string(255) |
data.appReturnUrl | URL для кнопки «Вернуться в приложение» (только в режиме tp=app) | Нет | string(255) |
data.receipt.providerId | ID провайдера фискализации: 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" - набор методов уже, чем в
обычном платеже.
{
"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.
Обновление плана подписки
PATCH /v1/ecom/subscription-plansВсе параметры передаются в теле запроса (query-параметров у метода нет).
| Параметр | Описание | Обяз. | Формат |
|---|---|---|---|
subscriptionPlanId | ID плана подписки - используется для поиска плана | Одно из двух | string |
externalPlanId | Внешний ID плана - используется для поиска плана | Одно из двух | string(255) |
name | Новое название плана подписки | Нет | string(255) |
description | Новое описание плана. Значение null очищает поле | Нет | string | null |
{
"externalPlanId": "premium-monthly",
"name": "Подписка Премиум+",
"description": "Ежемесячный доступ ко всем функциям"
}{
"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"
}
}Получение списка планов подписок
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).
Создание подписок
POST /v1/ecom/buyer-subscriptions/orderСоздает подписку и возвращает ссылку на оплату первого платежа. План указывается одним из способов:
subscriptionPlanIdилиexternalPlanId- ID существующего плана; любой из них имеет приоритет надsubscriptionPlan. Не передавайте оба ID одновременно;subscriptionPlan- полные данные плана (та же структура, что при создании плана), если ID не переданы.
| Параметр | Описание | Обяз. | Формат |
|---|---|---|---|
subscriptionPlanId | ID плана подписки | Нет | string |
externalPlanId | Внешний ID плана | Нет | string |
subscriptionPlan | Полные данные плана подписки | Нет | object |
orderId | Внешний ID заказа (цифры, латиница и :, +, -, _, .) | Нет | string(255) |
notificationUrl | URL для уведомлений о статусе. Приоритет над настройками ЛК (Настройки > Настройки заказов > Настройки колбэков) | Нет | string(255) |
sourceName | Источник создания платежа (для CMS-модулей). По умолчанию api | Нет | string |
sourceVersion | Версия источника создания платежа (для CMS-модулей) | Нет | string(32) |
buyer | Данные покупателя | Нет | object |
buyer.id | ID конечного покупателя в системе мерчанта. К нему привязываются сохраненные карты; по нему же определяется право на пробный период | Нет | string(255) |
buyer.email | Email покупателя - подставляется на форме оплаты | Нет | string(64) |
buyer.inn / buyer.kpp | ИНН / КПП покупателя | Нет | string(255) |
Поле ответа (data) | Описание |
|---|---|
subscriptionId | ID созданной подписки |
subscriptionPlanId | ID плана подписки |
orderId | Внешний ID заказа первого платежа |
amount | Сумма платежа в копейках |
paymentUrls.main | Ссылка на оплату первого платежа (плюс mainFrame, mainApp, direct) |
paymentUrl | Устарело - используйте paymentUrls.main |
positions[] | Позиции заказа |
{
"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": []
}
}Отмена подписок
POST /v1/ecom/buyer-subscriptions/{subscriptionId}/cancel{ "status": "success", "data": {} }После отмены придет callback с subscriptionStatus: "canceled".
Получение списка подписок
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 |
GET /v1/ecom/buyer-subscriptions?subscriptionIds=8460382f-f3fc-49ae-9f37-e353d18fa4a5,7813357e-0f79-469b-9b10-289e848df225Callback подписок
Уведомления о жизненном цикле подписки приходят с type: "subscription" -
см. Callback-уведомления.