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

Вимоги

PrestaShop: 8.0–9.x.

PHP: 8.0 або новіша версія. Модуль відмовляється встановлюватися на старіших версіях PHP.

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

Обліковий запис Helcim: обліковий запис мерчанта Helcim у Канаді або Сполучених Штатах і API-токен з правом обробки транзакцій (див. Налаштування). Helcim обробляє CAD та USD. Тестовий (розробницький) обліковий запис Helcim необов'язковий і потрібен лише для тестів.

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

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

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

2. Коли завантаження завершиться, натисніть Configure або пізніше знайдіть VibeFox Helcim Gateway у списку модулів і натисніть Configure.

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

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 і сплатіть з тестового облікового запису; потім вимкніть його.

Під час встановлення модуль створює два статуси замовлення: Helcim payment authorized та Helcim payment on hold. PrestaShop активує новий платіжний модуль для всіх валют, країн і груп клієнтів. Їх можна обмежити в Payment > Preferences.

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

Усі параметри розміщені на сторінці модуля: Modules > Module Manager > VibeFox Helcim Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо валюта за замовчуванням вашого магазину не входить до Account currencies, а також, поки спосіб оплати увімкнено, — якщо API-токен поточного режиму порожній. У такому разі спосіб оплати приховується на сторінці оформлення замовлення.

Helcim

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

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

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

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

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

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

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

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

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

Clear saved tokens: позначте токен і натисніть Save, щоб видалити його. Порожнє поле зберігає збережене значення.

Оплата

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

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

Додатково

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

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

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

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

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

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

Одна спроба оплати на кошик виконується одночасно, а кошик, у якого вже є замовлення, ніколи не списується повторно. Кожна спроба використовує ключ ідемпотентності. Якщо 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-токен відсутній або відхилений Helcim; 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., коли платіж схвалено, але замовлення не вдалося створити. Кошик зберігається. Технічні деталі записуються в журнал.

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

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

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

No order: картку відхилено, Helcim не відповів або покупець ще не сплатив. Існує лише кошик. Відмови та помилки записуються в журнал.

Payment accepted: покупку схвалено або попередню авторизацію захоплено. Платіж записується з ID транзакції Helcim, а примітка показує ID транзакції, код схвалення, тип картки, останні 4 цифри та режим.

Helcim payment authorized: попередню авторизацію схвалено. Кошти лише утримуються. Захопіть їх або зніміть утримання повним поверненням.

Helcim payment on hold: Helcim схвалив транзакцію, але сума, валюта або ID транзакції у його відповіді не збігаються з кошиком, наприклад після часткового схвалення або якщо кошик змінився під час оплати. У примітці зазначено Helcim response verification FAILED. Для покупки платіж записується з сумою, яку Helcim фактично списав. Перевірте транзакцію в Helcim, перш ніж виконувати замовлення.

Refunded: платіж повністю повернено через модуль.

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

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

Блок оплати Helcim

На сторінці замовлення показано блок Helcim payment з ID транзакції (а після захоплення — і з ID попередньої авторизації), типом транзакції та станом захоплення, номером рахунку, карткою та кодом схвалення, схваленою сумою, сумою замовлення та сумою повернення, позначкою Test mode для тестових платежів, історією повернень і Helcim notes замовлення. Для захоплення та повернень потрібне право редагувати замовлення.

Захоплення

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

Повернення

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

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

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

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

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

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

Один ключ працює на одному домені: домені основного магазину, також у мультимагазинній конфігурації. Видалення ключа з магазину не звільняє слот його домену. Звільніть слот у своєму обліковому записі vibefox.net.

Без активного ключа Helcim не показується клієнтам на сторінці оформлення замовлення. Якщо оплату все одно розпочато, клієнт бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви увійшли до бек-офісу, тому спосіб оплати приховано і для вас: модуль можна налаштувати до купівлі ключа, але протестувати його на сторінці оформлення замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: вже здійснені платежі зберігаються, а захоплення та повернення продовжують працювати.

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

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

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

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

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

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

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

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

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

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

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

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Helcim Gateway і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete data on uninstall увімкнено, налаштування шлюзу та журнал видаляються. Якщо вимкнено, всі налаштування зберігаються для подальшого повторного встановлення. Транзакції та повернення Helcim, а також статуси замовлень Helcim payment authorized і Helcim payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна захопити та повернути після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату та ID транзакцій.

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