VibeFox Cardcom for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

HTTPS: ваш магазин должен быть доступен из интернета по HTTPS, чтобы Cardcom мог отправить уведомление об оплате.

Валюта: валюта корзины должна быть ILS, USD, EUR или GBP. Для любой другой валюты способ оплаты скрыт при оформлении заказа.

Учётная запись Cardcom: для реальных платежей нужна учётная запись мерчанта Cardcom с номером терминала, именем пользователя API и паролем API. Для платежей нужны только номер терминала и имя пользователя API. Пароль API используется только для возвратов из PrestaShop. Тестовый режим работает без учётной записи Cardcom.

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

Установка

1. В админ-панели перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Cardcom Payment Gateway в списке модулей и нажмите Configure.

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

4. Включите Enable/Disable, оставьте Test Mode включённым и нажмите Save. Оформите тестовый заказ картой 4580 0000 0000 0000, с любым будущим сроком действия и CVV 123.

5. Для реальных платежей выключите Test Mode, введите Terminal Number, API Username и API Password, полученные от Cardcom, и нажмите Save.

При установке модуль создаёт статус заказа Cardcom payment on hold. PrestaShop предлагает новый модуль оплаты для всех валют, стран и групп покупателей. Ограничить их можно в разделе Payment > Preferences.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Cardcom Payment Gateway > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Над полями страница показывает предупреждение, пока включён тестовый режим. В рабочем режиме она предупреждает, если не заполнены номер терминала или имя пользователя API (тогда Cardcom скрыт при оформлении заказа), если в полях рабочего режима стоят публичный тестовый терминал 1000 / CardTest1994 (тогда Cardcom тоже скрыт, потому что реальные деньги не списывались бы), и напоминает, что без пароля API возвраты из PrestaShop невозможны. Также предупреждается, если валюта по умолчанию вашего магазина не поддерживается. При сохранении рабочего режима с пустыми или тестовыми учётными данными появляется сообщение об ошибке: шлюз остаётся скрытым при оформлении заказа, пока вы не введёте собственные номер терминала и имя пользователя API.

Cardcom

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

Title: название способа оплаты, которое видит покупатель при оформлении заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: Credit Card (Cardcom). Обязательное поле.

Description: текст, который отображается под способом оплаты при оформлении заказа. По умолчанию: Pay securely with your credit card via Cardcom.

Тестовый режим

Тестовый режим использует публичный тестовый терминал Cardcom 1000 (пользователь API CardTest1994). Реальные деньги не списываются, учётная запись Cardcom не нужна. Тестовая карта: 4580 0000 0000 0000, любой будущий срок действия, CVV 123. В тестовом режиме при оформлении заказа также показывается строка с этой тестовой картой.

Test Mode: включает тестовый режим (терминал 1000, реальные деньги не списываются). По умолчанию: включено. Выключите его, чтобы принимать реальные платежи с рабочими учётными данными ниже. Возвраты всегда отправляются с учётными данными того режима, в котором был оплачен заказ.

Рабочие учётные данные

Номер терминала, имя пользователя API и пароль API предоставляет Cardcom вместе с вашей учётной записью мерчанта: в личном кабинете Cardcom в разделе настроек API или через службу поддержки Cardcom. Эти поля используются только в рабочем режиме.

Terminal Number: ваш номер терминала Cardcom. Он должен содержать только цифры. Если введено что-либо другое, появляется ошибка и сохраняется предыдущее значение.

API Username: ваше имя пользователя API Cardcom (ApiName) для этого терминала. При сохранении пробелы удаляются.

API Password: ваш пароль API Cardcom. Он нужен только для возвратов из PrestaShop. Сохранённый пароль больше не отображается: поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Clear the saved API password: отметьте флажок и нажмите Save, чтобы удалить пароль. Пустое поле сохраняет сохранённое значение.

Платёжная страница

Notification URL: Cardcom отправляет уведомления об оплате (IndicatorUrl) на этот адрес. При включённых человекопонятных URL он выглядит так: https://your-shop/module/wcp_cardcom_payment_gateway/webhook, возможно, с кодом языка, например /en/. Адрес автоматически передаётся в Cardcom при каждом платеже вместе с идентификатором корзины, поэтому в Cardcom ничего настраивать не нужно. Он должен быть доступен из интернета по HTTPS.

Operation: что делает Cardcom на платёжной странице.

Max Installments: максимальное число платежей в рассрочку, которое покупатель может выбрать на странице Cardcom, от 1 до 36. 1 означает без рассрочки. По умолчанию: 1.

Success Order Status: статус заказа после подтверждённой оплаты. Заказ создаётся сразу в этом статусе.

Платежи, которые не соответствуют заказу, всегда переводятся в статус Cardcom payment on hold.

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

