VibeFox OpenPay for WooCommerce — Помощь

Требования

WordPress: 6.0 или новее.

WooCommerce: 8.0 или новее, установлен и активен. Плагин не активируется без него.

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

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

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

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

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

Установка

1. В WordPress откройте Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку wcp_openpay_gateway в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > OpenPay > Manage или нажмите Settings под названием плагина на странице Plugins.

4. Введите лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

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

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

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

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > OpenPay. Над полями страница предупреждает, если ключи текущего режима неполные (тогда способ оплаты скрывается при оформлении заказа), если валюта магазина не принимается выбранной страной учётной записи, и показывает Sandbox mode is enabled — no real charges are made., пока включён режим песочницы. В списке способов оплаты OpenPay отмечен как требующий настройки, пока в текущем режиме не заполнены все три ключа; пока режим песочницы включён, отображается значок тестового режима.

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

Общие

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: Use the OpenPay sandbox (test keys, no real charges) переключает на песочницу и ключи, и 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_...).

Ключи из версии 1.0 плагина (один набор ключей и флаг песочницы) автоматически переносятся в поля песочницы или рабочего режима.

Вебхук

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

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

Выберите эти события:

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

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

Debug log: Log payment steps (errors are always logged) записывает шаги платежа в WooCommerce > Status > Logs, источник wcp_openpay_gateway. Ошибки и предупреждения записываются, даже если опция выключена. Ключи, данные карты и данные покупателя никогда не записываются в журнал. По умолчанию: отключено.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. По умолчанию: отключено.

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

Покупатель выбирает способ оплаты (по умолчанию Credit or debit card (OpenPay)) и заполняет Cardholder name, Card number, Expiry (MM/YY) и Card code (CVV). При оформлении заказа openpay.js в браузере превращает карту в одноразовый токен, а библиотека OpenPay для проверки на мошенничество добавляет идентификатор сессии устройства. Вашему магазину передаются только эти два значения.

Затем плагин создаёт списание с 3D Secure на сумму заказа в валюте заказа и перенаправляет покупателя на страницу 3D Secure его банка, которую предоставляет OpenPay. Каждая попытка получает собственную ссылку на заказ в OpenPay (номер заказа и короткий суффикс). Описание списания — Order #, номер заказа и название вашего сайта. Имя, адрес электронной почты и телефон покупателя передаются в OpenPay; учётная запись покупателя в OpenPay не создаётся. Пока покупатель находится на странице 3D Secure, заказ остаётся в статусе Ожидает оплаты.

Когда покупатель возвращается, плагин считывает списание из API OpenPay. Заказ отмечается оплаченным только после подтверждения OpenPay: списание должно относиться к этому заказу, быть завершённым и точно совпадать с суммой и валютой заказа. Если результат ещё неизвестен, страница заказа получен показывает We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. Затем вебхук обновит заказ.

Если карта отклонена или 3D Secure не пройден, покупатель возвращается на страницу Pay for order с сообщением The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. и может оплатить снова. Перед новой попыткой плагин проверяет предыдущее списание заказа: если оно действительно было оплачено, заказ отмечается оплаченным без второго списания; если оно ещё обрабатывается, покупатель видит, что предыдущий платёж ещё обрабатывается, и не должен оплачивать повторно; если его состояние проверить невозможно, новая попытка не делается, и покупателя просят повторить через несколько минут.

Отклонённые карты получают понятное сообщение, например 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 покупателям никогда не показываются; они попадают в заметки к заказу и в журнал.

Способ оплаты работает в классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Он совместим с WooCommerce High-Performance Order Storage (HPOS). При оформлении заказа он скрывается, если отключён, если ключи текущего режима неполные или если валюта заказа не принимается страной учётной записи.

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

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

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

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

В обработке: оплата подтверждена. Это обычный статус WooCommerce после оплаты; заказы только с виртуальными загружаемыми товарами переходят в статус «Выполнен». В заметке к заказу указаны ID списания и режим (рабочий или песочница). ID транзакции — это ID списания OpenPay.

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

Неудачный: карта была отклонена при создании списания, либо последняя попытка не удалась, была отменена или истекла. Покупатель может оплатить снова.

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

Возвраты

Для учётных записей из Мексики и Перу: откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Credit or debit card (OpenPay) (на кнопке отображается название вашего способа оплаты). Поддерживаются полный и частичный возвраты. Возврат отправляется в том режиме и стране учётной записи, в которых был оплачен заказ, поэтому держите ключи песочницы заполненными, пока есть заказы песочницы, которые нужно вернуть. Если OpenPay не принимает возврат, WooCommerce показывает ошибку, например OpenPay refund failed: ..., и возврат не регистрируется. Успешный возврат добавляется в заметки к заказу с ID возврата OpenPay.

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

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

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

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Payments > OpenPay. Вставьте ключ в поле License key и нажмите Activate. В блоке показан статус, например дата, до которой действует лицензия, и ваш домен. Используйте Check now, чтобы повторно проверить статус, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить его с этого сайта. Ссылка Manage licenses and domains in your account открывает вашу учётную запись vibefox.net.

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

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

Когда лицензия истекает, плагин продолжает работать, но обновления и поддержка требуют продления. Статус автоматически проверяется в фоновом режиме.

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

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

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

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

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

Вебхук отвечает busy: заказ в этот момент обновлялся другим запросом. OpenPay повторит вебхук.

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

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

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

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

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

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите слот в своей учётной записи vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить его, деактивируйте и удалите плагин на странице Plugins. Лицензионный ключ и статус лицензии этого плагина всегда удаляются. Настройки шлюза, сохранённый код подтверждения вебхука и журналы плагина удаляются только если была включена опция Delete data on uninstall. Иначе они сохраняются для повторной установки. Данные заказов всегда сохраняются: существующие заказы сохраняют свои заметки об оплате, ID транзакций и данные списаний, необходимые для возвратов после повторной установки.

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