Журнал изменений API

Что и когда менялось в API для того, кто с ним интегрирован.

Сюда попадает всё, что меняет поведение API для интегратора: новая ручка, новое поле, новый код или правило отказа, изменённый предел.

Как читать журнал

  • Совместимые изменения выходят без смены версии: новая ручка, новое необязательное поле запроса, новое поле в ответе, новый код отказа или новое значение details.rule. Клиент обязан пропускать незнакомые поля ответа и обрабатывать незнакомый код отказа по статусу HTTP.
  • Несовместимые изменения в версии v1 не делаются: удалённые или переименованные ручка и поле, поле, сменившее смысл или вид, обязательное поле, которого раньше не было. Такое изменение выходит новой версией рядом со старой, и запись о нём появляется здесь заранее.

Записи идут от новых к старым.

17.11.2026

Страница оплаты, уведомления, возвраты и выплаты.

  • GET /api/v1/payments?reference=…: платёж по номеру заказа. Без reference адрес отвечает 501; ключ нужен и здесь.
  • POST /api/v1/payments/:id/refunds, GET /api/v1/payments/:id/refunds и GET /api/v1/payments/:id/refunds/:refundId: возвраты.
  • В платеже новые поля pageUrl (страница оплаты) и refundedMinor, в action вид requisite с реквизитом; в теле создания fieldsOnPage.
  • Уведомления payment.updated и refund.updated с подписью по Standard Webhooks.
  • Когда у установки есть страница оплаты, returnUrl принимается только из списка разрешённых источников мерчанта (правило return_url_not_allowed). Новые правила отказа создания: fields_on_page_conflict, pay_page_unavailable, fields_on_page_ttl_too_short.
  • У чтения возвратов и у создания возврата свои пределы частоты.
  • Создание возврата: отказы ключа API, мерчанта и контура при верном секрете (401 и 403) занимают ключ повтора, как отказ 409 (отозванный и просроченный ключ API только сутки после конца ключа); всё, что ответом не является, это 503 dependency_unavailable с правилами transaction_timeout, transaction_conflict, idempotency_unrecorded, keyring_unavailable, idempotency_key_unverifiable: Возвраты.
  • callbackUrl в теле создания платежа и возврата: адрес уведомлений этого объекта вместо адреса контура, как callback_url у Corefy; отдаётся в чтении. Порт адреса уведомлений (и адреса контура) только по умолчанию, 443, 8443, 80 или 8080. Правила отказа callback_url_invalid, callback_url_scheme, callback_url_internal, callback_secret_missing: Адрес в запросе.
  • POST /api/v1/notifications/secret: выпустить секрет подписи уведомлений ключом API, если его ещё нет (иначе 409 notify_secret_exists).
  • Исход ручного возврата и возврата, исход которого провайдер не назвал или назвал противоречиво, решают сотрудники: SUCCEEDED или FAILED с причиной operator_declined. Возврат, на который провайдер вернул другую сумму, остаётся PENDING с inReview: true до ручного исправления. После решения сотрудников о возврате через API провайдера, у которого можно спросить статус возврата, переспрашивают до 90 суток от создания и не меньше трёх суток после решения, спорный ответ даёт inReview: true при том же статусе: Возвраты.
  • Статус REJECTED у платежа: отклонён у нас до провайдера, без попытки. Причины customer_blocked, firewall_blocked, rule_declined.
  • POST /api/v1/payouts, GET /api/v1/payouts/:id и POST /api/v1/payouts/:id/cancel: выплаты в тестовом контуре, справочник. Заголовок Idempotency-Key обязателен, отказ по существу занимает ключ, ответ 5xx это не отказ. Выплата пока не отправляется: одобренная стоит в CREATED и отменяется. Боевые выплаты закрыты (правило live_payouts_closed).
  • Текст error.message у всех отказов по-английски. Коды, правила и details прежние: Формат ошибок.
  • Выплата на IBAN: сервис банковского перевода принимает beneficiary.iban, страна счёта это первые две буквы IBAN. Выплата на счёт, заблокированный у мерчанта, заводится отклонённой с причиной customer_blocked. IBAN верной формы, но не той длины для своей страны, у платежа и у выплаты это 422 identifier_invalid.
  • Уведомление payout.updated о выплате, подписанное как уведомления о платеже и возврате: Уведомления.
  • callbackUrl в теле создания выплаты: адрес уведомлений payout.updated этой выплаты вместо адреса контура, как у платежа и возврата (Адрес в запросе); ответы создания, чтения и отмены отдают callbackUrl; адрес не по форме 400 с правилом callback_url_invalid, callback_url_scheme или callback_url_internal; без секрета контура 409 callback_secret_missing, отказ занимает ключ повтора.

13.11.2026

Приём платежа.

  • POST /api/v1/payments: создать платёж; повтор с заголовком Idempotency-Key безопасен: Повтор запроса.
  • GET /api/v1/payments/:id: прочитать платёж и узнать исход: Приём платежа.
  • Коды отказа validation_failed, bad_amount, conflict, identifier_invalid, keyring_unavailable и dependency_unavailable: они описаны в справочнике под ручкой создания.
  • У создания и у чтения платежа свои пределы частоты: Ограничения.
  • Боевой приём закрыт; в тестовом контуре исход задают тестовые данные.
  • GET /api/v1/payments, список платежей, остаётся зарезервированным.

12.11.2026

Первый выпуск публичного API.

  • Вход по ключу API: Авторизация.
  • GET /api/v1/me: проверка ключа.
  • GET /api/v1/services: сервисы, которыми мерчант может принять платёж в контуре ключа.
  • Общий формат отказа и предел частоты запросов.
  • Адреса POST /api/v1/payments, GET /api/v1/payments/:id и GET /api/v1/payments зарезервированы.

Уточнения того же дня, сделанные до первых интеграций:

  • из ответа GET /api/v1/me убрано название ключа: это пометка администратора, она видна только в консоли;
  • схема Basic принимается только с пустым паролем;
  • если у ключа несколько причин отказа, называется одна, в порядке: отзыв, срок, выключатель.

API v1 · собрано 18.11.2026 · выпуск f13e6bf

Справочник методов собирается из кода сервера: он не описывает адрес, которого нет.