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

Вимоги

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

PHP: 8.0 або новіша.

HTTPS та PCI DSS: дані картки вводяться на сторінці оформлення замовлення і надсилаються з вашого сервера до Helcim. Вони ніколи не зберігаються і не записуються в журнал, але проходять через ваш сервер, тому магазину потрібен SSL-сертифікат для оформлення замовлення, а хостинг має відповідати вимогам PCI DSS (SAQ D).

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

Обліковий запис Helcim: обліковий запис мерчанта Helcim у Канаді або США та токен API з правом обробки транзакцій (див. Configuration). Тестовий (developer) обліковий запис Helcim необов'язковий для тестування.

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

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

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

OpenCart 3

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

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

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

4. У Helcim відкрийте All Tools > Integrations > API Access Configuration, створіть доступ до API з правом обробки транзакцій (покупки, попередні авторизації, захоплення та повернення коштів) і скопіюйте його токен.

5. Вставте токен у поле Live API token, а токен вашого тестового облікового запису Helcim у поле Test API token, якщо він у вас є.

6. Оберіть Transaction type та Account currencies, увімкніть Enable / Disable і натисніть Save. Щоб спочатку протестувати, увімкніть Test mode і сплатіть тестовим обліковим записом; потім вимкніть його.

OpenCart 4

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

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

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

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

Під час нового встановлення спосіб оплати вимкнений, а тестовий режим вимкнено.

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox Helcim Gateway > Edit. Розділи перелічені ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка попереджає, якщо валюта за замовчуванням вашого магазину не входить до Account currencies (тоді Helcim пропонується лише для замовлень у дозволеній валюті), а також, поки спосіб оплати увімкнено, якщо токен API поточного режиму порожній (тоді спосіб оплати приховується на оформленні замовлення). Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

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

Helcim

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

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

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

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

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

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

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

У Helcim перейдіть до All Tools > Integrations > API Access Configuration, створіть доступ до API і скопіюйте його токен. Надайте йому право обробки транзакцій для покупок, попередніх авторизацій, захоплень і повернень коштів. Тестові облікові записи Helcim використовують ту саму адресу API, що й робочі, тож тестовий режим просто використовує токен вашого тестового облікового запису Helcim. Розділ містить посилання на документацію API Helcim.

Live API token: токен API вашого робочого облікового запису Helcim. Використовується, коли тестовий режим вимкнено.

Test mode: використовує Test API token (тестовий обліковий запис Helcim). Платежі, захоплення та повернення коштів надсилаються на ваш тестовий обліковий запис Helcim, а покупці бачать повідомлення про тестовий режим. Захоплення та повернення коштів для замовлення завжди використовують токен того режиму, в якому замовлення було оплачено. За замовчуванням: вимкнено.

Test API token: токен API вашого тестового (developer) облікового запису Helcim. Використовується, коли тестовий режим увімкнено.

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

Оплата

Transaction type: спосіб списання коштів з картки.

Account currencies: валюти, які може обробляти ваш обліковий запис Helcim. Замовлення завжди списуються у валюті замовлення. Для інших валют спосіб оплати на оформленні замовлення приховується.

Замовлення

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

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

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

On Hold (Review) Status: відповідь Helcim не збігається із замовленням (часткове схвалення, інша валюта, немає ID транзакції або сума замовлення відрізняється від списання). Перевірте транзакцію в Helcim перед виконанням замовлення; примітка пояснює причину. За замовчуванням: Очікування. Ви можете створити власні статуси в System > Localisation > Order Statuses, щоб відрізняти авторизовані замовлення від замовлень на перевірці.

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

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

Додатково

Debug log: записує запити та відповіді API у файл wc_hlg_debug.log.php у папці журналів OpenCart (storage/logs). Файл не можна відкрити з веб-браузера. Номери карток скорочуються до останніх 4 цифр. CVC, термін дії, токени, імена, адреси, e-mail та IP-адреси ніколи не записуються. Помилки (відхилені або невдалі платежі, помилки API, невдалі захоплення та повернення коштів) записуються завжди, навіть коли цю опцію вимкнено. За замовчуванням: вимкнено.

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

