Простое подключение эквайринга Тинькофф (Т-Банк) к WooCommerce

Какую задачу решал этот код

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

Упрощённый поток выглядел так:

1. Прочитать корзину

   Получить товары, варианты, сумму и контактные данные покупателя из WooCommerce.

2. Создать заказ

   Добавить позиции, адрес и доставку, пересчитать итог и оставить заказ в ожидании оплаты.

3. Сформировать чек

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

4. Открыть форму банка

   Заполнить скрытые поля и отправить пользователя на платёжную страницу через клиентский скрипт.

Почему это только базовое подключение

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

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

Без отслеживания транзакции нельзя менять заказ на «оплачен»

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

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

local order: pending_payment
        ↓
create bank payment → save PaymentId
        ↓
customer pays on the bank page
        ↓
verified notification / status request
        ↓
paid | failed | cancelled | refunded

Как строить полноценную интеграцию

1. Зафиксировать заказ на сервере

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

2. Инициализировать платёж серверным запросом

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

3. Хранить историю статусов

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

4. Принимать уведомления

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

5. Обеспечить идемпотентность

   Повторное уведомление или retry запроса не должны повторно подтверждать заказ или выполнять бизнес-операцию.

6. Проверять зависшие платежи

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

7. Выполнять сверку

   Заказы, банковские операции, возвраты и фактические поступления регулярно сопоставляются. Расхождения попадают в отдельную очередь разбора.

Когда упрощённый вариант допустим

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

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