VibeFox MakeCommerce for OpenCart — Помощь

Требования

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

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

Доступ к магазину из Интернета: MakeCommerce отправляет уведомления о платежах в ваш магазин, поэтому сайт должен быть доступен из Интернета. Брандмауэр или базовая аутентификация могут их блокировать. Режим обслуживания их не блокирует: OpenCart 3 пропускает запросы расширений оплаты, а в OpenCart 4 расширение добавляет для них стартовое действие (startup action).

Аккаунт MakeCommerce: нужны Shop ID и Secret key из MakeCommerce Merchant Portal (Settings > API). Тестовая и боевая среды имеют отдельные аккаунты и ключи. Доступные способы оплаты и валюты определяются вашим договором с MakeCommerce. Валюты с тремя знаками после запятой, например KWD или BHD, не предлагаются.

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

Установка

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

OpenCart 3

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

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

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

4. Введите Shop ID и Secret key тестовой среды и, для реальных платежей, боевые ключи (см. Настройка). В Merchant Portal ничего настраивать не нужно.

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

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox MakeCommerce Payment > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница показывает Test mode is on: payments are created in the MakeCommerce test environment and no real money is charged., пока включён тестовый режим. Она предупреждает, если способ оплаты включён, но Shop ID или Secret key текущей среды пусты (тогда способ оплаты скрыт на оформлении заказа), и если валюта магазина по умолчанию не может быть списана MakeCommerce (тогда способ скрыт для заказов в этой валюте). Без права на изменение расширения страница показывает настройки, но не может их сохранить.

При сохранении поле Title не должно быть пустым и не должно быть длиннее 128 символов, Sort Order должно быть целым числом (отрицательные числа допускаются), Total — числом, не меньше 0, а каждый статус заказа должен существовать. Если поле заполнено неверно, ничего не сохраняется, и страница указывает на это поле. Пробелы из Shop ID и ключей удаляются при сохранении.

MakeCommerce

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay with your Estonian, Latvian, Lithuanian or Finnish bank, or by card. You will be redirected to the secure MakeCommerce payment page.

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

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

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

Аккаунт MakeCommerce

Shop ID и Secret key находятся в MakeCommerce Merchant Portal в разделе Settings > API. Тестовый и боевой портал имеют отдельные аккаунты и ключи. В разделе есть ссылки на оба портала и на страницу регистрации MakeCommerce.

Test mode: использует тестовую среду MakeCommerce (реальные деньги не списываются). Новые платежи создаются в выбранной среде с её ключами. Каждый заказ запоминает среду, в которой он был оплачен: проверки статуса и возвраты всегда идут туда. Пока режим включён, покупатели видят на шаге Confirm Order сообщение TEST MODE — MakeCommerce test environment, no real money is charged. По умолчанию: включено.

Test Shop ID: Shop ID вашего тестового аккаунта в формате xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Test Secret key: Secret key вашего тестового аккаунта. Он подписывает и проверяет сообщения об оплате.

Live Shop ID: Shop ID вашего боевого аккаунта в том же формате.

Live Secret key: Secret key вашего боевого аккаунта.

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

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

В Merchant Portal ничего настраивать не нужно. Callback URLs показывает для справки адрес возврата или отмены для покупателя и адрес уведомлений об оплате. Они формируются из адреса витрины вашей установки OpenCart, например https://your-store/index.php?route=extension/payment/wcp_makecommerce_payment/notification в OpenCart 3 и https://your-store/index.php?route=extension/wcp_makecommerce_payment/payment/wcp_makecommerce_payment.notification в OpenCart 4. Каждая транзакция содержит собственные URL возврата, отмены и уведомления, основанные на этих адресах с добавлением номера заказа и ключа. MakeCommerce отправляет подписанное сообщение на URL уведомления (сервер — сервер), а через браузер покупателя — на URL возврата или отмены. Подпись проверяется Secret key той среды, в которой была создана транзакция. Сообщения без корректной подписи отклоняются.

Расширение обрабатывает эти статусы транзакций MakeCommerce:

Платёж также подтверждается, когда покупатель возвращается в магазин. Если покупатель возвращается без подписанного сообщения, расширение запрашивает статус через API MakeCommerce.

Заказы

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

