VibeFox CCAvenue for OpenCart — Помощь

Требования

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

PHP: 8.0 или новее, с расширением OpenSSL (используется для шифрования запроса и расшифровки ответа).

Аккаунт CCAvenue: нужен аккаунт мерчанта CCAvenue с Merchant ID, Access Code и Working Key. Access Code и Working Key выдаются для домена сайта, поэтому создайте их для домена этого магазина. CCAvenue использует те же учётные данные для тестовой среды; тестовый доступ должен быть включён для вашего аккаунта со стороны CCAvenue. Расширение использует эндпоинты CCAvenue India.

Валюта: валюта заказа передаётся в CCAvenue без изменений. Аккаунты CCAvenue по умолчанию принимают INR; для других валют на вашем аккаунте CCAvenue требуется мультивалютная обработка.

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

Установка

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

OpenCart 3

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

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

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

4. Введите Merchant ID, Access Code и Working Key из вашей панели CCAvenue, включите Enable/Disable и нажмите Save.

5. Во время тестирования оставьте Test mode включённым, а затем выключите его, чтобы принимать реальные платежи. В панели CCAvenue ничего настраивать не нужно: адрес возврата передаётся с каждым платежом.

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox CCAvenue Payment > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если CCAvenue включён, но не заполнены Merchant ID, Access Code или Working Key (способ оплаты тогда скрыт при оформлении заказа, пока все три поля не заполнены), показывает CCAvenue test mode is on: customers are sent to test.ccavenue.com and no real money is taken., пока способ оплаты включён в тестовом режиме, и напоминает о мультивалютной обработке, когда валюта магазина по умолчанию не INR. Если у вас нет права на изменение расширения, страница показывает настройки, но не может их сохранить.

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

CCAvenue

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely via Credit/Debit card, Net Banking, UPI or Wallet through CCAvenue.

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

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

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

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

Войдите в панель мерчанта CCAvenue (M.A.R.S.) и откройте Settings > API Keys. Создайте Access Code и Working Key для домена этого магазина. Пробелы в учётных данных удаляются при сохранении.

Merchant ID: ваш числовой Merchant ID CCAvenue. Если он содержит что-либо, кроме цифр, при сохранении появится сообщение CCAvenue: the Merchant ID must contain digits only — the previous value was kept., предыдущее сохранённое значение останется, а остальные настройки будут сохранены.

Access Code: Access Code для этого сайта (Settings > API Keys).

Working Key: Working Key (ключ шифрования) для этого сайта. Он шифрует платёжный запрос и является единственным способом проверить ответ CCAvenue, поэтому храните его в секрете. Сохранённый Working Key больше никогда не отображается. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить ключ, отметьте Clear saved Working Key под полем и нажмите Save.

Test mode: отправляет покупателей в тестовую среду CCAvenue (test.ccavenue.com). CCAvenue использует одинаковые Merchant ID, Access Code и Working Key для тестов и для боевого режима; тестовый доступ должен быть включён для вашего аккаунта со стороны CCAvenue. В тестовом режиме на шаге Confirm Order показывается TEST MODE: no real transactions will be processed. По умолчанию: включено. Для реальных платежей выключите.

URL возврата

CCAvenue возвращает покупателя на адрес, показанный в этом разделе. В OpenCart 3 он выглядит как https://your-store/index.php?route=extension/payment/wcp_ccavenue_payment/back, в OpenCart 4 как https://your-store/index.php?route=extension/wcp_ccavenue_payment/payment/wcp_ccavenue_payment.back. Он формируется из адреса витрины вашей установки OpenCart. Расширение отправляет этот URL с каждым платежом (как адрес перенаправления и отмены), поэтому в CCAvenue ничего настраивать не нужно. Он должен принадлежать домену, зарегистрированному в CCAvenue.

Заказы

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

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

Awaiting Payment Status: Awaited: банк ещё не подтвердил платёж. Заказ получает Order Status After Payment, когда CCAvenue сообщает Success для того же tracking ID. По умолчанию: Ожидает оплаты.

