Partner API ApiPay

Server-to-server API для партнёров-интеграторов (CRM, маркетплейсы, white-label-кассы). Партнёр онбордит своих мерчантов, авторизует их Kaspi-кассы и выдаёт им платёжный ключ X-API-Key — всё программно, из своей системы.

Платёжные операции, webhook-события и проверка HMAC живут в документации для мерчантов (/docs) и здесь не дублируются. Привязку кассира перед боевым подключением можно прогнать в песочнице партнёра — детерминированно, без единого реального вызова Kaspi и без SMS.

1. Базовые URL

2. Ключи аутентификации

Релевантны API ровно два ключа.

X-Partner-Key выдаётся в партнёрском кабинете; ротация ключа и переключение sandbox/production — тоже в кабинете (фронт), не через API.

3. Partner API (X-Partner-Key)

Префикс /api/partner. Лимит группы — 120 req/min на партнёра. Server-to-server: создавайте организации мерчантов, авторизуйте кассира, мониторьте свои организации и выдавайте X-API-Key мерчанту.

curl -X POST https://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",
  "payment_status": "active", "has_active_payment": true,
  "created_at": "2026-05-16T10:00:00+00:00" } }

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

curl -X POST https://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 }

Авторизация кассира Kaspi (3 шага)

Префикс /api/partner/organizations/{id}/kaspi-auth. process_id живёт 10 минут — шаги send-phone и verify-otp нужно выполнить в этом окне. Боевая org доступна только production-партнёру (иначе 403 production_access_required); тестовая org всегда идёт мок-путём.

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

{ "success": true, "status": "active", "kaspi_connected": true, "expires_at": "..." }

4. Карточка организации <card>

{
  "id": 50, "name": "ТОО Example", "idn": "123456789012",
  "status": "pending|verified|suspended",
  "sandbox_mode": false, "has_catalog": false, "kaspi_connected": true,
  "session_mode": "self", "external_id": "crm-client-42",
  "payment_status": "none|active|expired",
  "payment_expires_at": "2026-06-16T00:00:00+00:00",
  "has_active_payment": false, "created_at": "2026-05-16T10:00:00+00:00"
}

5. Sandbox — отладка привязки кассира

Песочница партнёра детерминированно эмулирует привязку кассира: ни одного реального вызова Kaspi, ни одной SMS. Магические номера на send-phone подменяют ответ Kaspi на фиксированный; любой другой валидный номер 7XXXXXXXXXX трактуется как «обычный» (success). Тестовая организация архитектурно не может стать боевой.

Магические значения (только привязка кассира):

Сценарии тестирования

Сценарий 1 — успешная привязка (happy path)

• POST /organizations {"external_id":"test-1"} → org.id
• POST .../{id}/kaspi-auth/init → process_id
• POST .../send-phone {"cashier_phone":"77770000010"} → success
• POST .../verify-otp {"otp":"0000"} → org status: verified
• POST .../{id}/api-key → X-API-Key мерчанта (дальше — по /docs)

Сценарий 2 — номер не кассир

• POST .../send-phone {"cashier_phone":"77770000011"} → 422 not_cashier
• Покажите клиенту инструкцию по добавлению роли «Кассир» в Kaspi.

Сценарий 3 — сбой отправки SMS

• POST .../send-phone {"cashier_phone":"77770000012"} → 502 sms_failed
• Обработайте как временную ошибку — предложите повтор.

Сценарий 4 — неверный код из SMS

• POST .../send-phone {"cashier_phone":"77770000010"} → success
• POST .../verify-otp {"otp":"1234"} → { "success": false, "error": "invalid_otp" } — повторяемо
• Повторите verify-otp с кодом 0000 — сессия остаётся живой.

6. Лимиты

7. Полный E2E (sandbox)

Партнёрский онбординг до выдачи X-API-Key:

1. Получите X-Partner-Key в партнёрском кабинете (фронт).
2. POST /api/partner/organizations {external_id} → org.id
3. POST .../{id}/kaspi-auth/init → process_id
4. POST .../{id}/kaspi-auth/send-phone {"cashier_phone":"77770000010"} → success
5. POST .../{id}/kaspi-auth/verify-otp {"otp":"0000"} → org status: verified
6. POST .../{id}/api-key → X-API-Key мерчанта + webhook_secret
7. Мерчант создаёт счета этим X-API-Key — по документации для мерчантов (/docs).
8. Мониторьте свои организации: GET /api/partner/organizations.

8. Webhooks и HMAC

Партнёр задаёт webhook_url при выдаче X-API-Key. Формат событий и проверка HMAC-подписи описаны в документации для мерчантов (/docs) — здесь не дублируются.

9. FAQ

Как получить доступ?

X-Partner-Key выдаётся в партнёрском кабинете (фронт). Sandbox — сразу self-service. Production (реальный Kaspi-auth и mode=production) — после ручного одобрения админом; переключение режима тоже в кабинете.

Что покрывает песочница партнёра?

Онбординг мерчанта и привязку кассира — детерминированно, без реального Kaspi и SMS (магические номера). Тестирование счетов/возвратов/webhooks — это отдельная песочница мерчанта, см. /docs.

Где платёжные операции и webhooks?

В документации для мерчантов /docs. Партнёр задаёт webhook_url при выдаче X-API-Key, а формат событий и проверку HMAC мерчант (и ваш сервер) берёт из /docs.