VibeFox MakeCommerce for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

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

Учётная запись MakeCommerce: нужны Shop ID и Secret key из Merchant Portal MakeCommerce (Settings > API). Тестовая и рабочая среды имеют раздельные учётные записи и ключи. Доступные способы оплаты и валюты определяются вашим договором с MakeCommerce. Валюты с тремя знаками после запятой, например KWD или BHD, не предлагаются.

Лицензионный ключ VibeFox: приобретается на vibefox.net. Один ключ работает на одном домене.

Установка

1. В бэк-офисе перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. По завершении загрузки нажмите Configure или позже найдите VibeFox MakeCommerce Payment в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в поле License key в блоке лицензии в верхней части страницы Configure и нажмите Activate (см. Лицензионный ключ).

4. Введите Shop ID и Secret key тестовой среды и, для реальных платежей, рабочие ключи (см. Настройка). В Merchant Portal ничего настраивать не нужно.

5. Включите Enable/Disable и нажмите Save. Проверьте платёж при включённом Test mode, затем отключите его, чтобы принимать реальные платежи.

При установке модуль создаёт статус заказа MakeCommerce payment on hold. PrestaShop предлагает новый модуль оплаты для всех валют, стран и групп покупателей. Ограничить их можно в разделе Payment > Preferences.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox MakeCommerce Payment > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Над полями страница показывает Test mode is on: payments are created in the MakeCommerce test environment and no real money is charged., пока включён тестовый режим. Она предупреждает, если способ оплаты включён, но Shop ID или Secret key текущей среды пусты, а также если MakeCommerce не может принимать оплату в валюте магазина по умолчанию. В обоих случаях способ оплаты скрывается на этапе оформления заказа. При сохранении пробелы из ключей удаляются.

MakeCommerce

Enable/Disable: Enable MakeCommerce payments включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое видят покупатели на этапе оформления заказа. Оно также сохраняется в заказе как название способа оплаты. По умолчанию: Bank link or card (MakeCommerce). Обязательное поле.

Description: текст, который отображается под способом оплаты на этапе оформления заказа. По умолчанию: Pay with your Estonian, Latvian, Lithuanian or Finnish bank, or by card. You will be redirected to the secure MakeCommerce payment page.

Учётная запись MakeCommerce

Shop ID и Secret key находятся в Merchant Portal MakeCommerce в разделе Settings > API. Тестовый и рабочий портал имеют раздельные учётные записи и ключи. В этом разделе есть ссылки на оба портала и на страницу регистрации MakeCommerce.

Test mode: использует тестовую среду MakeCommerce (реальные деньги не списываются). Новые платежи создаются в выбранной среде с её ключами. Каждый заказ запоминает среду, в которой был оплачен: проверки статуса и возвраты всегда направляются туда. Пока режим включён, покупатели видят под способом оплаты TEST MODE — MakeCommerce test environment, no real money is charged. По умолчанию: включено.

Test Shop ID: Shop ID вашей тестовой учётной записи в формате xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Test Secret key: Secret key вашей тестовой учётной записи.

Live Shop ID: Shop ID вашей рабочей учётной записи.

Live Secret key: Secret key вашей рабочей учётной записи.

Сохранённые секретные ключи больше не отображаются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Введите новое значение, только если хотите его изменить.

Clear saved secret keys: отметьте ключ и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

Уведомления об оплате

В Merchant Portal ничего настраивать не нужно. Callback URLs показывает для справки адрес возврата или отмены для покупателя и адрес для уведомлений об оплате. Каждая транзакция передаёт собственные URL-адреса возврата, отмены и уведомления, построенные на основе этих адресов с номером корзины и добавленным ключом. MakeCommerce отправляет подписанное сообщение на URL уведомлений (сервер — сервер), а через браузер покупателя — на URL возврата или отмены. Подпись проверяется Secret key той среды, в которой была создана транзакция. Сообщения без действительной подписи отклоняются.

Модуль обрабатывает следующие статусы транзакций MakeCommerce:

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

Дополнительно

Debug log: записывает вызовы API и уведомления об оплате в logs/wc_mkc_debug.log.php в папке модуля. Файл нельзя открыть через веб. Ошибки записываются всегда. Ключи и данные покупателей никогда не записываются. По умолчанию: выключено.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Delete data: если включено, при удалении модуля удаляются его настройки и журнал. Заказы и их платёжные данные MakeCommerce всегда сохраняются. По умолчанию: выключено.

