Partner API ApiPay

POST /api/partner/organizations — создать организацию мерчанта

Идемпотентно по external_id — повторный POST вернёт существующую org. Лимит 10/min. Ответ 201 (создана) / 200 (идемпотентный повтор).

curl -X POST https://api.apipay.kz/api/partner/organizations \
  -H 'X-Partner-Key: <X-Partner-Key>' -H 'Content-Type: application/json' \
  -d '{"has_catalog":false,"external_id":"crm-client-42"}'

{ "success": true, "organization": {
  "id": 50, "name": "ТОО Example", "idn": "123456789012",
  "status": "verified", "sandbox_mode": true, "has_catalog": false,
  "kaspi_connected": true, "session_mode": "self", "external_id": "crm-client-42",
  "origin": "created", "payment_status": "active", "has_active_payment": true,
  "created_at": "2026-05-16T10:00:00+05:00" } }

Опциональное поле name (max 255): пусто → автоген PARTNER_<id>_<ts>, позже подменяется именем из Kaspi на verify-otp.

GET /api/partner/organizations — список организаций (мониторинг)

Мониторинг своих организаций: список с пагинацией. В карточке есть origin. Query: per_page (1–100, def 25), page (def 1), status (pending|verified|suspended), sandbox_mode (true/false/1/0), is_test (true/false/1/0), kyc_status (required|submitted|needs_changes|approved|blocked), search (LIKE-поиск по name / external_id / idn, max 255). Фильтры применяются до пагинации. Ключ data — алиас organizations (back-compat).

kyc_status принимает один статус или список через запятую: ?kyc_status=required,needs_changes — это клиенты, которым анкету нужно заполнить или переделать. Неизвестное значение и пустая строка отбиваются 422, молча они не игнорируются. is_test — не синоним sandbox_mode: у боевой организации sandbox_mode остаётся true до первой успешной авторизации кассира.

{ "success": true, "organizations": ["<card>"], "data": ["<card>"],
  "current_page": 1, "per_page": 25, "total": 42, "last_page": 2 }

GET /api/partner/organizations/{id} — карточка организации

Получить карточку конкретной организации. → { "success": true, "organization": <card> }

DELETE /api/partner/organizations/{id} — отвязать организацию

Деактивирует все API-ключи org и делает soft-delete. → { "success": true }

POST /api/partner/organizations/{id}/api-key — выдать X-API-Key мерчанту

Создать/перегенерировать ключ мерчанта + webhook. webhook_url проходит SSRF-валидацию (приватные IP → 422). Повторный вызов НЕ безопасен для ретрая: он перевыпускает ключ — ранее выданные X-API-Key и webhook_secret перестают действовать сразу, и работающая интеграция мерчанта начнёт получать 401. Повторяйте только при плановой ротации. Дальше мерчант работает этим ключом по документации для мерчантов (/docs).

На боевой организации webhook_url должен быть адресом на домене: IP-адрес или временный туннель (ngrok и подобные) отклоняются с 422. В ответе приходит webhook_review_status — пока он не approved, события на этот адрес мерчанту не доставляются.

curl -X POST https://api.apipay.kz/api/partner/organizations/501/api-key \
  -H 'X-Partner-Key: <X-Partner-Key>' -H 'Content-Type: application/json' \
  -d '{"name":"CRM key","webhook_url":"https://crm.example.kz/sub/501/webhook"}'

{ "success": true, "key": "<X-API-Key, один раз>", "key_id": 900,
  "webhook_url": "https://crm.example.kz/sub/501/webhook",
  "webhook_secret": "whsec_yyyy", "is_org_default": true, "regenerated": false }

POST .../kaspi-auth/init — Шаг 1

Инициировать авторизацию кассира Kaspi. Body {} (опц. { "force": true }). force: true — переавторизация поверх активной сессии (смена кассира). Без force по уже подключённой org → 409 already_connected.

{ "success": true, "process_id": "SANDBOX-<uuid>", "process_status": "phone_required" }

POST .../kaspi-auth/send-phone — Шаг 2

Body { "cashier_phone": "7XXXXXXXXXX" }. Kaspi отправляет SMS на номер кассира. Успех → { "success": true, "process_status": "otp_required" }.