Delete data on uninstall: якщо увімкнено, при видаленні розширення видаляються налаштування шлюзу та його файли журналу. Транзакції та повернення Helcim завжди зберігаються, тож замовлення, оплачені раніше, можна буде захопити та повернути після повторного встановлення. За замовчуванням: вимкнено.

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

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

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

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Credit card (Helcim)). На кроці Confirm Order покупець бачить значок картки, ваш опис і форму з полями Card Number, Expiry (MM/YY), CVC та Cardholder Name. У тестовому режимі форма показує TEST MODE — payments go to a Helcim test account, no real charges are made. OpenCart створює замовлення на цьому кроці, все ще без статусу. Коли покупець натискає Confirm Order, розширення перевіряє контрольну суму номера картки, що термін дії дійсний і не минув, що CVC має 3 або 4 цифри і що ім'я заповнено. Помилки показуються над формою, і нічого не надсилається до Helcim.

В OpenCart 4 покупець обирає спосіб оплати кнопкою Choose в блоці способу оплати, у вікні Payment method options. Форма картки тоді з'являється в блоці підтвердження замовлення внизу сторінки оформлення, над кнопкою Confirm Order. За замовчуванням OpenCart 4 не запитує платіжну адресу; тоді розширення надсилає до Helcim адресу доставки разом з іменем власника картки для перевірки адреси.

Далі ваш сервер надсилає картку до Helcim як покупку або попередню авторизацію на суму замовлення у валюті замовлення. Ім'я власника картки, платіжна адреса, телефон і e-mail передаються для перевірки адреси. Платіж у Helcim відображається з номером рахунку, що складається з номера замовлення, -OC та короткого коду. Helcim відповідає у тому самому запиті. Замовлення отримує статус лише після того, як Helcim схвалить транзакцію, стандартним способом OpenCart, зі звичними листами про замовлення та оновленням залишків. Кошик одразу очищується, і покупець потрапляє на стандартну сторінку успішного оформлення замовлення OpenCart.

Для одного кошика одночасно виконується лише одна спроба оплати, і оплачений кошик ніколи не списується повторно, навіть якщо OpenCart у цей час створив для нього нове замовлення (OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order; в OpenCart 4 попереднє замовлення або друга вкладка браузера все ще можуть мати той самий кошик). OpenCart 4 зберігає одне замовлення для оформлення і оновлює його, тож після відхиленої картки покупець сплачує те саме замовлення. Якщо це замовлення тим часом закрили (наприклад, ви його скасували), або воно вже оплачене, а в кошику тепер нова покупка, Confirm Order повертає покупця на сторінку оформлення з повідомленням Your previous order is already closed (cancelled or refunded by the store) or paid for another cart. Please confirm the order again: the cart will be paid with a new order. над ним, а наступне натискання Confirm Order оплачує нове замовлення кошика. Зміна кошика, включно з новою кількістю, вважається новим кошиком, який потребує власної оплати. Кожна спроба використовує ключ ідемпотентності. Якщо Helcim не відповідає, замовлення залишається без статусу, а повторна спроба протягом 5 хвилин повертає початковий результат Helcim замість подвійного списання з картки. Якщо платіж схвалено, але статус замовлення не вдалося встановити, наступна спроба для того самого кошика встановлює статус без повторного списання з картки.

Повідомлення, які покупець може побачити над формою: Your card was declined. Please check the card details or use another card., коли Helcim відхиляє; Payment failed: з причиною від Helcim для інших відхилених запитів; We could not confirm your payment with the card processor. Please try again in a minute; if the problem persists, contact us before using another card., коли Helcim не відповідає; This payment method is temporarily unavailable. Please choose another payment method., коли токен API відхилено; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. при подвійному натисканні; Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again., коли платіж схвалено, але статус замовлення не вдалося встановити. Покупець залишається на кроці Confirm Order з тим самим кошиком. Технічні подробиці записуються до журналу.

Розширення не використовує HelcimPay.js чи Helcim.js, тому дані картки проходять через ваш сервер. Воно не підтримує збережені картки, підписки, платежі ACH чи банківські перекази, Apple Pay, Google Pay або 3-D Secure, а також вебхуки Helcim.

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

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

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

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

Authorized Status (за замовчуванням Pending): попередню авторизацію схвалено. Кошти лише заблоковані. Захопіть їх або зніміть блокування повним поверненням.

On Hold (Review) Status (за замовчуванням Pending): Helcim схвалив транзакцію, але сума, валюта або ID транзакції у його відповіді не відповідають замовленню, наприклад після часткового схвалення або коли сума замовлення змінилася під час оплати. Примітка містить Helcim response verification FAILED. Перевірте транзакцію в Helcim перед виконанням замовлення.

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

Canceled Status (за замовчуванням Canceled): незахоплену попередню авторизацію знято. Покупця не списали.

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

Вкладка VibeFox Helcim Gateway

