Интеграция интернет-эквайринга ВТБ на сайте Yii: как подключить оплату и не сломать логику заказов

Подключение интернет-эквайринга к действующему сайту редко сводится к простой отправке запроса в API банка. Особенно если проект уже работает, принимает заказы, бронирует билеты, меняет внутренние статусы и отправляет клиентам подтверждения. В такой задаче важно не только получить ссылку на оплату, но и правильно встроить банк в существующий бизнес-процесс.

В этом материале разберем реальный пример интеграции ВТБ в проект на Yii: с получением токена, созданием платежного заказа, возвратом клиента на сайт, проверкой статуса через API и переводом локального заказа в оплаченный статус.

Задача

Нужно было подключить новый способ оплаты через ВТБ к сайту на Yii, где уже была реализована старая логика оплаты через другой банк. То есть задача заключалась не просто в том, чтобы добавить еще одну кнопку оплаты, а в том, чтобы встроить новый банк в уже работающий процесс оформления заказа.

Для клиента всё должно выглядеть просто: пользователь выбрал билет, нажал кнопку оплаты, оплатил заказ и получил подтверждение. Но внутри сайта этот сценарий состоит из нескольких связанных этапов:

• получение access token;
• создание платежного заказа в ВТБ;
• редирект клиента на страницу оплаты;
• возврат клиента на сайт;
• проверка статуса заказа через API банка;
• смена внутреннего статуса заказа;
• смена статусов связанных билетов;
• запуск дальнейшей логики выдачи билета и отправки письма.

Это типичная задача из области сложных PHP-доработок: нужно не просто написать запрос к API, а аккуратно встроить новую логику в существующий проект. Похожие задачи мы выполняем в рамках услуги доработки Bitrix / PHP-задачи.

Что было на руках

Для подключения интернет-эквайринга были получены стандартные реквизиты:

• client_id;
• client_secret;
• Merchant-Authorization;
• test endpoint для token API;
• prod endpoint для token API;
• test endpoint для order API;
• prod endpoint для order API.

На этом этапе часто кажется, что большая часть интеграции уже решена. Есть доступы, есть адреса API, остается только отправить запрос. Но на практике реквизиты — это только стартовая точка.

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

Почему одной документации оказалось недостаточно

Формально документация ВТБ дает общую схему взаимодействия: как получить токен, как создать заказ, куда отправить пользователя и как получить информацию о платеже. Но в реальной интеграции важны детали, которые не всегда очевидны из инструкции.

В процессе подключения нужно было точно понять:

• нужно ли передавать Merchant-Authorization при получении токена;
• как правильно формировать заголовок X-IBM-Client-Id;
• какой набор полей должен быть в теле запроса при создании заказа;
• откуда брать ссылку на оплату;
• какие статусы реально возвращает ВТБ после оплаты;
• что считать успешной оплатой: статус заказа, статус транзакции или оба значения вместе.

Именно такие детали часто приводят к ошибкам вроде 403 Forbidden, unauthorized_client или к ситуации, когда заказ фактически оплачен, но внутри сайта остается в неправильном статусе.

С какими проблемами пришлось столкнуться

1. Ошибки соединения и SSL

Первый этап интеграции — получение токена — показал, что даже корректный endpoint может не заработать с первого раза. Причина может быть не в банке и не в реквизитах, а в окружении проекта: настройках curl, SSL-сертификатах и проверке цепочки сертификатов на сервере.

Поэтому при интеграции платежных систем важно проверять не только код, но и серверную среду. Если проект работает на старом окружении, проблемы могут возникнуть еще до того, как запрос дойдет до бизнес-логики.

2. 403 Forbidden при создании заказа

После успешного получения токена следующая ошибка появилась на этапе создания заказа. Это важный момент: если токен уже получен, значит базовая авторизация работает. Проблему нужно искать не в самом факте доступа, а в конкретном ресурсе, заголовках, формате запроса или связке client_id и Merchant-Authorization.

Такие ошибки нельзя решать угадыванием. Нужно сравнивать рабочий запрос, заголовки, тело JSON и фактический ответ банка.

3. Разница между test и prod

Отдельная проблема — разделение тестовой и боевой среды. Если использовать боевые реквизиты с тестовым endpoint или тестовые реквизиты с боевым endpoint, интеграция не заработает. Для банка это будут просто неверные данные.

