VibeFox CCAvenue for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

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

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

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

Установка

1. В бэк-офисе перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox CCAvenue Payment в списке модулей и нажмите Configure.

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

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

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

При установке модуль создаёт два статуса заказа: Awaiting CCAvenue payment и CCAvenue payment on hold. PrestaShop включает новый платёжный модуль для всех валют, стран и групп клиентов. Ограничить их можно в Payment > Preferences.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox CCAvenue Payment > Configure. У каждого раздела есть собственная кнопка 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.

CCAvenue

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

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

Description: текст под способом оплаты на странице оформления заказа. По умолчанию: Pay securely via Credit/Debit card, Net Banking, UPI or Wallet through 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, чтобы удалить сохранённый Working Key. Пустое поле оставляет сохранённое значение.

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

URL возврата

CCAvenue возвращает покупателя по адресу, указанному в этом разделе. При понятных URL он выглядит так: https://your-shop/module/wcp_ccavenue_payment/return, возможно с кодом языка, например /en/. Модуль передаёт этот URL с каждым платежом (как адрес перенаправления и отмены), поэтому в CCAvenue ничего настраивать не нужно. Он должен принадлежать домену, зарегистрированному в CCAvenue.

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

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

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

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

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию CCAvenue) и подтверждает выбор. Страница показывает Thank you for your order. You are being redirected to CCAvenue to complete the payment. и отправляет покупателя на платёжную страницу CCAvenue. Без JavaScript покупатель нажимает Pay via CCAvenue или Back to checkout. На этом этапе заказа ещё не существует.

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

После оплаты CCAvenue возвращает покупателя с зашифрованным ответом. Заказ отмечается как оплаченный только после подтверждения CCAvenue: ответ должен расшифровываться вашим Working Key, относиться к попытке этого магазина и иметь ту же сумму и валюту, что были отправлены и что указаны в корзине. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с сообщением 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 shop. Если заказ в ожидании позже отменяется или не удаётся без оплаты, страница подтверждения показывает Your CCAvenue payment was not completed. Please contact us about this order.

Если платёж не прошёл, покупатель возвращается к оформлению заказа с сообщением 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. В этих случаях заказ не создаётся, корзина сохраняется, и покупатель может оплатить снова. Если в корзине уже есть заказ, новая попытка сразу ведёт на страницу подтверждения этого заказа, а не на повторную оплату.

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

Заказы

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

No order yet: покупатель был отправлен на CCAvenue и не вернулся либо платёж не удался или был отменён. Существует только корзина. Если покупатель не вернулся, проверьте платёж в панели CCAvenue.

Payment accepted: платёж подтверждён. Он регистрируется с ID трекинга CCAvenue в качестве ID транзакции, а примечание показывает банковскую ссылку, ID трекинга и режим оплаты.

Awaiting CCAvenue payment: CCAvenue сообщил о платеже как Awaited (банк его ещё не подтвердил). Заказ никогда не помечается как неудачный, пока деньги могут ещё быть списаны. Проверьте его в панели CCAvenue перед обработкой заказа. Последующий ответ с тем же ID трекинга всё равно применяется: Success переводит заказ в Payment accepted, Failure — в Payment error, Aborted — в Canceled.

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

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

Блок платежа CCAvenue

На странице заказа показан блок CCAvenue payment с номером заказа CCAvenue, ID трекинга, статусом, банковской ссылкой, режимом оплаты и названием карты, отправленной и полученной суммой, датой и сообщением CCAvenue, а также метка Test mode для тестовых платежей. Примечания CCAvenue — это закрытые сообщения заказа, видимые только в бэк-офисе.

Возвраты

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

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox CCAvenue Payment — это первый блок на странице Modules > Module Manager > VibeFox CCAvenue Payment > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-ccavenue и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока соответствуют языку бэк-офиса (включены английский и русский).

Если ключ не принят, блок объясняет причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: домене основного магазина, в том числе при мультимагазинной настройке. Удаление ключа из магазина не освобождает слот домена. Освободите слот в своём аккаунте vibefox.net.

Без действующего ключа CCAvenue не показывается покупателям на оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его на оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: платежи, которые уже начаты, по-прежнему подтверждаются, когда покупатель возвращается из CCAvenue.

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

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

CCAvenue не отображается на оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включён и заполнены все три учётных данных: Merchant ID, Access Code и Working Key. Страница настроек показывает предупреждение, если чего-то не хватает. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

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

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

CCAvenue показывает ошибку до страницы оплаты: проверьте, что Access Code и Working Key сгенерированы для этого домена, что URL возврата принадлежит домену, зарегистрированному в CCAvenue, и — в тестовом режиме — что CCAvenue включил тестовый доступ для вашей учётной записи. Для валюты, отличной от INR, на вашей учётной записи CCAvenue должна быть включена мультивалютная обработка.

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

Покупатель видит This payment method is not available: модуль выключен или не разрешён для валюты корзины, страны или группы покупателя в Payment > Preferences.

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

Merchant ID не меняется при сохранении: значение содержит что-то кроме цифр. Введите только цифры вашего Merchant ID.

Заказ в статусе CCAvenue payment on hold или Awaiting CCAvenue payment: прочитайте примечание к заказу (см. Статусы заказов). Проверьте платёж в панели CCAvenue, а затем обработайте заказ или выполните возврат платежа.

Для разработчиков модуль предоставляет хук actionCcavenueRequestParams (изменяет данные, отправляемые в CCAvenue, до шифрования, например merchant_param2–merchant_param5; значения не должны содержать &; не меняйте amount, currency, order_id и merchant_param1).

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox CCAvenue Payment и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. В окне подтверждения напоминается, что настройки и ссылки CCAvenue сохраняются, если не включено Delete data on uninstall. Если эта опция включена, удаляются настройки модуля, журнал и номера заказов CCAvenue. Если выключена, всё сохраняется для повторной установки. Статусы заказов Awaiting CCAvenue payment и CCAvenue payment on hold всегда сохраняются. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

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