VibeFox eWAY for OpenCart — Допомога

Вимоги

OpenCart: 3.0.x (перевірено на версії 3.0.5.0) або 4.0.2 і новіші (перевірено на 4.1.0.3).

PHP: 8.0 або новіша, з розширенням cURL.

Валюта: AUD, NZD, SGD, HKD або MYR. Для інших валют оформлення замовлення спосіб оплати приховано на оформленні. Оплата списується у валюті замовлення.

Обліковий запис eWAY: потрібен обліковий запис мерчанта eWAY з доступом до Rapid API та його ключ і пароль Rapid API; їх можна знайти в MyeWAY у розділі Settings, API Key. Для тестування потрібен обліковий запис sandbox eWAY з власним ключем і паролем. Ключі sandbox і робочі ключі відрізняються. У MyeWAY нічого налаштовувати не потрібно: URL повернення передається з кожним платежем.

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

Встановлення

Завантаження — це один zip-файл з пакетами для обох версій OpenCart. Розпакуйте його на комп'ютері. Він містить README.txt, пакет для OpenCart 3 wcp_eway_payment_gateway-oc3-(version).ocmod.zip і пакет для OpenCart 4 wcp_eway_payment_gateway.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

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

2. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox eWAY Payment Gateway і натисніть Install (зелена кнопка +). Вашому користувачу-адміністратору потрібне право змінювати список платіжних розширень.

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

4. Введіть ключ і пароль API sandbox, залиште Sandbox Mode увімкненим, увімкніть Enable/Disable, натисніть Save і оформіть тестове замовлення.

5. Введіть робочий ключ і пароль API, вимкніть Sandbox Mode і натисніть Save.

6. За бажанням додайте URL cron, показаний на сторінці налаштувань, до cron-завдань вашого сервера (див. Налаштування).

OpenCart 4

1. В адміністративній частині перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_eway_payment_gateway.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з імені файлу, тому перейменований пакет не працює.

2. Пакет з'являється у списку встановлених розширень на тій самій сторінці. Натисніть Install (зелена кнопка +) поруч із ним.

3. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox eWAY Payment Gateway, натисніть Install (зелена кнопка +), а потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ, ключі eWAY і URL cron, як у кроках 3–6 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях. Відрізняється лише URL cron (див. Re-check of lost returns (cron)).

Нове встановлення починає роботу з вимкненим способом оплати та увімкненим режимом sandbox.

Налаштування

Усі налаштування містяться на сторінці розширення: Extensions > Extensions > Payments > VibeFox eWAY Payment Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями бейдж показує режим: SANDBOX — payments go to the eWAY sandbox, no real money is charged. або LIVE — real payments are taken with the live API key. Сторінка попереджає, якщо для поточного режиму не вказано ключ або пароль API (тоді спосіб оплати не показується на оформленні замовлення), і якщо eWAY не підтримує валюту магазину за замовчуванням. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

Під час збереження Title має містити від 1 до 128 символів, Sort Order — ціле число, Total — число не менше нуля, а вибрані географічна зона та статуси замовлень мають існувати. Інакше нічого не зберігається, і сторінка показує, що потрібно виправити.

eWAY

Enable/Disable: Enable eWAY Payment Gateway вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

Title: назва способу оплати, яку бачить покупець на оформленні замовлення. Вона ж зберігається в замовленні. За замовчуванням: Credit Card (eWAY). Обов'язкове поле, до 128 символів.

Description: текст, який покупець бачить на кроці Confirm Order над кнопкою підтвердження. За замовчуванням: Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.

Sort Order: положення eWAY серед способів оплати на оформленні замовлення. Залиште поле порожнім або введіть ціле число.

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

Total: сума кошика в валюті магазину за замовчуванням, яку має досягти замовлення, щоб пропонувався eWAY. Залиште поле порожнім, щоб пропонувати eWAY за будь-якої суми.

Облікові дані API

Ключ і пароль Rapid API містяться в MyeWAY у розділі Settings, API Key. eWAY має інструкції для робочих ключів і ключів sandbox, посилання на які є в цьому розділі. Ключі sandbox і робочі ключі відрізняються. Режим sandbox використовує лише облікові дані sandbox, робочий режим — лише робочі облікові дані.

Sandbox Mode: платежі надсилаються в sandbox eWAY з ключем і паролем sandbox; реальні кошти не списуються. За замовчуванням: увімкнено. Вимкніть, щоб приймати робочі платежі з робочим ключем. Поки режим увімкнено, покупець бачить Test mode: no real payment is taken. на кроці Confirm Order.

Live API Key: ключ Rapid API вашого робочого облікового запису eWAY.