On Hold (Review) Status: CCAvenue сообщил сумму или валюту, отличающиеся от суммы заказа, либо платёж пришёл для отменённого заказа. Примечание объясняет это. По умолчанию: Ожидает оплаты, так как в OpenCart нет статуса На удержании. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

Cancelled Payment Status: ожидаемый платёж был затем прерван (Aborted для того же tracking ID). По умолчанию: Отменён.

Failed Payment Status: ожидаемый платёж затем не удался (Failure, Invalid или Timeout для того же tracking ID). Сбой более раней попытки не меняет заказ. По умолчанию: Не удался.

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

Debug log: записывает события CCAvenue в ccavenue_p_debug.log.php в папке логов OpenCart (storage/logs). Файл нельзя открыть через веб. Журналируются только ссылки на заказы, tracking ID и статусы; ключи, данные карт, адреса электронной почты и почтовые адреса не журналируются. По умолчанию: выключено. Пока он выключен, ничего не записывается, включая ошибки.

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию CCAvenue). На шаге Confirm Order покупатель видит ваше описание. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, шаг показывает Thank you for your order. You are being redirected to CCAvenue to complete the payment. и отправляет покупателя на страницу оплаты CCAvenue. Пока браузер переходит туда, показывается кнопка Pay via CCAvenue. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа.

Каждая попытка получает новую ссылку на заказ CCAvenue, которая состоит из номера заказа OpenCart и времени. Сумма и валюта заказа, платёжные данные, адрес доставки (когда заказ отправляется и адрес доставки отличается от платёжного) и секретный токен попытки передаются в зашифрованном запросе. Имена и адреса очищаются до символов и длины, которые принимает CCAvenue; страна и регион передаются названиями, телефон — только цифрами. Покупатель выбирает карту, Net Banking, UPI, кошелёк или EMI на странице CCAvenue. OpenCart 4 по умолчанию не запрашивает платёжный адрес; тогда платёжные данные берутся из адреса доставки.

После оплаты CCAvenue возвращает покупателя с зашифрованным ответом. Заказ отмечается оплаченным только после подтверждения CCAvenue: ответ должен расшифроваться вашим Working Key, относиться к попытке этого магазина и содержать ту же сумму и валюту, что были отправлены и что указаны в заказе. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart с сообщением Your CCAvenue payment has been received. Для платежа Awaited страница показывает Your CCAvenue payment is awaiting confirmation from your bank. The order will be processed as soon as the payment is confirmed. После расхождения суммы или валюты она показывает Your payment was received and is being reviewed by the store. В OpenCart 4 браузер не отправляет сессию магазина, когда CCAvenue возвращает покупателя, поэтому после обработки ответа расширение показывает короткую страницу, которая заново открывает адрес возврата в вашем магазине: покупатель сохраняет корзину и вход в аккаунт.

Если платёж не удался, покупатель возвращается к оформлению заказа с сообщением Payment was not completed. Please try again or choose a different payment method. Если покупатель отменяет платёж на странице CCAvenue, сообщение: Payment was cancelled. You may try again. Если ответ не удаётся проверить, сообщение: We could not confirm the payment result. If your account was charged, please contact us before paying again. В OpenCart 4 эти сообщения показываются над страницей оформления заказа. В этих случаях заказ остаётся без статуса, корзина сохраняется, и покупатель может оплатить снова. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order; OpenCart 4 сохраняет один заказ на время оформления и обновляет его. Каждая попытка получает собственную ссылку на заказ CCAvenue. CCAvenue не может отменить начатый платёж, поэтому поздний успешный платёж более ранней попытки всё равно применяется к её собственному заказу. Одна корзина оплачивается один раз: корзина, уже оплаченная другим заказом, в CCAvenue повторно не отправляется (покупатель переходит на страницу успеха). Если та же корзина всё же оплачивается дважды (например, в двух вкладках браузера), второй заказ остаётся без статуса, а оплаченный заказ получает примечание о том, что покупатель мог быть списан дважды, чтобы вы могли вернуть деньги в панели CCAvenue.

