VibeFox Wompi for OpenCart — Помощь

Требования

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

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

Валюта: колумбийский песо (COP). Wompi Colombia списывает средства в COP. Добавьте COP в System > Localisation > Currencies, если её ещё нет в магазине; способ оплаты предлагается только тогда, когда покупатель оформляет заказ в COP. Страница настроек предупреждает, если валюта магазина по умолчанию не COP.

Аккаунт Wompi: мерчант-аккаунт Wompi Colombia. В каждой среде (тестовой и боевой) есть четыре ключа: публичный ключ, приватный ключ, секрет событий и секрет целостности. Их можно найти в личном кабинете мерчанта Wompi (comercios.wompi.co) в разделе для разработчиков. Wompi El Salvador и Panama используют другие API и не поддерживаются.

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

Установка

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

OpenCart 3

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

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

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

4. Вставьте ключи тестовой и боевой среды из личного кабинета мерчанта Wompi и укажите Events URL в Wompi (см. раздел «Настройка»).

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

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Wompi Payment > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками блок состояния показывает текущий режим, SANDBOX или PRODUCTION. Если ключ этого режима не заполнен, блок перечисляет его и сообщает, что способ оплаты скрыт при оформлении заказа, пока не заполнены все ключи этой среды. Когда все ключи заполнены, он указывает, будут ли списываться реальные платежи. При сохранении расширение предупреждает, если ключ не начинается с префикса своего раздела, а также если Wompi включён, но скрыт при оформлении из-за незаполненных ключей. Title должно содержать не более 128 символов (Title must be at most 128 characters.), Sort Order должно быть целым числом (Sort Order must be a whole number.), Total должно быть числом, 0 или больше (Total: enter a number, 0 or greater.), а выбранная гео-зона и статусы заказов должны существовать; в противном случае ничего не сохраняется, и страница показывает ошибку. Без права изменять расширение страница показывает настройки, но не может их сохранить.

Wompi

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

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

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

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

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

Total: сумма заказа в валюте магазина по умолчанию, которую должен достичь заказ, чтобы предлагался Wompi: число, 0 или больше. Оставьте поле пустым, чтобы предлагать Wompi при любой сумме. Сам Wompi требует минимум COP 1,500.

Аккаунт Wompi

Скопируйте ключи из личного кабинета мерчанта Wompi (comercios.wompi.co), раздел для разработчиков. У каждой среды свой публичный ключ, приватный ключ, секрет событий и секрет целостности.

Sandbox mode: использует тестовую среду Wompi (тестовые ключи, без реальных денег). Переключаются и ключи, и API Wompi (sandbox.wompi.co или production.wompi.co). Попытки оплаты сохраняют среду, в которой были сделаны. По умолчанию: включено. Выключите, чтобы принимать реальные платежи. Пока режим включён, покупатели видят на шаге Confirm Order сообщение Sandbox mode: no real payment is made.

Тестовые ключи

Четыре ключа тестовой среды Wompi. Они начинаются с pub_test_, prv_test_, test_events_ и test_integrity_.

Public key: публичный тестовый ключ (pub_test_...). Он идентифицирует ваш аккаунт в Wompi Web Checkout.

Private key: приватный тестовый ключ (prv_test_...). Используется для чтения транзакций через API Wompi.

Events secret: тестовый секрет событий (test_events_...). Он проверяет подпись событий Wompi.

Integrity secret: тестовый секрет целостности (test_integrity_...). Он подписывает запрос на оплату, отправляемый в Web Checkout.

Боевые ключи

Четыре ключа боевой среды Wompi. Они начинаются с pub_prod_, prv_prod_, prod_events_ и prod_integrity_.

Public key: публичный боевой ключ (pub_prod_...).

Private key: приватный боевой ключ (prv_prod_...).

Events secret: боевой секрет событий (prod_events_...).

Integrity secret: боевой секрет целостности (prod_integrity_...).

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

Events URL (webhook)

События Wompi сообщают вашему магазину, что транзакция изменилась. В личном кабинете мерчанта Wompi, в разделе для разработчиков, укажите Events URL, показанный в этом разделе, для тестовой и для боевой среды. Она формируется из адреса витрины вашей установки OpenCart. В OpenCart 3 она выглядит так: https://your-store/index.php?route=extension/payment/wcp_wompi_payment/webhook, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_wompi_payment/payment/wcp_wompi_payment.webhook. Скопируйте URL точно так, как он показан в настройках.

