Интеграция с банковским API нужна не только крупным компаниям. Интернет-магазину она помогает автоматически принимать платежи и проверять их статус, сервису подписок — управлять регулярными списаниями, а бухгалтерии — быстрее сверять поступления. Подключение через Систему быстрых платежей (СБП) добавляет еще один способ оплаты: клиент сканирует QR-код, переходит по ссылке или подтверждает операцию в банковском приложении.
Главная сложность обычно связана не с отправкой первого запроса. Надежная интеграция должна корректно переживать повторы, задержки, недоступность банка, отмены и расхождения между заказами и платежами. Поэтому проект начинают не с написания кода, а с описания бизнес-сценариев и требований к данным.
1. Определите, что именно должна делать интеграция
Сначала зафиксируйте операции, которые понадобятся системе. Минимальный набор для приема оплаты выглядит так:
- создание платежа с указанием суммы, заказа и назначения;
- получение ссылки на оплату или данных для формирования QR-кода СБП;
- проверка статуса операции;
- получение уведомления от банка об изменении статуса;
- возврат всей суммы или ее части;
- формирование отчетов для сверки.
Для выплат физическим лицам, зарплатных проектов, автоплатежей и валютных операций понадобятся другие методы и отдельные договоренности с банком. Не стоит включать их в первый релиз без понятного сценария: каждая новая операция увеличивает объем тестирования и число исключений.
2. Выберите схему подключения
У бизнеса обычно есть три варианта. Первый — прямое подключение к API банка-эквайера. Оно дает больше контроля над платежным сценарием, но требует самостоятельно реализовать авторизацию, обработку статусов, возвраты и мониторинг.
Второй вариант — платежный агрегатор. В таком случае компания получает единый интерфейс для нескольких способов оплаты, а часть технических и договорных вопросов берет на себя провайдер. Цена удобства — комиссия, зависимость от внешней платформы и меньше возможностей для настройки.
Третий путь — подключение через банковский интернет-эквайринг или готовый платежный модуль для CMS. Это разумное решение для небольшого магазина, если стандартного сценария достаточно. Для сложной логики заказов и собственной подписочной модели обычно требуется прямой API или специализированный провайдер.
СБП может быть встроена в платежную страницу, оформлена как отдельный способ оплаты или подключена через API банка. Конкретный набор методов зависит от банка и договора: один поставщик выдает платежную ссылку, другой — данные для динамического QR, третий поддерживает оба варианта.
3. Подготовьте договоры, доступы и требования к данным
До разработки нужно выяснить, какие продукты банк подключает юридическому лицу, какие лимиты действуют и кто отвечает за возвраты. Уточните комиссию, сроки зачисления, формат выписок, правила работы с частичными возвратами и доступность тестовой среды.
Для API обычно выдаются идентификатор клиента, сертификат, ключ или токен. Секреты нельзя хранить в исходном коде, файлах конфигурации в репозитории и открытых переменных на рабочем компьютере. Используйте защищенное хранилище секретов, ограничивайте права доступа и заранее продумайте замену ключей без остановки сервиса.
Отдельно проверьте требования к персональным данным и кассовым чекам. Если в системе обрабатываются имя, телефон, адрес или данные покупателя, нужно учитывать требования законодательства о персональных данных. Для расчетов в России может потребоваться онлайн-касса и передача чека по правилам, применимым к вашей модели продаж. Банк не всегда закрывает этот вопрос автоматически.
4. Спроектируйте платежный сценарий
У каждого платежа должен быть собственный внутренний идентификатор. В запросе в банк обычно передаются сумма в минимальных денежных единицах, валюта, номер заказа, описание, адрес возврата и срок действия платежной сессии. Не полагайтесь только на номер, который вернул банк: храните связь между заказом, внутренним платежом и внешним идентификатором операции.
Для статусов лучше использовать явную модель, а не одно поле «оплачен». Например, заказ может иметь состояния «создан», «ожидает оплаты», «оплачен», «отменен», «возвращен» и «требует проверки». Статус банковской операции и статус заказа не всегда меняются одновременно. Заказ переводят в оплаченный только после подтвержденного результата, а не после перехода клиента на страницу магазина.
Особое значение имеет идемпотентность. Если запрос создания платежа оборвался из-за сетевой ошибки, приложение может повторить его. Без специального ключа банк иногда создаст две операции. Один и тот же идентификатор идемпотентности должен связывать повторные попытки с исходным запросом, а сервер магазина — безопасно обрабатывать повторное уведомление.
5. Подключите СБП
В сценарии с динамическим QR-кодом сервер сначала создает платеж и получает данные для отображения. На странице заказа можно показать QR-код, кнопку перехода в банковское приложение и текстовую инструкцию. Статический QR удобен для офлайн-точки, но хуже связывает конкретную оплату с конкретным заказом, поэтому для интернет-магазина чаще используют динамический вариант.
После подтверждения клиентом банк или платежный провайдер отправляет уведомление. Нельзя считать оплату успешной только потому, что покупатель вернулся на страницу «Спасибо». Возврат может произойти при закрытии приложения, повторном открытии браузера или подмене параметров. Источником истины должен быть подтвержденный ответ API либо проверенное серверное уведомление.
Уведомления нужно принимать на отдельном защищенном endpoint. Проверяйте подпись, сертификат или другой механизм аутентификации, предусмотренный банком; контролируйте сумму, валюту и идентификатор заказа; фиксируйте исходное событие в журнале. Ответ об успешной доставке уведомления следует отправлять только после того, как событие сохранено или поставлено в надежную очередь.
6. Реализуйте обработку ошибок и повторов
Ошибки стоит разделить на несколько групп. Неверная сумма или просроченный платеж требуют исправления данных и обычно не должны повторяться автоматически. Временная недоступность банка, тайм-аут и разрыв соединения допускают повторный запрос, но только с тем же ключом идемпотентности. Неизвестный статус нельзя превращать в «неуспешно» без дополнительной проверки: операция могла пройти, а ответ потерялся.
Для фоновой проверки используйте ограниченное число повторов с увеличивающимся интервалом. Слишком частые запросы могут привести к блокировке или превысить лимит API. Нужны также тайм-ауты, защита от повторной обработки, очередь событий и понятная процедура ручной проверки спорных платежей.
7. Организуйте сверку и контроль
Сверка сопоставляет заказы в вашей системе с операциями в банке и поступлениями по выписке. Она выявляет ситуации, которые не всегда видны в реальном времени: платеж принят, но уведомление не дошло; возврат создан в магазине, но отклонен банком; сумма в заказе не совпала с фактическим зачислением.
Запускайте автоматическую сверку по расписанию и сохраняйте результат каждой проверки. Полезные поля — внутренний номер заказа, банковский идентификатор, сумма, комиссия, дата операции, статус и дата последней проверки. Сотруднику должны быть видны не только ошибки, но и следующий шаг: повторить запрос, связаться с банком или вернуть деньги вручную.
8. Проведите тестирование до запуска
В тестовой среде проверьте успешную оплату, отказ, истечение срока действия, отмену, полный и частичный возврат, повторную отправку уведомления и задержку ответа. Отдельно смоделируйте два параллельных запроса на оплату одного заказа и повторное создание платежа после сетевого сбоя.
Перед переходом в рабочий режим проверьте сертификаты, адреса уведомлений, лимиты, часовой пояс, округление сумм и тексты чеков. Составьте план отката: как отключить новый способ оплаты, не потеряв уже созданные операции, и кто принимает решение по спорным платежам.
После запуска следите за долей успешных операций, временем ответа банка, числом неподтвержденных платежей, ошибками уведомлений и расхождениями при сверке. Эти показатели быстро показывают, где проблема — в интерфейсе, API банка, обработке событий или внутренних правилах заказа. Хорошая интеграция с банковскими API и СБП — это не один удачный запрос, а управляемый процесс от создания платежа до окончательного зачисления или возврата.
