Skip to main content

​
Ключ

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

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

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

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

Сеть рвётся: запрос на выставление счёта мог дойти, а ответ — потеряться. Чтобы повтор не выставил клиенту второй счёт, 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 в ошибках. Без заголовка или с другим языком — английский.

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

Новые поля в ответах и новые коды ошибок появляются без смены версии. Код интеграции не должен ломаться на незнакомых полях, а незнакомый код ошибки — трактовать как обычный отказ. Удаление и переименование полей — только в новой версии пути (/v2).