Debug log: записывает запросы к API и уведомления в logs/cardcom_p_debug.log.php в папке модуля. Файл нельзя открыть из браузера. Ошибки записываются всегда. Учётные данные, токены карт и данные держателя карты никогда не записываются. По умолчанию: выключено.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Delete on Uninstall: если включено, при удалении модуля настройки и журналы удаляются безвозвратно. Заказы, транзакции и возвраты Cardcom и статус заказа Cardcom payment on hold всегда сохраняются, поэтому старые заказы можно вернуть и после повторной установки. По умолчанию: выключено.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Credit Card (Cardcom)) и видит примечание You will be redirected to the secure Cardcom payment page. После подтверждения модуль создаёт платёжную страницу Cardcom на сумму корзины в валюте корзины и отправляет покупателя туда. На этом этапе заказа ещё нет. Страница открывается на иврите, если язык покупателя — иврит, в остальных случаях на английском. Товары из корзины передаются в Cardcom как название товара. Покупатель вводит данные карты и, если рассрочка разрешена, выбирает число платежей.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается как оплаченный только после подтверждения Cardcom. Cardcom вызывает адрес уведомлений, и модуль берёт из этого вызова только код платёжной страницы. Он проверяет, что этот код выдан вашим магазином для этой корзины, и затем запрашивает у Cardcom фактический результат с сервера на сервер. Если уведомление опаздывает, та же проверка выполняется, когда покупатель возвращается. Тогда заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с сообщением Your payment with Cardcom has been received. Если Cardcom ещё не подтвердил оплату, когда покупатель возвращается, страница Payment confirmation показывает сообщение Your payment is being confirmed by Cardcom. You will receive an e-mail as soon as it is confirmed. и кнопку Check again; уведомление создаёт заказ, как только придёт.

Если оплата не завершена или Cardcom её отклонил, покупатель возвращается к оформлению заказа и видит сообщение The card payment was not completed. Please try again or choose a different payment method. Заказ не создаётся, корзина сохраняется. Покупатель может повторить попытку: каждая попытка получает новую платёжную страницу Cardcom. Оплата, сделанная на более ранней платёжной странице той же корзины, по-прежнему распознаётся, а отказ на более ранней странице не влияет на новую попытку.

Если Cardcom не может открыть платёжную страницу, покупатель остаётся на оформлении заказа с коротким сообщением, например Could not connect to Cardcom. Please try again in a moment., или с сообщением о том, что Cardcom не смог открыть платёжную страницу, с кодом Cardcom, и может выбрать другой способ оплаты.

Уведомление работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по стране вашего магазина.

Модуль принимает оплату картами только на платёжной странице Cardcom. В нём нет сохранённых карт и платежей в один клик, подписок, он не списывает сохранённые токены, не имеет настроек счетов и чеков Cardcom, а также не поддерживает Bit, Apple Pay, Google Pay или PayPal через Cardcom, режим iframe и сделки с отложенным списанием.

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

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

No order yet: покупатель был отправлен в Cardcom и ещё не оплатил, оплата была отклонена или Cardcom ещё не подтвердил оплату. Существует только корзина.

Payment accepted, Delivered or Cardcom payment on hold: оплата подтверждена. Статус соответствует Success Order Status. Платёж записывается с номером операции (deal) Cardcom в качестве идентификатора транзакции. Внутреннее сообщение к заказу показывает транзакцию Cardcom и, если Cardcom их передаёт, последние четыре цифры карты, номер счёта и число платежей в рассрочку. Тестовые платежи отмечаются как Test mode — no real money was charged.

Cardcom payment on hold after payment: Cardcom подтвердил платёж, который не соответствует заказу, например корзина была изменена после открытия платёжной страницы или списана другая сумма или валюта. Сообщение объясняет это, а блок Cardcom показывает такой заказ в разделе Needs review. Платёж записывается на сумму, которую списал Cardcom, если валюта совпадает с валютой заказа. Сравните платёж в личном кабинете Cardcom с заказом, затем выполните заказ или сделайте возврат платежа.

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

Если поступает второй успешный платёж по корзине, для которой уже есть заказ (например, покупатель оплатил в двух вкладках браузера), заказ не меняется. Сообщение предупреждает, что покупатель мог быть списан дважды, и просит вас вернуть деньги в личном кабинете Cardcom.

Блок оплаты Cardcom

На странице заказа показан блок Cardcom payment с транзакцией, кодом платёжной страницы, статусом, картой, рассрочкой, счётом, токеном карты (при Charge + Save token), списанной суммой, суммой заказа и возвращённой суммой, значком Test mode для тестовых платежей и историей возвратов.

Возвраты

