API подписок: тарифы, доступ и лимиты для вашего SaaS

Как описать тарифы в кабинете и проверять доступ, пробные периоды и расход лимитов через /v2/subscriptions с ключом xsub_….

Зачем нужны подписки в xpayment

Если у вас SaaS, приложение, клуб или школа и пользователи платят за доступ по тарифам, вам нужно хранить три вещи: что входит в каждый тариф, до какого числа оплачено и сколько лимита уже израсходовано. Раздел «Подписки» берёт это на себя. Вы описываете тарифы в кабинете, а ваш сервис через API спрашивает: «что доступно этому пользователю?».

xpayment ведёт:

Это не то же самое, что платёж через API: платёж принимает деньги один раз, а подписка отвечает на вопрос «есть ли у пользователя доступ сейчас». Одно с другим связано: счёт за подписку — это обычный удалённый платёж Kaspi.

Как это устроено

Кабинет «Подписки»        Ваш сервис                       xpayment
 планы, лимиты    <--->   PUT  /v2/subscriptions/accounts/{id}   (создать пользователя)
 выдача, оплата           GET  .../{id}/check?capability=...     (есть ли доступ?)
                          POST .../{id}/usage                    (учесть расход)

Для этого API у вас свой ключ: xsub_…. Он выдаётся вместе с проектом подписок и работает только на /v2/subscriptions. Ключи платежей xapi_… и ключи подписок xsub_… не взаимозаменяемы: ключ одного вида на эндпоинтах другого даёт 401.

Подписки сейчас в бете. Условия и поля могут уточняться; актуальный справочник — в документации.

Настройка в кабинете

1. Проект и ключ

Откройте «Подписки» и создайте проект («Новый проект»). Вместе с ним создаётся ключ xsub_…: он показывается один раз, потом виден только префикс. Храните ключ на сервере, как и ключ xapi_….

Ключ можно ротировать: новый ключ начинает работать сразу, а старый продолжает действовать ещё 24 часа, чтобы вы успели обновить сервис. Завершить старый ключ раньше срока можно в настройках проекта.

2. Каталог

На вкладках кабинета вы описываете, что продаёте:

Что Для чего Пример
Возможность Флаг доступа catalog — «Каталог товаров»
Лимит Счётчик с единицей и периодом сброса (нет, день, месяц) orders_m — «Заказы» в месяц
План Набор возможностей и лимитов, собирается из блоков (групп) «Старт» в блоке «Каталог»
Дополнение Что можно докупить к плану seat_extra — «Дополнительный сотрудник»

У каждой сущности есть код, по которому ваш сервис обращается к ней в API, поэтому выбирайте короткие и стабильные коды. План бывает в статусах «черновик», «активный» и «в архиве»; в состав подписки попадают только активные планы.

3. Аккаунты и выдача подписок

Аккаунт — это пользователь или компания вашего продукта. Подписку аккаунту можно:

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

4. Касса и оплата

Подписки оплачиваются счётом Kaspi, который выставляется на телефон аккаунта с кассы проекта. Для этого у аккаунта должен быть указан телефон (иначе API ответит 409 PHONE_REQUIRED), а в проекте выбрана касса: Подключение кассы и ключ API v2.

Как работает автосчёт: за несколько дней до конца периода xpayment выставляет счёт Kaspi и повторяет попытки, пока он не оплачен; оплата продлевает период. Если касса сломана или не выбрана, счёт не уходит, пока вы не исправите её. Деньги идут напрямую на ваш счёт в Kaspi.

API для вашего сервиса

База: https://api.xpayment.kz/v2/subscriptions. Заголовок: Authorization: Bearer xsub_…. Ответы приходят с заголовком Cache-Control: no-store. Тексты ошибок в этом API английские.

Метод Путь Что делает
PUT /accounts/{externalID} Создать или обновить аккаунт
GET /accounts/{externalID} Права аккаунта (entitlements)
GET /accounts/{externalID}/check Проверить одну возможность или лимит
POST /accounts/{externalID}/trial Запустить пробный период
POST /accounts/{externalID}/usage Учесть расход лимита

externalID — ваш идентификатор пользователя: 1–100 символов из A–Z a–z 0–9 . _ : @ + -. В адресе его нужно URL-кодировать (user@mail.kz → user%40mail.kz).

Создать аккаунт

curl -X PUT "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040" \
  -H "Authorization: Bearer xsub_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kazmart.kz", "phone": "+7 701 200 10 30", "email": "admin@kazmart.kz"}'