Order Status After Payment: статус после проверенного платежа MakeCommerce. По умолчанию: В обработке.

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

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

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

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

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

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Bank link or card (MakeCommerce)). На шаге Confirm Order покупатель видит ваше описание. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение создаёт транзакцию MakeCommerce на сумму заказа в валюте заказа и отправляет покупателя на страницу оплаты MakeCommerce. Там покупатель выбирает банковскую ссылку или карту. На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. E-mail и страна покупателя передаются в MakeCommerce, а страница открывается на языке магазина, если MakeCommerce его поддерживает (эстонский, английский, латышский, литовский, финский, русский, немецкий, польский), иначе на английском.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения MakeCommerce: подписанным уведомлением или подписанным возвратом покупателя с проверкой транзакции через API MakeCommerce. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, и покупатель видит страницу успешного заказа OpenCart с сообщением Your MakeCommerce payment has been received. Если заказ перешёл в статус проверки, страница показывает Your MakeCommerce payment was received and is being reviewed by the store.

Если платёж одобрен, но ещё не завершён, если заказ в тот же момент подтверждается другим запросом или если MakeCommerce недоступен, появляется страница Payment confirmation с сообщением We could not confirm your payment yet. If you completed it, your order will be updated automatically — please do not pay again. и кнопками Check again и Back to checkout. Check again запрашивает у MakeCommerce статус последних транзакций заказа. Уведомление устанавливает статус заказа, как только платёж завершён.

Если покупатель отменяет платёж на странице MakeCommerce, либо платёж истекает или не проходит, покупатель возвращается на оформление заказа с сообщением, например The payment was cancelled. You can try again or choose another payment method., The payment session expired. Please try again. или The payment was not completed. Please try again or choose another payment method. На OpenCart 4 эти сообщения показываются над страницей оформления заказа. Корзина сохраняется, и покупатель может оплатить снова. Каждая попытка — это новая транзакция MakeCommerce (OpenCart 3 также создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, а OpenCart 4 сохраняет один заказ для оформления и оплачивает тот же заказ снова). Перед созданием новой транзакции открытые попытки той же корзины проверяются в MakeCommerce: если одна из них уже оплачена, покупатель сразу попадает на страницу успеха. Старая ссылка на оплату той же корзины продолжает работать, но корзина никогда не оплачивается в два заказа: поздний платёж по старому заказу уже оплаченной корзины лишь добавляет заметку к оплаченному заказу.

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

Если MakeCommerce не может начать платёж, покупатель остаётся на шаге Confirm Order с сообщением MakeCommerce is temporarily unavailable. Please try again in a moment or choose another payment method. или MakeCommerce could not start the payment for this order. Please choose another payment method or contact us. Техническая причина записывается в журнал.

Банк или карта выбирается на странице MakeCommerce, а не на оформлении заказа в вашем магазине. Расширение не поддерживает сохранённые карты, регулярные платежи и подписки, а также доставку через MakeCommerce (постаматы, этикетки).

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

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

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

Order Status After Payment (по умолчанию В обработке): платёж подтверждён. Заметка показывает сумму, транзакцию, среду и способ проверки (API MakeCommerce или подписанное уведомление).

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

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

Если по уже оплаченному заказу поступает второй платёж, заказ не меняется. Заметка просит вас вернуть дубликат в MakeCommerce Merchant Portal. Платёж по возвращённому заказу или по заказу, переведённому на другой способ оплаты, лишь добавляет заметку.

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

Вкладка VibeFox MakeCommerce Payment

В Sales > Orders откройте заказ, оплаченный через MakeCommerce. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox MakeCommerce Payment показывает все транзакции MakeCommerce по заказу (дата, ID транзакции, метку Test для тестовых платежей, сумму, статус и результат MakeCommerce), суммы Paid / refunded, форму возврата, историю возвратов и MakeCommerce notes заказа. Вкладка показывается пользователям, которые имеют доступ к расширению; её кнопки требуют права на изменение расширения (задаётся в System > Users > User Groups).

Check MakeCommerce payment status: запрашивает у API MakeCommerce статус транзакций заказа (сначала последних), применяет его и добавляет заметку с результатом. Используйте, когда покупатель говорит, что оплатил, но у заказа нет статуса.

Возвраты

