VibeFox 2C2P for OpenCart — Помощь

Требования

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

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

Учётная запись 2C2P: вам нужны Merchant ID и Secret Key вашей торговой учётной записи 2C2P. Их выдаёт 2C2P при открытии торговой учётной записи. У тестовых (sandbox) и рабочих учётных записей разные ключи. Документация для разработчиков и тестовые карты sandbox находятся на developer.2c2p.com.

Валюта: валюта оформления заказа должна поддерживаться расширением и быть включена в вашей учётной записи 2C2P. Поддерживаются, в частности, THB, SGD, MYR, PHP, IDR, VND, MMK, KHR, LAK, CNY, HKD, TWD, JPY, KRW, INR, AUD, NZD, USD, EUR и GBP. Если валюта покупателя не поддерживается, способ оплаты не отображается при оформлении заказа.

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

Установка

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

OpenCart 3

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

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

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

4. Введите Merchant ID и Secret Key вашей тестовой среды (sandbox), включите Enable/Disable, нажмите Save и оформите тестовый заказ.

5. Когда всё будет готово, введите рабочие данные и отключите Sandbox Mode.

OpenCart 4

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

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

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

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

Новая установка начинает работу с выключенным способом оплаты и включённым режимом sandbox. Адреса возврата и уведомления передаются с каждым платежом. В портале 2C2P ничего настраивать не нужно.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox 2C2P Payment > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница показывает Sandbox mode is active. No real transactions will be processed., пока включён режим sandbox. Она предупреждает, если шлюз включён, но Merchant ID или Secret Key текущего режима пусты, а также если валюта магазина по умолчанию не поддерживается. В обоих случаях способ оплаты не отображается при оформлении заказа. Без права изменять расширение страница показывает настройки, но не может их сохранить.

При сохранении с выключенным Sandbox Mode страница показывает Please enter your live Merchant ID. или Please enter your live Secret Key., если рабочее поле пусто. Настройки всё равно сохраняются. Sort Order должен быть целым числом, Total — числом 0 или больше, а Title — не более 128 символов; геозона и статусы заказов должны существовать. Иначе ничего не сохраняется, и страница указывает поле.

2C2P

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

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

Description: текст, который показывается покупателю на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely via credit/debit card, e-wallet, or internet banking through 2C2P. В режиме sandbox добавляется (TEST MODE).

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

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

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

Тестовый режим (sandbox)

Sandbox Mode: отправляет платежи в тестовую среду 2C2P (demo2.2c2p.com) с тестовыми данными, указанными ниже. По умолчанию: включено. Выключите, чтобы принимать реальные платежи.

Sandbox Merchant ID: ваш Merchant ID тестовой среды 2C2P.

Sandbox Secret Key: ваш Secret Key тестовой среды 2C2P.

Рабочие данные API

Используются, когда режим sandbox выключен.

Merchant ID: ваш рабочий Merchant ID 2C2P.

Secret Key: ваш рабочий Secret Key 2C2P. Ключ сохраняется так, как введён, включая кавычки и обратные слеши.

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

Страница оплаты

Result URLs: для справки показывает Frontend return URL и Backend notification URL. В OpenCart 3 они выглядят так: https://your-store/index.php?route=extension/payment/wcp_2c2p_payment/back и https://your-store/index.php?route=extension/payment/wcp_2c2p_payment/notify, а в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_2c2p_payment/payment/wcp_2c_2p_payment.back и https://your-store/index.php?route=extension/wcp_2c2p_payment/payment/wcp_2c_2p_payment.notify. Они формируются из адреса витрины вашей установки OpenCart. Они отправляются автоматически с каждым платежом. Результаты всегда проверяются с Merchant ID и Secret Key того режима, в котором был совершён платёж: платёж, начатый в sandbox, после перехода на рабочий режим проверяется ключом sandbox, а результат, подписанный ключом другого режима, отклоняется.

Payment Page Language: язык страницы оплаты 2C2P. По умолчанию: English.

Redirect API version: оставьте 8.5, если 2C2P не сообщил, что ваша учётная запись всё ещё использует старую версию 7.0 (подписи SHA-1). Результаты платежей, начатых до переключения, по-прежнему проверяются.

Order ID prefix: необязательно, только буквы и цифры (не более 10), например SHOP1. 2C2P отклоняет номер заказа, который уже получал. Задайте уникальный префикс, если несколько магазинов используют одну учётную запись 2C2P, а также в sandbox, где тестовые торговые учётные записи общие. Номер заказа в 2C2P состоит из префикса, номера заказа OpenCart и номера попытки, например SHOP1123A1. Прочие символы удаляются при сохранении, с предупреждением.

Заказы

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

Order Status After Payment: успешный платёж (статус 2C2P 000). По умолчанию: В обработке.

Awaiting Payment Status: платёж в ожидании (статус 001), например наличный или банковский платёж, который покупатель ещё не совершил. По умолчанию: Ожидает оплаты.

