> Источник: https://apipay.kz/guides/api-klyuch-i-webhook-secret · Обновлено: 2026-09-26 · apipay.kz
> ApiPay — независимый сервис приёма платежей поверх вашего Kaspi Pay.

# API-ключ и вебхук-секрет ApiPay: в чём разница?

**TL;DR.** Это два разных credential'а с противоположными направлениями. **API-ключ** — ваш пропуск К нам: кладётся в заголовок `X-API-Key` каждого запроса к API (лимит 200 запросов/мин на ключ). **Вебхук-секрет** — проверка того, что К вам пришли действительно мы: им вы считаете HMAC-подпись входящего вебхука и сравниваете с заголовком `X-Webhook-Signature`; в запросах он **никогда не отправляется** — ни вами, ни нами. Оба показываются целиком **один раз** — при создании/генерации; дальше видна только маска (`key_hint`). Ключ жёстко привязан к организации: sandbox-ключи не работают с боевой организацией.

## Коротко

| | API-ключ | Вебхук-секрет |
|---|---|---|
| Направление | Ваши запросы → ApiPay | Вебхуки ApiPay → ваш сервер |
| Где используется | Заголовок `X-API-Key` в каждом запросе | Локальная проверка подписи `X-Webhook-Signature: sha256=<hex>` (HMAC-SHA256 по raw body) |
| Передаётся ли по сети | Да, в каждом вашем запросе | **Нет, никогда** — только результат HMAC |
| Где взять | Кабинет → Настройки → «Подключение» → создать | Там же, только после сохранения `webhook_url`: экран «Готово» при создании ключа с адресом или карточка ключа → «Ещё» → «Создать секретный ключ подписи» |
| Показывается целиком | Один раз при создании; потом `key_hint` (хвост) | Один раз при генерации; потом маска |
| Перегенерация | `regenerate` — старый ключ сразу мёртв | `regenerate-secret` — старый секрет сразу мёртв |
| Привязка | Жёстко к организации (`organization_id`) | К тому же API-ключу (пара «URL + секрет» живёт на ключе) |

## Роли

Оба — длинные секретные строки из настроек, но роли противоположные:

- **API-ключ отвечает на вопрос «кто ко мне пришёл?» для ApiPay.** Вы выставляете счёт → кладёте ключ в `X-API-Key` → мы понимаем, чья это организация.
- **Вебхук-секрет отвечает на тот же вопрос для вас.** Мы присылаем вебхук об оплате → вы считаете HMAC от сырого тела запроса своим секретом → сверяете с заголовком `X-Webhook-Signature`. Совпало — это точно ApiPay, а не злоумышленник, слепивший фейковый «paid».

Две зеркальные ошибки:

1. **Подписывают исходящие запросы секретом** (кладут его в `X-API-Key` или городят HMAC на POST /invoices) → получают `401`. Ваши запросы к API подписывать не нужно — только ключ в заголовке.
2. **Проверяют вебхук API-ключом** → подпись «не сходится» при идеально правильном коде. HMAC считается от вебхук-секрета. Код проверки на Node/Python/PHP — в «[Как настроить вебхуки ApiPay](/guides/nastroyka-webhookov-apipay)».

## Где взять API-ключ

На главной раскройте **«Подключить сайт или программу» → «Получить API-ключ»**. Диалог откроется на этой же странице. В нём видна выбранная организация и уже подставлено название «Моё подключение» — его можно изменить. Тот же диалог доступен в **Настройки → «Подключение» → «Создать новый ключ»**.

Нажмите «Создать ключ», скопируйте ключ в защищённые настройки приложения и подтвердите **«Я сохранил ключ»**. Полный ключ показывается один раз. Не отправляйте его в чат или ИИ-помощнику. Готовая инструкция для ИИ раскрывается отдельно и не содержит ключей, секретов или адреса вашего webhook.

Адрес уведомлений необязателен при создании. По умолчанию выбран вариант «Быстрый старт»: программа узнаёт об оплате, сама запрашивая статус счёта `GET /invoices/{id}` с сервера, и секрет подписи ей не нужен. Для ручного выставления счетов в кабинете не нужны ни ключ, ни webhook. Когда программе понадобятся автоматические уведомления, откройте «Настроить уведомления об оплате» на главной: выберите подключение, укажите адрес и проверьте уведомление. Существующий секрет при редактировании адреса автоматически не перевыпускается.

Ключ принадлежит выбранной организации. При смене режима той же организации ключ сохраняется; ключ другой организации к ней доступа не даёт.

## Где взять вебхук-секрет

Секрет нужен, только если к ключу подключены уведомления (webhook). Он живёт **на API-ключе** и появляется только после того, как у ключа сохранён `webhook_url`:

