Релиз платёжной интеграции: API, вебхуки и финансовые отчёты

Финансовый сотрудник добавил полезный столбец в выгрузку. Утром автоматическая сверка записала комиссии в поле суммы. API платежей никто не менял, релиза сайта не было, но денежный процесс уже изменился. Это удобная отправная точка для разговора о версиях: контракт интеграции шире адреса платёжного запроса.

Изменение может затронуть SDK, версию API, формат уведомлений, настройки аккаунта, состав отчёта и вашу интерпретацию статусов. Если команда контролирует только код приложения, часть релизов происходит без её участия. Ниже предложен процесс, который делает такие изменения заметными и проверяемыми.

Четыре договора с данными

Первый договор: что приложение отправляет провайдеру и какой ответ понимает. Второй: какие асинхронные события принимает и как проверяет их подлинность. Третий: какие финансовые записи получает в отчётах. Четвёртый: что собственный продукт считает результатом этих сведений. Изменение одного договора может не ломать остальные технически, но менять их смысл.

Stripe позволяет задавать версию для API-запросов и отдельно учитывать версию webhook endpoint. Правила версионирования Stripe. Поэтому строка «SDK обновлён» не подтверждает, что все потребители получают ожидаемую структуру. Зафиксируйте реально применяемую конфигурацию каждого канала, а не только версии зависимостей в репозитории.

Adyen различает совместимые изменения и изменения, требующие новой версии API; версии библиотек имеют собственную схему. Правила Adyen. Точный контракт нужно читать у поставщика. Добавление допустимого нового поля и изменение значения существующего поля имеют разные последствия для вашего обработчика.

Новое неизвестное значение должно быть видно

В учебной системе parser понимает три статуса. Приходит четвёртый. Опасный вариант: отнести его к успешным, чтобы не падал процесс. Другой опасный вариант: отбросить строку и выдать финансовой команде «чистый» отчёт. Предлагаемая политика сохраняет запись в разрешённом объёме, отмечает неподдерживаемое значение и направляет его на разбор без автоматического финансового эффекта.

Для необязательного неизвестного поля поведение может быть иным: корректно проигнорировать его, если это соответствует документированному контракту. Поэтому правило «падать на любое новое поле» тоже слишком грубо. Разделите расширение структуры, неизвестный бизнес-статус, отсутствие обязательного поля и изменение формата суммы. Для каждого нужен свой тест.

Финансовый CSV тоже API

Adyen прямо предупреждает, что изменение состава и порядка колонок отчёта может повлиять на автоматическую обработку. Настройка колонок Payment accounting report. Считайте такие настройки частью контролируемой интеграции, даже если их меняют мышью в кабинете.

Парсеру полезно проверять ожидаемые заголовки и обязательные поля, а не полагаться на «сумма всегда в восьмой колонке». Дополнительно проверяйте валюту, знак, масштаб, число записей и контрольные суммы там, где они доступны. Правильный заголовок не защитит от изменения смысла поля, поэтому необходимы примеры реальных типов записей в разрешённом тестовом наборе.

Владелец отчёта должен знать, какие системы его читают. Перед изменением подготовьте образец, проверьте потребителей и согласуйте время переключения. Сохраните прежнюю конфигурацию, если продукт это поддерживает. Не просите финансовую команду каждое утро вручную переставлять столбцы, скрывая несовместимость.

Репетиция и граница отката

Соберите небольшой набор искусственных или разрешённых обезличенных примеров: оплата, отказ, частичный возврат, удержание, позднее событие, неизвестный статус. Прогоните его старым и новым разбором без внешних финансовых действий. Сравните не только успешность загрузки, но и итоговые обязательства, суммы и очередь исключений.

Если возможен параллельный расчёт, новая версия сначала вычисляет результат наблюдения, не выполняя списаний и выплат. Разница между версиями должна быть объяснена до расширения запуска. Определите условия остановки: потерянные записи, неверная валюта, необъяснимые суммы или изменение допустимости исполнения заказа.

Откат кода не отменяет уже созданный возврат и не возвращает автоматически старую настройку кабинета. Для каждого изменяемого компонента назовите способ возврата, ограничения и действия по операциям, которые успели пройти. Если обратный путь не поддержан, план должен честно описывать исправление вперёд, а не обещать волшебную кнопку.

Закрывать обновление стоит после первого полного затронутого цикла, включая отчёт и сверку, а не после первого HTTP 200. В итоге у команды остаётся короткий паспорт изменения: что поменялось, какие результаты сравнены, кто разрешил расширение и что ещё требуется наблюдать.