VibeFox Moyasar for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Валюта: валюта корзины должна быть SAR, AED, USD, EUR, KWD, BHD или OMR. Для любой другой валюты способ оплаты скрывается на этапе оформления заказа.

Аккаунт Moyasar: нужны секретные API-ключи вашего аккаунта Moyasar (тестовый и рабочий). Используются только секретные ключи. Публичный ключ не нужен, так как оплата проходит на странице Moyasar. Рекомендуется настроить вебхук в Moyasar Dashboard (см. раздел «Настройка»).

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

Установка

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

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

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

4. Вставьте секретные ключи Moyasar и нажмите Save. Настройте вебхук в Moyasar Dashboard (см. раздел «Настройка»).

5. Включите Enable/Disable и нажмите Save. Оформите тестовый заказ в тестовом режиме, затем отключите Test mode.

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Moyasar Payment Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если для текущего режима не задан секретный ключ (тогда способ оплаты скрыт на этапе оформления заказа), если не сохранён общий секрет вебхука (тогда вебхук отклоняет все запросы) или если валюта магазина по умолчанию не поддерживается. Когда модуль включён в тестовом режиме, он показывает Test mode is active: payments are simulated, no money is charged. При сохранении модуль отклоняет публичный ключ, ключ другого режима или ключ с пробелами, сохраняет предыдущее значение и показывает причину.

Moyasar

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

Title: название способа оплаты, которое видит покупатель на этапе оформления заказа. Оно же сохраняется как название способа оплаты в заказе. По умолчанию: Pay with Moyasar. Обязательное поле.

Description: текст, который отображается под способом оплаты на этапе оформления заказа. По умолчанию: You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay. В тестовом режиме на этапе оформления заказа добавляется (Test mode: no real payment is made.)

API-ключи

Скопируйте секретные ключи из раздела Moyasar Dashboard > Settings > API Keys. Тестовые и рабочие ключи разделены. Тестовый режим использует только тестовый ключ, рабочий режим — только рабочий ключ.

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

Test secret key: секретный ключ тестового режима. Начинается с sk_test_.

Live secret key: секретный ключ рабочего режима. Начинается с sk_live_.

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

Уведомления об оплате (вебхук)

Вебхук рекомендуется, но не обязателен. Заказы также подтверждаются, когда покупатель возвращается в магазин, и по уведомлению о счёте, которое Moyasar автоматически отправляет в ваш магазин после оплаты счёта. Вебхук покрывает покупателей, которые закрыли браузер до возврата, и сообщает о возвратах, выполненных в Moyasar Dashboard. Добавьте его в разделе Moyasar Dashboard > Settings > Webhooks.

Webhook URL: отображается только для чтения, с кнопкой Copy. При включённых понятных URL выглядит так: https://your-shop/module/wcp_moyasar_payment_gateway/webhook, возможно, с кодом языка, например /en/. Копируйте URL точно так, как он показан в настройках. HTTP-метод: POST.

Webhook shared secret: введите то же значение, что и Shared secret вебхука в Moyasar. Если ничего не сохранено, Save создаёт случайный секрет; Generate a new secret заменяет сохранённый. Созданный секрет показывается один раз над настройками после сохранения и больше не показывается, поэтому сразу скопируйте его в Moyasar. Вебхуки без правильного общего секрета отклоняются.

Выберите для вебхука эти события (они также перечислены в этом разделе):

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

Заказы

Status after payment: статус заказа, который устанавливается после подтверждённой оплаты. Заказ создаётся сразу в этом статусе.

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

Clear saved secrets: отметьте Test secret key, Live secret key или Webhook shared secret и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

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

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

Clean uninstall: если включено, при удалении модуля удаляются его настройки и журнал. Платёжные данные, сохранённые с заказами (идентификаторы счёта и платежа Moyasar), сохраняются, чтобы возвраты оставались прослеживаемыми. По умолчанию: выключено.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Pay with Moyasar) и подтверждает выбор. Модуль создаёт счёт Moyasar на сумму корзины в валюте корзины и отправляет покупателя на его платёжную страницу. Там покупатель платит любым способом, включённым в вашем аккаунте Moyasar. В счёте указаны Order #, номер корзины и название вашего магазина. На этом этапе заказа ещё нет.

Заказ отмечается как оплаченный только после подтверждения Moyasar: модуль получает счёт через API Moyasar и проверяет, что он оплачен, принадлежит этой корзине и точно совпадает по сумме и валюте с корзиной. Затем создаётся заказ, и покупатель видит стандартную страницу подтверждения заказа с сообщением Your payment with Moyasar has been received. Если Moyasar удерживает платёж для проверки, страница показывает Your payment is being reviewed by Moyasar. The order will be updated automatically when Moyasar confirms it — please do not pay again. Если заказ находится на удержании для вашей проверки, страница сообщает, что платёж получен и заказ проверяется. Если проверяемый платёж позже не прошёл или неоплаченный заказ отменён, страница показывает Your Moyasar payment was not completed. Please contact us about this order.

Если покупатель вернулся без оплаты (например, кнопкой «Назад» на платёжной странице), он оказывается на этапе оформления заказа с одним из сообщений: The payment at Moyasar was not completed. You can try again or choose another payment method., Your Moyasar payment was declined or has expired. Please try again or choose another payment method. или, если платёж ещё нельзя проверить, We could not confirm your payment with Moyasar yet. If you completed the payment, the order will be updated automatically in a few minutes — please check your e-mail before paying again. Корзина сохраняется.

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

Если Moyasar не может начать платёж, покупатель остаётся на этапе оформления заказа с коротким сообщением, например The Moyasar payment service is not responding. Please try again in a few minutes., и может выбрать другой способ оплаты. Подробности записываются в журнал.

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

