Интеграция Т-Банка с amoCRM: автоматическая обработка оплат и возвратов
amoCRM · Т-Банк · Laravel · Webhook · Очереди
Разработал серверную интеграцию, которая принимает уведомления Т-Банка, находит нужную сделку в amoCRM и обновляет её после оплаты или возврата.
Это уже не простая передача формы с лендинга в CRM. Система проверяет подлинность уведомления, защищается от повторной обработки, различает полную оплату и рассрочку, сохраняет историю операции и отдельно обрабатывает возвраты.
Задача проекта
После оплаты менеджеру не нужно вручную искать заказ, менять этап сделки и переносить данные из банковского кабинета в CRM. Интеграция связывает платёж с заявкой по идентификатору заказа и проводит сделку по нужному сценарию.
Банк должен быстро получить подтверждение приёма уведомления, а вся работа с amoCRM — выполняться надёжно в фоне, даже если API CRM временно недоступен.
Поэтому приём webhook и обновление сделки разделены. Публичная точка принимает и проверяет событие, сохраняет его в базе и ставит задание в очередь. Отдельный worker обращается к amoCRM и фиксирует результат.
Как проходит подтверждённая оплата
Т-Банк отправляет уведомление
Laravel принимает webhook, ограничивает размер запроса и проверяет обязательные поля.
HTTP webhook · rate limit · validationСистема проверяет подпись
Подпись пересчитывается по алгоритму банка с секретом терминала. Уведомление с неверным TerminalKey или Token отклоняется.
SHA-256 · hash_equalsПлатёж сохраняется
Событие записывается локально по уникальному PaymentId. Повторная доставка того же уведомления не создаёт вторую обработку.
MySQL · идемпотентностьЗадание уходит в очередь
Webhook сразу отвечает банку, а интеграция с CRM выполняется фоновым заданием с повторами при временных ошибках.
Laravel Queue · retry · lockСделка обновляется в amoCRM
Система находит единственную сделку с точным OrderId, проверяет PaymentId, меняет этап и добавляет примечание с параметрами операции.
amoCRM API · OrderId · PaymentId
Что автоматизировано
Точное сопоставление сделки
Поиск выполняется по OrderId. Совпадение должно быть единственным и точным; PaymentId используется как дополнительная проверка, а не как повод связать платёж с похожей заявкой.
Полная оплата или рассрочка
Сумма уведомления сравнивается с полной стоимостью сделки в целых копейках. Равная сумма переводит сделку в оплаченные, меньшая — на этап рассрочки. Переплата или некорректная стоимость требуют ручной проверки.
Примечание в карточке
В сделке остаются PaymentId, OrderId, сумма, статус и время подтверждения. Перед добавлением система проверяет, что такое примечание ещё не создано.
Связанные неоплаченные заявки
Интеграция может найти другие заявки пользователя без подтверждённой оплаты. Совпадение принимается только при одновременном точном совпадении нормализованных телефона и email.
Возврат платежа
Для статуса REFUNDED запускается отдельное задание. Оно повторно проверяет OrderId и PaymentId, переводит сделку на этап возврата и добавляет отдельное примечание.
Безопасные журналы
Секреты, данные карты и персональные поля маскируются перед сохранением технического payload и записью в лог. Ошибки остаются пригодными для диагностики без раскрытия чувствительных данных.
Надёжность при повторных уведомлениях и сбоях: вопросы и ответы
Что произойдёт, если Т-Банк отправит один webhook несколько раз?
PaymentId уникален в локальной таблице. Повторное уведомление подтверждается банку, но не создаёт второе задание, примечание или переход сделки.
Что будет, если amoCRM временно недоступна?
Платёж уже сохранён локально, поэтому событие не теряется. Фоновое задание повторит обращение к amoCRM по заданному графику; ошибки ограничения частоты и ответы сервера 5xx считаются временными.
Что делать, если сделка ещё не появилась в amoCRM?
Такое возможно, когда сайт создаёт сделку почти одновременно с оплатой. Интеграция считает отсутствие сделки временной ситуацией и повторяет поиск через очередь.
Как платёж сопоставляется со сделкой?
Основной ключ — OrderId из банковского уведомления. Интеграция требует единственного точного совпадения, а PaymentId использует как дополнительную проверку идентичности операции.
Можно ли использовать префикс в OrderId?
Да. Настроенный префикс удаляется только из значения для поиска сделки. Исходный OrderId сохраняется без изменений в локальной записи и примечании amoCRM.
Как система различает полную оплату и рассрочку?
Сумма подтверждённого платежа сравнивается с полной стоимостью сделки. Равная сумма означает полную оплату, меньшая переводит сделку на настроенный этап рассрочки.
Что произойдёт, если полная стоимость сделки не заполнена?
При отсутствии стоимости задание будет повторено: поле могло ещё не успеть заполниться. Некорректное значение считается постоянной ошибкой и не приводит к автоматическому изменению сделки.
Что будет, если сумма платежа больше стоимости сделки?
Интеграция не меняет этап автоматически. Переплата фиксируется как ситуация для ручной проверки, чтобы ошибочное сопоставление или неверная стоимость не исказили данные CRM.
Как обрабатываются суммы с копейками?
Сравнение выполняется в целых копейках без float. Если бюджет amoCRM нельзя передать без округления, система завершает операцию явной ошибкой вместо изменения суммы.
Как обрабатывается полный возврат платежа?
Для подтверждённого REFUNDED запускается отдельное задание. Оно проверяет OrderId и PaymentId, переводит сделку на этап возврата и добавляет отдельное примечание с параметрами операции.
Закроет ли частичный возврат сделку?
Нет. Статус PARTIAL_REFUNDED намеренно не переводит сделку на этап полного возврата: для него требуется отдельное бизнес-правило.
Может ли позднее уведомление об оплате отменить уже принятый возврат?
Нет. После принятого возврата устаревшее подтверждение оплаты не возвращает запись и сделку в предыдущее состояние.
Что происходит при конфликте OrderId или суммы возврата?
Сделка не закрывается автоматически. Событие сохраняется со статусом ручной проверки, а уже подтверждённая история оплаты остаётся неизменной.
Могут ли два worker одновременно обработать один платёж?
Для одного платежа используется блокировка задания и условные изменения состояния. Параллельный или запоздавший worker не должен повторно обновить сделку.
Попадают ли секреты и данные карты в технические логи?
Нет. Token, пароль терминала, данные карты и контактные поля маскируются перед сохранением payload и записью диагностической информации.
Технологии проекта
- Backend
- Laravel / PHP webhook, бизнес-правила и API-интеграция
- MySQL состояние платежей и защита от дублей
- Фоновая обработка
- Laravel Queue задания оплаты и возврата
- Queue worker повторы и восстановление после сбоев
- Внешние системы
- Т-Банк API подписанные уведомления
- amoCRM API / OAuth поиск и обновление сделок
- Эксплуатация
- Docker изолированный запуск сервисов
- Тесты webhook, дубли, рассрочка, сбои и возвраты
Результат
Оплата проходит от банковского уведомления до обновлённой карточки amoCRM без ручного переноса данных. Менеджер видит актуальный этап сделки и историю операции, а технические сбои не приводят к потере события или повторному проведению платежа.
Архитектуру можно адаптировать под другой сайт, набор этапов amoCRM и правила оплаты: полную сумму, рассрочку, возврат или дополнительную проверку связанных заявок.
Нужна интеграция оплаты с CRM?
Помогу связать сайт, платёжный сервис и amoCRM: спроектировать сценарии, реализовать webhook и очередь, учесть повторные уведомления, ошибки API и возвраты.