Расширение использует это событие:

На другие события отвечается Ignored. Каждое событие проверяется секретом событий своей среды (тестовой или боевой). Вебхуки без действительной подписи отклоняются. После проверки транзакция запрашивается через API Wompi приватным ключом этой среды, и используются только эти данные. Без Events URL заказ получает статус, только когда покупатель возвращается в магазин после оплаты.

Заказы

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

Order Status After Payment: транзакция APPROVED на ожидаемую сумму в COP. По умолчанию: Processing (В обработке).

Awaiting Payment Status: транзакция PENDING, например PSE, Nequi или наличный платёж, ожидающий подтверждения. Заказ получит Order Status After Payment, когда Wompi одобрит платёж. По умолчанию: Pending (Ожидание).

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

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

Cancelled Order Status: ожидающая транзакция последней попытки оплаты была аннулирована в Wompi. Платёж, одобренный для заказа в этом статусе, переводит его на удержание, а не отмечает как оплаченный. По умолчанию: Canceled (Отменён).

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

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

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Wompi). На шаге Confirm Order покупатель видит ваше описание. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение создаёт попытку оплаты с собственным номером (OC-, номер заказа и отметка времени), подписывает её ключом целостности и отправляет покупателя в Wompi Web Checkout с суммой заказа в COP. Адрес электронной почты покупателя и имя из адреса оплаты передаются в Wompi. На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Если в оформлении нет адреса оплаты, имя берётся из заказа или адреса доставки.

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

Когда транзакция одобрена, заказ получает статус стандартным способом OpenCart, с обычными письмами о заказе и обновлением склада, а покупатель видит стандартную страницу успешного оформления заказа OpenCart. Для ожидающего платежа (например PSE, Nequi или наличного платежа) страница показывает Your Wompi payment is pending confirmation (for example PSE, Nequi or a cash payment). We will process the order as soon as Wompi confirms the payment. Для заказа на удержании — We have received your Wompi payment and are reviewing it. We will contact you if anything is needed. Если ожидающий платёж позже отклоняется, страница показывает Your Wompi payment was not approved. Please contact us. Если он аннулирован, страница показывает Your Wompi payment was voided and this order was cancelled. Please contact us.

Если Wompi ещё не подтвердил транзакцию, когда покупатель возвращается, появляется страница с сообщением We are waiting for Wompi to confirm your payment. You will receive an e-mail as soon as it is confirmed. и кнопками Check again и Back to checkout. Событие Wompi устанавливает статус заказа, как только оно приходит.

Если платёж отклонён, заказ остаётся без статуса, корзина сохраняется. Покупатель возвращается к оформлению с сообщением Your Wompi payment was not approved (...). You can try again or choose another payment method. и причиной, указанной Wompi. Аннулированный платёж даёт Your Wompi payment was voided. You can try again or choose another payment method. Если покупатель уходит со страницы Web Checkout, не оплатив, сообщение: Your Wompi payment was not completed. You can try again or choose another payment method. Каждая новая попытка получает новый номер. OpenCart создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, но одна корзина оплачивается только один раз: как только один из заказов корзины оплачен, ожидает оплаты или находится на удержании, покупатель переходит на страницу успеха, а не оплачивает повторно.

На OpenCart 4 эти сообщения показываются над страницей оформления заказа. OpenCart 4 оставляет один заказ для оформления и обновляет его при каждом показе шага Confirm Order: после отклонённого или незавершённого платежа покупатель оплачивает тот же заказ новой попыткой. Если этот заказ к тому времени был закрыт без оплаты (например, его ожидающий платёж PSE или Nequi позже был отклонён или аннулирован либо вы его отменили), или корзина была изменена после начала платежа, заказ уходит из оформления, и покупатель видит Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order. Следующее нажатие Confirm Order оплачивает корзину новым заказом.

Способ оплаты показывается только тогда, когда лицензия активна, заполнены все четыре ключа текущего режима, покупатель оформляет заказ в COP и сумма составляет не менее COP 1,500. Если оплату не удаётся начать, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой:

Events URL работает и тогда, когда магазин находится в режиме обслуживания, потому что OpenCart пропускает запросы платёжных расширений. На OpenCart 4 стартовое действие расширения пропускает Events URL и возврат покупателя.

Расширение не делает возвраты из OpenCart. На вашем сайте нет сохранённых карт, подписок и полей для ввода карты: все платёжные данные вводятся в Wompi.

Заказы

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