Все поля необязательны: отсутствующее поле не меняется, null очищает его. Телефон приводится к виду +7XXXXXXXXXX. Ответ 201 (создан) или 200 (обновлён) содержит права аккаунта.

Права аккаунта

GET /accounts/{externalID} возвращает:

{
  "external_id": "shop_1040",
  "name": "Kazmart.kz",
  "status": "active",
  "access": true,
  "until": "2026-12-01",
  "access_ends_at": "2026-12-01T19:00:00Z",
  "period": "month",
  "plans": [{"code": "cat_start", "name": "Старт", "block": "Каталог"}],
  "capabilities": [
    {"code": "catalog", "name": "Каталог товаров",
     "source": {"type": "plan", "code": "cat_start", "name": "Старт", "block": "Каталог"}}
  ],
  "limits": [
    {"limit": "orders_m", "name": "Заказы", "limit_value": 300, "unlimited": false,
     "used": 121, "remaining": 179, "resets_at": "2026-11-30T19:00:00Z"}
  ]
}

status: none (нет подписки), trial, active, canceling (отменена, доступ до конца периода), expired. Поля capabilities и limits заполнены только при access: true. Ответ можно кэшировать не дольше минуты: изменения из кабинета видны со следующего запроса.

Проверка доступа

Для одной проверки удобнее check: укажите ровно одно из capability или limit.

# есть ли возможность
curl "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/check?capability=catalog" \
  -H "Authorization: Bearer xsub_ВАШ_КЛЮЧ"

# хватит ли лимита на 5 единиц
curl "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/check?limit=orders_m&need=5" \
  -H "Authorization: Bearer xsub_ВАШ_КЛЮЧ"

Ответ всегда 200 (даже для неизвестного аккаунта): {"allowed": true, "reason": null, "status": "active", ...}. Если allowed: false, reason объясняет, почему:

reason Значение
account_not_found Такого аккаунта нет
no_subscription У аккаунта нет подписки
expired Срок вышел
not_in_plan Возможности нет в планах аккаунта
limit_not_set В планах нет такого лимита
limit_exhausted Остаток меньше need

Неизвестный код возможности или лимита даёт 404 UNKNOWN_CODE.

Пробный период

curl -X POST "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/trial" \
  -H "Authorization: Bearer xsub_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"plans": ["cat_start"], "addons": [], "period": "month"}'

Аккаунт должен существовать (сначала PUT) и не иметь доступа. Пробный период длится столько, сколько самый длинный пробный период выбранных планов, а period (month или year) задаёт период после него. Ответ 201 содержит права. Типичные ошибки: 404 ACCOUNT_NOT_FOUND, 409 TRIAL_NOT_ALLOWED (уже есть доступ), 409 TRIAL_ALREADY_USED, 409 NO_TRIAL (ни у одного плана нет пробного периода).

Учёт расхода

curl -X POST "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/usage" \
  -H "Authorization: Bearer xsub_ВАШ_КЛЮЧ" \
  -H "X-Idempotency-Key: order-8812-created" \
  -H "Content-Type: application/json" \
  -d '{"limit": "orders_m", "delta": 1}'

Правила:

Лимиты сбрасываются по календарю Казахстана: раз в день, раз в месяц или не сбрасываются.

Общие ошибки и лимиты запросов

HTTP Код Причина
401 UNAUTHORIZED Нет заголовка, ключ неверный или отозван, либо это не xsub_
429 RATE_LIMITED Слишком много запросов; смотрите заголовок Retry-After
500 INTERNAL_ERROR Непредвиденная ошибка

Исходящих вебхуков у подписок нет: ваш сервис сам опрашивает GET /accounts/{id} или check в нужный момент.

Типичная схема внедрения

  1. Опишите тарифы в кабинете: возможности, лимиты, планы и дополнения. Выберите короткие стабильные коды.
  2. Заведите аккаунт при регистрации пользователя: PUT /accounts/{id} с именем, телефоном и email.
  3. Запустите пробный период, если он есть: POST …/trial с кодами планов.
  4. Проверяйте доступ там, где он важен: check?capability=… перед действием или GET /accounts/{id}, если нужны все права разом. Кэшируйте ответ не дольше минуты.
  5. Учитывайте расход: POST …/usage с X-Idempotency-Key, например, order-8812-created. Так повтор из-за таймаута не посчитает расход дважды.
  6. Продлением занимается xpayment: автосчёт Kaspi продлевает период после оплаты, а ваш сервис при следующей проверке увидит новый срок.

Практические советы

Где что смотреть