Логика заказов знает про провайдера
Названия статусов, поля и исключения конкретного эквайринга прорастают в оформление заказа, админку и учёт. Заменить шлюз становится отдельным проектом.
Платежи и финансы
Платёжные интеграции: эквайринг, подписки, возвраты и сверка
Провайдер — сменная деталь, а не фундамент заказа
Обычно первый эквайринг встраивают напрямую в оформление заказа, и дальше он определяет структуру кода. Мы делаем наоборот: заказ работает с внутренним платёжным слоем, а провайдер подключается адаптером — поэтому второго можно добавить, а первого заменить без переписывания логики заказов.
Почему платёжная логика прирастает к первому провайдеру
Проблема проявляется не на запуске, а через год: когда меняются тарифы, отказывает шлюз или бизнес хочет принимать оплату иначе.
Второй провайдер — это второй код
Добавить резервный шлюз можно только копированием ветки оплаты со своими особенностями. Копии постепенно расходятся.
Уведомления обрабатываются «как придёт»
Повторное уведомление создаёт второй платёж или перезаписывает статус заказа. Находится это обычно при сверке, когда деньги уже разошлись.
Возвраты живут в кабинетах провайдеров
История возврата не видна в заказе: непонятно, сколько уже вернули и по какой операции. Бухгалтерия выясняет это отдельно.
Что ходит между заказом и провайдером
Платёжный слой стоит между ними и определяет, какая сторона за что отвечает. Это позволяет менять шлюз, не переписывая работу с заказами и учётом.
Сущность
Направление
Что важно учесть
Платёжное намерение
Заказ → платёжный слой
Заказ не общается с провайдером напрямую. Он создаёт намерение с суммой и назначением, а выбор шлюза и формата запроса — задача слоя.
Событие провайдера
Провайдер → реестр событий
Уведомление сначала сохраняется с идентификатором и результатом проверки подписи, и только потом влияет на состояние заказа.
Состояние платежа
Платёжный слой → заказ
Заказ хранит внутренний статус — создан, оплачен, частично возвращён, — а не статус конкретного шлюза. Маппинг живёт в адаптере.
Возврат
Заказ → платёжный слой → провайдер
Возврат оформляется по платежу, а не по провайдеру: слой сам знает, куда его отправить, и отличает полный возврат от частичного.
Сверка
Провайдер → реестр платежей
Реестр платежей — внутренний источник правды по деньгам. С ним сверяются заказы, учётная система и выгрузка для бухгалтерии.
Регулярное списание
Платёжный слой → провайдер
Подписки и рекуррент используют тот же контракт: заказу не важно, списывается карта, кошелёк или счёт по рассрочке.
Договорённость простая: заказ ничего не знает о формате конкретного провайдера, а провайдер ничего не знает о структуре заказа. Всё, что между ними, описано один раз — во внутреннем контракте.
Из чего состоит платёжный слой
Четыре части, которые делают оплату предсказуемой и снимают привязку к одному шлюзу.
Контракт провайдера
Один интерфейс: создать платёж, вернуть статус, оформить возврат, отдать реестр операций. Особенности конкретного шлюза остаются внутри его адаптера.
Реестр платежей
Внутренняя таблица всех операций: сумма, валюта, способ оплаты, провайдер, внешний идентификатор, возвраты и связанный заказ.
Маппинг статусов
Статусы разных провайдеров сводятся к небольшому набору внутренних состояний. Именно по ним живёт заказ, а не по формулировкам шлюза.
Маршрутизация
Правила выбирают провайдера по способу оплаты, сумме, типу клиента или доступности шлюза. Резервный маршрут задаётся заранее, а не в момент сбоя.
Как добавляется и заменяется провайдер
Подключение второго шлюза — это работа над адаптером и правилом маршрутизации, а не над логикой оформления заказа.
Описать контракт
Фиксируем, что должен уметь любой провайдер: создание платежа, возврат, статус, реестр операций. Новые шлюзы подключаются к этому контракту, а не к логике заказа.
Подключить адаптер
Пишется только адаптер под API конкретного провайдера: подпись, форматы, коды ошибок. Оформление заказа, админка и учёт остаются нетронутыми.
Перевести маршрут
Отдельный способ оплаты или долю платежей переключаем правилом маршрутизации. Переключение обратимо: вернуться к прежнему провайдеру можно без правок в коде заказа.
Проверить на сверке
После включения сверяем реестры обоих провайдеров в одном формате. Расхождение видно сразу, потому что структура данных уже общая.
Реестр событий: повтор не создаёт второй платёж
Уведомления от провайдеров приходят повторно — при повторной доставке, при опросе и при ручном перезапуске. Обработка проектируется сразу с расчётом на это.
Правила обработки платёжных событий
- Идемпотентный ключ при создании платежа: повторная отправка формы возвращает уже созданный платёж
- Уведомление принимается только с валидной подписью и от известного источника
- Каждое событие сохраняется в реестре с внешним идентификатором — повтор не обрабатывается второй раз
- Статус меняется по правилу перехода: оплаченный платёж нельзя оплатить повторно, а возврат — превысить остаток
- Очередь и повторные попытки: недоступность провайдера не теряет событие и не блокирует оформление заказа
- Журнал событий доступен из админки: видно, что пришло, что отклонено и по какой причине
Возвраты и сверка в одном месте
Возвраты, комиссии и расхождения — та часть оплаты, которую обычно находят в конце периода. В платёжном слое они собираются в одном реестре.
Возвраты из одного места
Полный и частичный возврат оформляются по платежу. Слой сам определяет провайдера операции, а результат попадает в журнал с суммой и статусом.
Единый реестр операций
Операции всех провайдеров сводятся в один отчёт: по заказу видны все попытки оплаты, возвраты и удержанные комиссии, независимо от шлюза.
Выгрузка для бухгалтерии
Формат выгрузки не зависит от того, сколько провайдеров подключено и кто из них основной. Это снимает пересборку отчёта при каждой смене шлюза.
Как проектируется платёжный слой
Начинаем с инвентаризации: какие способы оплаты нужны, кто провайдеры, какие требования у учёта и бухгалтерии. Контракт и правила маршрутизации согласуются до разработки — потом это дешевле не менять.
-
01
Аудит и схема
Разбираем системы, сущности и потоки. Фиксируем, что считается источником правды и где сейчас расходятся данные.
-
02
Контракт обмена
Описываем поля, форматы, частоту и правила сопоставления справочников. Согласуем до начала разработки.
-
03
Прототип
Проверяем обмен на реальных данных в ограниченном объёме: несколько десятков записей в обе стороны.
-
04
Внедрение
Включаем полный обмен с очередью, повторными попытками, журналом и защитой от дублей.
-
05
Эксплуатация
Мониторинг, сверка расхождений, обновление коннекторов при изменениях API на стороне сервиса.
Что делает платёжный слой устойчивым
Оплата — критичный участок: сбой здесь означает потерянные заказы и разошедшийся учёт. Поэтому обязательны журнал, идемпотентность и резервный маршрут.
Идемпотентность
Повторная доставка одного и того же события не создаёт вторую сделку, второй заказ или второй платёж.
Очередь и повторные попытки
Если внешняя система недоступна, операция ждёт и повторяется по расписанию, а не теряется.
Журнал обмена
Видно, что и когда ушло, что вернулось и что не прошло. Неудачную операцию можно повторить вручную.
Лимиты провайдера
Учитываем ограничения по частоте запросов, чтобы не получить блокировку со стороны сервиса.
Сверка расхождений
Регулярная сверка ключевых сущностей между системами: расхождение видно в отчёте, а не в конце квартала.
Мониторинг и оповещения
При остановке обмена приходит уведомление ответственным, а не выясняется из жалобы клиента.
Ещё в категории «Платежи и финансы»
Часто эти интеграции внедряются вместе — например, CRM и телефония, или магазин и маркетплейсы.
ЮKassa
Оплата, возвраты и сверка без ручной работы
Интеграция с ЮKassa: приём платежей, возвраты, рекуррентные списания и автоматическая сверка с учётом.
ПодробнееCloudPayments
Платежи и подписки на одном шлюзе
Интеграция с CloudPayments: эквайринг, подписки, рекуррент и платёжные виджеты.
ПодробнееТинькофф
Эквайринг с рассрочкой и выплатами
Интеграция с Тинькофф: интернет-эквайринг, рассрочка, выплаты партнёрам и сверка операций.
ПодробнееВсе категории интеграций
Обмен редко ограничивается одной категорией: магазин обычно связан и со складом, и с платежами, и с маркетплейсами.
Частые вопросы о платёжном слое
Если вашего вопроса здесь нет — задайте его в форме ниже.
Можно ли добавить второго провайдера позже, не переделывая всё?
Да — именно для этого платёжный слой и проектируется. Заказ работает с внутренним контрактом, а не с API конкретного шлюза, поэтому новый провайдер подключается адаптером. Логика оформления заказа, статусов и учёта при этом не меняется, меняется только маршрут платежа.
Как устроена идемпотентность уведомлений об оплате?
Каждое входящее уведомление сначала попадает в реестр событий с внешним идентификатором и проверкой подписи. Если такое событие уже обработано, оно не проходит дальше, поэтому повторная доставка не создаёт второй платёж и не меняет статус заказа второй раз. Обработка статуса идёт по правилу перехода, а не присваиванием.
Кто считается источником правды по статусу оплаты?
Провайдер — источник событий, но состояние денег хранит внутренний реестр платежей: сумма, способ, комиссия, возвраты, связанный заказ. Статус заказа выводится из этого реестра, поэтому смена провайдера или сбой в его API не оставляет заказ в неопределённом состоянии.
Что произойдёт, если платёжный провайдер недоступен?
Оформление заказа не блокируется: операция встаёт в очередь и повторяется, а маршрутизация может увести платёж на резервного провайдера, если он настроен. Все неудачные обращения сохраняются в журнале с кодом ответа — видно, что именно не прошло и когда была последняя попытка.
Сколько стоит проектирование платёжного слоя и что нужно от нас?
Нужны перечень способов оплаты, требования учёта и бухгалтерии, а также доступы к текущим провайдерам, если оплата уже работает. Стоимость зависит от числа провайдеров, наличия рекуррента и выплат: после разбора этих пунктов называем состав и стоимость работ.
Разберём вашу схему приёма оплаты
Расскажите, какие провайдеры используются сейчас, что мешает добавить второй и как оплаты попадают в учёт. Предложим архитектуру платёжного слоя и назовём стоимость.
Бесплатный аудит
Разбор технической части сайта: скорость, SSR, фильтры
Аудит текущей рекламы: где сливается бюджет
Анализ конкурентов в вашей нише
Прогноз CPL, ROAS и окупаемости
План действий на первый месяц
Получите бесплатный аудит интернет-магазина
За 3 рабочих дня разберём: где вы теряете заявки, какие каналы недооценены, и что даст рост в первые 30 дней.
За этот месяц
42 компании получили аудит
30 мин
реакция
3 дня
аудит
100%
доступ к кабинетам
Заявка на аудит
Без обязательств. С конкретными цифрами.