MevvPos Documentation

Установка

MevvPos требует WordPress 6.0+, PHP 8.1+ и WooCommerce 9.0 или новее. WooCommerce — жёсткая зависимость, объявленная в заголовке плагина: без него WordPress откажет в активации, а на более старых версиях WordPress плагин просто ничего не делает.

Загрузите плагин в разделе Плагины → Добавить новый → Загрузить плагин и активируйте его.
Откройте MevvPos в левом меню админки. Есть и ярлык внутри WooCommerce — там, где продавцы обычно ищут настройки платежей.
На вкладке Общие включите способ оплаты и задайте название, которое покупатель увидит при оформлении заказа.
В разделе API банка выберите свой банк и введите выданные им учётные данные.
В разделе Рассрочка и комиссия введите свои ставки по рассрочке.
Проверьте работу с тестовыми учётными данными банка, прежде чем выходить в боевой режим.

Бесплатная редакция не создаёт таблиц в базе данных и не регистрирует запланированных задач. Всё живёт в настройках WordPress и в мета-полях заказа.

Pro — это отдельный плагин, который устанавливается рядом с бесплатным, а не заменяет его. Бесплатный плагин публикуется на WordPress.org, где всё опубликованное можно распространять дальше по GPL; если бы платный исходный код лежал в том же пакете, любой, кто удалил бы проверки лицензии, имел бы законное право его распространять. Лицензионный ключ вводится на вкладке Лицензия.

Открытие WooCommerce → Настройки → Платежи → MevvPos перенаправляет вас на экран MevvPos. Это сделано намеренно: у этих настроек одно место, а не два, которые могут разойтись.

Как это работает

Вы определяете одну или несколько записей POS. Запись POS — это виртуальный POS одного банка: его учётные данные, адрес шлюза, ставки рассрочки.
При оформлении заказа покупатель вводит карту. Первые шесть цифр — BIN — определяют выпустивший её банк.
MevvPos ищет этот BIN и отправляет платёж на ваш POS в этом банке, если он у вас есть. Иначе платёж уходит на ваш POS по умолчанию.
Рассрочка предлагается только тогда, когда карта принадлежит собственному банку этого POS, потому что банки не дают рассрочку по картам другого банка.
Покупатель проходит 3-D Secure в банке, и банк возвращается на единственный адрес обратного вызова на вашем сайте.
Подпись на возврате проверяется ключом того POS, который заказ действительно использовал, заказ завершается, а результат записывается.

Номер карты, срок действия и CVV никогда не записываются ни в вашу базу данных, ни в сессию WooCommerce. Из данных карты сохраняются только первые шесть цифр и распознанное имя банка.

Записи POS

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

По умолчанию: POS, который принимает платёж, когда лучшего совпадения не нашлось. Он всегда ровно один.
Неактивен: Сохранён, но не принимает платежи. Используйте это вместо удаления, когда POS настроен, но ещё не запущен в банке, — иначе покупатель с картой этого банка не сможет заплатить.
Ожидание лицензии: Запись существует, но спит, потому что лицензия неактивна. Ничего не удалено; при продлении лицензии она продолжит с того же места.
Данные API не введены: У записи ещё нет номера магазина.

Банки обозначены цветной полосой, а не логотипом. Логотипы банков — товарные знаки, а пятнадцать логотипов — это и юридический риск, и постоянное сопровождение; вы и так знаете, какой банк ваш.

Последний POS нельзя удалить, а последний включённый — отключить. Чтобы полностью перестать принимать оплату картой, отключите способ оплаты на вкладке Общие.

Бесплатная редакция допускает один POS. Дополнительные записи — возможность Pro, а следовательно, и маршрутизация по BIN: с единственным POS маршрутизировать не между чем.

API банка — учётные данные и адрес шлюза

Банк: Выберите банк, в котором открыт ваш POS. От этого выбора зависят и адрес шлюза, и список BIN, используемый для рассрочки. Организации, для которых реализации ещё нет, помечены «— yakında» (скоро) и выбрать их нельзя.
Номер продавца (Client ID): Номер магазина, который выдал вам банк.
Ключ продавца (Store key): Ключ безопасности магазина. Хранится как поле пароля; после сохранения показывается замаскированным.
Gate URL: Адрес, на который отправляется форма оплаты.
Включить тестовый режим: Останавливает автоматическое перенаправление, чтобы вы могли изучить запрос до отправки.