Live API Password: пароль Rapid API вашого робочого облікового запису eWAY.

Sandbox API Key: ключ Rapid API вашого облікового запису sandbox eWAY (партнерського або розробницького).

Sandbox API Password: пароль Rapid API вашого облікового запису sandbox eWAY.

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

Return URL: показує адресу повернення розширення. Вона автоматично передається в eWAY з кожним платежем разом із замовленням і випадковим ключем спроби оплати, тож у MyeWAY нічого налаштовувати не потрібно. Результат платежу завжди отримується від eWAY з сервера на сервер.

Re-check of lost returns (cron): необов'язковий URL cron, показаний під Return URL. Викликайте його з cron-завдання вашого сервера кожні 15 хвилин, наприклад за допомогою curl. Якщо покупець оплатив і закрив браузер, не повернувшись до магазину, платіж запитується в eWAY приблизно через 60 хвилин після відправлення покупця до eWAY, і замовлення оновлюється. Якщо eWAY недоступний, перевірка повторюється до трьох разів. Тримайте цей URL у таємниці: він містить секретний токен, створений під час встановлення, а виклик із хибним токеном отримує відповідь Forbidden. На OpenCart 4 URL має вигляд https://your-store/index.php?route=extension/wcp_eway_payment_gateway/payment/wcp_eway_payment_gateway.cron&token=(token).

Замовлення

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення). Замовлення отримує статус лише після того, як eWAY підтвердив платіж. Кожне з полів нижче пропонує ваші статуси замовлень OpenCart.

Order Status on Success: статус, що встановлюється, щойно eWAY підтверджує платіж. За замовчуванням: В обробці.

eWAY payment on hold status: статус для схваленого платежу, який потребує вашої перевірки: сума або валюта не відповідають замовленню, платіж схвалено після того, як покупець натиснув Cancel на сторінці eWAY, або замовлення вже мало інший статус. Примітка в історії замовлення пояснює причину. За замовчуванням: Очікування, оскільки в OpenCart немає статусу On hold. Власний статус можна створити в System > Localisation > Order Statuses і вибрати його тут.

Refunded order status: статус після повного повернення платежу зі сторінки замовлення. За замовчуванням: Повернено.

Додатково

Debug log: записує виклики API та результати платежів у eway_p_debug.log.php у папці журналів OpenCart (storage/logs). Файл не можна відкрити через веб; при розмірі 5 МБ його переміщують до eway_p_debug.old.log.php. Дані карток, ключі, паролі, електронні адреси покупців і коди доступу не записуються. Помилки завжди записуються. За замовчуванням: вимкнено.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб його очистити.

Delete all extension data on uninstall: якщо увімкнено, під час видалення розширення видаляються налаштування шлюзу та журнал. Записи про платежі й повернення eWAY за замовленнями завжди зберігаються. За замовчуванням: вимкнено.

Імпорт / експорт

Export: Download JSON зберігає налаштування у файл JSON. Ключі й паролі API не експортуються.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування. Збережені ключі й паролі API зберігаються.

Оформлення замовлення

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Credit Card (eWAY)). На кроці Confirm Order покупець бачить ваш опис і примітку You will be redirected to the secure eWAY payment page to pay by card. OpenCart створює замовлення на цьому кроці, все ще без статусу. На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення. Коли покупець натискає Confirm Order, розширення запитує в eWAY сторінку оплати на суму замовлення у валюті замовлення, з OC- і номером замовлення як посиланням на рахунок (invoice reference), а також з платіжною адресою та електронною адресою покупця, і надсилає покупця на захищену сторінку eWAY (Responsive Shared Page). Там покупець платить карткою. Платіж списується одразу.

Після оплати покупець повертається до вашого магазину. Розширення не довіряє браузеру: воно запитує в eWAY з сервера на сервер результат сторінки оплати, створеної для цього замовлення. Замовлення позначається оплаченим лише після того, як eWAY його підтвердить і схвалені сума та валюта збігаються із замовленням. Далі замовлення отримує статус стандартним для OpenCart способом, зі звичайними листами про замовлення та оновленням залишків, а покупець бачить сторінку успішного оформлення замовлення OpenCart. Для замовлення на утриманні сторінка додатково показує Your payment was received and is being reviewed by the store. We will contact you if anything is needed.

Якщо в цей момент запитати eWAY неможливо, сторінка Payment confirmation показує We have not received the confirmation of your payment from eWAY yet. If you completed the payment, this order will be updated shortly — please do not pay again. з кнопкою Check again і кнопкою Back to checkout. Замовлення отримає статус, коли покупець перевірить знову або коли буде викликано URL cron.