Ошибки: invalid_phone (422 — неверный формат), not_cashier (422 — номер не «чистый кассир»), not_registered (422 — не зарегистрирован кассиром в Kaspi), no_process (409 — нет активного процесса: вызовите init / он истёк), context_expired (409 — Kaspi-контекст протух, ~10 мин: init заново + повтор send-phone), cashier_unavailable (409 — кассира сейчас нельзя подключить; причина не раскрывается, повтор не поможет — направьте мерчанта в поддержку ApiPay), rate_limited (429 — за сутки с аккаунта пробовали слишком много разных номеров кассиров; окно суточное, выждите время из Retry-After / retry_after_seconds; уже подключённые кассиры этого владельца в счётчик не входят, переавторизация рабочей точки лимитом не блокируется), sms_failed (502), kaspi_busy (503 — Kaspi недоступен; повторите примерно через минуту, окна в ответе нет). В sandbox not_cashier / sms_failed / not_registered / context_expired / kaspi_busy эмулируются магическими номерами (см. раздел Sandbox); cashier_unavailable и rate_limited в песочнице не воспроизводятся: тестовая организация идёт мок-путём. Заложите обработку заранее — на 409 нейтральное сообщение мерчанту и отправка в поддержку, на 429 пауза по Retry-After.

POST .../kaspi-auth/verify-otp — Шаг 3

Body { "otp": "0000" } (4–6 цифр). Подтвердить код из SMS.

• Успех 200: { "success": true, "mode": "self", "organization": <card>, "process_status": "active" } — org → status: verified.
• Неверный код 200: { "success": false, "error": "invalid_otp", "process_status": "otp_required" } — повторяемо, сессия жива.
• cashier_unavailable (409): кассира сейчас нельзя подключить; причина не раскрывается, повтор не поможет — направьте мерчанта в поддержку ApiPay.
• В sandbox код 0000 = успех, любой другой = invalid_otp.

GET .../kaspi-auth/status — статус

Текущий статус авторизации кассира. status: none | pending | active | expired. process_status: idle | phone_required | otp_required | active | failed (выводится из persisted-сессии).

{ "success": true, "status": "active", "process_status": "active",
  "kaspi_connected": true, "expires_at": "2026-06-16T00:00:00+05:00" }

GET /api/partner/tariff-plans — каталог тарифов

Общий каталог (без привязки к орг): 4 тарифа + 16 планов (4 × 1/3/6/12 мес). → { "success": true, "tiers": [...], "plans": [...] }

GET /api/partner/organizations/{id}/tariff — статус подписки мерчанта

Снимок подписки. Нет тарифа → status: "none" (не 404). next_payment.amount — всегда.

{ "success": true, "tariff": {
  "status": "none|trial|active|expired", "tier": "business", "is_trial": false,
  "started_at": "2026-06-20T10:00:00+05:00", "expires_at": "2026-09-20T10:00:00+05:00",
  "days_remaining": 92, "auto_renew": false,
  "last_payment": { "amount": 71250, "paid_at": "...", "period_months": 3, "tier": "business", "status": "completed" },
  "next_payment": { "due_at": "2026-09-20T10:00:00+05:00", "amount": 71250, "tier": "business" } } }

POST /api/partner/organizations/{id}/tariff/pay — оплатить тариф

Body: { "tier_id": "business", "period_months": 3, "phone": "8XXXXXXXXXX", "set_billing_phone": false } (phone — плательщик, формат 8XXXXXXXXXX; НЕ кассир). Боевая org — только production-партнёру (иначе 403 production_access_required); тестовая → мгновенная мок-активация (201, status:"completed", self_api_invoice_id:null).

{ "success": true, "payment": {
  "id": 42, "amount": 71250, "status": "pending", "tier": "business", "period_months": 3,
  "self_api_invoice_id": 778899, "external_id": "partner-tariff-501-1716900000",
  "paid_at": null, "expires_at": null, "created_at": "2026-06-20T10:00:00+05:00", "failure_reason": null } }

Ошибки: 403 production_access_required, 404 organization_not_found, 409 tariff_payment_pending (в теле — существующий payment), 422 invalid_tariff_plan, 429 tariff_payment_cooldown (+Retry-After, retry_after_seconds:1800), 503 tariff_payment_unavailable (+Retry-After, retry_after_seconds:30).

POST /api/partner/organizations/{id}/tariff/assign — назначить тариф без оплаты

Назначение тарифа без оплаты со стороны мерчанта: счёт не выставляется, с организации ничего не списывается (payment.amount: 0, status: "completed"). Ручка доступна только партнёрам, которым ApiPay включил режим выдачи assignment; в режиме payment она отвечает 403 assignment_not_enabled. Боевая org — только production-партнёру. Расчёты с ApiPay по назначенным тарифам ведутся отдельно, вне API.

Body: { "tier_id": "business", "period_months": 3 }

{ "success": true, "already_assigned": false, "payment": {
  "id": 44, "amount": 0, "status": "completed", "tier": "start",
  "period_months": 3, "self_api_invoice_id": null, "external_id": null,
  "paid_at": "2026-08-13T10:00:00+05:00", "expires_at": "2026-11-13T10:00:00+05:00",
  "created_at": "2026-08-13T10:00:00+05:00", "failure_reason": null } }

