VibeFox Culqi for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Валюта магазина: перуанский соль (PEN) или доллар США (USD). Culqi не принимает другие валюты, а способ оплаты показывается только для корзин в PEN или USD.

Учётная запись Culqi: нужны публичный и секретный ключи вашей учётной записи Culqi. Тестовые (интеграционные) ключи берутся на integ-panel.culqi.com, рабочие (live) ключи — на mipanel.culqi.com, в разделе CulqiPanel > Desarrollo > API Keys. Публичный ключ используется всплывающим окном Culqi в браузере. Секретный ключ используется только на вашем сервере и никогда не передаётся в браузер. Вебхук не нужен.

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

Установка

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

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

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

4. Вставьте ключи интеграции и, для реальных платежей, рабочие ключи (см. раздел «Настройка»).

5. Включите Enable/Disable и нажмите Save. Оставьте Test Mode включённым во время проверки, затем выключите его, чтобы принимать реальные платежи.

6. Убедитесь, что PEN или USD — активная валюта вашего магазина.

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Culqi Payment > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает Test mode is active: the integration keys are used and no real money is charged., пока включён тестовый режим. Она предупреждает, если шлюз включён, но ключи текущего режима не заполнены, и если ни одна валюта магазина не поддерживается Culqi. В обоих случаях способ оплаты скрывается на оформлении заказа. Если валюта по умолчанию не PEN и не USD, страница сообщает, что Culqi предлагается только для корзин в поддерживаемых валютах.

Culqi

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

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

Description: текст под способом оплаты на странице оформления заказа. По умолчанию: Pay securely with your credit/debit card or Yape via Culqi.

API-ключи

Скопируйте ключи из CulqiPanel > Desarrollo > API Keys: ключи интеграции (тестовые) — на integ-panel.culqi.com, рабочие ключи — на mipanel.culqi.com. Тестовый режим использует только тестовые ключи, рабочий — только рабочие. Каждый ключ должен начинаться с префикса своего поля. Ключ с неверным префиксом не сохраняется: страница показывает ошибку, например Live Secret Key must start with sk_live_ — the previous value was kept., а остальные поля сохраняются.

Test Mode: когда включён, используются тестовые ключи (pk_test_ / sk_test_) и реальные деньги не списываются. По умолчанию: включено. Выключите, чтобы принимать реальные платежи рабочими ключами. Пока режим включён, покупатели видят под способом оплаты TEST MODE: No real charges will be made.

Test Public Key: публичный ключ интеграционной среды. Начинается с pk_test_.

Test Secret Key: секретный ключ интеграционной среды. Начинается с sk_test_ и никогда не передаётся в браузер.

Live Public Key: публичный ключ рабочей среды. Начинается с pk_live_.

Live Secret Key: секретный ключ рабочей среды. Начинается с sk_live_ и никогда не передаётся в браузер.

Сохранённые секретные ключи больше не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Введите новое значение, только если хотите его изменить.

Clear saved secret keys: отметьте Test Secret Key или Live Secret Key и нажмите Save, чтобы удалить ключ. Пустое поле сохраняет сохранённое значение.

Способы оплаты

Карты предлагаются всегда. Банковский перевод, агенты, кошельки и Cuotéalo требуют Culqi Orders API и этим модулем не предлагаются.

Yape: Offer Yape in the Culqi popup показывает Yape рядом с картами в окне Culqi. По умолчанию: включено.

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

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

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

Delete Data on Uninstall: когда включено, при удалении модуля удаляются настройки шлюза, записи о списаниях и возвратах Culqi этого модуля и журнал. Статус заказа и данные Culqi по заказам (платежи, примечания) всегда сохраняются. По умолчанию: выключено.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Credit/Debit Card or Yape (Culqi)) и нажимает кнопку оформления заказа. Всплывающее окно Culqi Checkout открывается на той же странице и показывает название вашего магазина, сумму корзины и валюту. Там покупатель вводит данные карты или платит через Yape. Скрипты Culqi загружаются только на странице оформления заказа.

Culqi преобразует платёжные данные в одноразовый токен, который отправляется в ваш магазин. Ваш сервер создаёт списание через Culqi Charges API на сумму корзины в валюте корзины, с немедленным списанием. Списание отображается в CulqiPanel как Cart и номер корзины, с e-mail покупателя. До этого момента заказа не существует. Заказ отмечается оплаченным только после подтверждения Culqi: заказ создаётся, когда Culqi отвечает об успешном списании, и покупатель видит стандартную страницу подтверждения заказа.

Если банк требует 3-D Secure, покупатель видит Your bank requires additional verification (3-D Secure). Please complete it in the window that opens. После аутентификации списание автоматически отправляется повторно. Если проверка не пройдена, покупатель видит The 3-D Secure verification was not completed. Please try again or use another card.