В блоке Cardcom payment введите сумму (по умолчанию подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via Cardcom. Подтвердите вопрос Refund this amount through Cardcom? This cannot be undone. Поддерживаются полные и частичные возвраты, и для одного заказа можно сделать несколько частичных возвратов. Нужно право редактировать заказы; доступ к страницам модулей не требуется. Возвраты делаются на ту сумму и в той валюте, которые списал Cardcom, поэтому после расхождения суммы или валюты можно вернуть не больше того, что покупатель фактически заплатил, а не сумму заказа. Возврат отправляется с учётными данными того режима, в котором был оплачен заказ: тестовые заказы возвращаются через тестовый терминал Cardcom даже после перехода в рабочий режим, а рабочие заказы всегда используют ваши рабочие учётные данные. Для рабочих возвратов нужны API Username и API Password. Если Cardcom не принимает возврат, блок показывает ошибку и возврат не регистрируется. Успешный возврат добавляется в историю возвратов и в сообщения заказа вместе с транзакцией возврата Cardcom и причиной. Полный возврат переводит заказ в статус Refunded. Частичный возврат статус не меняет.

Модуль не создаёт кредит-ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Cardcom. Возвраты, сделанные в личном кабинете Cardcom, в магазин не передаются.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Cardcom Payment Gateway является первым блоком на странице Modules > Module Manager > VibeFox Cardcom Payment Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия активна, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-cardcom и ссылка 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.

Без активного ключа Cardcom не показывается покупателям при оформлении заказа. Если оплата всё же начата, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в админ-панель, поэтому способ оплаты скрыт и для вас: настроить модуль можно до покупки ключа, но протестировать его при оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, и возвраты работают.

Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова, пока вы работаете в админ-панели: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

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

Cardcom не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и валюта корзины — ILS, USD, EUR или GBP. В рабочем режиме проверьте, что Terminal Number и API Username заполнены вашими собственными учётными данными, а не тестовым терминалом 1000 / CardTest1994. Страница настроек показывает предупреждение, если чего-то не хватает. В разделе Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Оплата прошла, но заказ не создан: Cardcom не смог связаться с вашим магазином, например из-за брандмауэра, защиты паролем или локального сайта для разработки. Адрес уведомлений должен быть доступен из интернета по HTTPS. Заказ также создаётся, когда покупатель возвращается в магазин после оплаты. Включите Debug log и посмотрите поле Log на странице модуля.

Уведомление отвечает Missing or invalid lowprofilecode or Unknown lowprofilecode for this order: вызов не содержал кода платёжной страницы, выданного вашим магазином для этой корзины. Ничего не меняется.

Уведомление отвечает Gateway not configured or Indicator check failed: отсутствуют учётные данные режима, в котором была создана платёжная страница, или Cardcom не удалось связаться для проверки. Ничего не меняется; платёж проверяется повторно, когда покупатель возвращается в магазин.

Уведомление отвечает Busy, retry: корзину в это же время подтверждал другой запрос, или заказ не удалось создать (например, модуль отключён). Включите Debug log, чтобы увидеть причину.

Уведомление отвечает ReturnValue mismatch or Terminal mismatch: Cardcom сообщил о платеже для другой корзины или другого терминала. Ничего не меняется. Проверьте, что Terminal Number — это терминал вашей учётной записи.

Покупатель видит Payment error: this currency is not supported by Cardcom.: валюта корзины — не ILS, USD, EUR или GBP.

Покупатель видит Card payment is temporarily unavailable. Please choose another payment method.: включён рабочий режим, но номер терминала или имя пользователя API не заполнены, либо в полях рабочего режима стоит публичный тестовый терминал.

Покупатель видит ошибку при выборе Cardcom: включите Debug log и посмотрите поле Log. Там записываются проблемы подключения и коды ошибок Cardcom.

Заказ в статусе Cardcom payment on hold after payment: прочитайте сообщение к заказу или раздел Needs review в блоке Cardcom payment. Оплаченная сумма или валюта отличались от заказа. Выполните заказ или сделайте возврат платежа.

Возврат не проходит с ошибкой API username and API password are required for refunds: введите API Password (и API Username) в настройках и повторите попытку.

Возврат не проходит с ошибкой Could not connect to Cardcom: перед повторной попыткой проверьте личный кабинет Cardcom, потому что возврат мог быть выполнен, а мог и не быть.

Для разработчиков в README описан хук actionCardcomSupportedCurrencies, который расширяет список валют (добавляйте только валюты, включённые на вашем терминале Cardcom), и actionCardcomLowProfileParams, который меняет параметры платёжной страницы.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Cardcom Payment Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete on Uninstall включено, настройки и журналы удаляются. Если выключено, все настройки сохраняются для последующей повторной установки. Транзакции и возвраты Cardcom и статус заказа Cardcom payment on hold всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои сообщения об оплате и идентификаторы транзакций.

Cardcom является торговой маркой своего владельца. Данный модуль не связан с Cardcom и не одобрен Cardcom.