VibeFox Conekta for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Валюта: валюта корзины должна быть MXN или USD. Для других валют способ оплаты скрывается.

Учётная запись Conekta: нужны приватные API-ключи вашей учётной записи Conekta (тестовый и рабочий) и вебхук в панели Conekta (см. раздел Конфигурация). Используются только приватные ключи. Публичный ключ не нужен, потому что оплата проходит на платёжной странице Conekta.

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

Установка

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

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

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

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

5. Включите Enable / Disable и нажмите Save. Проверьте оплату в тестовом режиме, затем выключите Test mode.

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

Конфигурация

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

Conekta

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

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

Description: текст, который отображается под способом оплаты на оформлении заказа. По умолчанию: Pay securely with card, OXXO cash or SPEI transfer. You will be redirected to Conekta to complete your payment.

Payment methods: способы, которые предлагаются на платёжной странице Conekta. По умолчанию: card, cash and bank transfer. Наличные, SPEI и BNPL доступны только для заказов в MXN (заказы в USD принимают только карты) и должны быть включены в вашей учётной записи Conekta. Если ничего не выбрано, используется карта, и страница предупреждает об этом при сохранении.

API-ключи

Скопируйте приватные ключи из панели Conekta в разделе Developers > API keys. Тестовые и рабочие ключи различаются.

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

Test private key: приватный API-ключ тестового режима вашей учётной записи Conekta.

Live private key: приватный API-ключ рабочего режима вашей учётной записи Conekta. Храните его в секрете.

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

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

Каждый заказ Conekta запоминает свой режим: уведомления и возвраты используют соответствующий ключ. Держите оба ключа заполненными, пока открыты старые тестовые заказы.

Webhook

Вебхук сообщает вашему магазину о платежах, например об оплатах OXXO или SPEI, совершённых после того, как покупатель покинул страницу Conekta. В панели Conekta перейдите в Developers > Webhooks и добавьте URL, который показан в поле Webhook раздела API keys, — отдельно для тестового и для рабочего режима. При включённых понятных URL он выглядит так: https://your-shop/module/wcp_conekta_gateway/webhook, возможно, с кодом языка, например /en/. Копируйте URL точно так, как он показан в настройках.

Выберите эти события (они также перечислены в настройках):

Тело вебхука лишь сообщает модулю, какой заказ Conekta изменился. Каждое уведомление проверяется повторным чтением заказа через API Conekta с приватным ключом его режима; заголовок подписи Digest вебхука не используется. Уведомления о заказах Conekta, которые не были созданы этим магазином для этой корзины, подтверждаются и игнорируются. Без вебхука заказ создаётся только тогда, когда покупатель возвращается в магазин после оплаты, или при следующей попытке оплаты той же корзины.

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

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

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

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

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Conekta) и подтверждает выбор. Модуль создаёт заказ Conekta на сумму корзины в валюте корзины, с товарами, подарочной упаковкой, скидками, налогом и доставкой, и отправляет покупателя на платёжную страницу Conekta. На странице Conekta платёж отображается как Order # и номер корзины. Там покупатель платит одним из разрешённых способов. На этом этапе заказа ещё не существует.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Conekta: модуль читает заказ через API Conekta, когда приходит вебхук, и когда покупатель возвращается. Тогда заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с сообщением Мы получили вашу оплату через Conekta. Если покупатель выбрал OXXO или SPEI и получил платёжный референс, заказ создаётся в статусе Awaiting Conekta payment, а страница показывает Ваш платёжный референс Conekta выдан. Заказ будет подтверждён, как только поступит оплата. Если референс позже истечёт, заказ отменяется, а на его странице подтверждения появляется сообщение Ваша оплата через Conekta не завершена. Пожалуйста, свяжитесь с нами по поводу этого заказа.

Если оплату ещё нельзя подтвердить, когда покупатель возвращается, появляется страница Подтверждение оплаты с текстом Мы подтверждаем вашу оплату через Conekta. Заказ будет обновлён автоматически — пожалуйста, не оплачивайте повторно. и кнопка Check again. Вебхук создаёт заказ, как только получает уведомление.

Если платёж отклонён, заказ не создаётся, а покупатель возвращается на оформление заказа с сообщением Платёж через Conekta не завершён. Попробуйте ещё раз или выберите другой способ оплаты. Если срок оплаты истёк или она была отменена, появляется сообщение Срок платежа через Conekta истёк или платёж отменён. Попробуйте ещё раз. Корзина сохраняется. Когда покупатель платит снова, открытая платёжная страница Conekta на ту же сумму используется повторно; в противном случае предыдущая отменяется в Conekta до создания новой, поэтому старая ссылка не может быть оплачена дважды. Если предыдущая страница уже была оплачена, создаётся заказ, а повторного списания не происходит.

