VibeFox OpenPay for PrestaShop — Помощь

Требования

PrestaShop: от 8.0 до 9.x.

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

HTTPS: ваш магазин должен использовать HTTPS, так как форма карты находится на странице оформления заказа.

Аккаунт OpenPay: аккаунт OpenPay из Мексики, Колумбии или Перу. Вам понадобятся его Merchant ID, закрытый ключ (sk_...) и открытый ключ (pk_...). В панелях песочницы и рабочего режима разные Merchant ID и ключи, и модуль хранит их раздельно.

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

Карта вводится на странице оформления заказа, но читается и токенизируется в браузере библиотекой openpay.js. Поля карты не имеют имени и никогда не отправляются на ваш сервер. Так как форма карты находится на вашей странице, область PCI DSS — SAQ A-EP; уточните это у вашего эквайера.

Установка

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

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

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

4. Выберите Account country и введите ключи песочницы и рабочего режима (см. «Настройка»).

5. Рекомендуется: добавьте URL вебхука в панели OpenPay (см. «Настройка»).

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

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox OpenPay Gateway > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если ключи текущего режима не заполнены (способ оплаты тогда скрыт на оформлении заказа), если валюта по умолчанию вашего магазина не принимается выбранной страной аккаунта, и показывает Sandbox mode is enabled — no real charges are made., пока включён режим песочницы.

При сохранении ключи проверяются. Merchant ID может содержать только буквы и цифры, закрытый ключ должен начинаться с sk_, а открытый — с pk_. Неверное значение не сохраняется: остаётся предыдущее значение и показывается ошибка, например Sandbox: The private key must start with sk_. Если способ оплаты включён, но ключи текущего режима не заполнены, вы также увидите сообщение, что шлюз остаётся скрытым на оформлении заказа. Пустое поле Title не принимается, выводится Enter a title for the payment method.

OpenPay

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

Title: название способа оплаты, которое видят покупатели на оформлении заказа. Оно также сохраняется в заказе как название способа оплаты. По умолчанию: Credit or debit card (OpenPay). Обязательно.

Description: текст над формой карты на оформлении заказа. По умолчанию: Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).

Аккаунт OpenPay

Merchant ID, закрытый ключ (sk_) и открытый ключ (pk_) находятся в панели OpenPay в разделе Settings (Configuración). В этом разделе есть ссылки на панели песочницы и рабочего режима для Мексики, Колумбии и Перу.

Account country: страна вашего аккаунта OpenPay. От неё зависят API OpenPay, библиотека openpay.js этой страны и принимаемые валюты. По умолчанию: Mexico.

Sandbox mode: использует песочницу OpenPay (тестовые ключи, без реальных списаний) и переключает и ключи, и API на песочницу. Пока режим включён, на оформлении заказа показывается значок SANDBOX MODE. По умолчанию: включено. Выключите его, чтобы принимать реальные платежи.

Sandbox Merchant ID: Merchant ID из панели песочницы, Settings (Configuración), API-ключи.

Sandbox Private Key: закрытый ключ песочницы. Начинается с sk_. Используется только на сервере; никому его не передавайте.

Sandbox Public Key: открытый ключ песочницы. Начинается с pk_. openpay.js использует его в браузере для токенизации карты.

Live Merchant ID: Merchant ID из панели рабочего режима, Settings (Configuración), API-ключи.

Live Private Key: закрытый ключ рабочего режима (sk_...).

Live Public Key: открытый ключ рабочего режима (pk_...).

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

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

Вебхук

Вебхук не обязателен, но рекомендуется. Он подтверждает платежи, когда покупатель не возвращается со страницы 3D Secure, например после закрытия браузера. В панели OpenPay перейдите в Settings > Webhooks и добавьте URL, который показан в поле Webhook URL в этом разделе. При понятных URL он выглядит так: https://your-shop/module/wcp_openpay_gateway/webhook, возможно с кодом языка, например /en/. Скопируйте его точно так, как он показан в настройках. Добавьте вебхук в панель каждого используемого режима (песочницы и рабочего режима).

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

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

