Документация / Авторизация и правила

Авторизация и правила API

Как передать ключ и по каким правилам устроены все запросы и ответы.

API-ключ

Каждый запрос (кроме GET /v1/currencies) — с ключом приложения в заголовке:

Authorization: Bearer kp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ключ выдаётся в боте при создании приложения: ➕ Ещё → 💼 Kivix Pay → ➕ Создать приложение. Там же его можно перевыпустить — старый сразу перестаёт работать.

Ключ — только на сервере. Никогда не отправляйте его в браузер, мобильное приложение или публичный репозиторий.

Переменные окружения

SDK сами берут ключ и адрес из окружения — в коде их можно не писать:

KIVIX_PAY_API_KEY=kp_...
KIVIX_PAY_BASE_URL=https://kivix.cc

Правила

💰 Суммы — строками

«12.50», а не 12.5 — так не теряются копейки. Точность: USDT и TRX — 6 знаков, остальные — 8; лишнее округляется вниз.

🕐 Время — ISO 8601, UTC

2026-10-26T12:30:00Z

🔁 Повторы безопасны

Повтор с тем же order_id или заголовком Idempotency-Key вернёт тот же счёт (код 200 и заголовок Idempotent-Replayed: true), а не создаст второй.

📄 Списки — курсором

{"object":"list","data":[…],"has_more":true}. Следующая страница — ?starting_after=<id последнего>.

Идемпотентность

Сеть ненадёжна: запрос мог дойти, а ответ — потеряться. Чтобы повтор не создал второй счёт:

order_id — ваш номер заказа, уникален внутри приложения. Повтор с тем же номером и той же суммой вернёт тот же счёт; с другой суммой — ошибку order_conflict.
Idempotency-Key — заголовок с любым уникальным значением (например UUID). SDK отправляют его сами и при сетевом сбое повторяют запрос с тем же ключом.

Версии

Все адреса начинаются с /v1. Внутри версии мы только добавляем: новые поля в ответах, новые необязательные параметры, новые типы событий. Пишите код так, чтобы незнакомые поля не ломали разбор ответа.