Если Conekta не может начать оплату, покупатель остаётся на оформлении заказа с коротким сообщением, например Не удалось начать оплату. Попробуйте ещё раз через минуту или выберите другой способ оплаты. Сообщения проверки от Conekta, например о минимальной сумме, показываются так, как их присылает Conekta. Техническая причина записывается в журнал.

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

Модуль принимает платежи только на странице Conekta. На странице оформления заказа нет формы карты, нет сохранённых карт, подписок, предавторизации и списания, а также помесячной рассрочки (MSI).

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

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

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

Payment accepted: Conekta подтвердила платёж с той же суммой и валютой. Платёж записывается с идентификатором списания Conekta в качестве ID транзакции, а примечание показывает способ оплаты (например, марку карты и последние четыре цифры, OXXO / наличные или банковский перевод SPEI), заказ Conekta и списание.

Awaiting Conekta payment: покупатель получил платёжный референс OXXO или SPEI. Заказ переходит в Payment accepted, когда Conekta сообщает о платеже.

Conekta payment on hold: сумма или валюта, полученные от Conekta, не совпадают с корзиной (например, корзина была изменена после начала оплаты), платёж в тестовом режиме поступил, пока магазин работал в рабочем режиме (реальные деньги не получены), или платёж поступил по уже отменённому заказу. Примечание объясняет причину, а платёж записывается с фактически оплаченной суммой. Проверьте заказ, затем выполните его или верните платёж. Заказ, который в Conekta только предавторизован, также переводится на удержание, с примечанием списать или отменить его в панели Conekta.

Canceled: истёк срок референса OXXO или SPEI ожидающего заказа либо его заказ Conekta был отменён.

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

Оплаченный или возвращённый заказ никогда не понижается в статусе и не открывается повторно. Если на уже оплаченный заказ поступает ещё один платёж Conekta, примечание WARNING просит вас вернуть его в панели Conekta.

Блок платежа Conekta

На странице заказа показан блок Conekta payment с заказом Conekta, списанием, статусом платежа, оплаченной и возвращённой суммой, значком Test mode для тестовых платежей, историей возвратов и Conekta notes заказа.

Возвраты

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

Модуль не создаёт кредитные чеки. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Conekta.

Возвраты, оформленные в панели Conekta, приходят через вебхук и добавляются как примечание с суммой, возвращённой в Conekta и в PrestaShop. Они не регистрируются автоматически. Обновите заказ вручную, не используя Refund via Conekta. Чарджбэк, о котором сообщила Conekta, также добавляется как примечание.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Conekta Gateway — это первый блок на странице Modules > Module Manager > VibeFox Conekta Gateway > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен), а также кнопки Check now, чтобы снова проверить статус, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: presta-payment-conekta и ссылка «Управление лицензиями и доменами в вашем аккаунте», которая открывает ваш аккаунт vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока соответствуют языку бэк-офиса (включены английский и русский).

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

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

Без активного ключа Conekta не показывается покупателям на оформлении заказа. Если платёж всё же начат, покупатель видит Этот способ оплаты недоступен. Выберите другой. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому способ оплаты скрывается и для вас: вы можете настроить модуль до покупки ключа, но не можете проверить его на оформлении заказа. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, и возвраты работают.

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

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

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

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

Вебхук отвечает Temporarily unavailable: не удалось связаться с API Conekta, отсутствует приватный ключ режима заказа, корзину в этот момент обрабатывал другой запрос, или заказ не удалось создать (например, модуль отключён). Conekta повторяет вебхук. Причину смотрите в поле Log.

Вебхук отвечает Verification failed, Invalid payload или Invalid order id: API Conekta не подтвердил заказ, либо уведомление не было допустимым событием заказа Conekta.

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

URL вебхука в браузере показывает Method not allowed: это нормально. URL принимает только запросы от Conekta.

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

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

Покупатель видит Проверка платежа не пройдена: ссылка возврата от Conekta не совпала с корзиной. Проверьте заказ в панели Conekta; вебхук по-прежнему подтверждает реальный платёж.

Заказ в статусе Awaiting Conekta payment или Conekta payment on hold: прочитайте Conekta notes в блоке заказа. Покупатель ещё не оплатил референс OXXO или SPEI, сумма или валюта не совпали, платёж в тестовом режиме поступил, пока магазин работал в рабочем режиме, либо платёж только предавторизован.

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

Для разработчиков README перечисляет хуки actionWcpConektaSupportedCurrencies, actionWcpConektaOrderRequest, actionWcpConektaAllowedPaymentMethods и actionWcpConektaRefundReason.

Удаление

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

Conekta — товарный знак её владельца. Этот модуль не аффилирован с Conekta и не одобрен ею.