VibeFox GoPay for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

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

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

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

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

Установка

Загружаемый файл — один zip-архив с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_gopay_gateway-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_gopay_gateway.ocmod.zip. Установите только пакет для вашей версии OpenCart. Лицензионный ключ одинаков для обеих версий.

OpenCart 3

1. В административной части откройте Extensions > Installer, нажмите Upload и выберите файл wcp_gopay_gateway-oc3-(version).ocmod.zip. Расширение не содержит модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload из этого пакета в корневую папку магазина.

2. Откройте Extensions > Extensions и выберите тип Payments. Найдите VibeFox GoPay Gateway и нажмите Install (зелёная кнопка +). Вашему администратору нужно право на изменение списка платёжных расширений.

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

4. Введите GoID, Client ID и Client Secret песочницы (sandbox), оставьте включённым Test Mode, включите Enable/Disable и нажмите Save.

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

OpenCart 4

1. В административной части откройте Extensions > Installer, нажмите Upload и выберите файл wcp_gopay_gateway.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на этой же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Откройте Extensions > Extensions и выберите тип Payments. Найдите VibeFox GoPay Gateway, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и учётные данные GoPay так же, как в шагах 3–5 для OpenCart 3. Страница настроек и её поля в обеих версиях одинаковы. Отличается только URL уведомления (см. «Уведомления об оплате»).

После новой установки способ оплаты выключен, режим тестирования включён.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox GoPay Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница показывает Sandbox mode — test payments only или Production mode — real payments. Она предупреждает, если у текущего режима не заполнены GoID, Client ID или Client Secret, и если GoPay не принимает валюту магазина по умолчанию. Без учётных данных GoPay не предлагается при оформлении заказа; при неподдерживаемой валюте по умолчанию он предлагается только покупателям, которые переключились на поддерживаемую валюту. Без права на изменение расширения страница показывает настройки, но не может их сохранить.

При сохранении поле с недопустимым значением сохраняет прежнее значение, а страница показывает ошибку; остальные поля сохраняются. Это относится к Title, который пуст или длиннее 128 символов, к GoID, который содержит не от 6 до 20 цифр, к Sort Order, который не является целым числом, к Total, который не является числом не меньше 0, и к геозоне или статусу заказа, которых не существует. Сохранение также очищает кэшированные токены доступа GoPay, чтобы новые учётные данные использовались сразу.

GoPay

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

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

Description: описание способа оплаты на шаге Confirm Order, над кнопкой подтверждения. По умолчанию: Pay securely via GoPay - cards, wallets, bank transfers.

Sort Order: положение GoPay среди способов оплаты при оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать GoPay только для платёжных адресов в выбранной геозоне. По умолчанию: All zones. Геозоны настраиваются в System > Localisation > Geo Zones.

Total: сумма заказа в валюте магазина по умолчанию, которую заказ должен достичь, прежде чем будет предложен GoPay. Оставьте поле пустым, чтобы предлагать GoPay при любой сумме.

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

GoID, Client ID и Client Secret показаны в вашей учётной записи мерчанта GoPay (настройки интеграции). У тестовой (sandbox) учётной записи свои учётные данные. В разделе есть ссылка на документацию API GoPay.

Test Mode: отправляет платежи на gw.sandbox.gopay.com с учётными данными песочницы. Реальные деньги не списываются. Выключите режим, чтобы принимать реальные платежи с рабочими учётными данными. По умолчанию: включено.

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

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 содержит только от 6 до 20 цифр, например 8123456789. Если вы введёте что-то другое, страница покажет GoID must contain digits only, 6 to 20 digits (for example 8123456789). The previous value was kept.

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

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

Оплата

Payment Page Language: язык страницы оплаты GoPay. По умолчанию: Automatic (site language, then billing country). Автоматический режим использует язык витрины; если GoPay его не поддерживает, решает страна выставления счёта, а если и это не помогает, используется английский. Можно также задать один из 19 языков: Czech, English, Slovak, German, Polish, Hungarian, Romanian, Bulgarian, Croatian, Slovenian, Estonian, Latvian, Lithuanian, French, Italian, Spanish, Portuguese, Ukrainian или Russian.