Якщо платіж відхилено, покупець повертається до оформлення замовлення з причиною, наприклад Your payment was declined: D4451 Insufficient funds. Please try again or use a different payment method. Замовлення залишається без статусу. Якщо покупець натискає Cancel на сторінці eWAY, розширення спочатку перевіряє в eWAY, що нічого не оплачено (наприклад, в іншій вкладці). Тоді покупець бачить You cancelled the payment on the eWAY page. Your order has not been paid — you can try again. Якщо платіж не було завершено, повідомлення таке: The payment was not completed. Please try again. Кошик у всіх випадках зберігається. На OpenCart 4 ці повідомлення показуються над сторінкою оформлення замовлення.

Покупець може спробувати знову. OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order, а OpenCart 4 оновлює замовлення в процесі оформлення, тож нова спроба відкриває нову сторінку оплати eWAY для того самого замовлення. Перед створенням нової сторінки оплати попередні сторінки цього замовлення та інших замовлень того самого кошика перевіряються в eWAY. Якщо якась із них уже оплачена, підтверджується саме цей платіж, а не створюється другий. Якщо eWAY не може відповісти щодо них, покупець бачить We could not check the status of your previous payment attempt. Please try again in a moment. Якщо eWAY не може створити сторінку оплати, покупець залишається на кроці Confirm Order з коротким повідомленням, наприклад Payment error: Unable to connect to eWAY. Please try again. або eWAY could not start the payment з кодами помилок eWAY.

OpenCart 4 зберігає замовлення в оформленні, доки не буде показано сторінку успіху. Якщо це замовлення було закрито без оплати (наприклад, ви його скасували), покупця повертає до оформлення з повідомленням Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., а наступне натискання Confirm Order оплачує нове замовлення кошика. Якщо це замовлення вже оплачено, але кошик відтоді змінився, зокрема змінилася кількість, повідомлення таке: Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. Оплачене замовлення ніколи не показується як оплачене для іншого кошика.

URL повернення та cron також працюють, коли магазин перебуває в режимі обслуговування, оскільки OpenCart 3 пропускає запити платіжних розширень, а на OpenCart 4 розширення додає для них стартову дію (startup action).

eWAY не надсилає сповіщень з сервера на сервер для Shared Page: результат отримується, коли покупець повертається, і через URL cron. У розширенні немає полів картки на вашому сайті, немає збережених карток і підписок, немає авторизації без списання та пізнішого захоплення (capture), а оцінки шахрайства Beagle не аналізуються (транзакції, заблоковані правилами eWAY проти шахрайства, відхиляє сам eWAY).

Замовлення та повернення коштів

Статуси замовлень

No status (missing order): покупця було відправлено до eWAY, і він не оплатив, скасував, платіж було відхилено, або результат ще не вдалося отримати. У Sales > Orders такі замовлення показуються лише з фільтром Order Status, встановленим на Missing Orders.

Order Status on Success (default Processing): платіж схвалено. Примітка показує ID транзакції eWAY, код авторизації, відповідь і режим (sandbox або робочий).

eWAY payment on hold status (default Pending): eWAY схвалив суму або валюту, відмінні від замовлення (наприклад, Approved for partial amount), платіж схвалено після того, як покупець скасував його на сторінці eWAY, або його схвалено для замовлення, якому ви вже присвоїли статус, наприклад Скасовано. Фактично списану eWAY суму записано, і примітка це пояснює. Перевірте замовлення та виконайте його або поверніть платіж.

Refunded order status (default Refunded): платіж повністю повернено через розширення.

Якщо другий платіж схвалено для вже оплаченого замовлення або для іншого замовлення того самого кошика, оплачене замовлення не змінюється. Примітка просить вас повернути дублікат у MyeWAY. Схвалений платіж за іншим посиланням на рахунок ніколи не застосовується до замовлення.

Примітки — це записи в History замовлення, які покупець не бачить.

Вкладка VibeFox eWAY Payment Gateway

У Sales > Orders відкрийте замовлення, оплачене через eWAY. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox eWAY Payment Gateway показує ID eWAY transaction з позначкою Sandbox або Live, Auth code, Response eWAY, Invoice reference, Status платежу, суми Paid / refunded, форму повернення коштів, історію повернень і eWAY notes замовлення. Вкладка показується користувачам, які мають доступ до розширення.

Повернення коштів

