VibeFox Helcim for WooCommerce — Помощь

Требования

WordPress: 5.8 или новее.

WooCommerce: 7.0 или новее, установлен и активен. Без WooCommerce плагин не активируется.

PHP: 8.0 или новее.

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

Учётная запись Helcim: учётная запись мерчанта Helcim в Канаде или США и API-токен с правами обработки транзакций (см. Настройка). Helcim обрабатывает платежи в CAD и USD. Тестовая учётная запись Helcim (для разработчиков) необязательна и используется для тестирования.

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

Установка

1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Вы также можете загрузить папку wcp_helcim_gateway в директорию /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. В Helcim откройте All Tools > Integrations > API Access Configuration, создайте доступ к API с правами обработки транзакций (покупки, предварительные авторизации, списания, возвраты) и скопируйте его токен.

4. Откройте настройки: WooCommerce > Settings > Payments > Helcim > Manage или нажмите Settings под названием плагина на странице «Плагины».

5. Введите лицензионный ключ VibeFox в блок лицензии в верхней части страницы и нажмите Activate.

6. Вставьте токен в поле Live API token, а токен вашей тестовой учётной записи Helcim — в поле Test API token (при наличии).

7. Выберите Transaction type и Account currencies, включите Enable / Disable и сохраните изменения. Чтобы предварительно протестировать работу, включите Test mode и выполните платёж через тестовую учётную запись; затем выключите его.

Настройка

Все параметры собраны на одной странице: WooCommerce > Settings > Payments > Helcim. Над полями настроек появляется предупреждение, если валюта магазина не входит в список Account currencies, а также если при включённом шлюзе API-токен текущего режима не указан. В обоих случаях шлюз скрывается на странице оформления заказа. В списке способов оплаты шлюз помечается как требующий настройки, пока для текущего режима не задан токен.

Enable / Disable: Enable Helcim Gateway включает или отключает способ оплаты. По умолчанию: выключено.

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: Use the Test API token (Helcim test account). Платежи, списания и возвраты отправляются на вашу тестовую учётную запись Helcim, а покупатели видят уведомление о тестовом режиме. Возвраты и списания по заказу всегда используют токен того режима, в котором был оплачен заказ. По умолчанию: выключено.

Test API token: API-токен вашей тестовой учётной записи Helcim (для разработчиков). Используется, когда тестовый режим включён.

Оплата

Transaction type: способ списания средств с карты.

Account currencies: валюты, которые может обрабатывать ваша учётная запись Helcim. Платежи всегда списываются в валюте заказа. Для других валют способ оплаты скрывается при оформлении заказа.

Дополнительно

Debug log: Log API requests and responses в WooCommerce > Status > Logs, источник wcp_helcim_gateway. Номера карт сокращаются до последних 4 цифр. CVC, срок действия, токены, имена, адреса, e-mail и IP-адреса никогда не записываются в журнал. По умолчанию: выключено.

Delete data on uninstall: Remove the gateway settings, its own options (wc_hlg_*) and its log files when the plugin is deleted. По умолчанию: выключено.

Оформление заказа

Покупатель выбирает способ оплаты (по умолчанию Credit card (Helcim)) и вводит Card Number, Expiry (MM/YY), CVC и Cardholder Name на странице оформления заказа. Рядом с заголовком отображаются значки Visa, Mastercard, American Express и Discover. В тестовом режиме форма показывает сообщение TEST MODE — payments go to a Helcim test account, no real charges are made. Перед отправкой плагин проверяет контрольную сумму номера карты, корректность срока действия (не истёк ли он), наличие 3 или 4 цифр в поле CVC и заполненность имени держателя карты.

При размещении заказа ваш сервер отправляет данные карты в Helcim как покупку или предварительную авторизацию на общую сумму заказа в валюте заказа. Адрес плательщика, номер телефона и адрес электронной почты передаются для проверки адреса. Платёж отображается в Helcim с номером счёта, составленным из номера заказа и короткого кода. 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-токен отсутствует или отклонён; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. при повторной отправке формы. Технические подробности записываются в примечания к заказу и в журнал.

Способ оплаты работает на классическом оформлении заказа, в блоке «Оформление заказа» (с теми же полями карты) и на странице Pay for order. Он совместим с высокопроизводительным хранилищем заказов WooCommerce (HPOS).

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

Заказы и возвраты

Статусы заказа

Pending payment: платёж был отклонён или ещё не подтверждён. Если Helcim не ответил, в примечании к заказу рекомендуется проверить счёт в Helcim перед повторным списанием средств с покупателя.

Processing: покупка одобрена или предварительная авторизация списана. Заказы, содержащие только виртуальные загружаемые товары, переходят в статус «Выполнен» согласно стандартному поведению WooCommerce. В примечании к заказу отображаются идентификатор транзакции, код авторизации, тип карты, последние 4 цифры и режим. Идентификатором транзакции является ID транзакции Helcim.

On hold (pre-authorization): средства только удержаны. Спишите их с помощью действия с заказом или снимите удержание полным возвратом средств.

