VibeFox ePayco for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Валюта: колумбийский песо (COP) или доллар США (USD). Для корзин в других валютах способ оплаты скрыт на этапе оформления заказа.

Учётная запись ePayco: нужны четыре ключа вашей учётной записи ePayco: P_CUST_ID_CLIENTE, P_KEY, PUBLIC_KEY и PRIVATE_KEY. Они находятся в панели ePayco в разделе Integrations, API keys. Одни и те же ключи работают в тестовом и рабочем режимах. Способы оплаты, которыми может пользоваться покупатель (карты, PSE, сети оплаты наличными, кошельки), — это способы, включённые в вашей учётной записи ePayco.

Публичный сайт: URL подтверждения вашего магазина должен быть доступен из интернета и не блокироваться брандмауэром или базовой аутентификацией.

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

Установка

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

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

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

4. Введите четыре ключа ePayco и выберите тип оформления (см. Настройки).

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

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

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox ePayco Payment > Configure. У каждого раздела своя кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если введены не все четыре ключа (тогда способ оплаты скрыт на этапе оформления заказа) и если валюта по умолчанию в вашем магазине не COP и не USD, а также показывает Test mode is on: customers pay with ePayco test cards and no real money is charged., пока включён тестовый режим.

ePayco

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

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

Description: текст под способом оплаты на этапе оформления заказа. По умолчанию: Pay securely with ePayco.

Ключи учётной записи ePayco

Четыре ключа находятся в панели ePayco в разделе Integrations, API keys. P_CUST_ID_CLIENTE и P_KEY проверяют подтверждения оплаты; PUBLIC_KEY и PRIVATE_KEY создают сессии оплаты. Одни и те же ключи работают в тестовом и рабочем режимах.

Customer ID (P_CUST_ID_CLIENTE): ваш идентификатор клиента ePayco (числовой).

Secret Key (P_KEY): используется для проверки подписи подтверждений оплаты ePayco. Храните в секрете.

Public Key (PUBLIC_KEY): ваш публичный ключ API ePayco.

Private Key (PRIVATE_KEY): ваш приватный ключ API ePayco. Храните в секрете.

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

Удаление сохранённых секретных ключей: отметьте Secret Key (P_KEY) или Private Key (PRIVATE_KEY) и нажмите Save, чтобы удалить ключ. Пустое поле сохраняет значение.

Test Mode: сессии оплаты создаются как тестовые транзакции. Покупатели платят тестовыми картами ePayco, реальные деньги не списываются. Тестовые транзакции никогда не оплачивают заказы, созданные в рабочем режиме. По умолчанию: выключено. Пока режим включён, покупатели видят под способом оплаты и на странице оплаты TEST MODE — use ePayco test cards, no real money is charged.

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

Checkout Type: как открывается платёжная форма ePayco.

URL подтверждения

URL подтверждения сообщает вашему магазину результат оплаты. Он автоматически передаётся в ePayco с каждым платежом, поэтому в панели ePayco ничего настраивать не нужно. В этом разделе показан URL. При ЧПУ-адресах он выглядит так: https://your-shop/module/wcp_epayco_payment/confirmation, возможно, с кодом языка, например /en/. Он должен быть доступен из интернета и не блокироваться брандмауэром или базовой аутентификацией. Он работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по стране вашего магазина.

Каждое подтверждение должно иметь корректную подпись, созданную с вашими P_CUST_ID_CLIENTE и P_KEY. Подтверждения без корректной подписи отклоняются и ничего не меняют. Без подтверждения заказ создаётся, только когда покупатель возвращается в магазин после оплаты.

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

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

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

Delete Data on Uninstall: если включено, при удалении модуля удаляются его настройки и журнал. Данные ePayco, сохранённые для заказов, и статусы заказов модуля всегда остаются, поэтому существующие заказы продолжают работать. По умолчанию: выключено.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию ePayco) и подтверждает выбор. Модуль создаёт сессию оплаты ePayco на сумму корзины в её валюте с налогами, номером корзины, а также именем плательщика, адресом, e-mail и телефоном. В ePayco платёж отображается как Cart # и номер корзины. Язык платёжной формы — испанский или английский, в зависимости от языка магазина. На этом этапе заказа ещё нет.

Затем покупатель видит страницу ePayco payment с сообщением Thank you for your order. The secure ePayco checkout opens automatically; if it does not, click the button below. Платёжная форма ePayco открывается всплывающим окном или перенаправлением — в зависимости от Checkout Type. На странице также есть кнопка Pay with ePayco и ссылка Choose another payment method. Каждое нажатие кнопки оплаты создаёт новую сессию ePayco.

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

При ожидающем платеже (например, PSE или наличные) заказ создаётся в статусе Awaiting ePayco payment, а страница подтверждения показывает Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved. Если ожидающий платёж позже отклоняется или истекает, страница показывает Your ePayco payment was not completed. Please contact us about this order. Если ePayco ещё не подтвердил платёж, когда покупатель возвращается, появляется страница Payment confirmation с сообщением We are waiting for ePayco to confirm your payment. This page does not need to stay open. и кнопкой Check again.

