docs.modx.pro
msp3Tochka
Приём оплаты через Точка Банк для MiniShop3: платёжная ссылка, webhook JWT, одно- и двухстадийная схема
  • MODX 3
  • PHP 8.2
  • miniShop3
Зависимости
  • miniShop3
  1. Компоненты
  2. msp3Tochka
  3. Быстрый старт

Быстрый старт ​

Требования ​

ТребованиеВерсия
MODX Revolution3.0+
MiniShop31.14.0‑beta1 и новее
PHP8.2+. Требуется расширение openssl для проверки подписи уведомления банка
pdoTools3.0+
СайтHTTPS на webhook; 301 с HTTP часто приводит к потере тела POST

Шаг 1: Провайдер modstore и установка пакета ​

  1. Система → Управление пакетами → Провайдеры → добавьте modstore.pro:
    • URL: https://modstore.pro/extras/
    • Email и API‑ключ из личного кабинета modstore.pro
  2. Убедитесь, что установлен MiniShop3.
  3. Управление пакетами → установите msp3Tochka (в Show Details укажите провайдера modstore.pro).
  4. Управление → Очистить кеш.

Резолвер создаёт два активных способа. Старый mspTochka, если он уже установлен, не удаляется.

НазваниеКласс
Оплата через Точка БанкMsp3Tochka\Payment\TochkaPayment
Оплата через Точка Банк (двухстадийная)Msp3Tochka\Payment\TochkaTwoStagePayment

JWT и customerCode поместите в msPayment.properties (ключи jwt_token, token, secret или secret_key). Если свойства пусты, пакет читает системные настройки. При пустом JWT пакет использует устаревший ключ msptochka_jwt_token.

Пакет не отправляет оплату, если сумма заказа меньше 1 копейки. paymentLinkId ограничен 45 символами.

Откуда брать ключи ​

Для работы требуется открытый счёт в Точке и подключённый интернет‑эквайринг. В песочнице боевые ключи не нужны. Публичные значения приведены в шаге 3.

JWT ​

Токен выпускается в интернет‑банке. Инструкция банка: авторизация по JWT.

  1. Вкладка Сервисы.
  2. В блоке Все сервисы откройте Интеграции и API.
  3. Создать JWT‑ключ. Укажите название и срок действия. По истечении срока ключ перевыпускается вручную. Refresh‑токен не предусмотрен.
  4. Продолжить. Отметьте разрешения. Для эквайринга банк обычно требует MakeAcquiringOperation и ReadAcquiringData. Пакет не проверяет права токена. При нескольких компаниях разрешения настраиваются для каждой. ManageWebhookData требуется только при регистрации webhook через API Точки. Из админки MODX пакет не регистрирует webhook.
  5. Создать ключ и ввести код из СМС.
  6. Скопируйте JWT в поле msp3tochka_jwt_token. Тот же токен отображается в блоке JWT‑ключи того же сервиса.

На том же экране банк показывает client_id. В настройках msp3Tochka поля для него нет. Он требуется при регистрации webhook через API Точки: один URL на один client_id.

При перевыпуске банк удаляет старый JWT и старый client_id. В MODX вставьте новый токен. Webhook со старым client_id зарегистрируйте заново.

В запросах пакет автоматически подставляет заголовок Authorization: Bearer.

customerCode ​

Это идентификатор компании в API. Банк обычно выдаёт строку до 9 символов. Пакет не проверяет длину. На экране создания JWT этот код не отображается.

Вызовите метод Get Customers List с вашим JWT. Найдите объект, у которого customerType равен Business, и возьмите значение customerCode. Вставьте его в поле msp3tochka_customer_code.

Неверный или пустой код приводит к ошибке 403 Forbidden by consent.

merchantId ​

Поле msp3tochka_merchant_id оставьте пустым, если у вас одна торговая точка интернет‑эквайринга.

При нескольких точках банк требует merchantId. Согласно документации банка, это 15 цифр из метода Get Retailers. Пакет не проверяет формат. Идентификатор точки СБП отличается: по правилам банка он начинается с MA или MB. Его не следует помещать в эту настройку.

Термины банка: customerCode и merchantId.

Шаг 2: Куда вписать в MODX ​

  1. Настройки → Системные настройки, фильтр msp3tochka.
  2. Либо откройте способ оплаты и заполните свойства: jwt_token (а также token, secret, secret_key) и customer_code. Непустые свойства имеют приоритет над системными настройками.
  3. После сохранения: Управление → Очистить весь кеш. Иначе API может не увидеть новые значения.

Список полей: Системные настройки.

Шаг 3: Песочница ​

msp3tochka_test_mode = Да. Хост: https://enter.tochka.com/sandbox/v2.

Публичные значения из документации Точки:

  • JWT: sandbox.jwt.token
  • customerCode: 1234567ab
  • merchantId: 200000000001097

В песочнице отсутствует платёжная форма. Ссылка ведёт на merch.example.com. Запрос статуса возвращает учебный ответ: оплачено, сумма 100 ₽, номер ссылки в ответе отсутствует. Пакет в этом случае берёт номер из токена. Уведомление пройдёт только при сумме заказа 100 ₽.

Оплата картой в песочнице невозможна.

Шаг 4: URL уведомлений ​

В кабинете Точки укажите событие acquiringInternetPayment. Укажите URL сайта:

text
https://ваш‑домен.ru/assets/components/msp3tochka/webhook.php

HTTPS без Basic Auth и без 301. Тело уведомления – компактный JWT, Content‑Type: text/plain. Пакет проверяет подпись ключом банка (msp3tochka_webhook_jwk_url), затем самостоятельно запрашивает статус платежа.

Шаг 5: Способ оплаты в MiniShop3 ​

  1. В админке MiniShop3 откройте Настройки → Оплаты.
  2. Включите Оплата через Точка Банк или Оплата через Точка Банк (двухстадийная).
  3. Привяжите способ к доставке.

Если рядом установлен старый mspTochka, отключите его и измените URL webhook. Подробнее: Переход.

Шаг 6: Боевой режим ​

  1. msp3tochka_test_mode = Нет. Хост в боевом режиме: https://enter.tochka.com/uapi, если не задан msp3tochka_api_base_url.
  2. Вставьте боевые JWT, customer_code и при нескольких точках merchant_id. Очистите кеш.
  3. Зарегистрируйте webhook из шага 4.
  4. Первый платёж лучше провести на 1 ₽. Проверьте попытку paid, статус ms3_status_paid и письмо из Центра уведомлений.
  5. Отключите msp3tochka_debug.