VibeFox GoPay for WooCommerce — Помощь

Требования

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

WooCommerce: 7.6 или новее, установлен и активен. Без него плагин не активируется.

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

Валюта: GoPay принимает CZK, EUR, PLN, USD, GBP, HUF, RON и BGN. При другой валюте способ оплаты скрывается на странице оформления заказа.

Учётная запись GoPay: вам понадобятся GoID, Client ID и Client Secret учётной записи мерчанта GoPay. Их можно найти в настройках интеграции учётной записи. У тестовой учётной записи sandbox свои учётные данные. Настраивать уведомления в GoPay не нужно, но ваш магазин должен быть доступен из интернета.

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

Установка

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

2. Нажмите Activate.

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

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

5. Введите GoID, Client ID и Client Secret для тестового режима, оставьте включённым Test Mode и включите Enable/Disable.

6. Оформите тестовый заказ. Когда всё заработает, введите учётные данные рабочего режима и снимите флажок Test Mode.

Настройка

Все параметры находятся на одной странице: WooCommerce > Settings > Payments > GoPay. Под описанием платёжного шлюза отображается Sandbox mode — test payments only или Production mode — real payments. Вы увидите предупреждение, если для текущего режима не указаны GoID, Client ID или Client Secret либо GoPay не принимает валюту магазина. В обоих случаях GoPay не предлагается на странице оформления заказа. В списке способов оплаты рядом со шлюзом будет указано, что требуется настройка, пока для текущего режима не заданы учётные данные. При сохранении кэшированные токены доступа GoPay удаляются, поэтому новые учётные данные сразу вступают в силу.

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

Title: название способа оплаты, показываемое при оформлении заказа. По умолчанию: GoPay.

Description: описание способа оплаты, показываемое при оформлении заказа. По умолчанию: Pay securely via GoPay - cards, wallets, bank transfers.

Учётные данные API

GoID, Client ID и Client Secret указаны в вашей учётной записи мерчанта GoPay (настройки интеграции). У тестовой учётной записи sandbox свои учётные данные. Документация API доступна на doc.gopay.com.

Test Mode: параметр Enable sandbox/test mode отправляет платежи на gw.sandbox.gopay.com с тестовыми учётными данными. Реальные деньги не списываются. Снимите флажок, чтобы принимать реальные платежи с учётными данными рабочего режима (gate.gopay.cz). По умолчанию: включено.

Sandbox GoID: GoID вашей тестовой учётной записи GoPay.

Sandbox Client ID: OAuth Client ID тестовой учётной записи.

Sandbox Client Secret: OAuth Client Secret тестовой учётной записи.

Production GoID: идентификатор мерчанта GoPay (GoID).

Production Client ID: OAuth Client ID от GoPay.

Production Client Secret: OAuth Client Secret от GoPay.

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

Платёж

Payment Page Language: язык платёжной страницы GoPay. По умолчанию: Automatic (site language, then billing country). Автоматический режим использует язык сайта; если GoPay его не поддерживает, используется страна выставления счёта, а в остальных случаях — английский. Также можно выбрать один из 19 языков: чешский, английский, словацкий, немецкий, польский, венгерский, румынский, болгарский, хорватский, словенский, эстонский, латышский, литовский, французский, итальянский, испанский, португальский, украинский или русский.

Order Status After Payment: статус заказа, который устанавливается после подтверждения платежа. Он назначается сразу, одним изменением статуса и одним письмом покупателю.

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

Уведомление сообщает магазину о совершении платежа. URL уведомления передаётся GoPay с каждым платежом, поэтому настраивать что-либо в учётной записи GoPay не нужно. URL показан в настройках. Он выглядит так: https://your-site/?gopay-api=gopay_payment_notification. Он должен быть доступен из интернета: без защиты паролем, режима обслуживания и блокирующего его межсетевого экрана.

Уведомления GoPay содержат только идентификатор платежа, без подписи. Каждое уведомление проверяется запросом состояния платежа к API GoPay; кроме того, платёж должен быть создан плагином для заказа вашего магазина. Если состояние нельзя получить от GoPay, магазин отвечает ошибкой, и GoPay отправляет уведомление повторно. Без уведомлений заказ подтверждается только после возвращения покупателя в магазин после оплаты.

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

Logging: параметр Enable logging записывает события GoPay в WooCommerce > Status > Logs, источник wcp_gopay_gateway. Ошибки записываются всегда. Учётные данные, токены, данные карт, а также электронная почта, телефон и адрес покупателя никогда не записываются. По умолчанию: выключено.

Delete Data on Uninstall: параметр Delete plugin settings, cached access tokens and log files when uninstalled. Если он включён, при удалении плагина удаляются настройки шлюза, кэшированные токены доступа GoPay и журналы. По умолчанию: выключено.

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

Покупатель выбирает способ оплаты (по умолчанию GoPay) и оформляет заказ. Плагин создаёт платёж GoPay на полную сумму заказа в валюте заказа с учётом товаров, доставки и сборов, а затем отправляет покупателя на платёжную страницу GoPay. Там GoPay предлагает способы оплаты, включённые в вашей учётной записи, например банковские карты, Apple Pay, Google Pay и банковские переводы. GoPay передаются имя для выставления счёта, электронная почта, телефон и адрес покупателя; пустые поля не отправляются. В GoPay платёж отображается как Order и номер заказа.

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