Поэтому в конфиг проекта были вынесены отдельные параметры для test и prod режима, чтобы не смешивать окружения и быстро переключать интеграцию между ними.

4. Ограничения старой версии PHP

Еще одна практическая проблема возникла из-за старой версии PHP на сервере. Подготовленный класс клиента ВТБ использовал современный синтаксис с типизированными свойствами, например private string и private array.

На старой версии PHP такой код просто не загружался. Поэтому класс пришлось адаптировать под старый синтаксис, убрав конструкции, которые не поддерживались текущим окружением проекта.

Это хороший пример того, почему перед сложными интеграциями полезно делать техническую проверку проекта: версия PHP, расширения, SSL, curl, права доступа, логи и совместимость кода. Для таких задач у нас есть отдельная услуга технический аудит и оптимизация сайта.

Что реально помогло в интеграции

Самым полезным решением стало использование готового модуля Bitrix, в котором уже была реализована рабочая логика подключения к API ВТБ.

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

Вместо того чтобы вслепую подбирать параметры по документации, мы:

• изучили рабочий код Bitrix-модуля;
• посмотрели, как именно он получает токен;
• поняли, какие заголовки реально используются;
• разобрали структуру запроса на создание заказа;
• посмотрели, где в ответе находится ссылка на оплату;
• разобрали структуру статусов заказа и транзакции;
• перенесли нужную логику в Yii-проект.

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

Что удалось понять из готового модуля

Анализ рабочего модуля дал несколько важных практических ответов:

• запрос на получение токена отправляется с Merchant-Authorization;
• X-IBM-Client-Id формируется на основе client_id в нужном формате;
• для создания заказа лучше использовать не минимальный JSON, а полный рабочий набор полей;
• ссылка на оплату приходит в response.object.payUrl;
• статус заказа приходит в response.object.status.value;
• статус транзакции оплаты находится глубже — в transactions.payments[].object.status.value.

Эти детали оказались ключевыми. Без них можно получить токен, создать часть запроса, но так и не собрать стабильный процесс оплаты от начала до конца.

Как была устроена интеграция в Yii

Шаг 1. Настройка параметров

Сначала в конфиг проекта были вынесены все параметры интеграции:

• режим работы: test или prod;
• token URL;
• orders URL;
• preauth URL;
• client_id;
• client_secret;
• Merchant-Authorization.

Это позволило не зашивать доступы прямо в код и безопасно переключать интеграцию между тестовым и боевым режимом.

Шаг 2. Создание отдельного клиента VTB

Для работы с банком был написан отдельный PHP-класс, который отвечал только за интеграцию с ВТБ:

• получал access token;
• создавал платежный заказ;
• получал информацию о заказе после возврата клиента;
• логировал запросы и ответы для отладки.

Такой подход удобнее, чем размазывать API-запросы по контроллерам. Вся логика банка находится в одном месте, а остальной проект работает уже с понятными методами.

Шаг 3. Создание заказа на оплату

Когда пользователь подтверждает заказ на сайте, система:

• берет локальный номер заказа;
• формирует итоговую сумму;
• создает платежный заказ в ВТБ;
• получает payUrl;
• перенаправляет клиента на страницу оплаты банка.

На этом этапе важно сохранить связь между локальным заказом сайта и заказом, созданным на стороне банка. Без этой связи потом будет сложно правильно обработать возврат клиента и обновить статус.

Шаг 4. Возврат клиента на сайт

После оплаты ВТБ возвращает пользователя на маршрут вида:

/order/result?orderId=...

Но сам факт возврата на сайт еще не означает успешную оплату. Пользователь мог закрыть окно, вернуться после неудачной попытки или открыть страницу результата повторно.

Поэтому после возврата сайт не должен слепо доверять URL. Он должен самостоятельно обратиться в API ВТБ и проверить реальный текущий статус заказа.

Шаг 5. Проверка оплаты через API

После возврата клиента система дополнительно запрашивает у ВТБ информацию о заказе и проверяет:

• статус заказа;
• статус транзакции оплаты;
• сумму;
• идентификатор заказа на стороне банка;
• служебные данные платежа.

В рабочем сценарии были получены реальные статусы:

