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

Вимоги

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

PHP: 8.0 або новіша версія.

Валюта: CAD для канадського облікового запису Moneris, USD для застарілого облікового запису Moneris USA. Спосіб оплати відображається, лише якщо валюта оформлення замовлення збігається з валютою облікового запису.

HTTPS та PCI DSS: номери карток вводяться на сторінці оформлення замовлення і проходять через ваш сервер. Для реальних платежів потрібні HTTPS і відповідність PCI DSS SAQ D. Якщо ви не можете цього забезпечити, скористайтеся натомість рішенням із розміщеною сторінкою оплати.

Обліковий запис Moneris: вам потрібні Store ID та API Token вашого магазину Moneris Gateway з розділу Moneris Merchant Resource Center > Admin > Store Settings. Для тестування за замовчуванням заповнено загальнодоступний тестовий магазин Moneris. Тестові облікові дані та тестові картки розміщені на порталі розробників Moneris.

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

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

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

OpenCart 3

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

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

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

4. Оберіть країну облікового запису та введіть Live Store ID і Live API Token. Тестовий режим увімкнено за замовчуванням і використовує загальнодоступний тестовий магазин (store5 / yesguy для Канади, monusqa002 / qatoken для США).

5. Оберіть тип транзакції та логотипи карток, потім увімкніть Enable / Disable і натисніть Save.

6. Оформіть тестове замовлення тестовою карткою Moneris, потім вимкніть Test mode.

OpenCart 4

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

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

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

4. Введіть ліцензійний ключ і налаштування так само, як у кроках 3–6 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях.

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

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

