Инструкция к модулю «Точка Банк Эквайринг»

Что делает модуль

Модуль подключает интернет-магазин CS-Cart к интернет-эквайрингу Точка Банк. Покупатель выбирает способ оплаты при оформлении заказа и переходит на защищённую платёжную страницу банка. Модуль проверяет результат операции, обновляет статус заказа и сохраняет сведения о платеже в админ-панели.

Модуль поддерживает одностадийную и двухстадийную оплату, полные и частичные возвраты, запись платёжных событий в штатный журнал CS-Cart, передачу чеков в Точка Банк и отдельную интеграцию с DigitalKassa.

Что подготовить перед настройкой

• Активный интернет-эквайринг в Точка Банк.
• Токен API с разрешениями на создание платёжных операций, чтение данных эквайринга и чтение данных клиента.
• Client ID и разрешение ManageWebhookData, если нужна автоматическая регистрация уведомлений банка.
• Работающий HTTPS-сертификат на витрине магазина.
• Данные подключения DigitalKassa, если чеки будут отправляться через этот сервис.

Где находится модуль

• Модули → Управление модулями → Точка Банк Эквайринг: файловый журнал и параметры надёжности.
• Настройки → Журнал событий → Точка Банк: включение платёжных событий и диагностических записей API.
• Администрирование → Способы оплаты: подключение Точка Банк, способы оплаты, статусы заказов и фискализация.
• Заказы → Просмотр заказов → карточка заказа: сведения о платеже, подтверждение списания, возвраты и чеки.

Общие настройки модуля

1. Откройте Модули → Управление модулями.
2. Найдите Точка Банк Эквайринг и откройте его настройки.
3. В магазине с несколькими витринами выберите витрину, для которой настраивается модуль.
4. При необходимости включите дополнительную запись в файл ms_tochka_api.log.
5. Задайте количество повторов безопасных информационных запросов при сетевой ошибке.
6. Сохраните настройки и откройте страницу ещё раз, чтобы проверить сохранённые значения.

Создание платежа, подтверждение списания и возврат не повторяются автоматически. Это защищает магазин от повторной финансовой операции при неопределённом сетевом ответе.

Журнал событий

1. Откройте Настройки → Журнал событий.
2. Найдите группу Точка Банк.
3. Отметьте Все операции, чтобы записывать платёжные операции, изменения статусов, webhook, успешные и неуспешные запросы и ответы.
4. Отметьте Неудавшиеся операции, чтобы записывать только ошибки API и сетевые ошибки.
5. Сохраните настройки и обновите страницу, чтобы проверить выбранные значения.

Все записи находятся в штатном разделе Настройки → Журнал событий. Из карточки заказа доступны ссылки на события текущего заказа и на все события Точка Банк. Дополнительных журналов модуль не создаёт.

Если отмечены оба пункта, успешные операции записываются как обычные, а ошибки — как неудавшиеся. Одна ошибка не создаёт две одинаковые записи.

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

Создание способа оплаты

1. Откройте Администрирование → Способы оплаты.
2. Создайте новый способ оплаты или откройте существующий.
3. Выберите процессор MS: Точка Банк Эквайринг.
4. Откройте вкладку настройки процессора.
5. Заполните параметры подключения и сохраните способ оплаты.
6. Убедитесь, что способ оплаты включён и доступен нужной витрине и группе пользователей.

Параметры подключения

• Токен API: токен авторизации для создания и проверки операций.
• Client ID: идентификатор, который требуется для автоматической регистрации уведомлений банка. Если уведомления отключены, поле можно не заполнять.
• Режим тестирования: переключает модуль на песочницу Точка Банк. Песочница предназначена для проверки запросов и ответов; доступность полноценной платёжной страницы зависит от возможностей тестового окружения банка.
• Режим оплаты: одностадийное списание или двухстадийная оплата с холдированием.
• Код клиента (customerCode): код бизнес-клиента в Точка Банк.
• ID магазина (merchantId): идентификатор активной торговой точки.
• Автоматически зарегистрировать webhook: включает регистрацию HTTPS-адреса для уведомлений банка.
• Способы оплаты: банковская карта, СБП, Тинькофф и «Долями». Если варианты не выбраны, используется банковская карта.

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

Уведомления банка и синхронизация

При включённом webhook модуль регистрирует адрес уведомлений во время сохранения способа оплаты. Для этого нужны Client ID, разрешение ManageWebhookData и доступность витрины по HTTPS.

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

В качестве дополнительной страховки можно настроить периодическую синхронизацию незавершённых операций. Добавьте на сервере задание cron, которое обращается к адресу вида https://store.example/index.php?dispatch=ms_tochka.sync&cron_password=YOUR_CRON_PASSWORD. Используйте пароль cron из настроек безопасности CS-Cart и не передавайте его третьим лицам. Рекомендуемый интервал: 5 минут.

Сопоставление статусов заказа

Статусы задаются отдельно в настройках каждого способа оплаты с процессором MS: Точка Банк Эквайринг:

• Успешно: применяется после подтверждённой оплаты.
• Неуспешно: применяется после отклонённой, отменённой или истёкшей операции.
• Авторизовано: применяется при холдировании средств до подтверждения списания.

Все три поля обязательны. Для способа оплаты с пустыми значениями используются безопасные значения по умолчанию: Обработан (P), Неуспешен (F) и На удержании (A) соответственно.