Модуль принимает только разовые платежи на странице Moyasar. У него нет формы карты на вашем оформлении заказа, сохранённых карт и токенизации, подписок, а также раздельных авторизации и списания.

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

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

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

Payment accepted, Delivered или Moyasar payment on hold: платёж подтверждён. Статус соответствует настройке Status after payment. Платёж записывается с идентификатором платежа Moyasar в качестве ID транзакции, а примечание показывает, как был подтверждён платёж (вебхук, уведомление о счёте, возврат покупателя или оформление заказа), ID счёта, ID платежа и способ оплаты.

Awaiting Moyasar payment: Moyasar удерживает платёж для проверки. Заказ переходит в оплаченный статус, когда Moyasar подтверждает платёж.

Ошибка оплаты: платёж, находившийся на проверке, не прошёл.

Moyasar payment on hold after payment: Moyasar сообщил сумму или валюту, отличные от суммы корзины (например, корзина была изменена в другой вкладке после начала оплаты), либо счёт был оплачен после того, как вы отменили заказ. Заказ не отмечается как оплаченный, но фактически полученная сумма записывается, если она в валюте заказа. Примечание объясняет ситуацию. Проверьте платёж в Moyasar Dashboard и выполните заказ или верните платёж.

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

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

Блок оплаты Moyasar

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

Возвраты

В блоке Moyasar payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via Moyasar. Подтвердите вопрос Refund this amount through Moyasar? This cannot be undone. Поддерживаются полные и частичные возвраты. Нужно право на редактирование заказов; доступ к страницам модулей не требуется. Возвраты выполняются на сумму и в валюте, которые списала Moyasar, поэтому после расхождения суммы вы можете вернуть не больше того, что покупатель фактически заплатил, а не сумму заказа. Полный возврат по картёжному платежу, совершённому менее 2 часов назад, отправляется как отмена (void): отмена до расчётов, без комиссий. В остальных случаях это возврат. Возврат использует секретный ключ того режима, в котором был произведён платёж (тестовый или рабочий), поэтому этот ключ должен быть задан. Модуль сначала проверяет в Moyasar валюту, статус и сумму платежа, доступную к возврату. Если Moyasar не принимает возврат, блок показывает ошибку, и возврат не записывается. Успешный возврат или отмена добавляются в историю возвратов и примечания. Полный возврат переводит заказ в статус Refunded. Частичный возврат не меняет статус. Возвраты доступны после того, как Moyasar подтвердил платёж.

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

Возвраты и отмены, выполненные в Moyasar Dashboard, поступают через вебхук. Если Moyasar показывает больше возвращённой суммы, чем записал модуль, к заказу добавляется примечание. Статус заказа и кредитные ноты автоматически не меняются. При необходимости обновите их вручную, не используя Refund via Moyasar.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Moyasar Payment Gateway — первый блок на странице Modules > Module Manager > VibeFox Moyasar Payment Gateway > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки: Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-moyasar и ссылка 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.

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

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

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

Moyasar не появляется на этапе оформления заказа: проверьте, что лицензия активна, что Enable/Disable включено, что для текущего режима задан секретный ключ (Test secret key в тестовом режиме, Live secret key в рабочем режиме) и что валюта корзины — SAR, AED, USD, EUR, KWD, BHD или OMR. Страница настроек показывает предупреждение, если ключ отсутствует или валюта магазина не поддерживается. В разделе Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: подтверждения не дошли до вашего магазина. Настройте вебхук: в Moyasar Dashboard проверьте, что он существует, что его URL точно совпадает с Webhook URL из настроек, что метод — POST, что выбраны все четыре события и что его общий секрет совпадает с сохранённым в Webhook shared secret. Заказ также создаётся, когда покупатель возвращается в магазин или пытается снова оплатить ту же корзину.

Вебхук отвечает Unauthorized: общий секрет в Moyasar отличается от сохранённого. Введите секрет вебхука Moyasar в Webhook shared secret и сохраните, либо отметьте Generate a new secret, сохраните и вставьте показанный секрет в Moyasar.

Вебхук отвечает Webhook secret not configured: общий секрет не сохранён, например после удаления через Clear saved secrets. Нажмите Save, чтобы создать секрет, и скопируйте его в Moyasar.

Вебхук отвечает Key not configured: счёт был создан в режиме (тестовом или рабочем), для которого секретный ключ пуст. Введите этот ключ.

Вебхук отвечает Verification failed или Try again later: счёт не удалось получить через API Moyasar, корзину в этот момент обновлял другой запрос, либо заказ не удалось создать (например, модуль отключён). Moyasar повторит вебхук. Включите Debug log, чтобы увидеть причину.

Ссылка Webhook URL в браузере показывает Method not allowed: это нормально. URL принимает только POST-запросы от Moyasar.

Ошибка при сохранении из-за ключа: вставлен публичный ключ (pk_...) или ключ другого режима, либо ключ содержит пробелы. Предыдущее значение сохранено. Тестовые ключи начинаются с sk_test_, рабочие — с sk_live_.

Покупатель видит ошибку при выборе Moyasar: включите Debug log и посмотрите поле Log на странице модуля. This payment method is temporarily unavailable. Please choose another payment method or contact us. обычно означает неверный или отсутствующий секретный ключ. A payment for this order has already been received and is being reviewed. Please contact us instead of paying again. означает, что у корзины уже есть оплаченный счёт, который не удалось превратить в заказ; проверьте журнал.

Order is Moyasar payment on hold after payment: прочитайте Moyasar notes в блоке Moyasar payment. Оплаченные сумма или валюта отличались от корзины, либо платёж поступил после отмены заказа. Выполните заказ или верните платёж.

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

Удаление

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

Moyasar — товарный знак его владельца. Этот модуль не связан с Moyasar и не одобрен компанией Moyasar.