Усі налаштування розміщені на сторінці розширення: Extensions > Extensions > Payments > VibeFox Moneris Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями, доки увімкнено тестовий режим, сторінка показує Moneris gateway is in TEST MODE. No real charges will be made. У робочому режимі вона попереджає, якщо робочі поля містять тестові облікові дані Moneris (тоді спосіб оплати приховується під час оформлення замовлення), і якщо на магазині не увімкнено SSL (в OpenCart 4 — коли адреса вітрини починається з http://). Також вона попереджає, якщо спосіб оплати увімкнено, але Store ID або API Token поточного режиму порожні, і якщо валюта магазину за замовчуванням не є валютою облікового запису Moneris; в обох випадках спосіб оплати приховується під час оформлення замовлення. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

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

Moneris

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

Title: назва способу оплати, яка відображається покупцеві. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Кредитна картка (Moneris). У тестовому режимі до назви додається (Test Mode). Обов’язкове поле.

Description: текст, що відображається над полями картки на кроці Confirm Order. За замовчуванням: Pay securely with your credit card.

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

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

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

Обліковий запис Moneris

Ваші Store ID та API Token містяться в Moneris Merchant Resource Center у розділі Admin > Store Settings. Тестові облікові дані та тестові картки розміщені на порталі розробників Moneris. Цей розділ містить посилання на обидва.

Moneris account country: канадські облікові записи списують кошти в CAD, американські — в USD. Спосіб оплати відображається, лише якщо валюта замовлення збігається. За замовчуванням: Канада (CAD).

Test mode: використовує тестовий шлюз QA від Moneris і тестові облікові дані; реальні списання не виконуються. Повернення, захоплення та анулювання завжди надсилаються до середовища, в якому було здійснено платіж. Покупці бачать TEST MODE: use a Moneris test card, no real charges are made. над полями картки. За замовчуванням: увімкнено.

Live Store ID: Store ID для робочого режиму, наприклад monca01234.

Live API Token: робочий API Token.

Test Store ID: загальнодоступний тестовий магазин Moneris: store5 (Канада) або monusqa002 (США). За замовчуванням: store5.

Test API Token: загальнодоступний тестовий токен: yesguy (Канада) або qatoken (США). За замовчуванням: yesguy.

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

Оплата

Transaction type: спосіб списання з картки. За замовчуванням: Purchase.

Card logos: бренди карток, які відображаються разом зі способом оплати під час оформлення замовлення: Visa, Mastercard, Discover, American Express, JCB. Прийнятні бренди залежать від вашого облікового запису Moneris. За замовчуванням: Visa і Mastercard.

Замовлення

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

Order Status After Payment: з картки списано кошти (покупка або захоплення попередньої авторизації). За замовчуванням: В обробці.

Authorized Status: попередня авторизація: кошти лише зарезервовано, але ще не списано. Захопіть їх на вкладці замовлення або встановивши оплачений статус. За замовчуванням: Очікується.

On Hold (Review) Status: потрібна ручна перевірка: сума, яку обробив Moneris, відрізняється від замовлення, або Moneris не відповів і перевірка статусу також не вдалася (картку могли списати). Примітка пояснює причину. За замовчуванням: Очікується, оскільки в OpenCart немає статусу «На утриманні». Власні статуси можна створити в System > Localisation > Order Statuses і вибрати їх тут та в Authorized Status.

Canceled Status: встановлюється кнопкою Void pre-authorization (cancel order) на вкладці замовлення. Переведення замовлення в цей статус знімає (анулює) незахоплену попередню авторизацію. За замовчуванням: Скасовано.

Refunded Status: встановлюється після повного повернення платежу з вкладки замовлення. Переведення замовлення в цей статус також знімає незахоплену попередню авторизацію. За замовчуванням: Повернено.

Додатково

Debug log: записує запити та відповіді API у файл wc_mng_debug.log.php у папці журналів OpenCart (storage/logs). Відкрити файл через веб не можна. Номер картки, CVV, термін дії та API Token маскуються. Помилки завжди записуються, навіть коли цей параметр вимкнено. За замовчуванням: вимкнено.

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

Delete data on uninstall: якщо увімкнено, під час видалення розширення видаляються налаштування шлюзу та журнал. Дані Moneris замовлень (потрібні для захоплень і повернень) завжди зберігаються. За замовчуванням: вимкнено.

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

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

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

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Credit card (Moneris)). На кроці Confirm Order покупець бачить ваш опис, логотипи карток і поля Card number, Expiry (MM/YY) та Card code (CVC). Усі три поля обов’язкові. На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose в блоці способу оплати, у вікні Payment method options; поля картки тоді з’являються в блоці підтвердження замовлення внизу сторінки оформлення, над кнопкою Confirm Order. Коли покупець натискає Confirm Order, ваш сервер надсилає картку до Moneris на суму замовлення і одразу отримує результат. Перенаправлення та вебхука немає. Дані картки використовуються лише для цього одного запиту; вони ніколи не зберігаються, а в журналі показано лише останні чотири цифри.

Замовлення отримує статус лише за схваленою відповіддю Moneris, стандартним для OpenCart способом, зі звичайними листами про замовлення та оновленням залишків. Кошик очищується, і покупець бачить сторінку успішного оформлення замовлення OpenCart. За попередньої авторизації замовлення чекає в Authorized Status, доки ви не захопите кошти. Якщо Moneris обробив суму, що відрізняється від суми замовлення, замовлення отримує статус перевірки з приміткою.

Якщо картку відхилено, покупець залишається на кроці Confirm Order з повідомленням Your card was declined і причиною від Moneris, та може перевірити дані картки або скористатися іншою карткою. Замовлення не отримує статусу; причина відхилення також записується в журнал. Якщо Moneris не зміг обробити запит (наприклад, через неправильний Store ID або API Token), покупець бачить The payment could not be processed. Please try again or use another payment method. Причина записується в журнал. Неправильні поля картки дають короткі повідомлення, наприклад Please enter your card details., Invalid card number. або Invalid card expiry date., і нічого не надсилається до Moneris.

