VibeFox CorvusPay for OpenCart — Помощь

Требования

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

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

Валюта: AUD, BAM, BHD, CAD, CHF, CZK, DKK, EUR, GBP, HRK, HUF, ISK, MKD, NOK, PLN, RON, RSD, RUB, SEK или USD. Для любой другой валюты оформления заказа способ оплаты на оформлении скрывается. Суммы передаются с 2 знаками после запятой; итог с большим количеством знаков (например, в валюте с 3 знаками, как BHD) отклоняется, а не округляется.

Аккаунт CorvusPay: нужен аккаунт мерчанта CorvusPay. CorvusPay выдаёт Store ID и Secret Key для каждого магазина отдельно для тестового и для рабочего магазина; они показаны в CorvusPay Merchant Center. Success URL и Cancel URL расширения нужно указать там (см. раздел Configuration).

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

Установка

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

OpenCart 3

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

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

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

4. Введите Store ID и Secret Key вашего тестового магазина CorvusPay (и магазина для рабочих платежей). Скопируйте Success URL и Cancel URL, показанные на странице настроек, в CorvusPay Merchant Center — для тестового и для рабочего магазина.

5. Включите Enable/Disable и нажмите Save. Оформите тестовый заказ, затем выключите Test Mode, чтобы перейти к реальным платежам.

OpenCart 4

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

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

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

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

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

Configuration

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox CorvusPay Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница показывает Test mode is on. Payments go to the CorvusPay test environment — no real money is taken., пока включён тестовый режим, предупреждает, если шлюз включён, но Store ID или Secret Key текущего режима пусты (тогда способ оплаты скрыт на оформлении до их заполнения), и если валюта по умолчанию вашего магазина не поддерживается CorvusPay. Без права изменять расширение страница показывает настройки, но не может их сохранить.

При сохранении Title не должно быть длиннее 128 символов, Sort Order должно быть целым числом, Minimum Total должно быть неотрицательным числом, а выбранная геозона и статусы заказов должны существовать; иначе ничего не сохраняется, и страница выводит ошибки.

CorvusPay

Enable/Disable: Enable CorvusPay Gateway. включает или выключает способ оплаты. Default: off.

Title: название способа оплаты, которое видит покупатель на оформлении заказа. Оно также сохраняется в заказе как название способа оплаты. Default: Credit/Debit Card (CorvusPay). До 128 символов; если поле пустое, показывается название по умолчанию.

Description: текст, который показывается покупателю на шаге Confirm Order, над кнопкой подтверждения. Default: Pay securely with your credit or debit card via CorvusPay. В тестовом режиме к нему добавляется (Test mode — no real payment is taken.)

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

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

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

Учётные данные магазина

Store ID и Secret Key выдаёт CorvusPay для каждого магазина (тестового и рабочего отдельно); они показаны в CorvusPay Merchant Center.

Test Mode: использует тестовую среду CorvusPay (wallet.test.corvuspay.com) и тестовые Store ID и Secret Key. Default: on. Выключите его, чтобы принимать реальные платежи на wallet.corvuspay.com.

Test Store ID: числовой Store ID вашего тестового магазина CorvusPay.

Test Secret Key: Secret Key вашего тестового магазина CorvusPay, используется для подписей HMAC-SHA256.

Live Store ID: числовой Store ID вашего рабочего магазина CorvusPay.

Live Secret Key: Secret Key вашего рабочего магазина CorvusPay, используется для подписей HMAC-SHA256.

Store ID должен содержать только цифры. Если вы введёте что-то другое, страница покажет … must contain digits only — the previous value was kept., а остальные поля всё равно сохранятся. Сохранённые Secret Key никогда не показываются снова: поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённый ключ, отметьте Clear the saved value on save под полем и нажмите Save. Платёж всегда проверяется по Secret Key магазина, в котором он был начат, поэтому держите тестовый ключ заполненным, пока могут прийти тестовые платежи.

Success и Cancel URL

Скопируйте два адреса из раздела Merchant Center URLs в CorvusPay Merchant Center — для тестового и для рабочего магазина. CorvusPay возвращает на них покупателя после оплаты. Они формируются из адреса витрины вашей установки OpenCart; копируйте их точно так, как их показывает страница.

Оплата

Transaction Type: как списываются деньги с карты.

