VibeFox Culqi for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

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

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

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

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

Установка

Скачиваемый архив — это один zip-файл с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_culqi_payment-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_culqi_payment.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ одинаков для обеих версий.

OpenCart 3

1. В админ-панели перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_culqi_payment-oc3-(version).ocmod.zip. Расширение не содержит модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload из этого пакета в корневую папку вашего магазина.

2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Culqi Payment и нажмите Install (зелёная кнопка +). Вашему администратору нужно право на изменение списка платёжных расширений.

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

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

5. Включите Enable/Disable и нажмите Save. Пока вы тестируете, оставьте Test Mode включённым, а для приёма реальных платежей выключите его.

OpenCart 4

1. В админ-панели перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_culqi_payment.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите Install (зелёная кнопка +) рядом с ним.

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Culqi Payment, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и ключи Culqi, как в шагах 3–5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях.

Новая установка начинает работу с выключенным способом оплаты и включённым тестовым режимом.

Настройка

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

При сохранении неверное значение не сохраняется и остаётся предыдущим, а остальные поля сохраняются. Страница показывает ошибку для каждого такого поля: ключ с неверным префиксом (например, Live Secret Key must start with sk_live_ — the previous value was kept.), пустое поле Title или длиннее 128 символов, Sort Order, который не является целым числом, Total, который не является числом 0 или больше, а также геозона или статус заказа, которых не существует.

Culqi

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

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

Description: текст, который покупатель видит на шаге Confirm Order, над кнопкой подтверждения. По умолчанию: Pay securely with your credit/debit card or Yape via Culqi.

Sort Order: место Culqi среди способов оплаты на оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать Culqi только для адресов оплаты в выбранной геозоне. По умолчанию: All zones. Геозоны настраиваются в разделе System > Localisation > Geo Zones.

Total: сумма заказа в валюте магазина по умолчанию, которую заказ должен достичь, прежде чем будет предложен Culqi. Оставьте поле пустым, чтобы предлагать Culqi при любой сумме.

API-ключи

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

Test Mode: когда включён, используются тестовые ключи (pk_test_ / sk_test_), и реальные деньги не списываются. По умолчанию: включено. Выключите, чтобы принимать реальные платежи рабочими ключами. Пока режим включён, покупатели видят на шаге Confirm Order надпись 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 the saved key on save под полем и нажмите Save.

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

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

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

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (пропавший заказ). Заказ получает статус только после того, как Culqi подтвердит списание. Каждое из полей ниже перечисляет статусы заказов вашего OpenCart.

Order Status After Payment: Culqi подтвердил списание, и его сумма и валюта совпадают с заказом. По умолчанию: Processing.

On Hold (Review) Status: Culqi списал сумму или валюту, которые не совпадают с заказом, либо не выполнил захват платежа. Примечание объясняет, что нужно проверить в CulqiPanel. По умолчанию: Pending, так как в OpenCart нет статуса On hold. Вы можете создать собственный статус в разделе System > Localisation > Order Statuses и выбрать его здесь.

Refunded Status: платёж полностью возвращён со страницы заказа. Частичные возвраты только добавляют примечание. По умолчанию: Refunded.

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

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

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

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

Импорт / Экспорт

Export: Download JSON сохраняет настройки в файл JSON. Секретные ключи не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые секретные ключи сохраняются.

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Credit/Debit Card or Yape (Culqi)). На шаге Confirm Order покупатель видит ваше описание, и OpenCart создаёт заказ, пока без статуса. Когда покупатель нажимает Confirm Order, на той же странице открывается всплывающее окно Culqi Checkout с названием вашего магазина, суммой заказа и валютой. Там покупатель вводит данные карты или платит через Yape. Скрипты Culqi всегда загружаются с Culqi. На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order в блоке подтверждения внизу страницы оформления заказа. Если магазин не запрашивает адрес оплаты (поведение OpenCart 4 по умолчанию), данные покупателя, передаваемые вместе со списанием, берутся из адреса доставки и имени покупателя.

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

Если банк требует 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, ничего не списывается, и кнопку Confirm Order можно нажать снова. Корзина во всех этих случаях сохраняется.

Заказ никогда не списывается дважды. Если покупатель отправляет форму повторно, пока выполняется платёж по тому же заказу, он видит 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. Списание сохраняется, и следующая попытка с той же корзиной устанавливает статус заказа по нему без нового списания. Корзина оплачивается только один раз: если другой заказ с той же корзиной (OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order) уже оплачен, покупатель попадает на страницу успеха и повторно не списывается. OpenCart 4 оставляет один заказ на оформление и обновляет его, поэтому после отказа карты покупатель оплачивает тот же заказ.

OpenCart 4 хранит заказ в оформлении до показа страницы успеха. Если этот заказ был закрыт магазином (например, отменён или возвращён) либо уже оплачен, а корзина с тех пор изменилась (другие товары или количество), Confirm Order возвращает покупателя на оформление заказа, которое создаёт новый заказ корзины с собственным платежом. Заказ, который был оплачен и затем закрыт, больше не удерживает корзину.

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

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

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