• PAID — заказ оплачен;
• CONFIRMED — платежная транзакция подтверждена.

Только после такой проверки можно безопасно переводить локальный заказ в оплаченный статус.

Почему бронь и оплата — не одно и то же

На проекте уже существовала внутренняя логика статусов:

• новый заказ;
• бронь;
• оплачен;
• аннулирован;
• возвращен.

На одном из этапов выяснилось, что после успешной оплаты через ВТБ заказ внутри сайта переводился не в статус “Оплачен”, а только в статус “Забронирован”.

Для бизнеса это критичная ошибка. Клиент оплатил заказ, но билет не отправился, потому что система считала заказ только забронированным. То есть оплата в банке прошла, но внутренняя бизнес-логика сайта не дошла до финального состояния.

После анализа логика была исправлена:

• успешный статус ВТБ начал переводить локальный заказ в оплаченный статус;
• связанные билеты также стали получать оплаченный статус;
• после этого могла запускаться стандартная логика выдачи билета;
• клиент начал получать письмо с подтверждением.

Именно поэтому интеграция оплаты всегда должна проверяться не только по факту списания денег, но и по финальному бизнес-результату: заказ оплачен, билет выдан, письмо отправлено.

Почему в логах могло быть несколько статусов по одному заказу

В процессе отладки было заметно, что по одному заказу в логах может появляться несколько записей со статусами. Это нормально, если таблица логов хранит историю обращений, а не только последнее состояние заказа.

Дополнительная сложность была в том, что старая модель логов изначально создавалась под другой банк и другие числовые коды ошибок. У ВТБ статусы приходят строками: CREATED, PAID, CONFIRMED и так далее.

Поэтому был добавлен дополнительный слой сопоставления:

• понятные статусы ВТБ сохраняются в логах как текст;
• внутренние integer-коды продолжают работать для старой админки;
• в истории остается полезная техническая информация;
• по заказу можно увидеть, например: order_status=PAID; payment_status=CONFIRMED.

Такой подход помогает не ломать старую часть проекта и при этом сохранять нормальную техническую диагностику для новой интеграции.

Что получилось в итоге

После доработки был собран полноценный рабочий процесс оплаты:

1. Пользователь оформляет заказ на сайте.
2. Сайт создает платежный заказ в ВТБ.
3. Клиент переходит на платежную страницу банка.
4. После оплаты возвращается на сайт.
5. Система дополнительно проверяет статус заказа через API ВТБ.
6. Если заказ действительно оплачен, локальный заказ переводится в оплаченный статус.
7. Связанные билеты также получают оплаченный статус.
8. После этого запускается логика выдачи билета и отправки письма клиенту.

В результате была подключена не просто “кнопка оплаты”, а полный надежный цикл: от создания платежа до корректного обновления внутренних данных проекта.

Что важно для владельца сайта

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

В такой задаче важно проверить:

• корректность реквизитов;
• работу test и prod окружения;
• авторизацию в API банка;
• SSL и сетевые запросы с сервера;
• создание платежного заказа;
• возврат клиента на сайт;
• повторную проверку статуса через API;
• обновление внутренних статусов заказа;
• финальную выдачу товара, услуги или билета.

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

Что важно для разработчика

С технической стороны в такой интеграции нужно собрать все уровни сразу:

• правильные endpoint’ы для test и prod;
• валидный token flow;
• корректные заголовки;
• правильное тело JSON-запроса;
• разбор структуры ответа банка;
• получение ссылки на оплату;
• обработку возврата клиента;
• идемпотентность повторных заходов на result URL;
• логирование запросов и ответов;
• сопоставление внешних статусов банка с внутренними статусами проекта;
• проверку конечного результата в бизнес-логике.

Главное — не ограничиваться проверкой “редирект на оплату работает”. Нужно убедиться, что после оплаты система действительно переводит заказ в нужное состояние и запускает все последующие действия.

Вывод

Интеграция ВТБ в Yii-проект показала типичную картину реальной разработки: документация нужна, но ее недостаточно; тестовое и боевое окружение могут вести себя по-разному; старый проект требует адаптации, а не простого копирования кода.

Ключевой результат был достигнут за счет технического разбора рабочей реализации, адаптации логики под Yii и внимательной связки внешних статусов банка с внутренними статусами проекта.

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