Точка Банк Эквайринг

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

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

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

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

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

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

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

• Модули → Управление модулями → Точка Банк Эквайринг: файловый журнал и параметры надёжности.
• Настройки → Журнал событий → Точка Банк: включение платёжных событий и диагностических записей 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.

Модуль проверяет подпись уведомления и сверяет сумму, operationId, paymentLinkId, customerCode и merchantId с сохранённой платёжной попыткой и заказом. При неполных или несовпадающих данных подписанного webhook модуль повторно проверяет операцию через GET по сохранённому ID платежа. Должны подтвердиться реквизиты, сумма и статус из уведомления.

Если API недоступен, данные не совпали или GET пока возвращает более ранний статус, модуль отвечает HTTP 503 и не отмечает уведомление обработанным. Ошибка применения статуса заказа также оставляет уведомление доступным для повторной обработки. В штатном журнале CS-Cart указываются источник проверки и названия несовпавших полей без раскрытия секретов.

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

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

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

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

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

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

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

Для запуска списания сменой статуса задайте разные статусы Авторизовано и Успешно. Только явный ручной переход между ними в двухстадийном режиме служит командой списания; переход в любой другой статус её не запускает.

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

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

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

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

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

Для российского НДС назначайте товару только один налог. Несколько выбранных налогов CS-Cart может рассчитать одновременно; они не являются альтернативными ставками, из которых магазин автоматически выбирает одну.

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

Единица измерения товара берётся из поля Товары → Товар → Цена за единицу → Название единицы. Точка Банк принимает только следующие значения: г., кг., т., см., дм., м., см2., дм2., м2., мл., л., м3, кВт.ч., Гкал., дн., ч., мин., сек., Кб., Мб., Гб., Тб. и шт.

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

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

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

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

Полученная предоплата 100%

Статус банка WAIT_FULL_PAYMENT при подтверждённых реквизитах и сумме, равной полной сумме заказа, означает полученную предоплату 100%, а не ожидание оплаты и не холд. Заказ получает настроенный успешный статус, оформление завершается штатным циклом CS-Cart, а покупатель возвращается на страницу «Спасибо», не в checkout.

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

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

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

1. После проверки банковского статуса AUTHORIZED, суммы и реквизитов заказ получает статус, выбранный для блокировки средств, а покупатель возвращается на страницу «Спасибо».
2. Откройте карточку заказа и найдите блок Точка Банк.
3. Запустите списание одним из двух способов: нажмите Подтвердить списание в блоке Точка Банк либо вручную измените статус заказа с настроенного статуса авторизации на настроенный успешный статус.
4. В обоих случаях модуль отправляет в Точка Банк команду подтверждения списания только один раз. Само нажатие кнопки или выбор статуса ещё не означает, что деньги списаны.
5. До подтверждения банка заказ сохраняет настроенный статус авторизации. После получения APPROVED модуль переводит заказ в настроенный успешный статус.
6. Если банк отклонил команду или запрос завершился ошибкой, успешный статус не применяется. Проверьте сообщение администратора и событие операции в штатном журнале CS-Cart.

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

Принятие команды списания ещё не подтверждает оплату. Состояния CAPTURE_PROCESSING и CAPTURE_ACCEPTED означают ожидание результата банка. Повторное нажатие, повторный переход статуса, webhook и синхронизация не отправляют повторный Capture. Запоздалый ответ на команду не заменяет уже полученный APPROVED старым холдом или ожиданием списания.

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

Полная отмена холда без списания

Кнопка Отменить холд доступна в карточке заказа для текущей платёжной попытки со статусом AUTHORIZED. Нужны права на управление заказами. Отмена выполняется только на всю исходную сумму холда; частичная отмена не поддерживается. Не используйте инструкции обычного частичного возврата для отмены части холда.

1. Откройте карточку заказа и проверьте текущий статус оплаты и ID платежа.
2. Нажмите Отменить холд и подтвердите полную отмену. Модуль через GET проверит в банке текущую операцию, её реквизиты, исходную сумму и статус AUTHORIZED. Изменение суммы заказа или ввод суммы возврата не меняют сумму отмены холда.
3. После проверки модуль отправит один запрос Refund Payment Operation на всю сумму в Data.amount. Предварительный Capture не выполняется, чек возврата DigitalKassa для отмены холда не создаётся.
4. Принятый банком запрос, в том числе ответ isRefund: true, ещё не означает, что холд снят. До конечного подтверждения отображаются Отмена холда обрабатывается и кнопка Проверить отмену холда.
5. Нажмите Проверить отмену холда, чтобы получить состояние банка. Эта проверка обращается к банку только через GET и не повторяет финансовый запрос. Фоновая синхронизация также только проверяет состояние.
6. После проверки конечного REFUNDED, CANCELLED/CANCELED или EXPIRED для ожидающей отмены модуль фиксирует REVERSE_CONFIRMED и показывает Холд отменён. Подтверждение отмены меняет состояние оплаты, но само по себе не меняет статус выполнения заказа.

Пока отмена ожидает подтверждения (REVERSE_PROCESSING или REVERSE_ACCEPTED), повторное нажатие не отправляет новый запрос отмены; доступны проверки состояния. Одновременное списание кнопкой или сменой статуса заказа блокируется. Устаревшая форма не может выполнить действие для старой платёжной попытки, а запоздалые события не открывают завершённый холд для нового списания.

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

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

Граница проверки: сценарий отмены проверен локальными тестами с подменой ответов API. Фактическое снятие холда, конечный ответ банка и уведомления на реальной банковской операции ещё требуют согласованной проверки. Локальные тесты не подтверждают реальное снятие блокировки средств.

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

Этот сценарий относится только к уже списанным средствам: APPROVED или REFUNDED_PARTIALLY при положительном доступном остатке. Он не применяется к AUTHORIZED или отмене части холда.

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

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

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

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

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

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

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

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

Отдельно отображаются ожидание оплаты, полученная предоплата, холд, ожидание списания, оплата, отказ, отмена, истечение срока, обработка и завершение отмены холда, обработка возврата, частичный и полный возврат. История платёжных событий остаётся в штатном журнале CS-Cart, а не в старых полях ответа в карточке заказа.

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

Событие платёжной операции содержит номер заказа, ID платежа и платёжной ссылки, тип и статус операции, сумму, валюту и состав заказа. Для товаров записываются ID, артикул, название, количество, цена, НДС и единица измерения; для доставки и доплат — тип, название и сумма без вымышленных артикулов.

Запрос отмены холда обозначается типом операции reverse, отдельно от обычного возврата refund. Запись об отправке или принятии запроса не заменяет подтверждение конечного состояния банка.

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

Как проверить работу

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

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

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

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

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