Для блокировки средств выбирайте статус, который уменьшает остаток товара. Рекомендуется штатный статус На удержании. Если выбрать Открыт, Возвращено или другой статус без уменьшения остатка, CS-Cart сочтёт оформление незавершённым и вернёт покупателя в checkout вместо страницы «Спасибо».

После сохранения обновите страницу и убедитесь, что выбранные статусы не сбросились.

Фискализация через Точка Банк

Чтобы передавать состав заказа вместе с платежом, включите Отправлять чек для 54-ФЗ и настройте:

• систему налогообложения;
• ставку НДС по умолчанию для товаров без собственной ставки;
• признак способа расчёта;
• резервный признак предмета расчёта.

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

Фискализация через DigitalKassa

Чтобы отправлять чеки через DigitalKassa, включите соответствующий переключатель и заполните:

• Actor;
• Token;
• ID группы DigitalKassa;
• Систему налогообложения DigitalKassa.

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

Фискализация через Точка Банк и DigitalKassa включается независимо. Не включайте оба варианта одновременно, если одновременная отправка двух чеков не предусмотрена вашей кассовой схемой.

Как проходит одностадийная оплата

1. Покупатель оформляет заказ и выбирает Точка Банк Эквайринг.
2. Модуль создаёт новую платёжную попытку с уникальным идентификатором.
3. Покупатель переходит на страницу Точка Банк и выполняет оплату.
4. Модуль получает уведомление банка или проверяет операцию через API.
5. Сумма, торговая точка, клиент и идентификаторы операции сверяются с заказом.
6. После успешной проверки заказ получает настроенный статус.

Сам по себе возврат покупателя на страницу магазина не подтверждает оплату.

Как проходит двухстадийная оплата

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

1. После авторизации средств заказ получает статус, выбранный для блокировки средств, а покупатель возвращается на страницу «Спасибо».
2. Откройте карточку заказа и найдите блок Точка Банк.
3. Нажмите Подтвердить списание.
4. Дождитесь подтверждения банка и проверьте итоговый статус операции и заказа.

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

API Точка Банк не предоставляет модулю отдельную операцию отмены холда. Возврат доступен после подтверждённого списания средств.

Полный и частичный возврат

1. Откройте оплаченный заказ.
2. В блоке Точка Банк проверьте доступную для возврата сумму.
3. Для частичного возврата укажите сумму и нажмите Частичный возврат.
4. Для возврата всего остатка нажмите Полный возврат.
5. Проверьте результат в карточке заказа и штатном журнале событий CS-Cart.

Возврат меняет состояние платёжной операции, но сам по себе не меняет статус заказа CS-Cart. Если бизнес-процесс требует отдельного статуса заказа, назначьте его вручную.

Не повторяйте возврат сразу после сетевой ошибки, пока не проверите журнал и состояние операции в Точка Банк.

Комиссия эквайринга

В карточке заказа нажмите Узнать комиссию. Модуль запросит реестр Точка Банк и, если исходный платёж уже обработан банком, покажет комиссию и сумму к зачислению. Запрос только читает данные реестра и не меняет платёж или заказ.

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

Платёжные данные и журналы

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

Ссылка События заказа открывает штатный журнал CS-Cart с фильтром по номеру заказа. Ссылка Все события Точка Банк показывает все записи модуля. В расширенном поиске доступны отдельные фильтры по номеру заказа и ID платежа.

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

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

Проверка после настройки

1. Сохраните настройки модуля, обновите страницу и проверьте файловый журнал и количество сетевых повторов.
2. В разделе Настройки → Журнал событий → Точка Банк включите нужный уровень и проверьте, что значения сохраняются.
3. Сохраните способ оплаты и убедитесь, что токен, customerCode, merchantId, выбранные способы оплаты и статусы заказов не сбросились.
4. Проверьте регистрацию webhook или настройте резервную синхронизацию.
5. Создайте тестовый заказ с суммой, содержащей рубли и копейки.
6. Проведите успешную и неуспешную оплату и проверьте статусы заказов.
7. Создайте вторую попытку оплаты для того же заказа и убедитесь, что каждая попытка учитывается отдельно.
8. При двухстадийной схеме проверьте переход на страницу «Спасибо» после авторизации и последующее подтверждение списания.
9. Выполните частичный возврат с копейками, затем верните оставшуюся сумму.
10. Если используется DigitalKassa, проверьте чек прихода, чек возврата, обновление статуса и безопасную повторную отправку.
11. Проверьте события оплаты и webhook в штатном журнале CS-Cart. Повторное уведомление не должно повторять обработку.

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

Если оплата не работает

• Проверьте токен API, срок его действия и необходимые разрешения.
• Проверьте, что customerCode и merchantId относятся к одному клиенту и активной торговой точке.
• Убедитесь, что выбран правильный режим: песочница или рабочее окружение.
• Если не регистрируется webhook, проверьте Client ID, разрешение ManageWebhookData, HTTPS-сертификат и доступность витрины извне.
• Если статус заказа не меняется, проверьте сопоставление статусов, сумму операции и события Точка Банк в журнале CS-Cart.
• Если не создаётся чек, проверьте фискальные настройки, контакт покупателя, налоговые ставки и данные DigitalKassa.
• При неопределённом результате финансовой операции сначала проверьте её состояние в журнале и личном кабинете банка, затем повторяйте действие.