201 — тариф назначен; 200 с already_assigned: true — запрошенный период уже покрыт назначением того же тарифа, второго срока и второго платежа не появляется (ретрай CRM безопасен). Назначение поверх активного тарифа не сжигает остаток: новый срок считается от текущего expires_at, если он в будущем. Актуальные tier и expires_at читайте из GET .../tariff, а не считайте у себя.

Ошибки: 403 assignment_not_enabled (у вас включён режим оплаты) / production_access_required / forbidden; 404 organization_not_found; 409 test_organization, tariff_payment_pending (есть неоплаченный счёт тарифа), custom_tariff_locked (у организации индивидуальные условия), hard_limited_org (действует ограничение по лимиту счетов, снимается на стороне ApiPay); 422 tier_not_in_partner_grid (тариф вне вашей сетки), 422 assignment_horizon_exceeded (суммарный срок дальше 12 месяцев).

GET /api/partner/organizations/{id}/tariff/payments и /{paymentId}

Список: { "success": true, "data": [ <payment> ] } (по убыванию даты, триальные amount=0 исключены). Один: { "success": true, "payment": <payment> }; неизвестный paymentId → 404 tariff_payment_not_found. <payment>: { id, amount, status, tier, period_months, self_api_invoice_id, external_id, paid_at, expires_at, created_at, failure_reason }.

GET /api/partner/health — health аккаунта партнёра

Агрегат по всем вашим организациям. Блок account отдаётся всегда актуальным, остальные агрегаты кэшируются на несколько секунд.

{ "success": true, "api": {"status":"ok"},
  "account": {"mode":"production","type":"operating",
              "api_access_status":"granted","tariff_billing_mode":"assignment",
              "inbound_sync":{"enabled":true,"secret_configured":true,
                              "secret_hint":"••••a1b2","accepting":true}},
  "organizations": {"total":12,"kaspi_connected":9,"needs_reauth":1,"tariff_active":7,"tariff_expired":2,"on_trial":3,
                    "kyc":{"required":2,"submitted":1,"needs_changes":0,"approved":9,"blocked":0}},
  "webhooks": {"delivered_24h":340,"failed_24h":5,"success_rate":98.6},
  "rate_limits": {"partner_api_per_min":120} }

account — состояние самого аккаунта: mode (sandbox|production), type (referral|operating), api_access_status (none|pending|granted|rejected; условие перехода в production — granted) и tariff_billing_mode (payment — тариф мерчанта оплачивается через .../tariff/pay или .../tariff/invoice; assignment — вы назначаете его без оплаты через .../tariff/assign).

account.inbound_sync — состояние приёма входящих синхронизаций подписки: enabled (тумблер), secret_configured (секрет задан и читается), secret_hint (последние 4 символа под маской либо null), accepting (дверь открыта).

organizations.kyc — раскладка клиентов по статусу анкеты. Кто именно — фильтром GET /api/partner/organizations?kyc_status=….

GET /api/partner/organizations/{id}/kyc — статус анкеты

{ "success": true, "kyc": {
  "status": "needs_changes", "required_action": "fix_and_resubmit",
  "can_submit": true, "comment": "Скриншот витрины нечитаемый",
  "submitted_at": "2026-08-14T12:00:00+05:00", "submitted_via": "invite" } }

Поллить каждую организацию не нужно. Сколько клиентов в каком состоянии — в GET /api/partner/health (organizations.kyc); кто именно — фильтром GET /api/partner/organizations?kyc_status=required,needs_changes. Статус каждой организации есть и в её карточке — поле kyc_status.

POST /api/partner/organizations/{id}/kyc/invite — выдать клиенту ссылку на анкету

{ "success": true, "invite_url": "https://apipay.kz/invite/2f6c…",
  "expires_at": "2026-08-29T12:00:00+05:00" }

Передайте ссылку мерчанту — он заполнит и подтвердит анкету сам, аккаунт в ApiPay ему для этого не нужен.

Передавайте адрес ровно так, как он пришёл в invite_url, — не собирайте его у себя из токена. Тем же механизмом мерчанту выдаётся и ссылка на подключение кассира, а адреса у ссылок разного назначения не обязаны совпадать.

Отказы: 409 test_organization (тестовой организации ссылка не выдаётся), 409 kyc_already_submitted (анкета уже подана или проверена — смотрите её статус в GET .../kyc), 403 forbidden, 404 organization_not_found, 429 — превышена частота выдачи ссылок.

PUT /api/partner/organizations/{id}/subscription

Заголовки: X-Partner-Key, X-ApiPay-Timestamp (unix-секунды) и X-ApiPay-Signature: sha256=<подпись>. Метка времени должна быть свежей: расхождение в несколько минут отклоняется.