Оставленное пустым поле Store Key при сохранении означает «не менять». Запись пустого значения стёрла бы ключ, и ваш магазин перестал бы принимать платежи без единого сообщения об ошибке. То же правило действует и для остальных секретных полей.

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

Garanti BBVA — Merchant ID, имя пользователя для авторизации, пароль авторизации.
VakıfBank — Terminal No и адрес MPI (оставьте пустым, чтобы использовать тестовый адрес).
PayTR — Merchant Salt.
iyzico, Craftgate, Sipay — дополнительных полей нет: ключ API вводится в поле «Номер продавца», а секрет — в «Ключ продавца».

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

Для семи банков на NestPay адрес шлюза подставляется по выбранному банку, поэтому Gate URL можно оставить пустым. Для остальных поле заранее не заполняется: введите адрес, который дал вам банк или провайдер, иначе форме оплаты некуда отправляться.

Тринадцать поддерживаемых организаций

NestPay / Asseco (Payten): İş Bankası, Akbank, Halkbank, QNB, Şekerbank, TEB, Ziraat Bankası
Garanti GT3D: Garanti BBVA
PayFlex V4: VakıfBank
Платёжные организации: iyzico, PayTR, Craftgate, Sipay

Организации без реализации намеренно остаются в списке банков с пометкой «— yakında». Если их убрать, станет не видно, каких семейств протоколов ещё нет. Если ваш банк из их числа, сообщите об этом на вкладке Запрос по банку.

Только подпись NestPay имеет эталонный тест по опубликованному примеру самого банка. Каждый другой провайдер помечен в своём исходном коде как beta: поток реализован по документации, но ещё не проверен от начала до конца на действующем торговом аккаунте в этой организации. Эта пометка остаётся до тех пор, пока проверка не будет проведена.

Платёжные организации не выпускают карты, поэтому списка BIN у них нет. Вы выбираете их как свой POS, а не маршрутизируете к ним.

Маршрутизация по BIN

Первые шесть цифр карты определяют выпустивший её банк. MevvPos сопоставляет ровно по этим шести цифрам.

Снимок таблицы BIN поставляется внутри плагина — 1.449 BIN по 36 банкам в текущей сборке, — поэтому маршрутизация работает офлайн, в бесплатной редакции, с момента установки.
Pro обновляет её еженедельно с наших серверов. Обновление накладывается на упакованную таблицу, а не заменяет её: частичный или пустой ответ ни в коем случае не должен оставить магазин вообще без данных BIN.
Ответ, содержащий меньше сотни BIN, отклоняется как неправдоподобный и не записывается.
Конфликты — когда один и тот же BIN заявляют два банка — разрешаются на нашей стороне до отправки списка. Магазин, разрешающий их у себя, мог бы одновременно считать карту «своей» и направлять её в другое место.

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

Та же таблица при оформлении заказа отвечает и на второй, другой вопрос: принадлежит ли эта карта собственному банку данного POS? Именно это решает, предлагать ли рассрочку, — см. ниже.

Точность BIN не является платной возможностью. Pro оплачивает свежесть, а не правильность: упакованный список — тот же самый список, просто зафиксированный на момент сборки.

Рассрочка и комиссия

Ставки задаются для каждого POS, от разового платежа до двенадцати частей, на вкладке Рассрочка и комиссия. Это проценты: пишите 5.50 для 5,5 %.

0: Вариант показывается, комиссия не добавляется.
Пусто: Вариант не показывается вовсе. Пусто и ноль — не одно и то же.

Комиссия появляется в корзине как облагаемый налогом сбор с названием «N Taksit Komisyonu» и рассчитывается от суммы корзины, включая доставку и налог.

Рассрочка предлагается только по картам, выпущенным собственным банком этого POS, и это проверяется на сервере, а не просто скрывается в интерфейсе. Карта другого банка принудительно возвращается к единовременному платежу, а сбор снимается.

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

Форма настроек всегда показывает все двенадцать полей, какой бы ни была ваша лицензия. Если бы они исчезали при истечении лицензии, сохранение страницы молча стирало бы уже введённые ставки. Поля выше вашего предела помечены как «Доступно в Pro», а ваши значения сохраняются.

Таблицы рассрочки от банка нет. Ставки — те, которые вводите вы, а комиссия по прошлому заказу считается по ставке, действовавшей в день продажи: изменение ставки сегодня не переписывает вчерашний отчёт.