OpenCart 4 сохраняет заказ на этапе оформления до показа страницы успешного оформления. Если этот заказ за это время закрылся, Confirm Order возвращает покупателя к оформлению заказа, и следующее нажатие Confirm Order оплачивает новый заказ корзины. Сообщение: Payment was cancelled. You may try again., если ожидаемый платёж был прерван, Payment was not completed. Please try again or choose a different payment method., если он не удался, и This order can no longer be paid (it was closed by the store). Please confirm your order again., если вы закрыли заказ, по которому была начата оплата. Если у заказа уже есть статус, а корзина с тех пор изменилась (другие товары или количество), сообщение: Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order.

Результат берётся только из возврата покупателя с CCAvenue: серверных уведомлений от сервера к серверу и запросов статуса не существует. Если покупатель закрывает браузер до возврата, заказ остаётся без статуса; проверьте платёж в панели CCAvenue. Расширение не поддерживает возвраты из OpenCart, сохранённые карты, подписки или регулярные платежи, встроенную форму карты на сайте, а также CCAvenue UAE или другие региональные платформы.

Заказы

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

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

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

Awaiting Payment Status (default Pending): CCAvenue сообщил о платеже как Awaited (банк ещё не подтвердил его). Заказ никогда не отмечается неудачным, пока деньги ещё могут быть списаны, а примечание просит проверить платёж в панели CCAvenue перед выполнением заказа. Более поздний ответ с тем же tracking ID всё равно применяется: Success устанавливает Order Status After Payment, Failure устанавливает Failed Payment Status, Aborted устанавливает Cancelled Payment Status. OpenCart уведомляет покупателя об этих изменениях.

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

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

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

VibeFox CCAvenue Payment tab

В Sales > Orders откройте заказ, оплаченный через CCAvenue. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox CCAvenue Payment показывает CCAvenue order ID с меткой Test mode для тестовых платежей, Tracking ID, Status, Bank reference, Payment mode и название карты, Amount sent и Amount received, Date, Message от CCAvenue и CCAvenue notes заказа. Вкладка показывается пользователям, у которых есть доступ к расширению.

Возвраты

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

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

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

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

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

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

CCAvenue does not appear at checkout: проверьте, что лицензия активна, Enable/Disable включён и заполнены все три учётных данных: Merchant ID, Access Code и Working Key. На странице настроек показывается предупреждение, если одно из них не заполнено. Также проверьте, что платёжный адрес входит в выбранную Geo Zone, и что сумма заказа достигает Total, заданного в настройках.

The payment went through, but the order stays without a status: покупатель не вернулся из CCAvenue в ваш магазин, например потому что закрыл браузер. Расширение не получает уведомлений от сервера к серверу. Проверьте платёж в панели CCAvenue и обновите заказ вручную.

Every payment ends with We could not confirm the payment result: ответ не удаётся расшифровать. Working Key неверный, относится к другому домену или скопирован с лишними символами. Создайте ключи для домена этого магазина и вставьте их заново. Включите Debug log и посмотрите поле Log на странице расширения.

CCAvenue shows an error before the payment page: проверьте, что Access Code и Working Key созданы для этого домена, что URL возврата принадлежит домену, зарегистрированному в CCAvenue, и что в тестовом режиме CCAvenue включил тестовый доступ для вашего аккаунта. Для валюты, отличной от INR, мультивалютная обработка должна быть включена в вашем аккаунте CCAvenue.

The customer sees This payment method is temporarily unavailable: не заполнено одно из учётных данных или сумма заказа равна нулю. Debug log показывает причину.

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

The customer sees Payment gateway error: encryption failed: не удалось зашифровать запрос. Проверьте, что установлено расширение OpenSSL для PHP.

The Merchant ID does not change on save: значение содержит что-то кроме цифр. Введите только цифры вашего Merchant ID.

Order is in the review or awaiting status: прочитайте примечания на вкладке VibeFox CCAvenue Payment (см. Статусы заказов). Проверьте платёж в панели CCAvenue, затем выполните заказ или верните платёж.

Для разработчиков: перед шифрованием запроса расширение вызывает событие OpenCart ccavenue_p_request_params с параметрами запроса и заказом (например, чтобы задать merchant_param2 ... merchant_param5; не меняйте amount, currency, order_id и merchant_param1).

Удаление

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

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

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