На вкладці введіть суму (сума, що ще не повернута, підставляється автоматично), за бажанням Reason (optional), і натисніть Refund via eWAY. Підтвердіть запитання Refund this amount through eWAY? This cannot be undone. Підтримуються повні та часткові повернення. Потрібне право змінювати розширення (налаштовується в System > Users > User Groups). Повернення виконуються в тій сумі та валюті, які списав eWAY, тож після схвалення на часткову суму можна повернути не більше того, що покупець фактично сплатив, а не суму замовлення. Повернення надсилається в тому середовищі, де було здійснено платіж (sandbox або робочому), тому мають бути заповнені ключ і пароль API цього середовища. Якщо eWAY відхиляє повернення, вкладка показує eWAY refund failed: з кодами eWAY, і жодне повернення не фіксується. Успішне повернення додається до історії повернень і приміток з ID транзакції повернення eWAY. Повне повернення встановлює замовленню статус Refunded order status без повідомлення покупця та без повернення товарів на склад, як ручна зміна статусу. Часткове повернення статус не змінює. Повернення доступні після того, як eWAY схвалив платіж.

Повернення товарів у Sales > Returns не повертають гроші через eWAY. Повернення, зроблені в MyeWAY, не синхронізуються назад з OpenCart. За потреби оновіть замовлення вручну.

Ліцензійний ключ

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

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

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

Усунення несправностей

eWAY does not appear at checkout: перевірте, що ліцензія активна, Enable/Disable увімкнено, заповнені ключ і пароль API поточного режиму (поля sandbox у режимі sandbox, робочі поля в робочому режимі), а валюта оформлення замовлення — AUD, NZD, SGD, HKD або MYR. Сторінка налаштувань показує попередження, якщо облікові дані не заповнено. Також перевірте, що платіжна адреса входить до вибраної Geo Zone і що замовлення досягає Total, заданого в налаштуваннях.

The payment went through, but the order stays without a status: покупець не повернувся з eWAY, або в цей момент не вдалося запитати eWAY. eWAY не надсилає сповіщень для Shared Page. Налаштуйте URL cron з розділу Re-check of lost returns (cron): він підхопить платіж приблизно через годину. Перевірте транзакцію в MyeWAY і подивіться поле Log на сторінці розширення.

The cron URL answers Forbidden: токен в URL невірний. Скопіюйте URL точно так, як його показано на сторінці налаштувань.

The customer sees This payment method is temporarily unavailable: ключ або пароль API поточного режиму відсутні, або eWAY їх відхилив. Перевірте облікові дані поточного режиму.

The customer sees eWAY could not start the payment: eWAY повернув коди помилок, які показано в повідомленні. Часто причина в некоректних платіжних даних.

The customer sees eWAY cannot take payments in a currency: валюта замовлення не належить до тих, які приймає eWAY. Використовуйте AUD, NZD, SGD, HKD або MYR.

The customer sees We could not match this payment to an order: посилання повернення не належить до замовлення цього магазину, або eWAY схвалив платіж за іншим посиланням на рахунок. Якщо з покупця списано гроші, знайдіть платіж у MyeWAY.

The customer sees This payment method is not available: сесія оформлення замовлення більше не відповідає замовленню, або спосіб оплати тим часом вимкнено. Покупець перезавантажує оформлення замовлення.

Order is in the on hold status after payment: прочитайте eWAY notes на вкладці VibeFox eWAY Payment Gateway (див. Статуси замовлень), потім виконайте замовлення або поверніть платіж.

No refund form in the tab: вкладка показує причину: для замовлення не знайдено ID транзакції eWAY, його повністю повернено, ваша група користувачів не має права змінювати розширення, або облікові дані API режиму платежу не заповнені.

Refund fails with a message about the sandbox or live mode: замовлення оплачено в цьому середовищі, а його ключ і пароль API не заповнені. Введіть їх і спробуйте знову.

Refund fails with at most … can be refunded: сума більша за ту, що eWAY списав, за вирахуванням уже виконаних повернень.

Для розробників: розширення викликає події OpenCart wcp_eway_payment_gateway_supported_currencies (якщо ваш обліковий запис eWAY підключено до інших валют) та wcp_eway_payment_gateway_create_access_code_request (тіло запиту перед створенням сторінки оплати).

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox eWAY Payment Gateway. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total і статуси замовлень із розділу Orders, які під час повторного встановлення повертаються до значень за замовчуванням. Подія OpenCart розширення також видаляється (на OpenCart 4 — її події та стартова дія, яка пропускає URL повернення і cron у режимі обслуговування). Якщо Delete all plugin data on uninstall увімкнено, видаляються інші налаштування шлюзу (назва, опис, режим sandbox, ключі та паролі API, перемикач журналу налагодження, токен cron) і журнал. Якщо вимкнено, їх зберігають для наступного повторного встановлення. Записи про платежі та повернення eWAY завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату.

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

eWAY — торгова марка її власника. Це розширення не афілійоване з eWAY і не схвалене eWAY.