OpenPay не подписывает вебхуки, поэтому модуль никогда не доверяет самому уведомлению. Он использует его только для поиска списания, а затем читает списание из API OpenPay закрытым ключом того режима и страны аккаунта, в которых был сделан платёж. Уведомление о списании, которого этот магазин не создавал, игнорируется. Вебхук работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по стране вашего магазина.

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

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

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

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

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

На шаге оплаты покупатель выбирает способ оплаты (по умолчанию Credit or debit card (OpenPay)) и заполняет Cardholder name, Card number, Expiry (MM/YY) и Card code (CVV). В режиме песочницы форма показывает SANDBOX MODE — Test environment. No real charges will be made. Когда покупатель подтверждает, openpay.js превращает карту в одноразовый токен в браузере, а библиотека антифрода добавляет ID сессии устройства. Вашему магазину отправляются только эти два значения и номер корзины. Если форма заполнена не полностью, под ней появляется Please fill in all card fields.

Затем модуль создаёт списание с 3D Secure на сумму корзины в валюте корзины и отправляет покупателя на страницу 3D Secure его банка, которую обслуживает OpenPay. Каждая попытка получает собственную ссылку на заказ в OpenPay. Описание списания — Cart #, номер корзины и название вашего магазина. Имя, e-mail и телефон покупателя передаются в OpenPay; учётная запись покупателя в OpenPay не создаётся. На этом этапе заказа ещё нет.

Когда покупатель возвращается, модуль читает списание из API OpenPay. Заказ отмечается как оплаченный только после подтверждения OpenPay: списание должно принадлежать этой корзине, быть завершённым и точно совпадать с суммой и валютой корзины. Затем заказ создаётся, и покупатель видит страницу подтверждения заказа с Your card payment has been received. Если OpenPay сообщает, что списание выполняется, заказ создаётся в статусе Awaiting OpenPay payment, а страница показывает We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. Если результат пока неизвестен, страница Payment confirmation показывает тот же текст с кнопкой Check again и кнопкой Back to checkout; вебхук создаёт заказ, как только приходит. Если выполнявшееся списание позже не удалось, страница подтверждения заказа показывает Your OpenPay card payment was not completed. Please contact us about this order.

Если карта отклонена или 3D Secure не пройден, покупатель возвращается на оформление заказа с сообщением The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. и может оплатить снова. Корзина сохраняется. Перед новой попыткой модуль проверяет предыдущее списание по корзине: если оно фактически оплачено, заказ создаётся по нему без второго списания; если оно ещё выполняется, заказ создаётся в статусе Awaiting OpenPay payment; если его состояние невозможно проверить, новое списание не делается, и покупатель видит We could not confirm the status of your previous payment attempt. Please try again in a few minutes. Корзина, для которой уже есть заказ, никогда не списывается повторно.

Отклонённые карты получают понятное сообщение, например The card has insufficient funds. Please use another card., The card has expired. Please use another card. или The security code (CVV) is not valid. Please check it and try again. Технические ошибки OpenPay покупателям никогда не показываются; они попадают в журнал.

Если купон в корзине перестаёт действовать между оплатой и её подтверждением, он удаляется из заказа. Тогда заказ переходит в статус OpenPay payment on hold с примечанием, так как покупатель оплатил цену со скидкой.

Способ оплаты скрыт на оформлении заказа, если он выключен, если ключи текущего режима не заполнены или если валюта корзины не принимается страной аккаунта.

Модуль принимает только платежи картой с немедленным списанием. Он не поддерживает сохранённые карты, подписки, беспроцентную рассрочку (MSI) или платежи в рассрочку, оплату бонусами карты, наличные, SPEI, PSE или CoDi, а также раздельные авторизацию и списание.

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

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

Заказа ещё нет: покупатель находится на странице 3D Secure, не завершил оплату или карта была отклонена. Существует только корзина.

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

Awaiting OpenPay payment: OpenPay сообщает, что списание выполняется (ещё не захвачено). Заказ переходит в Payment accepted, когда списание завершено, или в Payment error, если оно не удалось.

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

Payment error: выполнявшееся списание не удалось, было отменено или истекло.

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