Повторне натискання під час обробки платежу показує A payment for this order is already being processed. Please wait a moment and check your order status before trying again. OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order, OpenCart 4 залишає одне замовлення для оформлення, а після відхиленої картки покупець сплачує те саме замовлення. У будь-якому разі розширення розглядає всі замовлення одного кошика як один платіж: кошик, який уже оплачено або результат якого невідомий, ніколи не списується повторно, а покупець переходить на сторінку успіху. OpenCart 4 зберігає замовлення в оформленні, доки не показано сторінку успіху. Якщо це замовлення вже має статус, а в кошику знову є товари (наприклад, платіж пройшов, але сторінку успіху не показано, і покупець додав товари), або замовлення тим часом було скасовано, повернуто чи анульовано, покупця повертають на сторінку оформлення на кроці Confirm Order, а наступне натискання Confirm Order оплачує нове замовлення. Над сторінкою оформлення покупець бачить This order was cancelled or refunded by the store, so it cannot be paid again. Please check your cart and confirm the new order., якщо замовлення закрито, або This order has already been paid, and your cart now holds a new purchase. Please check your cart and confirm the new order., якщо його було оплачено за попередній кошик.

Якщо Moneris не відповідає (мережева помилка або тайм-аут), розширення надсилає до Moneris перевірку статусу з тим самим ідентифікатором замовлення Moneris, щоб дізнатися, чи пройшла транзакція. Якщо в Moneris такої транзакції немає, покупець може оплатити знову. Якщо перевірка статусу також не отримує відповіді, замовлення отримує статус перевірки з приміткою, яка називає ідентифікатор замовлення Moneris, і покупця не запрошують платити вдруге. Якщо платіж пройшов, але статус замовлення встановити не вдалося, покупець бачить Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again.

Розширення не має збережених карток і Moneris Vault, підписок, Apple Pay, Google Pay або Interac Online, Moneris Checkout чи Hosted Tokenization, 3-D Secure, AVS або Kount, а також ціноутворення у кількох валютах.

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

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

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

Order Status After Payment (за замовчуванням В обробці): покупку схвалено або попередню авторизацію захоплено. Примітка показує суму, Moneris Trans ID та чек.

Authorized Status (за замовчуванням Очікується): попередню авторизацію схвалено, і вона чекає на захоплення.

On Hold (Review) Status (за замовчуванням Очікується): оброблена сума відрізнялася від суми замовлення, або Moneris не підтвердив результат. Примітки пояснюють це.

Canceled Status (за замовчуванням Скасовано): для замовлення з попередньою авторизацією зарезервовані кошти було звільнено (анульовано).

Refunded Status (за замовчуванням Повернено): платіж повністю повернено через розширення.

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

Вкладка VibeFox Moneris Gateway

У Sales > Orders відкрийте замовлення, оплачене через Moneris. Внизу сторінки замовлення, поруч із History та Additional, вкладка VibeFox Moneris Gateway показує Trans ID (а після захоплення — Trans ID попередньої авторизації), Moneris order ID, Receipt, Transaction type та його стан (не захоплено, захоплено або звільнено), Account / environment з позначкою Test mode для тестових платежів, Card з кодом авторизації, суми Authorized / charged / refunded, кнопки захоплення, анулювання та повернення, історію повернень і Moneris notes замовлення. Якщо платіж не підтверджено, вкладка пропонує знайти ідентифікатор замовлення Moneris у Merchant Resource Center. Вкладка показується користувачам, які мають доступ до розширення; захоплення, анулювання та повернення потребують права змінювати розширення (встановлюється в System > Users > User Groups).

Захоплення та анулювання

Щоб захопити попередню авторизацію, натисніть Capture payment на вкладці та підтвердіть Capture the pre-authorized amount through Moneris?, або змініть статус замовлення через Add History на оплачений статус, наприклад Order Status After Payment чи інший статус OpenCart «В обробці» або «Завершено». Захоплюється сума замовлення мінус повернення; вона не може бути більшою за авторизовану суму. Після захоплення кнопкою замовлення отримує Order Status After Payment. Якщо Moneris відхиляє захоплення, статус не змінюється, листа не надсилається, Add History показує причину замість повідомлення про успіх, а примітка пояснює: Moneris: status not changed — the pre-authorization could not be captured з причиною. Попередні авторизації Moneris спливають через кілька днів, тож захоплюйте їх вчасно.

