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. В back office откройте 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, срок действия, токены, имена, адреса, адреса электронной почты и 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 для модуля. Тексты блока соответствуют языку back office (включены английский и русский).

Если ключ не принят, блок сообщает причину, например 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 не знает, что вы вошли в back office, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его при оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже совершённые платежи сохраняются, а списания и возвраты продолжают работать.

Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова, пока вы работаете в back office: раз в день в первые 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.