Как описать тарифы в кабинете и проверять доступ, пробные периоды и расход лимитов через /v2/subscriptions с ключом xsub_….
Если у вас 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.
Подписки сейчас в бете. Условия и поля могут уточняться; актуальный справочник — в документации.
Откройте «Подписки» и создайте проект («Новый проект»). Вместе с ним создаётся ключ xsub_…: он показывается один раз, потом виден только префикс. Храните ключ на сервере, как и ключ xapi_….
Ключ можно ротировать: новый ключ начинает работать сразу, а старый продолжает действовать ещё 24 часа, чтобы вы успели обновить сервис. Завершить старый ключ раньше срока можно в настройках проекта.
На вкладках кабинета вы описываете, что продаёте:
| Что | Для чего | Пример |
|---|---|---|
| Возможность | Флаг доступа | catalog — «Каталог товаров» |
| Лимит | Счётчик с единицей и периодом сброса (нет, день, месяц) | orders_m — «Заказы» в месяц |
| План | Набор возможностей и лимитов, собирается из блоков (групп) | «Старт» в блоке «Каталог» |
| Дополнение | Что можно докупить к плану | seat_extra — «Дополнительный сотрудник» |
У каждой сущности есть код, по которому ваш сервис обращается к ней в API, поэтому выбирайте короткие и стабильные коды. План бывает в статусах «черновик», «активный» и «в архиве»; в состав подписки попадают только активные планы.
Аккаунт — это пользователь или компания вашего продукта. Подписку аккаунту можно:
Вкладки кабинета показывают обзор, список подписок и аккаунтов, платежи, пробные периоды, расход лимитов и аналитику.
Подписки оплачиваются счётом Kaspi, который выставляется на телефон аккаунта с кассы проекта. Для этого у аккаунта должен быть указан телефон (иначе API ответит 409 PHONE_REQUIRED), а в проекте выбрана касса: Подключение кассы и ключ API v2.
Как работает автосчёт: за несколько дней до конца периода xpayment выставляет счёт Kaspi и повторяет попытки, пока он не оплачен; оплата продлевает период. Если касса сломана или не выбрана, счёт не уходит, пока вы не исправите её. Деньги идут напрямую на ваш счёт в Kaspi.
База: 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}'
Правила:
X-Idempotency-Key обязателен (1–100 видимых ASCII-символов). Повтор с тем же ключом и телом вернёт сохранённый ответ и ничего не посчитает; тот же ключ с другим телом даёт 422 IDEMPOTENCY_KEY_REUSED.delta — ненулевое целое в пределах ±10⁹. Отрицательное значение (например, пользователь удалил товар) уменьшает счётчик, но не ниже нуля, и принимается даже без доступа.409 NO_ACCESS). Если оно превысит конечный лимит, запрос отклоняется целиком: 409 LIMIT_EXCEEDED с текущими значениями, ничего не засчитано.200 с полями limit, used, limit_value, unlimited, remaining, resets_at.200 и 409; при 400, 404, 422, 429 и 500 ключ не запоминается, и повтор выполнится заново.Лимиты сбрасываются по календарю Казахстана: раз в день, раз в месяц или не сбрасываются.
| HTTP | Код | Причина |
|---|---|---|
| 401 | UNAUTHORIZED |
Нет заголовка, ключ неверный или отозван, либо это не xsub_ |
| 429 | RATE_LIMITED |
Слишком много запросов; смотрите заголовок Retry-After |
| 500 | INTERNAL_ERROR |
Непредвиденная ошибка |
Исходящих вебхуков у подписок нет: ваш сервис сам опрашивает GET /accounts/{id} или check в нужный момент.
PUT /accounts/{id} с именем, телефоном и email.POST …/trial с кодами планов.check?capability=… перед действием или GET /accounts/{id}, если нужны все права разом. Кэшируйте ответ не дольше минуты.POST …/usage с X-Idempotency-Key, например, order-8812-created. Так повтор из-за таймаута не посчитает расход дважды.usage: он атомарный и не даст превысить конечный лимит.409 LIMIT_EXCEEDED и 409 NO_ACCESS — штатные ситуации, а не сбои; покажите пользователю предложение сменить тариф.xsub_… для платежей и ключ xapi_… для подписок.