No status (missing order): покупатель ещё не оплатил, карта была отклонена или Culqi не ответил. В разделе Sales > Orders такие заказы показываются только с фильтром Order Status, установленным на Missing Orders. Примечания в истории заказа объясняют неудачные попытки.

Order Status After Payment (default Processing): списание подтверждено и соответствует заказу. Примечание показывает Culqi payment successful с режимом (тестовый или рабочий), 3-D Secure, если он использовался, и ID списания Culqi (chr_...).

On Hold (Review) Status (default Pending): Culqi сообщил о списании, сумма или валюта которого не совпадает с заказом, либо о платеже, который авторизован, но не захвачен. Примечание объясняет это и показывает ID списания. Проверьте списание в CulqiPanel, затем выполните заказ или сделайте возврат платежа.

Refunded Status (default Refunded): платёж полностью возвращён через расширение.

Примечания — это записи в History заказа, которые покупатель не видит.

Вкладка VibeFox Culqi Payment

В разделе Sales > Orders откройте заказ, оплаченный через Culqi. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Culqi Payment показывает Charge ID с меткой Test для тестовых платежей, списанную Amount (с 3-D Secure, если он использовался), подсказку Review для заказов на проверке, суммы Paid / refunded, форму возврата, историю возвратов и Culqi notes заказа. Вкладка показывается пользователям, которые имеют доступ к расширению.

Возвраты

На вкладке VibeFox Culqi Payment введите Amount (подставляется сумма, которая ещё не возвращена), при желании Reason (optional) и нажмите Refund via Culqi. Подтвердите вопрос Refund this amount through Culqi? This cannot be undone. Поддерживаются полные и частичные возвраты. Вам нужно право на изменение расширения (задаётся в разделе System > Users > User Groups). Возвраты выполняются в той сумме и валюте, которые списал Culqi, поэтому при расхождении суммы можно вернуть не больше того, что покупатель реально заплатил, а не сумму заказа. Возврат отправляется с ключами того режима, в котором была совершена оплата (тестового или рабочего), даже если вы с тех пор переключили режим, поэтому секретный ключ этого режима должен быть задан. Если Culqi не принимает возврат, вкладка показывает ошибку, и возврат не фиксируется. Успешный возврат добавляется в историю возвратов и примечания с ID возврата Culqi, суммой и вашей причиной. Полный возврат переводит заказ в Refunded Status без уведомления покупателя и без возврата товаров на склад, как и ручная смена статуса. Частичный возврат статус не меняет.

Возвраты товаров в разделе Sales > Returns не возвращают деньги через Culqi. Возвраты, сделанные в CulqiPanel, не синхронизируются с OpenCart. При необходимости обновите заказ вручную.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Culqi Payment — это первый блок в разделе Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в маскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен), а также кнопки Check now, чтобы повторно проверить статус, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: opencart-payment-culqi и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменять ключ могут только администраторы с правом Modify на расширение. Тексты блока следуют языку административной панели (включены английский и русский).

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

Один ключ работает на одном домене: адрес магазина из настроек OpenCart. Удаление ключа из магазина не освобождает место для домена. Освободите его в своём аккаунте на vibefox.net.

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

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

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

Culqi не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён, заполнены оба ключа текущего режима (Test Public Key и Test Secret Key в тестовом режиме, Live Public Key и Live Secret Key в рабочем) и что покупатель платит в PEN или USD. Страница настроек показывает предупреждение, если ключи не заполнены. Также проверьте, что адрес оплаты входит в выбранную Geo Zone, и что сумма заказа достигает значения Total в настройках.

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

Заказ после оплаты находится в статусе проверки: прочитайте примечания на вкладке VibeFox Culqi Payment. Списанная сумма или валюта отличались от заказа, либо платёж не был захвачен. Проверьте списание в CulqiPanel, затем выполните заказ или сделайте возврат платежа.

Ключ не сохраняется: ошибка говорит, что поле должно начинаться с префикса, например 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 payment method is not available.: в сессии оформления больше нет заказа Culqi, либо способ оплаты тем временем был выключен. Покупатель перезагружает оформление заказа.

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

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

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

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Culqi Payment. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов в разделе Orders, которые при повторной установке возвращаются к значениям по умолчанию. Если включено Delete data on uninstall, удаляются остальные настройки шлюза (название, описание, тестовый режим, ключи, Yape, логирование) и журнал. Если выключено, они сохраняются для последующей повторной установки. Списания и возвраты Culqi всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои платёжные примечания.

На OpenCart 4, чтобы удалить также файлы расширения, после удаления перейдите в Extensions > Installer, нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Culqi Payment в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

Culqi — товарный знак его правообладателя. Это расширение не связано с Culqi и не одобрено компанией Culqi.