Payment Page Language: язык страницы оплаты CorvusPay. Site language (по умолчанию) использует текущий язык вашего магазина, если CorvusPay его поддерживает, иначе английский. Также можно выбрать Hrvatski, English, Deutsch, Italiano, Srpski или Slovenščina.

Order Status After Payment: статус заказа после успешной оплаты Sale. Варианты указывают на статусы OpenCart, выбранные в разделе Order statuses.

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

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Ниже перечислены статусы OpenCart, которые устанавливает шлюз; каждое поле перечисляет ваши статусы заказов OpenCart. В OpenCart нет статуса On hold, поэтому статус проверки используется для Authorize only, для расхождений суммы или валюты и для платежей после отмены; примечание к заказу объясняет причину.

Processing status: используется, когда Order Status After Payment — Processing. Default: Processing.

Completed status: используется, когда Order Status After Payment — Completed. Default: Complete.

On hold (review) status: Authorize only, расхождение суммы или валюты, платёж после отмены или Order Status After Payment, установленный в On hold. Default: Pending. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

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

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

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

Delete Data: если включено, при удалении расширения удаляются настройки шлюза и файлы журналов. Заказы и данные транзакций CorvusPay всегда сохраняются. Default: off.

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Credit/Debit Card (CorvusPay)). На шаге Confirm Order покупатель видит ваше описание; OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, страница показывает Redirecting to CorvusPay for payment. Please wait... и отправляет подписанную форму на страницу оплаты CorvusPay. Если перенаправление не начинается, покупатель нажимает Pay via CorvusPay. Передаются сумма заказа в валюте заказа, краткое описание (Order, номер заказа и название магазина), а также адресные данные и адрес электронной почты покупателя (для предзаполнения страницы оплаты). Тот же номер заказа CorvusPay используется повторно, пока не меняются сумма, валюта, режим и тип транзакции, и CorvusPay не принимает для него второй платёж. На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Если магазин не запрашивает адрес оплаты (поведение OpenCart 4 по умолчанию), данные держателя карты берутся из имени покупателя и адреса доставки.

После оплаты CorvusPay возвращает покупателя на Success URL. Заказ отмечается оплаченным только после подтверждения CorvusPay: номер заказа CorvusPay должен быть выдан этим магазином, подпись должна совпадать с Secret Key магазина, в котором был начат платёж, а сумма и валюта должны совпадать с заказом. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, и покупатель видит страницу успешного оформления заказа OpenCart с надписью Your CorvusPay payment has been received. Для Authorize only страница показывает Your CorvusPay payment has been authorized. The amount will be charged when the shop processes your order., а для заказа в статусе проверки — Your payment was received and is being reviewed by the shop.

Если платёж в этот момент не удаётся применить (например, другой запрос подтверждает тот же заказ), покупатель видит Your payment is being confirmed с кнопкой Check again, которая ведёт на страницу успеха, как только у заказа появится статус. Если запрос на Success URL не удаётся проверить, покупатель видит Payment not confirmed и We could not confirm this CorvusPay payment. If your card was charged, please contact the shop — do not pay again. Ничего не меняется. Success URL работает и тогда, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы расширений оплаты, а на OpenCart 4 расширение добавляет стартовое действие (startup action) для адресов Success и Cancel. На OpenCart 4 браузер не передаёт сессию магазина, когда CorvusPay возвращает покупателя, поэтому расширение сначала показывает короткую страницу, которая заново открывает тот же адрес в вашем магазине: корзина и вход покупателя сохраняются.

Если покупатель отменяет платёж на странице CorvusPay, заказ остаётся без статуса, а покупатель возвращается на оформление заказа с сохранённой корзиной и сообщением The CorvusPay payment was cancelled and the order was not paid. Your cart is still here — you can try again or choose another payment method. На OpenCart 4 это сообщение выводится над страницей оформления заказа. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order; OpenCart 4 оставляет один заказ на оформление и обновляет его, а новая попытка получает новый номер заказа CorvusPay. Если другой заказ той же корзины уже оплачен, покупатель переходит на страницу успеха вместо повторной оплаты.