Оформление заказа

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Bank link or card (MakeCommerce)) и подтверждает выбор. Модуль создаёт транзакцию MakeCommerce на сумму корзины в валюте корзины и отправляет покупателя на страницу оплаты MakeCommerce. Там покупатель выбирает банковскую ссылку или карту. Адрес электронной почты и страна покупателя передаются в MakeCommerce, а страница открывается на языке магазина, если MakeCommerce его поддерживает (эстонский, английский, латышский, литовский, финский, русский, немецкий, польский), в противном случае на английском. На этом этапе заказа ещё не существует.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после того, как MakeCommerce его подтвердит: по подписанному уведомлению или по подписанному возврату покупателя с проверкой транзакции через API MakeCommerce. После этого заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с сообщением Your MakeCommerce payment has been received. Если заказ был переведён на удержание для проверки, страница показывает Your MakeCommerce payment was received and is being reviewed by the shop.

Если платёж одобрен, но ещё не завершён, или MakeCommerce недоступен, страница Payment confirmation показывает We could not confirm your payment yet. If you completed it, your order will be updated automatically — please do not pay again. с кнопками Check again и Back to checkout. Уведомление создаст заказ, как только платёж будет завершён.

Если покупатель отменяет платёж на странице MakeCommerce или платёж истекает либо завершается ошибкой, покупатель возвращается к оформлению заказа с сообщением, например The payment was cancelled. You can try again or choose another payment method., The payment session expired. Please try again. или The payment was not completed. Please try again or choose another payment method. Корзина сохраняется, и покупатель может оплатить снова. Каждая попытка — это новая транзакция MakeCommerce. Более старая платёжная ссылка той же корзины по-прежнему работает, и корзину нельзя оплатить дважды за два заказа.

Если MakeCommerce не может начать платёж, покупатель остаётся на этапе оформления заказа с сообщением MakeCommerce is temporarily unavailable. Please try again in a moment or choose another payment method. или MakeCommerce could not start the payment for this order. Please choose another payment method or contact us. Техническая причина записывается в журнал.

Банк или карта выбираются на странице MakeCommerce, а не на вашей странице оформления заказа. В модуле нет сохранённых карт, регулярных платежей и подписок, а также доставки MakeCommerce (почтоматов, этикеток).

Заказы и возвраты

Статусы заказа

No order yet: покупатель был отправлен в MakeCommerce и ещё не оплатил или MakeCommerce ещё не подтвердил платёж. Существует только корзина.

Payment accepted: платёж подтверждён. Он записывается с ID транзакции MakeCommerce, а примечание показывает сумму, транзакцию, среду и способ проверки (API MakeCommerce или подписанное уведомление).

MakeCommerce payment on hold: оплаченная сумма или валюта отличались от корзины (например, корзину изменили после начала платежа), сумма отсутствовала, транзакция в MakeCommerce ещё не была окончательной, хотя была помечена как завершённая, или платёж поступил после отмены заказа. Примечание поясняет причину. Если оплаченная валюта совпадает с валютой заказа, в заказе записывается фактически оплаченная сумма. Транзакция с несоответствием никогда не оплачивает заказ позже; транзакция, которая ещё не была окончательной, завершает заказ, когда MakeCommerce сообщает о её завершении. Проверьте транзакцию в Merchant Portal и либо выполните заказ, либо возвратите платёж.

Refunded: платёж полностью возвращён через модуль.

Если для уже оплаченного заказа поступает второй платёж, заказ не меняется. Примечание предлагает вам вернуть дубликат в Merchant Portal MakeCommerce.

Блок оплаты MakeCommerce

На странице заказа отображается блок MakeCommerce payment со всеми транзакциями MakeCommerce по корзине (дата, ID транзакции, метка Test для тестовых платежей, сумма, статус и результат MakeCommerce), оплаченные и возвращённые суммы, история возвратов и MakeCommerce notes заказа. Кнопки блока требуют только права на редактирование заказов, а не доступа к модулям.

Check MakeCommerce payment status: запрашивает у API MakeCommerce статус транзакций корзины (сначала самые новые), применяет его и добавляет примечание с результатом. Используйте, когда покупатель говорит, что оплатил, но заказ не был завершён.

