VibeFox Wompi for PrestaShop — Помощь

Требования

PrestaShop: 8.0 – 9.x.

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

Валюта: колумбийское песо (COP). Wompi Colombia принимает платежи в COP, а способ оплаты скрыт для корзин в других валютах. Страница настроек предупреждает, если валюта магазина по умолчанию не COP.

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

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

Установка

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

2. После окончания загрузки нажмите Configure или позже найдите VibeFox Wompi Payment в списке модулей и нажмите Configure.

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

4. Вставьте ключи sandbox и production из панели мерчанта Wompi и укажите URL событий в Wompi (см. Настройки).

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

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

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Wompi Payment > Configure. У каждого раздела с полями есть своя кнопка Save, которая сохраняет всю страницу. Над полями блок статуса показывает текущий режим, SANDBOX или PRODUCTION. Если ключа этого режима нет, блок его перечисляет и сообщает, что способ оплаты скрыт при оформлении заказа, пока не заданы все ключи этой среды. Когда все ключи заданы, блок сообщает, будут ли списываться реальные платежи. При сохранении модуль предупреждает, если ключ не начинается с префикса своего раздела, и если Wompi включён, но скрыт при оформлении заказа из-за отсутствующих ключей.

Wompi

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

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

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.

Аккаунт Wompi

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

Sandbox mode: использует песочницу Wompi (ключи sandbox, реальные деньги не списываются). Переключаются и ключи, и API Wompi (sandbox.wompi.co или production.wompi.co). Попытки оплаты сохраняют среду, в которой были сделаны. По умолчанию: on. Выключите, чтобы принимать реальные платежи. Пока режим включён, покупатели видят под способом оплаты Режим sandbox: реальный платёж не производится.

Ключи sandbox

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

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

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

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

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

Ключи production

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

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

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

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

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

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

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

URL событий (webhook)

События Wompi сообщают вашему магазину, что транзакция изменилась. В панели мерчанта Wompi, в разделе для разработчиков, укажите URL событий, который показан в этом разделе, — отдельно для sandbox и для production. При понятных URL он выглядит так: https://your-shop/module/wcp_wompi_payment/webhook, возможно с кодом языка, например /es/. Копируйте URL точно в том виде, в котором его показывают настройки.

Модуль использует это событие:

Остальные события получают ответ Ignored. Каждое событие проверяется секретом событий своей среды (sandbox или production). Webhook без корректной подписи отклоняется. После проверки транзакция читается из API Wompi приватным ключом этой среды, и используются только эти данные. Без URL событий заказ создаётся только тогда, когда покупатель возвращается в магазин после оплаты.

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

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

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

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

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Wompi) и подтверждает. Модуль создаёт попытку оплаты со своим референсом (PS-, номер корзины и отметка времени), подписывает её секретом целостности и отправляет покупателя в Wompi Web Checkout с суммой корзины в COP. E-mail покупателя и имя адреса для счёта передаются в Wompi. На этом этапе заказа ещё нет.

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

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

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

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

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

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

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

Заказы

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

Заказа ещё нет: покупатель отправлен в Wompi и не заплатил, платёж отклонён или Wompi ещё не подтвердил транзакцию. Существует только корзина.

Awaiting Wompi payment: Wompi сообщает, что транзакция ожидает обработки, например платежи PSE, Nequi или наличными, которые ждут подтверждения. Заказ ждёт, пока Wompi его одобрит или отклонит. Когда платёж одобрен, он регистрируется, и заказ переходит в статус Payment accepted.

Payment accepted: транзакция одобрена на сумму корзины в COP. Платёж регистрируется с ID транзакции Wompi, а примечание показывает транзакцию, тип способа оплаты (например, CARD, PSE или NEQUI), референс, сумму и среду.

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

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

Canceled: ожидающая транзакция последней попытки оплаты отменена в Wompi.

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

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

На странице заказа показывается блок Wompi payment с референсом, ID транзакции, статусом (со статусом Wompi), запрошенной суммой, суммой транзакции, способом оплаты, сообщением Wompi, значком SANDBOX для платежей sandbox, Payment attempts корзины, если их было несколько, и Wompi notes заказа.

Возвраты

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

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

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

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

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

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

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

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

Wompi не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён и заданы все четыре ключа текущего режима (блок статуса на странице настроек перечисляет недостающие ключи). Проверьте также, что валюта корзины COP и сумма не меньше COP 1 500. В Payment > Preferences проверьте, что модуль разрешён для COP, страны покупателя и группы покупателя.

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

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

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

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

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

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

URL событий отвечает Unknown reference: референс транзакции не выдан этим магазином, например, тот же аккаунт Wompi используется другим магазином. Референсы других систем получают ответ Ignored.

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

Предупреждение при сохранении, что ключ не начинается с ...: ключ вставлен не в тот раздел. Ключи sandbox начинаются с pub_test_, prv_test_, test_events_ и test_integrity_, ключи production — с pub_prod_, prv_prod_, prod_events_ и prod_integrity_.

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

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

Удаление

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

Wompi — товарный знак его владельца. Модуль не связан с Wompi и не одобрен Wompi.