OpenCart 4 хранит заказ в оформлении до показа страницы успеха. Если этот заказ тем временем был закрыт без оплаты (например, вы его отменили), Confirm Order или возврат из CorvusPay отправляет покупателя на оформление заказа с сообщением Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. Если у заказа уже есть статус и корзина с тех пор изменилась (другие товары или количество), сообщение такое: Your previous order is already placed. The cart has changed since then: please confirm the new order to pay for it. В обоих случаях следующий Confirm Order оплачивает новый заказ корзины.

Если платёж не удаётся начать, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой: CorvusPay is not configured. Please choose another payment method., CorvusPay does not accept payments in … или This order total cannot be paid via CorvusPay (it must be greater than zero with at most 2 decimals). Please choose another payment method.

Заказ подтверждается только тогда, когда CorvusPay возвращает покупателя на Success URL; серверных уведомлений от сервера к серверу нет. Если покупатель закроет браузер сразу после оплаты, заказ останется без статуса. Расширение не поддерживает возвраты, списания и отмены из OpenCart (серверный API CorvusPay требует клиентский сертификат), а также сохранённые карты, подписки, рассрочку и форму карты на сайте магазина.

Заказы

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

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

Processing, Completed или статус проверки: платёж Sale подтверждён. Статус соответствует Order Status After Payment. Примечание показывает номер заказа CorvusPay, код авторизации и тип карты.

Статус проверки, авторизован: выбран Authorize only. Спишите платёж в CorvusPay Merchant Center, затем измените статус заказа.

Статус проверки, расхождение суммы или валюты: оплаченная сумма или валюта не совпадают с заказом. Не отправляйте товар до проверки платежа в CorvusPay Merchant Center.

Статус проверки, платёж после отмены: успешный платёж пришёл по попытке оплаты, которую покупатель отменил. Выполните заказ или верните платёж в CorvusPay Merchant Center.

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

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

Вкладка VibeFox CorvusPay Gateway

В Sales > Orders откройте заказ, оплаченный через CorvusPay. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox CorvusPay Gateway показывает CorvusPay order number, Status попытки оплаты, Transaction type, Amount (и полученную сумму, если CorvusPay её сообщила), Approval code, Transaction, тип Card и CorvusPay notes. Тестовые платежи помечены как Test. Вкладка только для чтения и показывается пользователям, у которых есть доступ к расширению.

Возвраты: возвраты, списания и отмены из OpenCart не поддерживаются. Выполняйте их в CorvusPay Merchant Center и вручную фиксируйте результат в OpenCart. Возвраты товаров в Sales > Returns не возвращают деньги через CorvusPay.

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

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

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

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

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

CorvusPay не появляется на оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включён, что Store ID и Secret Key текущего режима заполнены (Test Store ID и Test Secret Key в тестовом режиме, Live Store ID и Live Secret Key в рабочем режиме) и что валюта оформления поддерживается CorvusPay. Также проверьте, что адрес оплаты входит в выбранную Geo Zone, и что сумма заказа достигает Minimum Total.

Платёж прошёл, но заказ остаётся без статуса: скорее всего, Success URL не указан в CorvusPay Merchant Center, или Secret Key в OpenCart не совпадает с магазином. Найдите INVALID signature в поле Log на странице расширения (ошибки записываются всегда). Заказ также остаётся без статуса, если покупатель закрыл браузер до возврата; тогда проверьте платёж в Merchant Center и установите статус заказа вручную.

Покупатель видит Payment not confirmed: запрос на Success URL был отклонён: не хватало обязательных полей, номер заказа CorvusPay не был выдан этим магазином, Secret Key этого магазина пуст или подпись не совпала. Ничего не меняется. Журнал показывает причину.

Покупатель долго видит Your payment is being confirmed: не удалось установить статус заказа. Журнал показывает причину; проверьте платёж в Merchant Center.

Покупатель видит This order total cannot be paid via CorvusPay: итог равен нулю или содержит более 2 знаков после запятой.

Покупатель видит CorvusPay is not configured или CorvusPay does not accept payments in …: отсутствует Store ID или Secret Key текущего режима, либо валюта оформления не поддерживается.

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

Заказ в статусе проверки: прочитайте примечания на вкладке VibeFox CorvusPay Gateway. Выбран Authorize only, оплаченная сумма или валюта не совпали с заказом, платёж пришёл после отмены покупателем, или Order Status After Payment установлен в On hold.

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

Удаление

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

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

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