Поток оплаты и обращение с картой

Каждое семейство проходит через 3-D Secure. Режима без 3-D нет, и настройки для его отключения тоже.

Поток через форму: NestPay, Garanti, PayTR и Sipay: браузер отправляет подписанную форму в банк, покупатель проходит аутентификацию, и банк возвращается на ваш сайт.
Поток через сервер: VakıfBank, iyzico и Craftgate: ваш сервер общается с провайдером, получает страницу 3-D, показывает её и после аутентификации завершает продажу в режиме сервер-сервер.

Банк всегда возвращается на один адрес на вашем сайте: ?wc-api=mevvpos_callback. Подпись на этом возврате проверяется ключом того POS, который заказ действительно использовал и который записан в самом заказе, — при нескольких POS проверка не тем ключом даёт ошибку хеша на каждом без исключения платеже.

Карта никогда не попадает в вашу базу данных. Она хранится в браузере на время перенаправления и затем удаляется. Если при загрузке страницы оплаты её там нет — новая вкладка, обновление, отключённое хранилище, возврат назад из банка, — вместо отправки пустых полей в банк показывается видимая форма карты. Форма карты видима по умолчанию, и это сделано намеренно: поток оплаты не может зависеть от того, выполнился ли JavaScript.

Когда банк одобряет платёж, заказ завершается, даже если код статуса 3-D был неожиданным: заметка к заказу фиксирует аномалию и просит вас подтвердить её на экране самого банка. Если банк говорит «одобрено», значит с покупателя уже списали; отказ означал бы «с вашей карты списали, но заказ не прошёл».

Каждая попытка фиксирует использованный POS, банк и BIN карты, число платежей рассрочки и ставку, результат, код и сообщение ответа банка, а также ссылки авторизации и транзакции.

Отчёты

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

Бесплатная редакция отчитывается по фиксированному 30-дневному окну. Pro добавляет диапазоны 7 / 30 / 90 дней и три разбивки:

Нагрузка по рассрочке и комиссии — количество, выручка и нагрузка по комиссии на каждой ступени рассрочки.
Разбивка по POS и банкам — выручка, успехи, отказы и доля успеха по каждому POS и по каждому банку-эмитенту.
Распределение кодов отказа — с экспортом в CSV. Повторяющийся код отказа указывает на то, что можно исправить: нехватка средств — проблема покупателя, но ошибки проверки 3-D и настройки POS — ваши.

Данные, на которых строятся отчёты, собирает бесплатный плагин, поэтому история накапливается независимо от наличия Pro. Иначе нельзя: прошлые данные невозможно создать задним числом при переходе на Pro.

У только что установленного магазина графика нет. Запись начинается вместе с плагином, и экран заполняется после первой попытки оплаты.

Заявки в банк и поддержка

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

Форма поддержки просит не указывать номер карты и код безопасности. Для диагностики проблемы с платежом они не нужны никогда, и ни одна из форм не отправляет платёжных данных или данных карты.

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

Free и Pro

Разделение проходит по количеству, а не по возможностям. Все тринадцать организаций, 3-D Secure, тестовый режим, неограниченный объём транзакций и базовый отчёт по выручке входят в бесплатную редакцию.

Бесплатно: Один POS. До трёх платежей рассрочки, показываемых покупателю. Фиксированная 30-дневная сводка по выручке. Таблица BIN, упакованная вместе с плагином.
Pro: Неограниченное число записей POS — а значит, и маршрутизация по BIN. До двенадцати платежей рассрочки. Диапазоны отчётов и разбивки по POS, банкам, рассрочке и кодам отказа с экспортом в CSV. Еженедельное живое обновление BIN. Автоматические обновления самого плагина Pro.

Когда лицензия истекает или отсутствует:

Ваш магазин продолжает принимать платежи. На пути платежа нет ни одной проверки лицензии. Отрезать магазину выручку — недопустимый способ напомнить о продлении.
POS по умолчанию продолжает работать, вместе с 3-D Secure и тестовым режимом.
Дополнительные записи POS засыпают, но никогда не удаляются, вместе с учётными данными. При продлении они возобновляются.
Потолок рассрочки опускается обратно до трёх. Введённые вами ставки выше него сохраняются, а не очищаются.
Отчёты возвращаются к 30-дневной сводке. Собранная история не удаляется.
Живое обновление BIN прекращается; упакованная таблица продолжает работать.

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