On Hold (Review) Status: 2C2P сообщил сумму или валюту, отличающиеся от суммы заказа. По умолчанию: Ожидает оплаты, так как в OpenCart нет статуса On hold. Свой статус можно создать в System > Localisation > Order Statuses и выбрать здесь.

Cancelled Payment Status: ожидавшийся платёж затем был отклонён, отменён или не прошёл (статусы 002, 003, 999). По умолчанию: Отменён.

Дополнительные настройки

Enable Logging: записывает события 2C2P в tc2p_p_debug.log.php в папке журналов OpenCart (storage/logs). Файл нельзя открыть через веб, а при достижении 5 МБ он переносится в tc2p_p_debug.old.log.php. Данные карт, Secret Key, e-mail покупателей и платёжные токены не записываются. По умолчанию: выключено. Пока журнал выключен, ничего не записывается, в том числе ошибки.

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

Delete Data on Uninstall: если включено, при удалении расширения удаляются настройки шлюза и журнал. Транзакции 2C2P всегда сохраняются, поэтому позднее уведомление о результате старого платежа будет обработано и после повторной установки. По умолчанию: выключено.

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию 2C2P Payment). На шаге Confirm Order покупатель видит ваше описание. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, страница показывает Thank you for your order. You will be redirected to 2C2P to complete your payment. и через мгновение перенаправляет покупателя на страницу оплаты 2C2P. Если этого не происходит, покупатель нажимает Pay via 2C2P.

На странице 2C2P покупатель платит любым способом, включённым в вашей учётной записи 2C2P, например картами, электронными кошельками, платежами по QR-коду, интернет-банкингом или наличными. Расширение передаёт сумму заказа в валюте заказа, e-mail покупателя и названия товаров в заказе. Платёж можно завершить в течение 24 часов. Каждое нажатие Confirm Order начинает новую попытку со своим номером заказа в 2C2P, потому что 2C2P никогда не принимает один и тот же номер заказа дважды.

2C2P сообщает о результате дважды: браузер покупателя возвращается в магазин, и 2C2P отправляет уведомление от сервера к серверу. Оба уведомления обрабатываются одинаково. Заказ отмечается оплаченным только после того, как 2C2P подтвердит его корректной подписью. Результат также должен относиться к платежу: номер заказа в 2C2P должен был быть выдан вашим магазином, а Merchant ID и случайный токен попытки проверяются. Результаты без корректной подписи отклоняются. Уведомление работает и тогда, когда магазин находится в режиме обслуживания, потому что OpenCart пропускает запросы платёжных расширений. На OpenCart 4 для этого расширение добавляет startup action, которое пропускает подписанные результаты 2C2P.

После успешного платежа заказ получает статус стандартным способом OpenCart, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart с Your 2C2P payment has been received. Для платежа в ожидании страница показывает Your 2C2P payment is pending (for example a cash or bank payment that is not made yet). The order will be processed as soon as 2C2P confirms the payment. Для заказа на проверке она показывает Your payment was received and is being reviewed by the shop.

Если платёж не был завершён или отменён на странице 2C2P, заказ остаётся без статуса. Покупатель возвращается к оформлению заказа с сообщением Payment was not completed. Please try again or choose a different payment method. Корзина сохраняется, и покупатель может оплатить снова или выбрать другой способ оплаты. Если результат невозможно подтвердить, покупатель видит We could not confirm the payment result. If your account was charged, please contact us before paying again. Если платёж не удаётся начать, например потому что валюта заказа не поддерживается или сумма заказа равна нулю, покупатель остаётся на шаге Confirm Order с сообщением This payment method is currently unavailable for this order. Please contact us or choose another payment method.

Если у заказа уже есть статус (оплачен или ожидает платежа в ожидании), вторая форма оплаты не создаётся. Покупатель переходит на страницу успешного оформления заказа.

На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Сообщения о незавершённом платеже или платеже, который не удалось подтвердить, показываются над страницей оформления заказа. OpenCart 4 хранит один заказ для оформления и обновляет его: после неудачного платежа покупатель оплачивает тот же заказ новой попыткой (новый номер заказа 2C2P, например SHOP1123A2). Если этот заказ за это время закрылся без оплаты (например, отложенный платёж был отменён или вы отменили заказ), покупатель возвращается к оформлению заказа с сообщением Payment was not completed. Please try again or choose a different payment method., а следующее нажатие Confirm Order оплачивает новый заказ. Если заказ был закрыт после платежа или уже имеет статус от платежа другой корзины, появляется сообщение This order can no longer be paid. Please confirm your order again. Оплаченный заказ никогда не показывается как оплаченный для другой корзины. Изменение корзины, в том числе нового количества, считается новой корзиной, которой нужна собственная оплата.

Расширение не поддерживает возвраты из OpenCart, сохранённые карты, регулярные платежи или подписки, поля для карт на вашем сайте, а также API 2C2P PGW 4.x.