Если платёж был отклонён, покупатель возвращается к оформлению заказа с сообщением Your ePayco payment was declined or could not be completed. You can try again or choose another payment method. Если покупатель возвращается, не заплатив, сообщение такое: The ePayco payment was not completed. If you already paid, the order will be updated as soon as ePayco confirms it; otherwise you can try again. Корзина сохраняется, заказ не создаётся.

Если ePayco не может начать оплату, покупатель остаётся на этапе оформления заказа с коротким сообщением, например We could not connect to ePayco. Please try again in a moment or choose another payment method. Техническая причина записывается в журнал.

Модуль принимает только разовые платежи. Он не поддерживает возвраты из магазина, сохранённые карты, подписки и разделённые платежи и не опрашивает ePayco о ожидающих транзакциях: заказы обновляются по подтверждению ePayco и при возврате покупателя.

Заказы

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

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

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

Awaiting ePayco payment: ePayco сообщил о платеже как об ожидающем или удержанном, например перевод PSE или платёж наличными. Заказ изменится автоматически, когда ePayco одобрит или отклонит платёж.

ePayco payment on hold: ePayco одобрил платёж, сумма или валюта которого отличается от заказа (например, корзина была изменена после начала оплаты), или одобрил платёж после отмены заказа. Фактически оплаченная сумма записывается в заказ, если валюта совпадает. Не отправляйте товар, пока не проверите транзакцию в панели ePayco.

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

Refunded: ePayco отменил платёж по этому заказу.

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

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

На странице заказа есть блок ePayco payment с референсом ePayco (ref_payco), ID транзакции, статусом, способом оплаты, кодом авторизации, датой транзакции, плашкой Test mode для тестовых платежей и ePayco notes заказа. Для заказа в статусе ePayco payment on hold блок показывает предупреждение проверить транзакцию перед отправкой.

Возвраты

Возвраты из магазина не поддерживаются. Оформите возврат платежа в панели ePayco, а при необходимости обновите заказ в PrestaShop вручную. Отмена платёжной транзакции, о которой сообщает ePayco, переводит заказ в статус Refunded.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox ePayco Payment — это первый блок на странице Modules > Module Manager > VibeFox ePayco Payment > Configure, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-epayco и ссылка Manage licenses and domains in your account, которая открывает вашу учётную запись vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку back office (английский и русский включены).

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

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

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

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

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

ePayco не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён, введены все четыре ключа и валюта корзины COP или USD. Страница настроек показывает предупреждение, если ключи не заполнены. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Оплата прошла, но заказ не создан: подтверждение ePayco не доходит до вашего магазина. Проверьте, что URL подтверждения из настроек открывается из интернета и не блокируется брандмауэром, модулем безопасности или базовой аутентификацией. Посмотрите поле Log на странице модуля; включите Logging, чтобы видеть каждое подтверждение. Заказ также создаётся, когда покупатель возвращается в магазин после оплаты.

Подтверждение отвечает «Invalid signature»: Customer ID (P_CUST_ID_CLIENTE) или Secret Key (P_KEY) не совпадает с учётной записью ePayco, которая принимала платёж. Скопируйте оба заново из панели ePayco.

Подтверждение отвечает «Gateway not configured»: P_CUST_ID_CLIENTE или P_KEY пуст. Введите их в настройках.

Подтверждение отвечает «Order not found»: подтверждение относится к корзине без платежа ePayco этого магазина.

Подтверждение отвечает «Busy, retry later»: заказ в это же время обновлялся другим запросом, или заказ не удалось создать (например, модуль отключён). ePayco повторит подтверждение. Причина записана в журнал.

Покупатель видит «We could not connect to ePayco»: ePayco отклонил PUBLIC_KEY и PRIVATE_KEY. В журнале показан ответ ePayco. Скопируйте оба ключа заново.

Покупатель видит «ePayco could not start the payment»: ePayco не создал сессию оплаты. Прочитайте в журнале ошибку ePayco.

Платёжная форма ePayco не открывается: покупатель видит The ePayco checkout could not be loaded. Please reload the page or choose another payment method. Скрипт платёжной формы ePayco не загрузился на странице оплаты. Покупатель может перезагрузить страницу или использовать Choose another payment method.

Тестовый платёж не оплатил заказ: тестовые транзакции никогда не оплачивают заказы, оформленные в рабочем режиме. Оформляйте тестовый заказ, пока включён Test Mode.

Заказ в статусе ePayco payment on hold: прочитайте примечания в блоке ePayco payment (см. Статусы заказов) и проверьте транзакцию в панели ePayco перед отправкой.

Удаление

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

ePayco является товарным знаком своего владельца. Модуль не связан с компанией ePayco и не одобрен ею.