VibeFox PayPlug for OpenCart — Помощь

Требования

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

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

Валюта и суммы: евро (EUR), от 0,99 до 20 000,00 за платёж, значения PayPlug по умолчанию. Евро должен быть включён в разделе System > Localisation > Currencies и выбран покупателем. При другой валюте оформления заказа или суммах вне этих пределов способ оплаты скрывается.

Аккаунт PayPlug: нужны секретные ключи вашего аккаунта PayPlug: тестовый ключ (sk_test_...) и/или боевой ключ (sk_live_...). Никакие другие ключи не нужны, и в PayPlug не нужно настраивать уведомления. Чтобы получать уведомления, ваш магазин должен быть доступен из интернета; иначе заказы подтверждаются, когда покупатель возвращается из PayPlug.

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

Установка

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

OpenCart 3

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

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

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

4. Вставьте секретные ключи из личного кабинета PayPlug (см. Конфигурация).

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

OpenCart 4

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

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

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

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

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

Конфигурация

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox PayPlug Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если способ оплаты включён, но секретный ключ текущего режима пуст, и если валюта магазина по умолчанию не EUR. В обоих случаях способ оплаты скрывается при оформлении заказа (при другой валюте по умолчанию — пока выбрана эта валюта). Без права изменять расширение страница показывает настройки, но не может их сохранить.

При сохранении Title должен содержать от 1 до 128 символов, Sort Order должен быть целым числом, Total должен быть числом не меньше 0, а статусы заказов должны существовать; иначе ничего не сохраняется и страница показывает ошибки. Секретный ключ в неверном формате не сохраняется, а остальные настройки сохраняются: страница показывает Settings saved, except the secret key shown in red. и, например, Test Secret Key must start with "sk_test_". The previous value was kept.

Checkout

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely by card via PayPlug.

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

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

Total: сумма заказа в валюте магазина по умолчанию, которую заказ должен достичь, чтобы предлагался PayPlug. Оставьте поле пустым, чтобы предлагать PayPlug при любой сумме. Сам PayPlug принимает от 0,99 до 20 000,00 EUR за платёж.

API-ключи

Секретные ключи находятся в личном кабинете PayPlug в разделе Developers > API keys. В этом разделе есть ссылка на личный кабинет.

Test Mode: использует тестовый секретный ключ для новых платежей. Настоящие платежи не проводятся. Платежи, сделанные в другом режиме, для проверки статуса и возвратов продолжают использовать ключ своего режима. По умолчанию: включено. Пока режим включён, покупатель видит на шаге Confirm Order сообщение Test mode: no real payment will be made.

Test Secret Key: ваш тестовый секретный ключ PayPlug. Начинается с sk_test_.

Live Secret Key: ваш боевой секретный ключ PayPlug. Начинается с sk_live_.

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

Уведомления

Notification URL: адрес, который расширение передаёт PayPlug с каждым платежом. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_payplug_gateway/webhook, в OpenCart 4: https://your-store/index.php?route=extension/wcp_payplug_gateway/payment/wcp_payplug_gateway.webhook. Он формируется из адреса витрины вашей установки OpenCart. В личном кабинете PayPlug ничего вводить не нужно. Каждое уведомление проверяется повторным чтением платежа через API PayPlug, поэтому платежи подтверждаются, даже если покупатель не возвращается в магазин. URL должен быть доступен из интернета; иначе заказы подтверждаются только тогда, когда покупатель возвращается из PayPlug.

Заказы

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

Order Status After Payment: статус, который устанавливается после успешной оплаты, например Processing или Complete. По умолчанию: Processing.

PayPlug Payment On Hold Status: платёж требует вашей проверки (см. Статусы заказов). По умолчанию: Pending, так как в OpenCart нет статуса On hold. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

Payment Error Status: авторизованный платёж заказа на проверке не прошёл или был отменён. По умолчанию: Failed.

Refunded Status: устанавливается после полного возврата платежа со страницы заказа. По умолчанию: Refunded.

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

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

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию PayPlug). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to the secure PayPlug payment page to pay by card.; в тестовом режиме также Test mode: no real payment will be made. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Когда покупатель нажимает Confirm Order, расширение создаёт платёж PayPlug на сумму заказа в копейках и отправляет покупателя на страницу оплаты PayPlug. Адреса платежа и доставки, e-mail и язык заказа передаются в PayPlug. Там покупатель оплачивает картой.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения PayPlug: расширение читает платёж через API PayPlug, когда приходит уведомление и когда покупатель возвращается. Затем заказ получает статус обычным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart с сообщением Your payment with PayPlug has been received. Если заказ на проверке, страница говорит We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again. Если заказ в статусе ошибки оплаты, страница говорит Your PayPlug payment was not completed. Please contact us about this order. Если при возврате покупателя запросить PayPlug не удалось, страница Payment confirmation показывает тот же текст о подтверждении и кнопку Check again; уведомление устанавливает статус заказа, как только придёт.

Если покупатель отменяет оплату на странице PayPlug, страница оплаты закрывается в PayPlug, поэтому её нельзя по ошибке оплатить позже. Покупатель возвращается к оформлению заказа с сообщением: You cancelled the PayPlug payment. You can try again or choose another payment method., The PayPlug payment session has expired. Please try again or choose another payment method., The PayPlug payment failed. Please try again or choose another payment method. или, если платёж остался открытым, Your PayPlug payment was not completed. You can try again or choose another payment method. Корзина сохраняется. В OpenCart 4 эти сообщения показываются над страницей оформления заказа.

OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, а OpenCart 4 обновляет заказ оформления (новая попытка — это новый платёж PayPlug для того же заказа), поэтому расширение сначала проверяет предыдущие попытки для той же корзины. Если одна из них оплачена, используется этот платёж без нового, и покупатель переходит на страницу успеха. Если попытка этого заказа ещё открыта на ту же сумму, используется та же страница оплаты. Иначе старая страница закрывается в PayPlug и создаётся новый платёж. Поздний платёж по закрытой странице всё равно фиксируется. Изменение корзины, в том числе нового количества, считается новой корзиной, которой нужен собственный платёж.

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

Если PayPlug не может начать платёж, покупатель остаётся на шаге Confirm Order с коротким сообщением, например PayPlug could not accept your billing details (postcode). Please check them and try again. или The payment provider could not be reached. Please try again in a moment. Техническая причина записывается в журнал.

Уведомление также работает, пока магазин находится в режиме обслуживания, потому что OpenCart пропускает запросы платёжных расширений (в OpenCart 4 расширение добавляет для этого собственное стартовое действие, которое также пропускает возврат покупателя из PayPlug).

Платежи списываются сразу. Расширение не поддерживает рассрочку Oney, сохранённые карты для оплаты в один клик, встроенную платёжную форму, подписки и отложенное списание.

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

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

Нет статуса (отсутствующий заказ): покупатель был отправлен в PayPlug и не оплатил, или PayPlug ещё не подтвердил платёж. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в значение Missing Orders. Если платёж не прошёл, попытка закрывается, и покупатель может оплатить снова.

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

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

Payment Error Status (по умолчанию Failed): авторизованный платёж заказа на проверке не прошёл или был отменён. OpenCart уведомляет покупателя об этом изменении.

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

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

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

Вкладка VibeFox PayPlug Gateway

В Sales > Orders откройте заказ, оплаченный через PayPlug. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox PayPlug Gateway показывает PayPlug payment ID с меткой Test mode для тестовых платежей, Status платежа, суммы Paid / refunded, форму возврата, историю возвратов (с режимом каждого возврата) и PayPlug notes заказа. Вкладка показывается пользователям, у которых есть доступ к расширению.

Возвраты

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

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

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

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox PayPlug Gateway — это первый блок на странице Extensions > Extensions > Payments > VibeFox PayPlug Gateway > Edit, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в маскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже них — строка Product: opencart-payment-payplug и ссылка 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.

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

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

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

PayPlug не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, в текущем режиме задан секретный ключ (Test Secret Key в тестовом режиме, Live Secret Key в боевом), валюта оформления — EUR, а сумма заказа от 0,99 до 20 000,00 EUR. Также проверьте, что платёжный адрес входит в выбранную Geo Zone, и что сумма заказа достигает Total, заданного в настройках. Разработчики могут изменить валюты и лимиты через события OpenCart ppg_supported_currencies и ppg_amount_limits (значения в копейках), а запрос на оплату — через ppg_payment_data.

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

Уведомление отвечает Verification failed.: платёж не удалось прочитать через API PayPlug, например потому что PayPlug не ответил или секретный ключ режима платежа не задан. Заказ не меняется, и PayPlug отправит уведомление повторно.

Уведомление отвечает Temporarily unavailable.: корзина в этот момент обновлялась другим запросом, например возвратом покупателя, или не удалось установить статус заказа. PayPlug отправит уведомление повторно. В журнале указана причина.

Уведомление отвечает Unknown payment. или Payment does not belong to the order.: платёж создан не этим магазином или не для этого заказа, например платёж другого магазина на том же аккаунте PayPlug. Он игнорируется.

URL уведомлений в браузере показывает Method not allowed.: это нормально. URL принимает только запросы от PayPlug.

Покупатель видит ошибку после Confirm Order: включите Logging и посмотрите поле Log. Неверный ключ даёт This payment method is temporarily unavailable. Please choose another payment method.; другие сообщения называют поле платёжных данных, которое отклонил PayPlug.

Покупатель возвращается и видит Payment verification failed.: ссылка возврата не соответствует ни одной попытке оплаты заказа, например её открыли в другом браузере. Проверьте платёж в личном кабинете PayPlug; уведомление всё равно установит статус заказа.

Заказ на проверке после оплаты: прочитайте примечания на вкладке VibeFox PayPlug Gateway (см. Статусы заказов), затем обработайте заказ или верните платёж.

На вкладке нет формы возврата: вкладка объясняет причину: платёж ещё не оплачен, он полностью возвращён, у вашей группы пользователей нет права изменять расширение, или не настроен секретный ключ режима платежа.

Возврат завершается ошибкой Unexpected response from PayPlug.: PayPlug ответил без действительного возврата. Ничего не зафиксировано. Проверьте возврат в личном кабинете PayPlug, прежде чем повторять попытку.

Удаление

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

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

PayPlug — товарный знак его владельца. Это расширение не связано с PayPlug и не одобрено PayPlug.