На вкладке VibeFox MakeCommerce Payment введите Amount (сумма, ещё не возвращённая, подставляется автоматически), при необходимости Reason (optional), и нажмите Refund via MakeCommerce. Подтвердите вопрос Refund this amount via MakeCommerce? Поддерживаются полные и частичные возвраты. Возвраты ограничены суммой и валютой транзакции MakeCommerce, поэтому после расхождения суммы можно вернуть не больше того, что покупатель реально заплатил, а не сумму заказа. Возврат отправляется в ту среду, в которой был сделан платёж (тестовую или боевую), поэтому ключи этой среды должны быть заданы. Причина передаётся в MakeCommerce как комментарий к возврату; если причины нет, комментарий — Refund for order и номер заказа. Если MakeCommerce не принимает возврат, вкладка показывает ошибку, добавляется заметка и возврат не записывается. Если MakeCommerce ещё обрабатывает платёж, сообщение — MakeCommerce is still processing this payment — try the refund again later. Успешный возврат добавляется в историю возвратов и заметки с ID возврата MakeCommerce. Полный возврат переводит заказ в Refunded Status без уведомления покупателя и без возврата товаров на склад, как при ручной смене статуса. Частичный возврат статус не меняет. Возвраты доступны после подтверждения платежа MakeCommerce.

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

Возвраты, сделанные в Merchant Portal, приходят вместе со статусом транзакции и добавляются в заметки. Статус заказа автоматически не меняется.

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

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

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

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

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

MakeCommerce не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и в текущей среде заданы ключи: Test Shop ID и Test Secret key в тестовом режиме, Live Shop ID и Live Secret key в боевом. Проверьте, что у валюты заказа не больше двух знаков после запятой, что адрес оплаты входит в выбранную Geo Zone и что сумма заказа достигает Total, заданного в настройках.

Платёж прошёл, но заказ остаётся без статуса: уведомления не смогли дойти до магазина, например из-за брандмауэра или базовой аутентификации. Заказ также получает статус, когда покупатель возвращается в магазин или нажимает Check again, а также когда вы нажимаете Check MakeCommerce payment status на вкладке заказа. Проверьте, что ключи среды, в которой был сделан платёж, заданы: уведомление проверяется Secret key этой среды, а без него MakeCommerce получает ошибку и повторяет отправку. Включите Debug log, чтобы видеть уведомления.

Заказ в статусе проверки: прочитайте MakeCommerce notes на вкладке заказа (см. Статусы заказов), проверьте транзакцию в Merchant Portal, затем выполните заказ или возвратите платёж.

Уведомления отклоняются: сообщение с неверной подписью, для другого заказа, другого магазина или транзакции, не созданной для этого заказа, отклоняется, и ничего не меняется. Проверьте, что Shop ID и Secret key принадлежат одному аккаунту MakeCommerce и одной среде.

Покупатель видит ошибку после Confirm Order: включите Debug log и посмотрите поле Log на странице расширения. This payment method is not available. Please reload the checkout page. означает, что сессия оформления больше не соответствует заказу или способ оплаты тем временем выключили: покупателю нужно перезагрузить оформление заказа. Валюта, которую MakeCommerce не может списать, даёт MakeCommerce cannot process payments in и код валюты.

Возврат не проходит с сообщением о среде: заказ оплачен в тестовой или боевой среде, а ключи этой среды не настроены. Введите их и попробуйте снова.

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

Для разработчиков: расширение вызывает события OpenCart wc_mkc_transaction_data, wc_mkc_customer_data, wc_mkc_supported_locales и wc_mkc_is_available, чтобы изменить данные транзакции, данные покупателя, языки страницы оплаты и доступность способа оплаты.

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox MakeCommerce Payment. Лицензионный ключ и статус лицензии этого расширения удаляются всегда. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Orders, которые при повторной установке возвращаются к значениям по умолчанию. Событие OpenCart расширения также удаляется (на OpenCart 4 также его события и стартовое действие (startup action), которое пропускает уведомления в режиме обслуживания). Если Delete data включено, удаляются остальные настройки (название, описание, тестовый режим, Shop ID, Secret key, журнал отладки) и журнал. Если выключено, они сохраняются для повторной установки. Транзакции и возвраты MakeCommerce всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои заметки об оплате.

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

MakeCommerce — торговая марка её владельца. Это расширение не связано с MakeCommerce и не одобрено MakeCommerce.