OpenCart создаёт заказ на шаге Confirm Order без статуса (пропавший заказ, missing order). Заказ получает статус только после того, как GoPay подтвердит оплату — уведомлением или возвратом покупателя; состояние всегда запрашивается через API GoPay. Каждое поле статуса ниже перечисляет ваши статусы заказов OpenCart.

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

GoPay Payment On Hold Status: платежи, которые не соответствуют заказу, платежи после отмены и платежи только с предварительной авторизацией. Примечание объясняет причину; проверьте платёж в учётной записи GoPay. По умолчанию: Ожидание, так как в OpenCart нет статуса On hold. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

Cancelled Order Status: платёж GoPay, который поступил для заказа в этом статусе (или в статусе возврата), переводит заказ в ожидание, а не открывает его молча. По умолчанию: Отменен.

Refunded Status: устанавливается, когда платёж полностью возвращён, со страницы заказа или по сообщению GoPay. По умолчанию: Возвращен.

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

Уведомление сообщает вашему магазину, что оплата произведена. Notification URL показан в этом разделе и передаётся в GoPay с каждым платежом, поэтому в учётной записи GoPay ничего настраивать не нужно. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_gopay_gateway/notify, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_gopay_gateway/payment/wcp_gopay_gateway.notify, и его составляют из адреса витрины вашей установки OpenCart. URL должен быть доступен из Интернета: без парольной защиты и без межсетевого экрана перед ним. Он работает и в режиме обслуживания магазина: OpenCart 3 пропускает запросы платёжных расширений, а в OpenCart 4 расширение добавляет стартовое действие (startup action), которое пропускает и уведомление, и возврат покупателя из GoPay.

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

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

Logging: записывает события GoPay в файл gopay_p_debug.log.php в папке журналов OpenCart (storage/logs). Файл нельзя открыть из веб-браузера. Ошибки и предупреждения записываются всегда. Учётные данные, токены, данные карт, а также e-mail и имя покупателя никогда не записываются в журнал. По умолчанию: выключено.

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

Delete Data on Uninstall: если включено, при удалении расширения удаляются настройки шлюза, кэшированные токены доступа GoPay и журнал. Заказы и их платёжные данные GoPay всегда сохраняются. По умолчанию: выключено.

Импорт / экспорт

Export: Download JSON сохраняет настройки в файл JSON. Client secret не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые client secret остаются.

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию GoPay). На шаге Confirm Order покупатель видит ваше описание. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение создаёт платёж GoPay на сумму заказа в валюте заказа, с товарами, подарочными сертификатами, доставкой и другими итогами заказа, и переводит покупателя на страницу оплаты GoPay. Там GoPay предлагает способы оплаты, включённые в вашей учётной записи GoPay, например банковские карты, банковские переводы и электронные кошельки. Имя, e-mail, телефон и платёжный адрес покупателя передаются в GoPay; пустые поля не отправляются. Платёж отображается в GoPay с номером заказа OC- и номером заказа OpenCart.

На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. В OpenCart 4 нет подарочных сертификатов, поэтому в GoPay они не передаются. По умолчанию OpenCart 4 не запрашивает платёжный адрес; в этом случае расширение передаёт в GoPay имя и адрес доставки.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после того, как GoPay его подтвердит: уведомлением или запросом к API GoPay при возврате покупателя. Уведомление и возврат, пришедшие одновременно, обрабатываются по очереди, поэтому платёж применяется только один раз. Затем заказ получает статус стандартным способом OpenCart, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. Если заказ перешёл в статус ожидания, на странице добавляется текст Your payment is being reviewed. We will contact you if anything else is needed.

Если GoPay ещё не подтвердил платёж, когда покупатель возвращается (например, банковский перевод в пути или GoPay недоступен), страница Payment confirmation показывает GoPay has not confirmed your payment yet. Your order will be confirmed automatically as soon as the payment is confirmed — please do not pay again. с кнопками Check again и Back to checkout.