Заказы

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

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

Order Status After Payment (default Processing): 2C2P сообщил об успешном платеже. Примечание показывает транзакцию 2C2P, код авторизации, дату и канал оплаты.

Awaiting Payment Status (default Pending): платёж ожидает в 2C2P, например наличный платёж, который покупатель ещё не внёс. Заказ переходит в Order Status After Payment, когда 2C2P сообщает о платеже. OpenCart уведомляет покупателя об этом изменении.

On Hold (Review) Status (default Pending): 2C2P сообщил сумму или валюту, отличающиеся от суммы заказа. Примечание показывает полученные и ожидаемые значения. Проверьте заказ и транзакцию в портале 2C2P.

Cancelled Payment Status (default Canceled): ожидавшийся платёж затем был отклонён, отменён или не прошёл. Примечание показывает статус и причину. Неудачный результат более ранней попытки не отменяет заказ, который ждёт другой попытки.

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

На OpenCart 4 неоплаченный заказ оформления может получить статус Voided, который OpenCart 4 ставит, когда покупатель возвращается на шаг Confirm Order. Расширение считает такой заказ заказом без статуса, и более поздний платёж всё равно подтверждает его.

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

Вкладка VibeFox 2C2P Payment

В Sales > Orders откройте заказ, оплаченный через 2C2P. В нижней части страницы заказа, рядом с History и Additional, вкладка VibeFox 2C2P Payment показывает номер заказа 2C2P с меткой Sandbox для платежей в sandbox, транзакцию, статус платежа, полученную сумму, канал, код авторизации, маскированный номер карты, дату, ответ канала, версию API и 2C2P notes заказа. Вкладка показывается пользователям, которые имеют доступ к расширению.

Возвраты

Возвраты из OpenCart не поддерживаются. Оформите возврат платежа в портале мерчанта 2C2P, а затем вручную зафиксируйте его в OpenCart, например изменив статус заказа.

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

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

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

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

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

2C2P не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и в текущем режиме заданы Merchant ID и Secret Key: поля sandbox в режиме sandbox, рабочие поля в рабочем режиме. Проверьте, что валюта покупателя поддерживается. Страница настроек показывает предупреждение, если учётные данные не заполнены или валюта по умолчанию не поддерживается. Также проверьте, что платёжный адрес входит в выбранную Geo Zone и что сумма заказа достигает Total, заданного в настройках.

Платёж прошёл, но заказ остался без статуса: в ваш магазин не пришёл корректный результат. Проверьте, что Merchant ID и Secret Key того режима, в котором совершён платёж, соответствуют учётной записи 2C2P, и что Redirect API version совпадает с вашей учётной записью. Результат с неверной подписью или для другого Merchant ID отклоняется. Включите Enable Logging и найдите сообщения о hash или Merchant ID в поле Log. Проверьте также, что ваш сервер принимает запросы от 2C2P на адрес уведомления сервера.

Уведомление сервера отвечает 400 FAIL: в результате отсутствуют поля, неверная подпись, другой Merchant ID или неверный токен. 404 FAIL означает, что номер заказа 2C2P не был выдан этим магазином. 503 RETRY означает, что заказ в этот момент подтверждался другим запросом или обработка не удалась; 2C2P повторит попытку позже. Включите Enable Logging, чтобы увидеть причину.

Адрес уведомления в браузере показывает FAIL: это нормально. Адрес принимает только POST-запросы от 2C2P.

2C2P сообщает, что номер заказа уже существует: 2C2P не принимает один и тот же номер заказа дважды. Это случается, когда несколько магазинов используют одну учётную запись 2C2P или в sandbox, где демонстрационные торговые учётные записи используются многими разработчиками. Задайте уникальный Order ID prefix.

Платёж совершён, но заказ находится в статусе ожидания платежа или проверки: либо платёж всё ещё ожидает в 2C2P (например, наличный платёж, который покупатель ещё не внёс), либо оплаченная сумма или валюта не совпали с заказом. Проверьте примечания на вкладке VibeFox 2C2P Payment и транзакцию в портале 2C2P.

Покупатель видит This payment method is currently unavailable for this order: валюта заказа не поддерживается, Merchant ID или Secret Key текущего режима пусты, либо сумма заказа равна нулю.

Покупатель видит This payment method is not available. Please reload the checkout page.: сеанс оформления заказа больше не соответствует заказу, либо способ оплаты тем временем был выключен. Покупателю нужно перезагрузить страницу оформления заказа.

Please enter your live Merchant ID или Please enter your live Secret Key при сохранении: режим sandbox выключен, а рабочее поле пусто. Введите рабочие данные или оставьте Sandbox Mode включённым.

Для разработчиков: перед подписью платёжной формы расширение вызывает событие OpenCart tc2p_p_payment_fields с полями формы и заказом.

Удаление

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

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

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