Кабинетте тарифтерді қалай сипаттап, xsub_… кілтімен /v2/subscriptions арқылы қолжетімділікті, сынақ мерзімдерін және лимит шығынын тексеруге болады.
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 — сіздің пайдаланушы идентификаторыңыз: A–Z a–z 0–9 . _ : @ + - таңбаларынан 1–100 таңба. Мекенжайда оны 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, ештеңе есептелмейді.limit, used, limit_value, unlimited, remaining, resets_at өрістері бар 200.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}.POST …/trial.check?capability=… немесе барлық құқық бірден қажет болса, GET /accounts/{id}. Жауапты бір минуттан артық кэштемеңіз.X-Idempotency-Key бар POST …/usage, мысалы, order-8812-created. Сонда тайм-аутқа байланысты қайталау шығынды екі рет санамайды.usage жауабы бойынша қабылдаңыз: ол атомарлы және шектеулі лимиттен асуға жол бермейді.409 LIMIT_EXCEEDED және 409 NO_ACCESS — ақау емес, қалыпты жағдайлар; пайдаланушыға тарифті ауыстыруды ұсыныңыз.xsub_… кілтін төлемдер үшін, xapi_… кілтін жазылымдар үшін қолданбаңыз.