How to describe plans in the dashboard and check access, trials, and limit usage through /v2/subscriptions with an xsub_… key.
If you run a SaaS, an app, a club, or a school and users pay for access by plans, you need to store three things: what each plan includes, until when it is paid, and how much of a limit has been used. The “Подписки” (Subscriptions) section takes this on. You describe plans in the dashboard, and your service asks through the API: “what is available to this user?”.
xpayment keeps track of:
This is not the same as a payment through the API: a payment accepts money once, while a subscription answers the question “does the user have access right now”. The two are connected: an invoice for a subscription is an ordinary Kaspi phone invoice.
"Подписки" dashboard Your service xpayment
plans, limits <---> PUT /v2/subscriptions/accounts/{id} (create a user)
grants, payment GET .../{id}/check?capability=... (is there access?)
POST .../{id}/usage (record usage)
For this API you have your own key: xsub_…. It is issued together with a subscriptions project and works only on /v2/subscriptions. Payment keys xapi_… and subscription keys xsub_… are not interchangeable: a key of one kind on the endpoints of the other gives 401.
Subscriptions are in beta for now. Terms and fields may be refined; the current reference is in the documentation.
Open Подписки (Subscriptions) and create a project (“Новый проект”, New project). Together with it an xsub_… key is created: it is shown once, afterwards only the prefix is visible. Keep the key on the server, like the xapi_… key.
The key can be rotated: the new key works at once, while the old one keeps working for another 24 hours so you have time to update your service. You can end the old key earlier in the project settings.
On the dashboard tabs you describe what you sell:
| What | What it is for | Example |
|---|---|---|
| Capability | An access flag | catalog — “Product catalog” |
| Limit | A counter with a unit and a reset period (none, day, month) | orders_m — “Orders” per month |
| Plan | A set of capabilities and limits, assembled from blocks (groups) | “Start” in the “Catalog” block |
| Add-on | What can be bought on top of a plan | seat_extra — “Extra employee” |
Every entity has a code that your service uses in the API, so choose short, stable codes. A plan can be a draft, active, or archived; only active plans can make up a subscription.
An account is a user or company of your product. A subscription can be:
The dashboard tabs show the overview, the list of subscriptions and accounts, payments, trials, limit usage, and analytics.
Subscriptions are paid with a Kaspi invoice issued to the account’s phone from the project’s register. For that the account must have a phone number (otherwise the API answers 409 PHONE_REQUIRED), and the project must have a register chosen: Connecting a cash register and getting an API v2 key.
How the auto-invoice works: a few days before the end of the period xpayment issues a Kaspi invoice and keeps retrying until it is paid; payment extends the period. If the register is broken or not chosen, the invoice is not sent until you fix it. The money goes straight to your Kaspi account.
Base: https://api.xpayment.kz/v2/subscriptions. Header: Authorization: Bearer xsub_…. Responses come with the header Cache-Control: no-store. Error texts in this API are in English.
| Method | Path | What it does |
|---|---|---|
PUT |
/accounts/{externalID} |
Create or update an account |
GET |
/accounts/{externalID} |
The account’s entitlements (entitlements) |
GET |
/accounts/{externalID}/check |
Check one capability or limit |
POST |
/accounts/{externalID}/trial |
Start a trial |
POST |
/accounts/{externalID}/usage |
Record usage of a limit |
externalID is your user identifier: 1–100 characters from A–Z a–z 0–9 . _ : @ + -. In the address it must be URL-encoded (user@mail.kz → user%40mail.kz).
curl -X PUT "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040" \
-H "Authorization: Bearer xsub_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Kazmart.kz", "phone": "+7 701 200 10 30", "email": "admin@kazmart.kz"}'
All fields are optional: a missing field is left unchanged, and null clears it. The phone is normalized to the form +7XXXXXXXXXX. The answer 201 (created) or 200 (updated) contains the account’s entitlements.
GET /accounts/{externalID} returns:
{
"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": "Start", "block": "Catalog"}],
"capabilities": [
{"code": "catalog", "name": "Product catalog",
"source": {"type": "plan", "code": "cat_start", "name": "Start", "block": "Catalog"}}
],
"limits": [
{"limit": "orders_m", "name": "Orders", "limit_value": 300, "unlimited": false,
"used": 121, "remaining": 179, "resets_at": "2026-11-30T19:00:00Z"}
]
}
status: none (no subscription), trial, active, canceling (cancelled, access until the end of the period), expired. The capabilities and limits fields are filled only when access: true. You can cache the response for no longer than a minute: changes from the dashboard are visible from the next request.
For a single check, check is handier: specify exactly one of capability or limit.
# is a capability available
curl "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/check?capability=catalog" \
-H "Authorization: Bearer xsub_YOUR_KEY"
# is there enough limit for 5 units
curl "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/check?limit=orders_m&need=5" \
-H "Authorization: Bearer xsub_YOUR_KEY"
The answer is always 200 (even for an unknown account): {"allowed": true, "reason": null, "status": "active", ...}. If allowed: false, reason explains why:
reason |
Meaning |
|---|---|
account_not_found |
There is no such account |
no_subscription |
The account has no subscription |
expired |
The term has ended |
not_in_plan |
The capability is not in the account’s plans |
limit_not_set |
The plans have no such limit |
limit_exhausted |
The remainder is less than need |
An unknown capability or limit code gives 404 UNKNOWN_CODE.
curl -X POST "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/trial" \
-H "Authorization: Bearer xsub_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"plans": ["cat_start"], "addons": [], "period": "month"}'
The account must exist (PUT first) and have no access. The trial lasts as long as the longest trial of the chosen plans, and period (month or year) sets the period after it. The 201 response contains the entitlements. Typical errors: 404 ACCOUNT_NOT_FOUND, 409 TRIAL_NOT_ALLOWED (access already exists), 409 TRIAL_ALREADY_USED, 409 NO_TRIAL (none of the plans has a trial).
curl -X POST "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/usage" \
-H "Authorization: Bearer xsub_YOUR_KEY" \
-H "X-Idempotency-Key: order-8812-created" \
-H "Content-Type: application/json" \
-d '{"limit": "orders_m", "delta": 1}'
Rules:
X-Idempotency-Key is required (1–100 visible ASCII characters). A repeat with the same key and body returns the stored answer and counts nothing; the same key with a different body gives 422 IDEMPOTENCY_KEY_REUSED.delta is a non-zero integer within ±10⁹. A negative value (for example, the user deleted a product) lowers the counter, but not below zero, and is accepted even without access.409 NO_ACCESS). If it would exceed a finite limit, the request is rejected entirely: 409 LIMIT_EXCEEDED with the current values, nothing counted.200 with the fields limit, used, limit_value, unlimited, remaining, resets_at.200 and 409 answers are stored; on 400, 404, 422, 429, and 500 the key is not remembered, and a repeat is executed again.Limits reset by the Kazakhstan calendar: daily, monthly, or never.
| HTTP | Code | Cause |
|---|---|---|
| 401 | UNAUTHORIZED |
The header is missing, the key is wrong or revoked, or it is not an xsub_ key |
| 429 | RATE_LIMITED |
Too many requests; see the Retry-After header |
| 500 | INTERNAL_ERROR |
An unexpected error |
Subscriptions have no outgoing webhooks: your service polls GET /accounts/{id} or check when it needs to.
PUT /accounts/{id} with a name, phone, and email.POST …/trial with plan codes.check?capability=… before an action, or GET /accounts/{id} if you need all entitlements at once. Cache the answer for no more than a minute.POST …/usage with X-Idempotency-Key, for example order-8812-created. That way a retry after a timeout does not count the usage twice.usage response: it is atomic and will not let a finite limit be exceeded.409 LIMIT_EXCEEDED and 409 NO_ACCESS are normal situations, not failures; offer the user a plan change.xsub_… key for payments or the xapi_… key for subscriptions.