- **Адрес указан при создании ключа** (вариант «Уведомления на мой сервер (webhook)») — секрет выпускается сразу и показывается один раз на экране «Готово».
- **Адрес добавлен позже:**
  1. Откройте ключ в разделе **Настройки → «Подключение»**.
  2. Меню **«Ещё»** → **«Подключить уведомления»** (или кнопка **«Изменить»**): впишите `webhook_url` — публичный HTTPS постоянного домена вашего сервиса, не шортенер и не временная заглушка — и сохраните.
  3. Меню **«Ещё»** → **«Создать секретный ключ подписи»**. Это и есть вебхук-секрет; показывается один раз.

Пока `webhook_url` не сохранён, в карточке ключа у секрета написано «Появится после адреса уведомлений» — это не ошибка.

## Когда ключи «внезапно» перестают работать

Причины:

- **Перегенерация.** `regenerate` (ключ) и `regenerate-secret` (секрет) мгновенно убивают старое значение. Если интеграций несколько — обновите значение во всех местах сразу.
- **Партнёрская повторная выдача.** Партнёрский эндпоинт `POST /api/partner/organizations/{id}/api-key` **идемпотентен**: повторный вызов (например, «на всякий случай» после привязки кассира) перегенерирует ключ **той же записи** и заменяет её вебхук-настройки — старый ключ мгновенно мёртв.
- **Переход партнёра в рабочий режим.** `PUT /api/partner/mode {"mode":"production"}` удаляет тестовые организации и деактивирует их API-ключи; ключи для боевых организаций выпускаются заново. Тестовая организация архитектурно не может стать боевой, поэтому её ключи не «мигрируют». Подробнее о режимах — «[Песочница и рабочий режим](/guides/pesochnitsa-i-rabochiy-rezhim)».
- **Флаг org-default перескочил.** Если у организации не было org-default ключа, первый ключ с `webhook_url` становится им автоматически; назначение org-default другому ключу снимает флаг с прежнего. На доставку вебхуков это влияет (org-default — второй получатель) — если вебхуки «переехали», проверьте, какой ключ сейчас default.
- **Организация переехала на другой аккаунт.** Если тот же бизнес (тот же БИН) уже был заведён на другом аккаунте ApiPay и перенос подтверждён, организация переезжает вместе с данными, а все её прежние ключи **гасятся**: значение не меняется, ключ просто перестаёт действовать. Нужен новый ключ и заново указанные у него `webhook_url` и секрет. Обычное подключение кассира к своей же организации ключи не трогает.

## Правила хранения (коротко и жёстко)

- Оба значения — только на сервере: переменные окружения или менеджер секретов. **Никогда** в клиентском JS, репозитории, скриншотах и чатах с поддержкой. ИИ-агенту достаточно сказать, что ключ лежит в переменной окружения `APIPAY_API_KEY`.
- Утечка ключа = кто угодно выставляет счета от вашего имени → немедленно `regenerate`.
- Утечка секрета = кто угодно подделывает вебхуки «оплачено» → немедленно `regenerate-secret`.
- Разные среды — разные ключи: тестовая организация со своим ключом, боевая со своим.

## Вопросы и ответы

**Обязателен ли вебхук-секрет?**
Нет. Если программа узнаёт об оплате опросом `GET /invoices/{id}` с сервера, секрет не нужен. С уведомлениями секрет рекомендуем создать: только по подписи `X-Webhook-Signature` можно убедиться, что запрос прислал ApiPay. Без секрета вебхуки доставляются без этого заголовка и ничем не подтверждены — перед выдачей товара сверяйте статус счёта через `GET /invoices/{id}`.

**Можно ли иметь несколько API-ключей?**
Да, в одной организации — несколько ключей (например, по ключу на систему), у каждого свой `webhook_url` и секрет. Учтите правило org-default: он — второй получатель вебхуков организации.

**Чем отличается партнёрский ключ?**
`X-Partner-Key` — отдельный server-to-server ключ партнёрского API; к мерчантским `X-API-Key` он отношения не имеет. Если вы обычный мерчант — вам нужен только `X-API-Key`.

Смотрите также: [Вебхуки ApiPay](/guides/nastroyka-webhookov-apipay) · [Песочница и рабочий режим](/guides/pesochnitsa-i-rabochiy-rezhim) · [Как создать счёт по номеру](/guides/kak-sozdat-schet-kaspi-po-nomeru) · пиллар «[Как принимать оплату Kaspi через API](/kaspi-api)» · [Документация API](/docs).

---

ApiPay — независимый сервис и не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки их правообладателя.
База знаний: https://apipay.kz/guides