Журнал изменений 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, если его ещё нет (иначе 409notify_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 верной формы, но не той длины для своей страны, у платежа и у выплаты это 422identifier_invalid. - Уведомление
payout.updatedо выплате, подписанное как уведомления о платеже и возврате: Уведомления. callbackUrlв теле создания выплаты: адрес уведомленийpayout.updatedэтой выплаты вместо адреса контура, как у платежа и возврата (Адрес в запросе); ответы создания, чтения и отмены отдаютcallbackUrl; адрес не по форме 400 с правиломcallback_url_invalid,callback_url_schemeилиcallback_url_internal; без секрета контура 409callback_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принимается только с пустым паролем; - если у ключа несколько причин отказа, называется одна, в порядке: отзыв, срок, выключатель.