Когда что-то не работает

Банк отклоняет каждый платёж без полезного сообщения: Почти всегда дело в подписи. Неверная подпись нигде не вызывает ошибки — банк просто отказывает. Проверьте номер магазина, ключ магазина и все дополнительные учётные данные для этого семейства: все они входят в подпись. Полезная проверка: банки по-разному отвечают на ошибку подписи и на недействительную карту; сообщение «недействительная карта» означает, что подпись у вас верная.
«Hash error» на обратном пути, когда POS несколько: Возврат — это отдельный запрос без сессии. MevvPos записывает, какой POS использовал заказ, и проверяет его ключом. Если вы удалили запись POS, через которую был оплачен заказ, проверка откатывается к POS по умолчанию и может не пройти.
Покупатель попадает на пустую страницу оплаты, или кнопка Öde (оплатить) ничего не делает: Плагин кеширования или оптимизации откладывает скрипты. В LiteSpeed исключите mevvpos, jquery и фронтенд-скрипты WooCommerce из списка задержки. Форма карты показывается по умолчанию, поэтому поток всё равно работает, а вот автоматическое перенаправление — нет.
После успешного платежа заказ остаётся в статусе «в ожидании»: Банк или провайдер не достучался до адреса обратного вызова. Проверьте, что ?wc-api=mevvpos_callback доступен снаружи — режим обслуживания, ограничение по IP или требование входа перед сайтом его заблокируют.
Форма оплаты отправляется обратно на ту же страницу: Поле Gate URL пусто для банка, чей адрес не подставляется заранее. Введите адрес, который дал вам банк или провайдер.
Тестовый режим включён, но платёж всё равно уходит в боевой банк: Тестовый режим останавливает автоматическое перенаправление и показывает вам запрос; он не переписывает адрес шлюза для банков на NestPay. На время тестирования впишите тестовый адрес вашего банка в Gate URL.
Рассрочка не появляется: Либо ставка для этого числа платежей пуста, а не равна нулю, либо карта другого банка, либо вы вышли за потолок бесплатной редакции в три платежа.
После обновления карты уходят не на тот POS: В более старых версиях были написанные вручную диапазоны BIN, частично неверные. Проверьте, что каждый POS записан на тот банк, в котором он действительно открыт.
Экран админки выглядит без стилей, или исправление не появляется: Устаревший кеш браузера. Перезагрузите страницу в обход кеша.

Ограничения

Список ниже составлен намеренно. Ничто из этого не является ошибкой.

Никаких возвратов и отмен из WordPress. Плагин не реализует API возвратов WooCommerce, и ни у одного провайдера нет вызова возврата. Возвращайте средства на экране самого банка.
Только турецкая лира. Код валюты зафиксирован у каждого провайдера; настройки мультивалютности нет.
Ни сохранённых карт, ни токенизации, ни подписок или регулярных платежей.
Предавторизации нет. Каждая транзакция — прямая продажа.
Маршрутизации по правилам нет. Маршрутизация идёт только по банку-эмитенту — не по сумме, платёжной системе или стране.
Форма оплаты написана для классического оформления заказа WooCommerce. Отдельного компонента для блочного оформления заказа в пакете нет.
От 3D Pay Hosting отказались намеренно. Размещённая у банка страница снимает область действия PCI, но заодно убирает BIN и таблицу рассрочки — а вся ценность этого плагина именно в маршрутизации, которую они делают возможной.
Редактора BIN нет. Таблицу ведём мы и объединяем её с живым обновлением; экрана для ручного редактирования нет.
Двадцать шесть организаций перечислены, но не реализованы. Они остаются на виду, чтобы был виден и пробел.
Каждый провайдер, кроме NestPay, сам объявлен бетой до проверки от начала до конца на действующем торговом аккаунте.
Вкладки находятся внутри страницы. Пункты бокового меню открывают экран MevvPos; переключайте вкладки на самой странице.

Что не хранится никогда и ни в каком виде: номер карты, срок действия и код безопасности. Из данных карты сохраняются только первые шесть цифр и банк, который они определяют. Хранение кода безопасности запрещено при любых обстоятельствах, а даже замаскированный код выдаёт свою длину.

От одного виртуального POS до карты, направленной в выпустивший её банк.