У Sales > Orders відкрийте замовлення, оплачене через Helcim. Унизу сторінки замовлення, поруч із History та Additional, вкладка VibeFox Helcim Gateway показує Transaction ID (і ID попередньої авторизації після захоплення) з позначкою Test mode для тестових платежів, Transaction type та стан захоплення, Invoice, Card і код схвалення, суми Approved / order / refunded, кнопку захоплення та форму повернення, історію повернень і Helcim notes замовлення. Вкладка показується користувачам, які мають доступ до розширення; захоплення та повернення потребують права змінювати його (встановлюється в System > Users > User Groups).

Захоплення

Для незахопленої попередньої авторизації натисніть Capture payment на вкладці (на кнопці показано суму) і підтвердьте Capture the pre-authorized amount through Helcim? Захоплюється поточна сума замовлення мінус повернення. Вона може бути меншою за авторизовану суму, але не більшою. Захоплення використовує токен режиму, в якому замовлення було оплачено. Після успішного захоплення замовлення отримує Order Status After Payment. Якщо захоплення не вдалося, вкладка показує причину і додає її до приміток.

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

На вкладці введіть Amount (підставляється сума, яка ще не повернута), за бажанням Reason (optional), і натисніть Refund via Helcim. Підтвердьте Refund this amount through Helcim? This cannot be undone. Підтримуються повні та часткові повернення покупки або захопленої попередньої авторизації, але не більше суми, яку Helcim фактично списав; тому після часткового схвалення ви не можете повернути більше, ніж сплатив покупець. Для незахопленої попередньої авторизації кнопка називається Release pre-authorization: можна зняти лише повну суму, блокування видаляється, а замовлення отримує Canceled Status.

Повернення надсилається в режимі, в якому замовлення було оплачено, тож токен цього режиму має бути встановлено. Воно зараховується лише тоді, коли Helcim його схвалює. Якщо Helcim відхиляє повернення, вкладка показує помилку, і жодне повернення не записується. Успішне повернення додається до історії повернень і приміток з ID транзакції повернення Helcim. Повне повернення встановлює замовленню статус Refunded Status без сповіщення покупця і без повернення товарів на склад, як і ручна зміна статусу. Часткове повернення статус не змінює. Повторна спроба після тайм-ауту не повертає кошти двічі.

Повернення товарів у Sales > Returns не повертають гроші через Helcim. Розширення не отримує вебхуки Helcim: захоплення, повернення та анулювання, зроблені в панелі Helcim, не відображаються в OpenCart, тож виконуйте їх зі сторінки замовлення.

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

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

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

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

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

Helcim не з'являється на оформленні замовлення: перевірте, що ліцензія активна, Enable / Disable увімкнено, для поточного режиму задано токен API (Live API token або в тестовому режимі Test API token) і валюта оформлення замовлення входить до Account currencies. Сторінка налаштувань показує попередження, коли токен відсутній або валюта магазину не дозволена. Також перевірте, що платіжна адреса входить до вибраної Geo Zone і що замовлення досягає Total, встановленого в налаштуваннях.

Покупець бачив We could not confirm your payment: Helcim не відповів, тому картку могли списати. Примітка до замовлення та журнал вказують рахунок Helcim. Перевірте цей рахунок у Helcim, перш ніж знову списувати кошти з покупця. Повторна спроба протягом 5 хвилин повертає початковий результат і не списує подвійно.

Покупці бачать This payment method is temporarily unavailable: Helcim відхилив токен API. Примітка до замовлення радить перевірити токен і його права. Переконайтеся, що доступ до API має право обробки транзакцій.

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

Оплата не вдалася з причиною від Helcim: Helcim відхилив запит, наприклад через картку або платіжні дані. Подробиці є в примітці до замовлення та в журналі.

Покупець бачив Your payment was received, but the order could not be completed: Helcim схвалив платіж, але OpenCart не зміг встановити статус замовлення. Причина є в журналі. Коли покупець знову надсилає той самий кошик, статус встановлюється з уже схваленого платежу без другого списання.

Замовлення в статусі перевірки: прочитайте примітки на вкладці VibeFox Helcim Gateway. Відповідь Helcim не збіглася із замовленням (перевірка відповіді не пройдена). Перевірте транзакцію в Helcim, а потім виконайте замовлення або поверніть платіж.

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

Повернення не вдається: прочитайте повідомлення. Незахоплену попередню авторизацію можна зняти лише повністю. Повідомлення про режим означає, що токен режиму, в якому замовлення було оплачено, порожній. Відхилене повернення не записується. You do not have permission to capture or refund (modify this extension). означає, що ваша група користувачів не має права змінювати розширення.

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

Видалення

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

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

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