Если карта отклонена, покупатель видит сообщение от Culqi, например Payment failed: и причину, и может попробовать другую карту. Если Culqi не отвечает, покупатель видит We could not confirm your payment with Culqi. Please check your email or contact us before trying again. Если покупатель закрывает окно Culqi, ничего не списывается, и он видит The payment window was closed before the payment was completed. Оформить заказ он может снова. Корзина во всех этих случаях сохраняется. Неудачные попытки записываются в журнал модуля, так как заказа ещё нет.

По одной корзине деньги никогда не списываются дважды. Если покупатель отправляет форму повторно, пока выполняется платёж по этой же корзине, он видит This order is already being paid. Please wait a moment and check your email before trying again. Если Culqi списал деньги, но заказ создать не удалось, покупатель видит Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. Списание сохраняется, и следующая попытка создаёт заказ на его основе без повторного списания.

Модуль принимает только разовые платежи картой и через Yape, с немедленным списанием. В нём нет кодов PagoEfectivo и CIP, банковского приложения, агентов, кошельков и Cuotéalo, нет сохранённых карт, подписок и платежей в рассрочку, нет вебхуков Culqi и нет раздельной авторизации и списания.

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

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

No order yet: карта отклонена, покупатель закрыл окно Culqi или Culqi не ответил. Существует только корзина. Подробности в журнале модуля.

Payment accepted: списание подтверждено и совпадает с корзиной. Платёж записывается с ID списания Culqi (chr_...) в качестве ID транзакции, а примечание показывает режим (тестовый или рабочий) и то, использовался ли 3-D Secure.

Culqi payment on hold: Culqi сообщил о списании, сумма или валюта которого не совпадает с корзиной, либо о платеже, который авторизован, но не списан. Примечание объясняет это и показывает ID списания. Списание, выполненное в валюте корзины, записывается как платёж на фактически списанную сумму. Проверьте списание в CulqiPanel, затем выполните заказ или сделайте возврат платежа.

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

Если для корзины, которая уже имеет заказ, приходит второе списание, заказ не меняется. Примечание просит проверить списание в CulqiPanel и при необходимости вернуть деньги.

Блок оплаты Culqi

На странице заказа есть блок Culqi payment с ID списания, списанной суммой (с 3-D Secure, если он использовался), значком Test для тестовых платежей, подсказкой о проверке для заказов на удержании, суммами оплаты и возвратов, а также историей возвратов.

Возвраты

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

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

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

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

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

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

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

Culqi не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён, заполнены оба ключа текущего режима (Test Public Key и Test Secret Key в тестовом режиме, Live Public Key и Live Secret Key в рабочем) и валюта корзины — PEN или USD. Страница настроек показывает предупреждение, если ключи не заполнены. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: модуль не использует вебхуки. Списание подтверждается только ответом Culqi вашему серверу. Если Culqi не ответил вовремя, в журнале модуля будет Culqi did not confirm the charge с номером корзины. Найдите списание по этому cart_id в CulqiPanel. Если покупатель видел сообщение, что заказ не удалось оформить, следующая попытка оплаты той же корзины создаст заказ без повторного списания.

После оплаты заказ в статусе Culqi payment on hold: прочитайте примечание в заказе. Списанные сумма или валюта отличались от корзины, либо платёж не был списан. Проверьте списание в CulqiPanel (его ID указан в примечании), затем выполните заказ или сделайте возврат платежа.

Ключ не сохраняется: ошибка говорит, что поле должно начинаться с префикса, например sk_live_. Каждое поле принимает только ключи своего типа и режима: pk_test_, sk_test_, pk_live_ или sk_live_.

Покупатель видит Payment gateway misconfiguration. Please contact the store owner.: ключи текущего режима не заполнены либо Culqi отклонил секретный ключ. Проверьте ключи в настройках.

Покупатель видит Payment token is invalid. Please try again.: токен из окна Culqi относится к другому режиму, например после переключения Test Mode при открытой странице оформления заказа. Покупатель должен перезагрузить страницу и оплатить снова.

Окно Culqi не открывается: покупатель видит The Culqi payment window could not be loaded. Please reload the page and try again. Проверьте, что скрипты с js.culqi.com и 3ds.culqi.com не блокируются на странице оформления заказа, например кэширующим или оптимизирующим модулем.

Покупатель видит Security check failed. Please reload the page and try again.: страница оформления заказа была открыта слишком долго или в другой сессии. Перезагрузка страницы исправляет это.

Покупатель видит This order is already being paid: в тот же момент выполнялся другой запрос на оплату той же корзины. Покупателю следует подождать и проверить e-mail, прежде чем пробовать снова.

Карта была отклонена, и нужна причина: посмотрите поле Log на странице модуля. Отказы записываются с кодом отказа Culqi, даже когда Debug log выключен.

Возврат не проходит с сообщением о ключах: платёж был проведён в тестовом или рабочем режиме, а секретный ключ этого режима не задан. Введите его и повторите попытку.

Удаление

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

Culqi — товарный знак его владельца. Модуль не связан с Culqi и не одобрен Culqi.