Возвраты

В блоке MakeCommerce payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину и нажмите Refund via MakeCommerce. Подтвердите вопрос Refund this amount via MakeCommerce? Поддерживаются полные и частичные возвраты. Возвраты ограничены суммой и валютой транзакции MakeCommerce, поэтому после несоответствия суммы можно вернуть не больше того, что покупатель фактически оплатил, а не сумму заказа. Возврат отправляется в ту среду, в которой был совершён платёж (тестовую или рабочую), поэтому ключи этой среды должны быть заданы. Причина передаётся в MakeCommerce как комментарий к возврату; если причины нет, комментарий — Refund for order и номер заказа. Если MakeCommerce не принимает возврат, блок показывает ошибку, добавляется примечание, и возврат не регистрируется. Если MakeCommerce ещё обрабатывает платёж, выводится сообщение MakeCommerce is still processing this payment — try the refund again later. Успешный возврат добавляется в историю возвратов и примечания с ID возврата MakeCommerce. Полный возврат переводит заказ в статус Refunded. Частичный возврат статус не меняет. Возвраты доступны после того, как MakeCommerce подтвердил платёж.

Модуль не создаёт накладные (credit slip). Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через MakeCommerce.

Возвраты, выполненные в Merchant Portal, поступают вместе со статусом транзакции и добавляются в примечания. Статус заказа и накладные автоматически не меняются.

Лицензионный ключ

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox MakeCommerce Payment — это первый блок на странице Modules > Module Manager > VibeFox MakeCommerce Payment > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату окончания действия лицензии и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-makecommerce и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только сотрудники, имеющие право Configure для этого модуля. Тексты блока следуют языку панели администратора (включены английский и русский).

Если ключ не принят, блок сообщает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: домене основного магазина, в том числе при мультимагазинной настройке. Удаление ключа из магазина не освобождает слот домена. Освободите слот в своём аккаунте на vibefox.net.

Без активного ключа MakeCommerce не показывается покупателям на этапе оформления заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в панель администратора, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его на этапе оформления заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты работают.

Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется, пока вы работаете в панели администратора: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

MakeCommerce не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён и в текущей среде заданы ключи: Test Shop ID и Test Secret key в тестовом режиме, Live Shop ID и Live Secret key в рабочем режиме. Проверьте, что у валюты корзины не более двух знаков после запятой. В разделе Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: уведомления не смогли дойти до магазина, например из-за брандмауэра или базовой аутентификации. Заказ также создаётся, когда покупатель возвращается в магазин или нажимает Check again. Проверьте, что заданы ключи той среды, в которой был совершён платёж: уведомление проверяется по Secret key этой среды, и без него MakeCommerce получает ошибку и повторяет попытку. Включите Debug log, чтобы увидеть уведомления.

Заказ в статусе MakeCommerce payment on hold: прочитайте MakeCommerce notes в блоке на странице заказа (см. Статусы заказа), проверьте транзакцию в Merchant Portal, затем выполните заказ или возвратите платёж.

Уведомления отклоняются: сообщение с неверной подписью, для другой корзины, другого магазина или транзакции, не созданной для корзины, отклоняется, и ничего не меняется. Проверьте, что Shop ID и Secret key принадлежат одной учётной записи и одной среде MakeCommerce.

Покупатель видит ошибку при выборе MakeCommerce: включите Debug log и посмотрите поле Log на странице модуля. Валюта, которую MakeCommerce не может списать, приводит к сообщению MakeCommerce cannot process payments in и коду валюты.

Возврат завершается ошибкой с сообщением о среде: заказ оплачен в тестовой или рабочей среде, а ключи этой среды не настроены. Введите их и повторите попытку.

Возврат завершается ошибкой No MakeCommerce transaction ID found for this order: у заказа нет подтверждённого платежа MakeCommerce. Выполните возврат в Merchant Portal.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox MakeCommerce Payment и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete data включено, настройки модуля и журнал удаляются. Если выключено, все настройки сохраняются для повторной установки. Транзакции и возвраты MakeCommerce и статус заказа MakeCommerce payment on hold всегда сохраняются, поэтому заказы, оплаченные ранее, можно вернуть и после повторной установки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

MakeCommerce — торговая марка её владельца. Этот модуль не связан с MakeCommerce и не одобрен ею.