Если платёж не был завершён, отменён или истёк срок его действия, покупатель возвращается к оформлению заказа с сообщением 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. Корзина сохраняется. В OpenCart 4 эти сообщения показываются над страницей оформления заказа. Каждая новая попытка (OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order; OpenCart 4 обновляет заказ оформления и оплачивает его новым платежом GoPay под тем же номером заказа) сначала проверяет через API GoPay открытые платежи корзины. Если один из них уже оплачен, этот платёж подтверждается, и покупатель переходит на страницу успеха без повторной оплаты. Любое изменение корзины, в том числе новое количество товара, считается новой корзиной, которой нужна собственная оплата.

OpenCart 4 хранит заказ оформления до показа страницы успеха. Если этот заказ тем временем закрыт без оплаты (например, вы его отменили или вернули), покупатель возвращается к оформлению заказа с сообщением Your previous order was cancelled or refunded. Please confirm the order again. (или сообщением об отменённом платеже), и следующее нажатие Confirm Order оплачивает новый заказ. Оплаченный заказ никогда не показывается как оплаченный для другой корзины.

Если GoPay не может начать платёж, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой, например 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. Техническая причина записывается в журнал.

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

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

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

No status (missing order): покупатель был направлен в GoPay и не оплатил, или GoPay ещё не подтвердил платёж. Отменённый или просроченный платёж GoPay оставляет заказ без статуса, с примечанием. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в значение Missing Orders.

Order Status After Payment (по умолчанию Processing): платёж подтверждён. Примечание показывает идентификатор платежа GoPay.

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

Refunded Status (по умолчанию Refunded): платёж GoPay по заказу полностью возвращён — через расширение или в учётной записи GoPay.

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

Примечания — это записи в History заказа, которые покупатель не видит.

Вкладка VibeFox GoPay Gateway

В Sales > Orders откройте заказ, оплаченный через GoPay. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox GoPay Gateway показывает GoPay payment ID (с меткой Sandbox для тестовых платежей), GoPay state и способ оплаты, Payment amount, Paid / refunded, Needs review с причиной, если заказ в ожидании, форму возврата, историю возвратов и GoPay notes заказа. Вкладка показывается пользователям, которые имеют доступ к расширению.

Возвраты

На вкладке введите Amount (подставляется сумма, которая ещё не возвращена), при необходимости Reason (optional), и нажмите Refund via GoPay. Подтвердите вопрос Refund this amount through GoPay? This cannot be undone. Поддерживаются полные и частичные возвраты. Нужно право на изменение расширения (настраивается в System > Users > User Groups). GoPay принимает частичные возвраты только в течение 24 часов после оплаты. Возвраты выполняются в той сумме и валюте, которые списал GoPay, поэтому после расхождения суммы или валюты можно вернуть не больше того, что покупатель фактически заплатил. Возвраты доступны для оплаченных заказов и для заказов в ожидании после расхождения или позднего платежа. Возврат отправляется в том режиме, в котором был сделан платёж (песочница или рабочий режим), поэтому учётные данные этого режима должны быть заданы. Если GoPay отклоняет возврат, вкладка показывает сообщение GoPay, и возврат не регистрируется. Успешный возврат добавляется в историю возвратов и примечания; возврат, который GoPay принял к последующей обработке, отмечается как принятый. Полный возврат переводит заказ в Refunded Status без уведомления покупателя и без возврата товаров на склад, так же как при ручном изменении статуса. Частичный возврат статус не меняет.

Возвраты товаров в Sales > Returns не возвращают деньги через GoPay.

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

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox GoPay Gateway — это первый блок на странице Extensions > Extensions > Payments > VibeFox GoPay Gateway > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now, чтобы проверить статус ещё раз, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: opencart-payment-gopay и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменять ключ могут только администраторы с правом Modify на расширение. Тексты блока следуют языку административной части (включены английский и русский).

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

Один ключ работает на одном домене: адрес магазина из конфигурации OpenCart. Удаление ключа из магазина не освобождает место для домена. Освободите его в аккаунте vibefox.net.

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

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

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