Щоб звільнити кошти, натисніть Void pre-authorization (cancel order) і підтвердіть, або встановіть замовленню Canceled Status. Встановлення замовленню Refunded Status також звільняє відкриту попередню авторизацію. Якщо звільнення не вдалося, примітка попросить вас звільнити її в Merchant Resource Center.

Ці зміни статусів працюють і тоді, коли розширення вимкнено (але встановлено), тож попередні авторизації, зроблені раніше, все ще можна захопити та звільнити.

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

На вкладці VibeFox Moneris Gateway введіть Amount (сума, яка ще не повернута, заповнюється автоматично), за бажання Reason (optional), і натисніть Refund via Moneris. Підтвердіть запитання Refund this amount through Moneris? This cannot be undone. Підтримуються повні та часткові повернення. Повернення обмежені сумою, яку Moneris фактично списав; тому після розбіжності суми ви можете повернути не більше того, що сплатив покупець, а не суму замовлення. Попередню авторизацію можна повернути лише після її захоплення; до цього анулюйте її, щоб звільнити кошти. Повернення надсилається до того середовища та облікового запису, в яких було здійснено платіж, тож облікові дані цього режиму мають залишатися заповненими. Якщо Moneris не приймає повернення, вкладка показує Refund failed з причиною, і жодне повернення не реєструється. Успішне повернення додається до історії повернень і приміток разом з Moneris Trans ID. Повне повернення встановлює замовленню Refunded Status; часткове повернення статус не змінює. Захоплення, анулювання та повернення безпосередньо змінюють статус замовлення, без сповіщення покупця і без повернення товарів на склад, як під час ручної зміни статусу.

Повернення товарів у Sales > Returns не повертають гроші через Moneris.

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

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

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

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

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

Moneris не відображається під час оформлення замовлення: перевірте, що ліцензія активна, Enable / Disable увімкнено і в поточному режимі є Store ID та API Token. У робочому режимі робочі поля мають містити ваші робочі облікові дані, а не тестові облікові дані Moneris. Перевірте, що валюта оформлення замовлення збігається з валютою облікового запису (CAD для Канади, USD для американського облікового запису), що платіжна адреса входить до вибраної Geo Zone і що замовлення досягає Total, заданого в налаштуваннях.

Платіж пройшов, але замовлення має статус перевірки: у розширення немає вебхука; результат надходить лише з відповіді Moneris. Прочитайте Moneris notes на вкладці. Якщо Moneris не підтвердив результат, значить, Moneris не відповів і перевірка статусу також не вдалася. Знайдіть ідентифікатор замовлення Moneris у Merchant Resource Center: якщо транзакція там є, відправте замовлення (і поверніть кошти там, якщо потрібно); якщо її немає, скасуйте замовлення або попросіть покупця оплатити знову. Якщо сума відрізнялася, перевірте замовлення та виконайте його або поверніть платіж.

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

Покупець бачить This payment method does not support the order currency.: валюта замовлення не є валютою облікового запису Moneris.

Покупець бачить помилку під час оплати: перегляньте поле Log на сторінці розширення. Помилки завжди записуються; увімкніть Debug log, щоб побачити повні запити та відповіді.

Захоплення не вдається: у замовлення немає попередньої авторизації, що чекає на захоплення, сума замовлення дорівнює нулю, або сума більша за авторизовану. Крім того, попередні авторизації Moneris спливають через кілька днів.

Повернення, захоплення або анулювання не вдається з повідомленням про режим чи обліковий запис: платіж було здійснено в тестовому або робочому режимі, а облікові дані цього режиму не вказано, або платіж було здійснено з обліковим записом Moneris іншої країни. Введіть облікові дані або обробіть платіж у Merchant Resource Center.

Атаки перебору карток: прямі форми карток є мішенню для перебору карток. Використовуйте правила eFraud або правила за частотою у вашому обліковому записі Moneris, а також розширення CAPTCHA або обмеження частоти запитів для вашого магазину.

Видалення

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

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

Moneris є торговельною маркою її власника. Це розширення не пов’язане з Moneris і не схвалене Moneris.