mspTBank
Приём оплаты через T-Bank для MiniShop3: redirect, webhook, чеки 54-ФЗ, одно- и двухстадийная схема, возвраты
Системные настройки mspTBank
Краткая последовательность шагов: Быстрый старт.
Все настройки в пространстве имён msptbank. Ключ в modSystemSetting и в getOption() пишется с подчёркиванием: msptbank_terminal_key, msptbank_password и т.д.
Обязательные
| Ключ | Тип | Описание |
|---|---|---|
msptbank_terminal_key | текст | TerminalKey терминала из личного кабинета T-Bank (20 символов). |
msptbank_password | пароль | Password терминала (20 символов, секрет). Используется для подписи запросов и проверки webhook. |
Без пары ключ + пароль TbankPayment::send() вернёт ошибку «Payment is not configured».
Режим и API
| Ключ | Тип | По умолчанию | Описание |
|---|---|---|---|
msptbank_test_mode | да/нет | Да | Да: API https://rest-api-test.tinkoff.ru/v2/. Нет: боевой https://securepay.tinkoff.ru/v2/. |
msptbank_debug | да/нет | Нет | Подробные логи компонента в MODX. Password в лог не попадает. |
msptbank_two_stage | да/нет | Нет | Двухстадийная схема: в Init передаётся PayType = T. После webhook AUTHORIZED компонент вызывает Confirm. |
Возврат покупателя
| Ключ | Тип | Описание |
|---|---|---|
msptbank_success_url | URL | Куда направить покупателя после успешной оплаты. Если пусто, используется страница благодарности MS3 (ms3_order_redirect_thanks_id) с msorder=<uuid>. |
msptbank_fail_url | URL | Страница при неуспешной оплате. Если пусто, используется та же страница благодарности с payment_fail=1. |
Возвраты
| Ключ | Тип | По умолчанию | Описание |
|---|---|---|---|
msptbank_status_refunded | число | 0 | ID статуса заказа после REFUNDED в webhook или успешного processor refund. При 0 статус не меняется. |
Служебные
| Ключ | Тип | Описание |
|---|---|---|
msptbank_core_path | текст | Путь к core/components/msptbank/, если компонент лежит не в стандартном месте. Используется в webhook.php при bootstrap. Обычно менять не нужно. |
Чеки 54-ФЗ
| Ключ | Тип | По умолчанию | Описание |
|---|---|---|---|
msptbank_send_receipt | да/нет | Да | Передавать Receipt в T-Bank. Отключите, если онлайн-касса не подключена в терминале. |
msptbank_taxation | список | usn_income | Система налогообложения для Receipt.Taxation. |
msptbank_vat | список | none | Ставка НДС для всех позиций чека. |
Если msptbank_send_receipt включён, компонент добавляет объект Receipt в запросы Init, Confirm для двухстадийной оплаты и Refund.
Чек собирается из данных заказа MiniShop3:
- товары берутся из
msOrder->getMany('Products') - доставка добавляется отдельной строкой, если
delivery_cost > 0 - разница между итогом заказа и суммой строк добавляется как «Комиссия за оплату»
- если сумма строк больше итога заказа, позиции корректируются под сумму операции
- Email или телефон берётся из адреса заказа, затем из клиента MiniShop3.
Для T-Bank обязателен Email или Phone. Если оба значения пустые или не проходят базовую проверку, компонент пишет warning и отправляет платёж без Receipt, чтобы не блокировать оплату. Если сумма строк чека не равна сумме платежа или возврата, запрос не отправляется и в лог попадает ошибка.
Системы налогообложения
| Значение | Описание |
|---|---|
osn | Общая система налогообложения |
usn_income | УСН «доходы» |
usn_income_outcome | УСН «доходы минус расходы» |
esn | Единый сельскохозяйственный налог |
patent | Патентная система |
Ставки НДС
| Значение | Описание |
|---|---|
none | Без НДС |
vat0 | НДС 0% |
vat5 | НДС 5% |
vat7 | НДС 7% |
vat10 | НДС 10% |
vat22 | НДС 22% |
vat105 | НДС 5/105 |
vat107 | НДС 7/107 |
vat110 | НДС 10/110 |
vat122 | НДС 22/122 |
Связанные настройки MiniShop3
| Ключ MS3 | Роль |
|---|---|
ms3_status_paid | Статус «оплачен» (часто ID 3). Webhook выставляет при CONFIRMED или AUTHORIZED. |
ms3_status_canceled | Статус отмены (часто ID 5). Webhook выставляет при REJECTED. |
ms3_order_redirect_thanks_id | Ресурс «Спасибо за заказ», если не заданы msptbank_success_url / msptbank_fail_url. |
Проверьте значения в Системные настройки → minishop3 или в админке MiniShop3.
Что дальше
- Интеграция и сценарии: webhook, чеки 54-ФЗ, двухстадийная оплата, processor refund
- FAQ: типовые ошибки конфигурации