Если по уже оплаченному заказу поступает второе завершённое списание, заказ не меняется. Примечание, начинающееся с WARNING, просит вас вернуть дубликат в панели OpenPay.

Блок оплаты OpenPay

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

Возвраты

Для аккаунтов из Мексики и Перу: в блоке OpenPay payment введите сумму (не возвращённая сумма подставляется автоматически), при необходимости причину, и нажмите Refund via OpenPay. Подтвердите вопрос Refund this amount through OpenPay? This cannot be undone. Поддерживаются полный и частичный возврат, не больше суммы, которую списала OpenPay. Нужно право на редактирование заказов. Возврат отправляется с ключами того режима и страны аккаунта, в которых выполнялось списание, поэтому ключи этого режима должны быть заполнены: сохраняйте ключи песочницы, пока вы ещё можете возвращать заказы песочницы. Если OpenPay не принимает возврат, блок показывает ошибку, например OpenPay refund failed: ..., и возврат не записывается. Успешный возврат добавляется в историю возвратов и в примечания вместе с ID возврата OpenPay. Полный возврат переводит заказ в статус Refunded. Частичный возврат статус не меняет. Возвраты доступны, когда OpenPay подтвердила платёж; заказ на удержании после расхождения суммы через модуль не возвращается.

OpenPay Colombia не поддерживает возвраты по картам через API, как и официальные плагины OpenPay. Для колумбийских списаний блок не предлагает формы возврата; верните списание в панели OpenPay.

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

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

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox OpenPay Gateway — первый блок на странице Modules > Module Manager > VibeFox OpenPay Gateway > Configure, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действительна, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-openpay и ссылка 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.

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

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

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

OpenPay не появляется на оформлении заказа: проверьте, что лицензия активна, что Enable / Disable включено и что в текущем режиме заполнены все три ключа: ключи песочницы в режиме песочницы, ключи рабочего режима в рабочем режиме. Проверьте, что валюта корзины принимается Account country (Мексика: MXN, USD; Колумбия: COP, USD; Перу: PEN, USD). В каждом таком случае страница настроек показывает предупреждение. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы клиентов.

Платёж прошёл, но заказ не создан: покупатель не вернулся со страницы 3D Secure, а вебхук не работает. Проверьте, что URL вебхука добавлен в панели OpenPay того режима, который вы используете, точно как показано в настройках, с перечисленными выше событиями. Проверьте, что заполнены ключи того режима, в котором был сделан платёж: без них вебхук отвечает not configured, и OpenPay повторяет попытку позже. Заказ также создаётся, когда покупатель возвращается в магазин или пытается снова оплатить ту же корзину.

Вебхук отвечает ignored (unknown order): списание создано не этим магазином, например списание другого магазина на том же аккаунте OpenPay. Ничего не меняется.

Вебхук отвечает verification failed: не удалось обратиться к API OpenPay, чтобы прочитать списание. OpenPay повторяет вебхук.

Вебхук отвечает busy: корзина в тот же момент обновлялась другим запросом, или заказ не удалось создать (например, модуль выключен). OpenPay повторяет вебхук. Включите Debug log, чтобы увидеть причину.

Покупатель видит The secure card form could not be loaded: openpay.js или библиотека антифрода OpenPay не загрузились в браузере, либо не удалось создать ID сессии устройства. Попросите покупателя перезагрузить страницу и попробовать снова.

Покупатель видит The payment could not be processed right now: OpenPay отклонила запрос или не ответила. Причина указана в журнале. Типичная причина — неверные Merchant ID или закрытый ключ. Если OpenPay не ответила, проверьте списание в панели OpenPay, прежде чем покупатель заплатит снова.

Покупатель видит This test card cannot be used for real payments: использована тестовая карта песочницы, когда режим песочницы выключен.

Заказ в статусе OpenPay payment on hold после оплаты: прочитайте OpenPay notes в блоке (см. «Статусы заказа»), затем выполните заказ или верните платёж.

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

Возврат не выполняется с сообщением The order is being updated right now: вебхук или другой запрос в этот момент обновлял заказ. Повторите попытку через минуту.

Удаление

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

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