Skip to main content

​
Ключ

Каждый запрос подписывается ключом партнёра в заголовке:
Ключ выпускается в кабинете партнёра, раздел «API»: значение показывается один раз, в базе хранится только его хеш. Ключ один — чтобы заменить, отзовите прежний и выпустите новый; пока новый ключ не встал на сервер, запросы получают 401. Без ключа, с неверным или отозванным ключом, при выключенном доступе к API, а также когда аккаунт партнёра заблокирован платформой, ответ один и тот же — 401 UNAUTHORIZED: по ответу нельзя понять, существовал ли ключ.
  • Храните ключ только на сервере: в переменных окружения или хранилище секретов, не в репозитории.
  • В код мини-аппа, сайта или мобильного приложения ключ не попадает никогда. Клиентская часть ходит к вашему серверу, сервер — к API.
  • Ключ утёк — сразу отзовите его в разделе «API» и выпустите новый.
Тестового режима нет. Каждый ключ боевой: POST /payments выставляет настоящий счёт, пробный период выдаёт настоящий доступ. Неоплаченный счёт ничего не стоит — он просто истекает. Проверку интеграции проведите на себе: выставьте счёт своему client_id и оплатите его.

​
Клиент — ваш id

Клиент определяется вашим идентификатором client_id: номер пользователя в вашем боте, id в базе сайта — что угодно, что не меняется.
  • 1–128 символов: латиница, цифры и . _ : @ + -; не из одних точек; регистр различается.
  • Уникален внутри вашего аккаунта: одинаковый client_id у двух партнёров — разные клиенты.
  • Отдельно заводить клиента не нужно: он появляется с первым запросом счёта или пробного периода — даже если сам счёт не выставился, например из-за NO_ACTIVE_SUBSCRIPTION или 503.

​
Повтор запроса без второго счёта

Сеть рвётся: запрос на выставление счёта мог дойти, а ответ — потеряться. Чтобы повтор не выставил клиенту второй счёт, POST /payments требует заголовок Idempotency-Key:
Удобнее всего передавать номер заказа в вашей системе. Ключ — до 200 символов, уникален внутри вашего аккаунта. «Те же поля» — это client_id, purpose, plan_id, devices, method и return_url. Порядок ключей в JSON значения не имеет.
Таймаут, обрыв соединения, 5xx на POST /payments — повторяйте с тем же Idempotency-Key. Новый ключ на повторе — это новый счёт.

​
Источник истины — запрос GET

Состояние счёта и клиента всегда берите из API: GET /payments/{payment_id} и GET /clients/{client_id}. Перед тем как выдать клиенту что-то у себя (открыть доступ, начислить бонус), перечитайте счёт. Пока клиент на странице оплаты, опрашивайте счёт раз в несколько секунд — или подключите вебхуки, и об оплате ваш сервер узнает сам. Статус expired не окончательный: оплата, пришедшая позже срока, всё равно проходит, и счёт становится succeeded. Поэтому к истёкшему счёту стоит вернуться, когда клиент снова придёт к вам.

​
Язык ответов

Заголовок Accept-Language: ru — тексты на русском: подписи ссылок на приложения, заголовки документов, поле message в ошибках. Без заголовка или с другим языком — английский. Названия способов оплаты из GET /payment-methods от заголовка не зависят и всегда на русском.

​
Совместимость

Новые поля, коды ошибок и типы событий появляются без смены версии, и интеграция не должна на них ломаться. Подробно — Ошибки и лимиты.