GoPay does not appear at checkout: проверьте, что лицензия активна, что Enable/Disable включено, что у текущего режима заполнены GoID, Client ID и Client Secret, и что валюта оформления заказа — одна из CZK, EUR, PLN, USD, GBP, HUF, RON или BGN. Страница настроек показывает предупреждение, если учётные данные не заполнены. Также проверьте, что платёжный адрес входит в выбранную Geo Zone и что сумма заказа достигает значения Total, заданного в настройках.

The payment went through, but the order stays without a status: GoPay не смог достучаться до URL уведомления, указанного в настройках, и покупатель не вернулся в магазин. Снимите парольную защиту или правила межсетевого экрана, которые блокируют URL. Проверьте, что учётные данные того режима, в котором прошёл платёж, заданы, так как каждое уведомление проверяется с их помощью. Включите Logging и посмотрите поле Log. GoPay повторяет уведомления, которые не получили успешного ответа.

Notification answers Order not found: платёж создан не этим магазином.

Notification answers Missing payment ID: запрос пришёл не от GoPay, или URL был изменён. Ничего делать не нужно.

Notification answers Payment state could not be verified: API GoPay недоступен, либо учётные данные этого режима отсутствуют или неверны. GoPay повторяет уведомление.

Notification answers Busy, retry later: заказ в тот же момент обрабатывался другим запросом. GoPay повторяет уведомление. Включите Logging, чтобы увидеть причину.

The customer sees an error after Confirm Order: включите Logging и посмотрите поле Log. Неверные учётные данные или учётные данные другого режима — частая причина. Сообщение о платёжных данных означает, что GoPay не принял e-mail, телефон или адрес. This payment method is not available. Please reload the checkout page. означает, что сеанс оформления больше не соответствует заказу или способ оплаты был выключен в это время.

The customer comes back and sees We could not verify the GoPay payment. If money was charged, please contact us before paying again.: ссылка возврата не соответствовала ни одному заказу магазина, например её открыли в другом браузере или изменили. Проверьте платёж в учётной записи GoPay; уведомление по-прежнему подтверждает реальный платёж.

Test payments do not confirm a live order: песочница и рабочий режим разделены. Каждый платёж проверяется в том режиме, в котором был создан. Переключите Test Mode в нужный режим и используйте его учётные данные.

Order is in the on hold status after payment: прочитайте примечания на вкладке VibeFox GoPay Gateway. Оплаченная сумма или валюта отличались от заказа, платёж пришёл после отмены заказа, или платёж только предварительно авторизован.

Refund fails: прочитайте сообщение GoPay на вкладке. Частичный возврат возможен только в течение 24 часов после оплаты. Сообщение о режиме означает, что платёж был сделан в режиме песочницы или рабочем режиме, и учётные данные этого режима не заданы. You do not have permission to refund (modify this extension). означает, что у вашей группы пользователей нет права на изменение расширения.

Для разработчиков: до отправки платежа в GoPay расширение вызывает событие OpenCart gopay_p_payment_payload с запросом на оплату и заказом.

Удаление

Откройте Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox GoPay Gateway. Лицензионный ключ и статус лицензии этого расширения удаляются всегда. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и четыре поля статусов заказа, которые при повторной установке возвращаются к значениям по умолчанию. Событие OpenCart расширения тоже удаляется (в OpenCart 4 также его события и стартовое действие, которое пропускает уведомление и возврат покупателя в режиме обслуживания). Если Delete Data on Uninstall включено, удаляются остальные настройки шлюза (название, описание, тестовый режим, учётные данные, язык страницы оплаты, журналирование), кэшированные токены доступа GoPay и журнал. Если выключено, они сохраняются для повторной установки. Платёжные данные GoPay по заказам и возвраты всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои примечания об оплате.

В OpenCart 4, чтобы удалить и файлы расширения, после удаления откройте Extensions > Installer и нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox GoPay Gateway в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

GoPay — товарный знак его правообладателя. Это расширение не аффилировано с GoPay и не одобрено им.