Без статуса (недооформленный заказ): покупатель был отправлен в Wompi и не оплатил, платёж был отклонён или Wompi ещё не сообщил о транзакции. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным на Missing Orders.

Awaiting Payment Status (по умолчанию Pending): Wompi сообщает о транзакции как об ожидающей, например платежи PSE, Nequi или наличные, ожидающие подтверждения. Заказ ждёт, пока Wompi одобрит или отклонит платёж. После одобрения заказ переходит в Order Status After Payment.

Order Status After Payment (по умолчанию Processing): транзакция одобрена на сумму заказа в COP. Примечание показывает транзакцию, тип способа оплаты (например CARD, PSE или NEQUI), номер, сумму и среду.

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

Failed Payment Status (по умолчанию Failed): ожидающая транзакция последней попытки оплаты была отклонена или завершилась ошибкой. Сообщение Wompi добавляется в примечание. Результаты старых попыток не меняют заказ.

Cancelled Order Status (по умолчанию Canceled): ожидающая транзакция последней попытки оплаты была аннулирована в Wompi.

Когда у заказа, который уже имеет статус, он меняется (например, с ожидания на оплачен или неудачный), OpenCart уведомляет покупателя. Если приходит второй одобренный платёж для уже оплаченного заказа или для другого заказа уже оплаченной корзины, заказ не меняется. Примечание просит вас вернуть дублирующий платёж в личном кабинете Wompi. Если платёжная транзакция аннулируется в Wompi, примечание просит проверить заказ. Повторные события и возвраты никогда не создают дубликаты примечаний или платежей.

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

Вкладка VibeFox Wompi Payment

В Sales > Orders откройте заказ, оплаченный через Wompi. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Wompi Payment показывает Reference, Transaction ID, Status (со статусом Wompi), запрошенную сумму Requested, Transaction amount, Payment method, Wompi message, метку SANDBOX для тестовых платежей, Payment attempts корзины, если их было несколько, и Wompi notes заказа. Вкладка показывается пользователям, имеющим доступ к расширению.

Возвраты

Возвраты не отправляются из OpenCart. Сделайте возврат или аннулируйте платёж в личном кабинете мерчанта Wompi, а затем вручную зафиксируйте возврат в OpenCart. Аннулирование платёжной транзакции, сделанное в Wompi, добавляется к заказу как примечание. Возвраты товаров в Sales > Returns не возвращают деньги через Wompi.

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

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

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

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

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

Wompi не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и заполнены все четыре ключа текущего режима (блок состояния на странице настроек перечисляет недостающие ключи). Проверьте также, что покупатель оформляет заказ в COP и сумма составляет не менее COP 1,500. Убедитесь, что адрес оплаты входит в выбранную Geo Zone и что заказ достигает Total, указанного в настройках.

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

Events URL answers Not configured: секрет событий среды события пуст. Вставьте его в настройки.

Events URL answers Invalid signature: секрет событий принадлежит другой среде или другому аккаунту. Скопируйте его заново из личного кабинета Wompi.

Events URL answers Transaction lookup failed: API Wompi не вернул транзакцию, например из-за неверного приватного ключа или проблемы с сетью. Wompi отправит событие повторно позже.

Events URL answers Retry: заказ в этот момент подтверждался другим запросом или не удалось установить статус заказа. Wompi отправит событие повторно позже. Причину смотрите в поле Log.

Events URL answers Environment mismatch: тестовая транзакция пришла для боевой попытки оплаты или наоборот. Тестовые платежи никогда не подтверждают боевые заказы.

Events URL answers Unknown reference: номер транзакции похож на номер этого магазина, но здесь он никогда не выдавался, например другим магазином OpenCart на том же аккаунте Wompi. Номера других систем получают ответ Ignored: not an OpenCart reference.

The Events URL shows Method not allowed in the browser: это нормально. URL принимает запросы только от Wompi.

The key does not start with ... warning on save: ключ вставлен в неверный раздел. Тестовые ключи начинаются с pub_test_, prv_test_, test_events_ и test_integrity_, боевые — с pub_prod_, prv_prod_, prod_events_ и prod_integrity_.

Order is in the review status: прочитайте примечания на вкладке VibeFox Wompi Payment (см. Статусы заказов), затем выполните заказ или сделайте возврат в личном кабинете Wompi.

Other errors: смотрите поле Log на странице расширения и Wompi notes заказа. Ошибки записываются всегда. Включите Debug log для подробностей.

Удаление

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

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

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