Если платёж не завершён, отменён или срок его действия истёк, покупатель перенаправляется на страницу Pay for order с сообщением The GoPay payment was not completed. You can try again or choose another payment method. или The GoPay payment was cancelled or has expired. You can try again or choose another payment method. С этой страницы можно повторно оплатить неоплаченный заказ. Для уже оплаченного заказа второй платёж GoPay не создаётся.

Если GoPay не может начать обработку платежа, покупатель видит короткое сообщение, например GoPay could not accept the payment details. Please check your billing details (e-mail, phone, address) or choose another payment method. или GoPay is temporarily unavailable. Please try again in a moment or choose another payment method. Техническая причина добавляется в примечания к заказу.

Способ оплаты работает при классическом оформлении заказа, в блоках Cart и Checkout и на странице Pay for order. В тестовом режиме блок Checkout показывает сообщение Sandbox mode: no real payment will be made. Поддерживается WooCommerce High-Performance Order Storage (HPOS).

Покупатель выбирает способ оплаты на странице GoPay; в WooCommerce выбрать его нельзя. Плагин не поддерживает подписки и регулярные платежи, сохранённые карты, встроенную платёжную форму, а также списание или отмену предварительной авторизации из WooCommerce.

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

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

Pending payment: покупатель был перенаправлен в GoPay и ещё не заплатил, либо GoPay ещё не подтвердил платёж.

Processing or Completed: платёж подтверждён. Статус зависит от параметра Order Status After Payment. В примечании к заказу указан идентификатор платежа GoPay и платёжный инструмент. Идентификатор транзакции совпадает с идентификатором платежа GoPay.

On hold: GoPay подтвердил платёж, но сумма или валюта отличаются от заказа; либо платёж поступил после отмены заказа; либо платёж только предварительно авторизован, а деньги ещё не списаны. Причина указана в примечании к заказу. Предварительно авторизованный платёж нужно списать в GoPay, после чего заказ необходимо завершить вручную.

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

Refunded: платёж GoPay по заказу был полностью возвращён, например из учётной записи GoPay.

Если также будет оплачен ещё один платёж по уже оплаченному заказу, заказ не изменится. В примечании будет предложено вернуть дублирующую оплату через учётную запись GoPay. Такое же примечание добавляется, когда платёж GoPay поступает по заказу, ранее отмеченному оплаченным без GoPay, например вручную. Более позднее уведомление не откроет повторно оплаченный заказ, который вы отменили или по которому сделали возврат.

Возвраты

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

Возвраты, выполненные в учётной записи GoPay, поступают через уведомление. Полный возврат меняет статус заказа на «Возвращён», частичный добавляет примечание. Они не регистрируются автоматически как возвраты WooCommerce.

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

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

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

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

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

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

GoPay не отображается при оформлении заказа: проверьте, активна ли лицензия, включён ли параметр Enable/Disable, указаны ли для текущего режима GoID, Client ID и Client Secret и выбрана ли валюта CZK, EUR, PLN, USD, GBP, HUF, RON или BGN. На странице Pay for order учитывается валюта заказа. Если учётные данные или валюта указаны неверно, на странице настроек появится предупреждение.

Платёж прошёл, но заказ остаётся в статусе Pending payment: GoPay не удалось обратиться к URL уведомления из настроек, а покупатель не вернулся в магазин. Отключите защиту паролем, режим обслуживания или правила межсетевого экрана, блокирующие URL. Убедитесь, что заданы учётные данные режима, в котором был выполнен платёж: каждое уведомление проверяется с их помощью. Проверьте WooCommerce > Status > Logs, источник wcp_gopay_gateway. GoPay повторно отправляет уведомления, на которые не получил успешный ответ.

В уведомлении указано «Order not found»: платёж был создан не этим магазином или его заказ был удалён.

В уведомлении указано «Payment state could not be verified»: API GoPay недоступен или учётные данные этого режима неверны. GoPay отправляет уведомление повторно.

При оформлении заказа покупатель видит ошибку: откройте примечания к заказу или включите Logging. В примечании указана ошибка GoPay. Обычно причина — неверные учётные данные или данные другого режима. Сообщение о данных для выставления счёта означает, что GoPay не принял электронную почту, телефон или адрес.

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

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

Не удаётся выполнить возврат: прочитайте сообщение GoPay. Частичный возврат возможен только через 24 часа после платежа. Сообщение о режиме означает, что платёж был выполнен в тестовом или рабочем режиме, но учётные данные этого режима не указаны.

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

Для разработчиков: фильтр gopay_p_payment_payload изменяет запрос платежа, а gopay_p_icon — значок способа оплаты.

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза, кэшированные токены доступа и журналы удаляются только при включённом параметре Delete Data on Uninstall. В противном случае они сохраняются для последующей повторной установки. Идентификаторы платежей GoPay, сохранённые в заказах, всегда остаются. В существующих заказах сохраняются примечания о платежах и идентификаторы транзакций.

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