VibeFox ePayco for OpenCart — Помощь

Требования

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

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

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

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

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

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

Установка

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

4. Введите лицензионный ключ, ключи ePayco и настройки, как в шагах 3–5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только URL подтверждения (см. URL подтверждения).

Новая установка начинает работу с выключенным способом оплаты и выключенным тестовым режимом. URL подтверждения передаётся в ePayco при каждом платеже, поэтому в панели ePayco ничего настраивать не нужно.

Настройка

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

При сохранении Title не должен превышать 128 символов, Sort Order должен быть целым числом, Total должен быть числом не меньше нуля, а геозона и статусы заказов должны существовать. В противном случае появляется ошибка с указанием поля, и ничего не сохраняется.

ePayco

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely with ePayco.

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

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

Total: сумма заказа в валюте магазина по умолчанию, которую заказ должен достичь, чтобы предлагался ePayco. Оставьте поле пустым, чтобы предлагать 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. Храните в тайне.

Сохранённые ключи Secret Key (P_KEY) и Private Key (PRIVATE_KEY) больше не отображаются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённый ключ, отметьте Clear saved secret on save под полем и нажмите Save.

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

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

Checkout Type: способ открытия формы оплаты ePayco.

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

URL подтверждения сообщает вашему магазину результат платежа. Он автоматически передаётся в ePayco с каждым платежом, поэтому в панели ePayco ничего настраивать не нужно. В разделе отображается URL. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_epayco_payment/confirmation, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_epayco_payment/payment/wcp_epayco_payment.confirmation. Он формируется из адреса витрины вашей установки OpenCart. Он должен быть доступен из интернета и не должен блокироваться брандмауэром или базовой аутентификацией. Он также работает, пока магазин находится в режиме обслуживания, поскольку OpenCart 3 пропускает запросы платёжных расширений, а в OpenCart 4 расширение для этого добавляет действие запуска (startup action).

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

Заказы

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

Order Status After Payment: ePayco одобрил платёж, а сумма и валюта совпадают с заказом. По умолчанию: В обработке.

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

On Hold (Review) Status: ePayco одобрил платёж, сумма или валюта которого отличаются от заказа, либо одобрил его после того, как заказу был присвоен другой статус (например, Отменён). Примечание объясняет причину. Не отправляйте товар до проверки транзакции в панели ePayco. По умолчанию: Ожидает оплаты, потому что в OpenCart нет статуса «На удержании». Вы можете создать собственный статус в разделе System > Localisation > Order Statuses и выбрать его здесь.

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

Reversed Status: ePayco отменил платёж по заказу. По умолчанию: Возвращён.

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

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

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию ePayco). На шаге Confirm Order покупатель видит ваше описание и примечание After confirming the order you pay securely in the ePayco checkout (cards, PSE, cash, wallets). OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Когда покупатель нажимает Confirm Order, расширение создаёт сессию оплаты ePayco на сумму заказа в валюте заказа, с учётом налогов, номером заказа, а также именем, адресом, e-mail и телефоном для выставления счёта. В ePayco платёж отображается как Order # и номер заказа. Язык формы оплаты — испанский или английский, в зависимости от языка магазина покупателя.

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

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

Для платежа в ожидании (например, PSE или наличные) заказ получает Awaiting Payment Status, а страница успеха показывает 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. Корзина сохраняется, а заказ остаётся без статуса. На OpenCart 4 эти сообщения выводятся над страницей оформления заказа.

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

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

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

Заказы

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

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

Order Status After Payment (default Processing): ePayco одобрил платёж. Примечание показывает ссылку ePayco, состояние, сумму, способ оплаты и код одобрения.

Awaiting Payment Status (default Pending): ePayco сообщил, что платёж находится в ожидании или на удержании, например перевод PSE или наличный платёж. Когда ePayco его одобряет, заказ переходит в Order Status After Payment; когда он отклоняется, завершается ошибкой, истекает или отменяется, заказ переходит в Payment Failed Status. OpenCart отправляет покупателю письма об этих изменениях.

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

Payment Failed Status (default Failed): платёж в ожидании не прошёл. Примечание показывает причину от ePayco. Новый одобренный платёж всё равно оплачивает заказ. Поздний сбой никогда не меняет оплаченный заказ.

Reversed Status (default Refunded): ePayco отменил платёж, которым был оплачен этот заказ.

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

Вкладка VibeFox ePayco Payment

В разделе Sales > Orders откройте заказ, оплаченный через ePayco. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox ePayco Payment показывает ePayco reference (ref_payco), Transaction ID, State, Payment method, Approval code, Transaction date, Mode (с меткой Test mode для тестовых платежей), Attempt status и ePayco notes заказа. Для заказа на проверке вкладка показывает предупреждение проверить транзакцию перед отправкой. Вкладка доступна только для чтения и показывается пользователям, у которых есть доступ к расширению.

Возвраты

Возвраты из магазина не поддерживаются. Верните платёж в панели ePayco, а при необходимости вручную обновите заказ в OpenCart. Отмена платёжной транзакции, которую сообщает ePayco, переводит заказ в Reversed Status. Возвраты товаров в разделе Sales > Returns не возвращают деньги через ePayco.

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

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

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

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

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

ePayco does not appear at checkout: проверьте, что лицензия активна, Enable/Disable включён, все четыре ключа введены и покупатель платит в COP или USD. Страница настроек показывает предупреждение, если ключи не заполнены. Также проверьте, что платёжный адрес входит в выбранную Geo Zone и что заказ достигает Total, заданного в настройках.

The payment went through, but the order stays without a status: подтверждение ePayco не доходит до вашего магазина. Проверьте, что URL подтверждения, указанный в настройках, открывается из интернета и не блокируется брандмауэром, расширением безопасности или базовой аутентификацией. Посмотрите поле Log на странице расширения; включите Logging, чтобы видеть каждое подтверждение. Заказ также получает статус, когда покупатель возвращается в магазин после оплаты.

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

Confirmation answers Gateway not configured: P_CUST_ID_CLIENTE или P_KEY пуст. Введите их в настройках.

Confirmation answers Order not found: подтверждение относится к заказу без платежа ePayco этого магазина.

Confirmation answers Busy, retry later: заказ в тот же момент обновлялся другим запросом. ePayco повторит подтверждение. Причина указана в журнале.

The customer sees We could not connect to ePayco: ePayco отклонил PUBLIC_KEY и PRIVATE_KEY. В журнале показан ответ ePayco. Скопируйте оба ключа заново.

The customer sees ePayco could not start the payment: ePayco не создал сессию оплаты. Посмотрите в журнале ошибку ePayco.

The customer sees This payment method is not available right now: сессия оплаты больше не соответствует заказу, способ оплаты тем временем выключили или ключи удалили. Покупатель перезагружает страницу оформления заказа.

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

A test payment did not pay the order: тестовые транзакции никогда не оплачивают заказы, созданные в боевом режиме. Оформляйте тестовый заказ, пока Test Mode включён.

Order is in the review status after payment: прочитайте примечания на вкладке VibeFox ePayco Payment (см. Статусы заказов) и проверьте транзакцию в панели ePayco перед отправкой.

Удаление

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

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

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