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.