Интеграции
ТЗ на онлайн-оплату: состояния платежа, повторы и возвраты
Как описать интеграцию оплаты: заказ и платёж, подтверждение провайдера, идемпотентность, частичный возврат, сверка и приёмочные тесты.
Разделите заказ и платёжную операцию
ТЗ на онлайн-оплату должно описывать больше, чем кнопку перехода к провайдеру. Заказ выражает намерение купить, а платёж — отдельную операцию со своими состояниями. У одного заказа могут быть неудачная и успешная попытки, частичная оплата или возврат. Если свести всё к флажку «оплачено», разбирать сбои и сверять деньги станет трудно.
Начните с границ первой версии: товары или услуги, валюта, выбранный провайдер, способы оплаты, допустимость частичных операций и момент исполнения заказа. Условия подключения, доступность способов и требования провайдера проверяют для конкретного бизнеса. Этот материал описывает техническое задание и не заменяет договорные, бухгалтерские или правовые решения ответственных специалистов.
Для каждого сценария назовите владельца: кто утверждает сумму, кто разрешает возврат, кто разбирает расхождение и кто отвечает покупателю. Интеграция может автоматически передать событие, но не определяет самостоятельно коммерческие полномочия сотрудника. Если порядок действий при спорном платеже неизвестен, его нужно согласовать до запуска, а не оставлять разработчику на усмотрение.
Задайте модель попыток, сумм и состояний
Опишите связь заказа, попытки оплаты, платежа у провайдера и возврата. У каждого объекта должен быть устойчивый идентификатор. Сохраните исходную сумму и валюту операции, время создания, подтверждённое состояние и причину отказа в доступном виде. Не используйте номер заказа как единственный ключ всех платёжных действий: разные попытки должны различаться.
Сумму к оплате формирует доверенная серверная сторона по согласованным данным заказа. Значение из браузера нельзя без проверки считать окончательным. В ТЗ укажите, что происходит при изменении корзины, скидки или доставки после открытия платёжной страницы. Старое платёжное намерение не должно незаметно подтверждать новый состав заказа с другой суммой.
Составьте таблицу допустимых переходов. Какие состояния разрешают выдачу товара? Что означает отмена? Может ли платёж оставаться в ожидании и кто проверит его позднее? Названия состояний сверяют с документацией выбранного провайдера, а бизнес-последствия утверждают отдельно. Сообщение покупателю должно отражать подтверждённый факт, особенно когда результат ещё неизвестен.
Определите источник подтверждения
Возврат пользователя на страницу магазина не доказывает успешную оплату. Браузер может закрыться, повторно открыть адрес или вернуться раньше окончательного результата. Приложение должно связать подтверждение провайдера с нужным платежом, заказом, суммой и валютой. Только после согласованной проверки выполняются действия, которые зависят от оплаты.
В документации ЮKassa по входящим уведомлениям описаны события и способ их обработки. При проектировании соответствующей интеграции проверяют подлинность и актуальность уведомления предусмотренным провайдером способом. Не принимайте произвольный входящий JSON как распоряжение выдать товар. Подробности зависят от платёжной системы и должны быть сверены перед реализацией.
Отдельно задайте поведение страницы ожидания. Человек должен видеть, что проверка продолжается, и понимать, нужно ли что-то делать. Повторное нажатие не должно автоматически создавать новые платёжные обязательства. Если подтверждение задержалось, полезны номер заказа и доступный способ обращения. Нельзя заменять неопределённость ложным сообщением об успехе только ради спокойного интерфейса.
Опишите сетевые повторы и неоднозначный результат
Сетевой тайм-аут не сообщает, была ли операция выполнена на стороне провайдера. Повтор с новым идентификатором может создать отдельную операцию. В ТЗ необходимо различать повтор того же намерения и действительно новую попытку. Сохраняйте связь ключа повтора с параметрами и результатом, а ограничения по срокам и повторному использованию проверяйте у выбранного провайдера.
Документация ЮKassa по формату взаимодействия описывает идемпотентность запросов. Это означает предусмотренный API способ безопаснее повторять одну операцию при соблюдении его правил. Для проекта дополнительно нужен бизнес-контракт: какое действие считается тем же самым, кто создаёт ключ и как система восстанавливает состояние после потери ответа. Один заголовок запроса не заменяет эту модель.
Учебный сценарий: сервер создал платёж, но не получил ответ. Покупатель нажал кнопку ещё раз. Проверка должна показать, что приложение выясняет судьбу исходной операции и не выдаёт заказ дважды. Затем измените сумму заказа и повторите тест: система обязана отличить новое намерение от сетевого повтора прежнего. Ожидаемый результат записывают до испытания.
Продумайте отмену и возвраты
Отмена заказа и возврат денег — связанные, но отдельные действия. Возврат может быть частичным и иметь собственный результат обработки. В требованиях укажите основание, роль инициатора, допустимую сумму, связь с исходным платежом и способ подтверждения. Кнопка в административном интерфейсе должна сообщать точное действие, которое сотрудник выполняет.
Согласуйте, как частичный возврат отражается в заказе, остатках и отчётах. Возвращённый товар не всегда сразу доступен к продаже, а отменённая услуга может иметь другие условия. Техническая система не должна придумывать эти правила. Решения передают владельцы процесса, после чего команда проверяет непротиворечивость переходов и доступность необходимых данных.
Учебный пример: из двух позиций возвращается одна, доставка сохраняется, затем повторно приходит уведомление о том же возврате. Ожидаемые суммы и статусы должны остаться согласованными, повтор не создаёт вторую операцию. Отдельно проверьте неуспешный возврат и ситуацию, когда сотрудник не имеет нужной роли. Эти случаи важнее демонстрации одного успешного нажатия.
Включите сверку и эксплуатацию
Даже хорошо проверенная интеграция требует наблюдения. Опишите периодическую сверку заказов и подтверждённых операций провайдера: какие записи сравниваются, какие расхождения считаются критическими и кто их разбирает. Отчёт должен различать неоплаченный заказ, неизвестный результат, подтверждённый платёж без завершённого заказа и возврат в обработке.
Журнал должен помогать восстановить последовательность событий по идентификатору операции. Сохраняйте необходимые технические факты, но не секреты и не лишние платёжные данные. Доступ к диагностике ограничивается задачей сотрудника. Если используется размещённая у провайдера платёжная форма, не расширяйте проект самостоятельным сбором реквизитов карты без отдельной обоснованной архитектуры.
Назначьте порядок ручного вмешательства. Сотрудник должен понимать, когда можно повторить проверку, когда требуется обращение к провайдеру и какое действие запрещено до выяснения результата. Ручная отметка «оплачено» не должна бесследно заменять финансовое подтверждение. Любое исключение нуждается в роли, причине и журнале, иначе сверка быстро перестанет отражать фактические операции.
Проверьте интеграцию в тестовом окружении
Приёмочный набор включает успешную оплату, отказ, ожидание, закрытие браузера, тайм-аут, повтор запроса и повтор уведомления. Добавьте изменение суммы, отмену и частичный возврат, если они входят в проект. Все испытания проводят предусмотренным провайдером тестовым способом. Тестовый успех не доказывает коммерческую доступность подключения: рабочие настройки проверяются отдельно по согласованному порядку.
Для каждого сценария сохраните исходные данные, действия, идентификаторы и ожидаемые последствия в заказе. Проверяйте сервер и административный интерфейс, а не только страницу покупателя. Ошибка может скрываться в повторном уведомлении складу или двойной отправке письма. Финальный эффект должен произойти согласованное число раз, даже если техническое событие пришло повторно.
Проверьте выпуск новой версии интеграции при существующих незавершённых платежах. Старые операции должны оставаться распознаваемыми, а обновление схемы — не терять связь с заказом. План возврата версии также учитывает уже созданные внешние операции. Откат приложения не отменяет движение денег; это различие обязательно должно быть понятно команде запуска.
Соберите бриф, который можно оценить
К брифу приложите модель заказа, выбранного провайдера, таблицу состояний, примеры попыток и правила возвратов. Укажите владельцев решений, тестовый доступ и зависимости от учётной системы. Скачиваемый шаблон содержит поля для повторов, ошибок и доказательств приёмки. Не оставляйте эти разделы пустыми только потому, что основной успешный сценарий кажется простым.
Разделите оценку на подключение, реализацию переходов, интеграцию с заказом, испытания и запуск. Если часть функций ещё не подтверждена провайдером, обозначьте её как зависимость. Стоимость и сроки определяются конкретным охватом, поэтому в статье нет универсального обещания запуска за фиксированное время или гарантии безошибочной работы.
Хороший итог проекта — возможность объяснить состояние любой операции и безопасно обработать повтор. Пользователь видит понятный результат, сотрудник находит заказ и подтверждение, а команда знает порядок действий при расхождении. Материалы о checkout и надёжности событий помогут углубить отдельные решения; профильная услуга позволяет обсудить конкретную модель вашего бизнеса.
Источники
- Формат взаимодействия с API
ЮKassa / доступ 2026-10-12
Первичный источник для соответствующей технической темы. Структура брифа и учебные проверки разработаны редакцией; возможности конкретной системы проверяются перед внедрением.
- Входящие уведомления
ЮKassa / доступ 2026-10-12
Первичный источник для соответствующей технической темы. Структура брифа и учебные проверки разработаны редакцией; возможности конкретной системы проверяются перед внедрением.
- Скачать заполняемый бриф / ТЗ (.txt)
Малевич — практическое приложение / доступ 2026-10-12
Сохраните файл и заполните исходные данные, решения и критерии приёмки своего проекта.
FAQ
Можно ли считать заказ оплаченным после возврата на сайт?
Возврат браузера не является достаточным подтверждением. Приложение должно получить проверяемое состояние платежа со стороны провайдера и связать его с нужным заказом и суммой. Покупатель может закрыть вкладку или попасть на страницу раньше, чем обработка завершилась.
Нужно ли создавать новый ключ при сетевом повторе?
Для повтора той же операции сохраняют предусмотренный провайдером ключ идемпотентности и исходные параметры в пределах его правил. Новый ключ может означать новую операцию. Если намерение покупателя изменилось, это нужно оформить как отдельную попытку и проверить состояние предыдущей.
Почему возврат нельзя обозначать одним флажком?
Возврат может быть частичным, находиться в обработке или завершиться ошибкой. Полезно хранить отдельную операцию с суммой, причиной и связью с платежом. Состояние заказа и фактическое движение денег сверяют, а доступ к ручному возврату ограничивают ролью сотрудника.
