VibeFox Moyasar for WooCommerce — Помощь

Требования

WordPress: 6.0 или новее.

WooCommerce: 8.0 или новее, установлен и активен. При более старой версии WooCommerce плагин показывает уведомление и не загружается.

PHP: 8.0 или новее.

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

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

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

Установка

1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку wcp_moyasar_payment_gateway в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > Moyasar > Manage или нажмите Settings под названием плагина на странице Plugins.

4. Введите лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

5. Вставьте секретные ключи Moyasar и сохраните. Настройте вебхук в Moyasar Dashboard, указав URL и общий секрет, которые показаны в настройках (см. раздел «Настройка»).

6. Включите Enable/Disable. Сделайте тестовый заказ в тестовом режиме, затем снимите отметку с Test mode.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Moyasar. В заголовке страницы отображается метка TEST MODE или LIVE. Над полями страница предупреждает, если для текущего режима не задан секретный ключ (тогда способ оплаты скрывается при оформлении заказа) или валюта магазина не поддерживается, а при включённом тестовом режиме показывает 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: Enable test mode использует тестовый секретный ключ: платежи имитируются, деньги не списываются. По умолчанию: включено. Отключите его, чтобы принимать реальные платежи с рабочим секретным ключом.

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

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

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

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

Webhook URL: отображается только для чтения, с кнопкой Copy. Выглядит примерно так: https://your-site/wp-json/moyasar_p/v1/webhook. Метод HTTP: POST.

Webhook shared secret: введите то же значение, что и Shared secret вебхука в Moyasar. Оставьте поле пустым и сохраните, чтобы сгенерировать случайный секрет, затем нажмите Show и скопируйте его в Moyasar. Вебхуки без правильного общего секрета отклоняются.

Выберите для вебхука следующие события:

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

Заказы

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

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

Debug log: Log API calls and notifications записывает подробности в WooCommerce > Status > Logs, источник wcp_moyasar_payment_gateway. Ошибки записываются всегда. Ключи API, данные карт и покупателей никогда не записываются. По умолчанию: выключено.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. Платёжные данные, сохранённые в заказах (ID счёта и платежа Moyasar), сохраняются, чтобы возвраты оставались отслеживаемыми. По умолчанию: выключено.

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

Покупатель выбирает способ оплаты (по умолчанию Pay with Moyasar) и оформляет заказ. Плагин создаёт счёт Moyasar на сумму заказа в валюте заказа и отправляет покупателя на платёжную страницу. Там покупатель оплачивает любым способом, включённым в вашем аккаунте Moyasar, например mada, Visa, Mastercard, Apple Pay или STC Pay. В счёте отображаются Order, номер заказа и название вашего сайта.

Заказ отмечается оплаченным только после подтверждения Moyasar: плагин получает счёт через API Moyasar и проверяет, что он оплачен, относится к этому заказу и имеет точно такую же сумму и валюту. После оплаты покупатель возвращается на страницу «Заказ получен» вашего магазина. Если покупатель вернулся без оплаты (например, кнопкой «Назад» на платёжной странице), он попадает обратно в оформление заказа или на страницу Pay for 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 не может начать платёж, покупатель видит короткое сообщение, например The Moyasar payment service is not responding. Please try again in a few minutes., и может выбрать другой способ оплаты. Подробности записываются в журнал.

Способ оплаты работает в классическом оформлении заказа, в блоке оформления заказа и на странице Pay for order. Совместим с WooCommerce High-Performance Order Storage (HPOS).

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

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

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

Pending payment: счёт создан, но покупатель ещё не оплатил. В примечании к заказу указаны ID счёта, сумма и режим.

Processing, Completed or On hold: оплата подтверждена. Статус соответствует Status after payment. В примечании к заказу указано, как подтверждена оплата (вебхук, уведомление о счёте, возврат покупателя или оформление заказа), ID счёта, ID платежа и способ оплаты. ID транзакции — это ID платежа Moyasar.

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

On hold before payment: Moyasar удерживает платёж для проверки. Заказ обновится, когда Moyasar примет решение.

Failed: последний счёт неоплаченного заказа был отклонён, истёк или отменён. Покупатель может попробовать оплатить снова.

Cancelled: заказ отменён покупателем, вами или по истечении времени резервирования товара в WooCommerce. Открытый счёт Moyasar по заказу также отменяется, поэтому оплатить его уже нельзя.

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

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Pay with Moyasar (кнопка использует название способа оплаты). Полные и частичные возвраты поддерживаются для заказов с платежом Moyasar. Полный возврат картёжного платежа, совершённого менее 2 часов назад, отправляется как отмена (void, отмена до расчёта); в остальных случаях это возврат. Возврат использует секретный ключ режима, в котором была произведена оплата (тестовый или рабочий), поэтому этот ключ должен быть задан. Перед возвратом плагин проверяет платёж в Moyasar: его валюту, статус и сумму, которую ещё можно вернуть. Если Moyasar не принимает возврат, WooCommerce показывает ошибку, и возврат не регистрируется. Успешный возврат или отмена добавляются в примечания к заказу.

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

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

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Payments > Moyasar. Вставьте ключ в поле License key и нажмите Activate. В блоке отображается статус, например дата, до которой лицензия активна, и ваш домен. Используйте Check now, чтобы снова проверить статус, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить его с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает слот домена. Освободите слот в вашем аккаунте на vibefox.net.

Без активного ключа Moyasar не показывается покупателям при оформлении заказа. Если оплата всё же начата, покупатель видит This payment method is not available. Please choose another one. Вошедшие администраторы магазина по-прежнему видят способ оплаты с пометкой (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты работают.

Когда срок лицензии истекает, плагин продолжает работать, но для обновлений и поддержки требуется продление. Статус автоматически проверяется снова в фоновом режиме.

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

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

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

Вебхук отвечает Unauthorized: общий секрет в Moyasar отличается от Webhook shared secret. Нажмите Show, скопируйте значение и вставьте его в вебхук в Moyasar.

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

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

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

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

Покупатель видит ошибку при оформлении заказа: включите Debug log и посмотрите WooCommerce > Status > Logs, источник wcp_moyasar_payment_gateway. 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. означает, что у заказа уже есть оплаченный счёт, который требует вашей проверки.

Заказ в статусе On hold after payment: прочитайте примечание к заказу. Оплаченные сумма или валюта отличались от заказа, либо платёж поступил после отмены заказа. Выполните заказ или сделайте возврат.

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

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите слот в аккаунте на vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза и журналы удаляются только если была включена опция Clean uninstall. Иначе они сохраняются для повторной установки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

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