On hold after payment: Helcim одобрил транзакцию, однако сумма, валюта или идентификатор транзакции в его ответе не совпадают с заказом. В примечании указано Helcim response verification FAILED. Проверьте транзакцию в Helcim перед выполнением заказа.

Списание

Откройте заказ (статус «На удержании»), выберите действие с заказом Capture Helcim pre-authorization и нажмите Update. Списывается текущая итоговая сумма заказа за вычетом возвратов. Она может быть меньше авторизованной суммы, но не больше её. Для списания используется токен того режима, в котором был оплачен заказ. После успешного списания заказ переходит в статус «Обработка», а идентификатор транзакции меняется на ID транзакции списания. В случае сбоя списания причина отображается на экране и добавляется в примечания к заказу.

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Credit card (Helcim) (на кнопке отображается ваш Title). Поддерживаются полные и частичные возвраты по покупке или списанной предварительной авторизации. Несписанную предварительную авторизацию можно вернуть только полностью: при этом удержание снимается, и средства с покупателя не взимаются. Возврат отправляется в том режиме, в котором был оплачен заказ, поэтому токен этого режима должен быть настроен. Он учитывается только после подтверждения Helcim. Если Helcim отклоняет запрос, WooCommerce отображает ошибку, и возврат не фиксируется. Успешный возврат добавляется в примечания к заказу с идентификатором транзакции возврата Helcim. Повторная попытка после тайм-аута не приводит к двойному возврату.

Плагин не принимает вебхуки Helcim. Списания, возвраты и отмены, выполненные в панели управления Helcim, не отражаются в WooCommerce, поэтому выполняйте их непосредственно из WooCommerce.

Лицензионный ключ

Плагин работает с лицензионным ключом VibeFox от vibefox.net. Блок лицензии находится в верхней части страницы WooCommerce > Settings > Payments > Helcim. Вставьте ключ в поле License key и нажмите Activate. В блоке отобразится статус, например дата окончания действия лицензии и ваш домен. Используйте Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа с этого сайта. Ссылка Manage licenses and domains in your account открывает вашу учётную запись на vibefox.net.

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает слот домена. Освободите слот в вашей учётной записи на vibefox.net.

Без активного ключа способ оплаты Helcim не отображается покупателям при оформлении заказа. Если платёж всё же будет инициирован, покупатель увидит сообщение This payment method is not available. Please choose another one. Авторизованные менеджеры магазина по-прежнему видят способ оплаты с отметкой (unlicensed — visible to admins only), что позволяет настроить и протестировать плагин до покупки ключа. Напоминание отображается на странице «Плагины» и страницах WooCommerce. На существующие заказы это не влияет: списания и возвраты продолжают работать.

По истечении срока действия лицензии плагин продолжает работать, но для обновлений и технической поддержки требуется продление. Статус лицензии автоматически проверяется повторно в фоновом режиме.

Устранение неполадок

Helcim не отображается при оформлении заказа: убедитесь, что лицензия активна, опция Enable / Disable включена, для текущего режима задан API-токен (Live API token или Test API token в тестовом режиме), а валюта корзины входит в список Account currencies. На странице Pay for order учитывается валюта заказа. Страница настроек выводит предупреждение в обоих случаях.

Helcim не ответил, и заказ остался в статусе «В ожидании оплаты»: возможно, с карты были списаны средства. Ознакомьтесь с примечанием к заказу и проверьте счёт в Helcim перед повторным списанием с покупателя. Повторная попытка в течение 5 минут возвращает исходный результат и исключает повторное списание.

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

Оплата не удалась с указанием причины Helcim: Helcim отклонил запрос, например из-за данных карты или адреса плательщика. Подробности указаны в примечании к заказу.

Заказ находится в статусе «На удержании» после оплаты: прочтите примечание к заказу. По заказу выполнена предварительная авторизация и ожидается списание, либо ответ Helcim не совпал с заказом (проверка ответа не пройдена).

Списание невозможно: сумма списания должна быть больше 0 и не превышать авторизованную сумму, а токен того режима, в котором был оплачен заказ, должен быть задан.

Ошибка возврата средств: прочитайте сообщение. Несписанную предварительную авторизацию можно вернуть только полностью. Сообщение о режиме означает, что токен режима оплаты заказа не указан. Отклонённый возврат не фиксируется.

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

В блоке лицензии отображается ошибка: следуйте инструкциям в блоке. Например, если ключ уже используется на другом домене, освободите слот в учётной записи на vibefox.net и нажмите Check now. Если изменился адрес сайта, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать с последним известным статусом.

Для разработчиков: фильтр wc_hlg_supported_currencies изменяет список валют, а wc_hlg_card_brands изменяет значки карт при оформлении заказа.

Удаление

При деактивации плагина все данные сохраняются. Чтобы удалить его, деактивируйте и удалите плагин на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза, собственные опции плагина и файлы журналов удаляются только в том случае, если была включена опция Delete data on uninstall. В противном случае они сохраняются для повторной установки. Данные заказов являются частью истории заказов и никогда не удаляются. Существующие заказы сохраняют свои примечания об оплате и идентификаторы транзакций.

Helcim — товарный знак соответствующего правообладателя. Этот плагин не связан с Helcim и не одобрен ею.