Схема подписи — строка из четырёх частей через точку: {timestamp}.{МЕТОД}.{путь}.{сырое тело}, например 1786000000.PUT./api/partner/organizations/829/subscription.{"state":"active",…}. Метод и путь входят в подпись намеренно: организация приезжает в пути, и подпись по одному телу позволила бы переиграть перехваченный запрос на другую вашу организацию, не изменив ни байта тела.

{ "state": "active", "tier": "business", "paid_through": "2026-09-12T18:50:12+05:00",
  "cause": "autoprolongation", "trial": false,
  "external_tariff_id": "23ca69d4-2657-40c4-8ba1-6ce24ddeac2e", "partner_context": {} }

{ "success": true, "sync_id": 8123, "result": "applied",
  "organization_id": 829, "external_id": "crm-client-42",
  "applied": { "tier": "business", "tier_label": "Бизнес", "daily_limit": 100,
               "limits_source": "partner_grid",
               "expires_at": "2026-09-12T23:50:12+05:00", "status": "active" },
  "ignored": { "daily_limit": { "sent": 999, "applied": 100 } } }

result: applied — тариф изменён; unchanged — уже соответствует (в том числе если ваша дата не дальше текущей); noted — приостановка или отмена зафиксирована, тариф не тронут. Блок applied — что реально действует у мерчанта после синхронизации.

Инварианты — тариф двигается только вперёд и только вверх:

• более ранняя paid_through не укорачивает оплаченный срок → 200, result: unchanged;
• понижение тира отклоняется (409 tier_downgrade_not_allowed) — понижает человек;
• дальше чем на 12 месяцев вперёд назначить нельзя (422 assignment_horizon_exceeded);
• отзыва тарифа через этот эндпоинт нет: suspended и cancelled фиксируются в журнале, срок не трогают, выданный период истечёт сам. Поэтому синхронизируйте помесячно — тогда приостановка у вас становится приостановкой у нас максимум через месяц.

Скоуп организаций здесь шире, чем у остальных машинных ручек: доступны и созданные вами, и заклеймленные. Исключение — заклеймленная организация, которая оплачивает тариф самостоятельно: 409 claimed_paying_organization. Такой перевод оформляет ApiPay, потому что владение при claim не менялось.

SECRET='<секрет приёма>'
KEY='<X-Partner-Key>'
ORG=829
API_PATH="/api/partner/organizations/$ORG/subscription"
BODY='{"state":"active","tier":"business","paid_through":"2026-09-12T18:50:12+05:00","cause":"autoprolongation"}'
TS=$(date +%s)
SIG=$(printf '%s.PUT.%s.%s' "$TS" "$API_PATH" "$BODY" \
      | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)

curl -X PUT "https://api.apipay.kz$API_PATH" \
  -H "X-Partner-Key: $KEY" \
  -H "X-ApiPay-Timestamp: $TS" \
  -H "X-ApiPay-Signature: sha256=$SIG" \
  -H 'Content-Type: application/json' \
  --data-raw "$BODY"

GET /api/partner/subscription-syncs и /{sync}

Журнал: что мы приняли и почему отказали — по каждому вашему вызову, включая отказы. Карточка одной записи дополнительно отдаёт исходное тело запроса (payload); в списке его нет.

Query: organization_id, result (applied|unchanged|noted|rejected|failed), state (active|suspended|cancelled), окно from/to по времени приёма (голая дата трактуется в Asia/Almaty; to не раньше from, иначе 422), per_page (1–100, def 25), page (def 1).

Неизвестное значение фильтра — 422, а не пустая страница: молчаливый ноль неотличим от «вы нам ничего не присылали». Чужой organization_id, наоборот, даёт пустую страницу — существование чужих записей мы не подтверждаем.

{ "success": true, "data": [
  { "id": 8123, "organization_id": 829, "state": "active", "cause": "autoprolongation",
    "requested_tier": "business", "requested_paid_through": "2026-09-12T18:50:12+05:00",
    "applied_tier": "business", "applied_expires_at": "2026-09-12T23:50:12+05:00",
    "result": "applied", "outcome_code": "applied", "http_status": 200,
    "external_tariff_id": "23ca69d4-2657-40c4-8ba1-6ce24ddeac2e",
    "received_at": "2026-08-12T18:50:13+05:00" } ],
  "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }

outcome_code — точная причина отказа или успеха: слаг ошибки либо applied/unchanged/noted. Неизвестная или чужая запись в карточке → 404 sync_not_found.

curl "https://api.apipay.kz/api/partner/subscription-syncs?result=rejected&from=2026-08-01" \
  -H "X-Partner-Key: $KEY"