VibeFox Worldline for WooCommerce — Помощь

Требования

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

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

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

Аккаунт Worldline: аккаунт мерчанта Worldline Direct (ранее Ingenico Direct). Тестовый и боевой аккаунты разделены и имеют разные учётные данные. Для каждого аккаунта нужны Merchant ID (ваш PSPID), API Key ID с его Secret API Key и ключ вебхука с его секретом. Всё это создаётся в Merchant Portal Worldline (см. раздел «Configuration»).

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

Установка

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

2. Нажмите Activate.

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

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

5. Введите тестовые учётные данные, сохраните настройки и нажмите Test credentials.

6. Добавьте URL вебхука в Merchant Portal тестового аккаунта и введите ключ и секрет вебхука (см. раздел «Configuration»).

7. Включите Enable/Disable и совершите тестовый платёж. Затем введите боевые учётные данные, повторите настройку вебхука в боевом аккаунте, нажмите Live credentials и снимите отметку Test Mode.

Configuration

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Worldline (Ingenico). В списке способов оплаты Worldline помечен как требующий настройки, пока в текущем режиме не заданы Merchant ID, API Key ID и Secret API Key. На странице настроек поля учётных данных неиспользуемого режима выделены серым.

General

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

Title: название способа оплаты, которое видят покупатели при оформлении заказа. По умолчанию: Worldline.

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely via Worldline.

Worldline Direct API

Получите учётные данные в Merchant Portal Worldline для тестового и для боевого аккаунта. Ваш PSPID — это Merchant ID. В разделе Developer > Payment API создаются API Key ID и Secret API Key, в разделе Developer > Webhooks — ключ и секрет вебхука. В этом разделе есть ссылки на оба портала и на документацию Worldline.

Test Mode: Enable test mode (pre-production environment, no real money) переключает и адрес API, и учётные данные. Тестовый режим использует предпродуктивную среду и тестовые учётные данные, боевой режим — производственную среду и боевые учётные данные. По умолчанию: включено. Снимите отметку, чтобы принимать реальные платежи. Пока тестовый режим включён, покупатели видят под способом оплаты надпись Test mode — no real money is charged.

Тестовый аккаунт (предпродуктивная среда)

Test Merchant ID (PSPID): PSPID вашего тестового аккаунта.

Test API Key ID: API Key ID, созданный в разделе Developer > Payment API тестового аккаунта.

Test Secret API Key: Secret API Key, который относится к этому API Key ID.

Test Webhook Key ID: необязательно. Если указан, принимаются только вебхуки, отправленные с этим ключом.

Test Webhook Secret: секрет вебхука тестового аккаунта. Он используется для проверки подписи каждого вебхука.

Боевой аккаунт (производственная среда)

Live Merchant ID (PSPID): PSPID вашего боевого аккаунта.

Live API Key ID: API Key ID, созданный в разделе Developer > Payment API боевого аккаунта.

Live Secret API Key: Secret API Key, который относится к этому API Key ID.

Live Webhook Key ID: необязательно. Если указан, принимаются только вебхуки, отправленные с этим ключом.

Live Webhook Secret: секрет вебхука боевого аккаунта.

Проверка учётных данных

Кнопки Test credentials и Live credentials проверяют сохранённые учётные данные каждого аккаунта тестовым запросом к Worldline. Сначала сохраните изменения. Ответ появляется рядом с кнопками, например Test credentials: connection successful., API credentials are not configured. или ошибка, которую вернул Worldline.

Webhooks

Вебхук сообщает вашему магазину о платежах, даже если покупатель не возвращается в магазин, например после закрытия браузера или когда платёж подтверждается позже. В Merchant Portal откройте Developer > Webhooks тестового аккаунта и добавьте URL эндпоинта, который показан в этом разделе настроек. Он выглядит так: https://your-site/wc-api/wlg_worldline_webhook/. Скопируйте URL точно так, как он показан в настройках: он должен отвечать без перенаправлений, поэтому проверьте префиксы языка и принудительные перенаправления на www или https. Затем введите ID и секрет ключа вебхука в поля Test Webhook Key ID и Test Webhook Secret. Для боевого аккаунта сделайте то же самое с боевыми полями.

Плагин автоматически отвечает на проверочный запрос эндпоинта Worldline. Он обрабатывает события платежей (изменения статуса платежа) и события возвратов (изменения статуса возврата). Остальные события принимаются и игнорируются. Вебхуки без действительной подписи отклоняются. Вебхук также игнорируется, если он пришёл от другого Merchant ID, чем тот, к аккаунту которого относится подписавший его секрет. Без вебхука заказ подтверждается только тогда, когда покупатель возвращается в магазин после оплаты.

Страница оплаты и заказы

Payment page template: необязательное название шаблона (варианта) размещённой страницы оплаты, загруженного в Merchant Portal, например SimplifiedCustomPaymentPage. Оставьте поле пустым, чтобы использовать стандартную страницу оплаты Worldline.

Order Status After Payment: статус заказа после того, как Worldline подтвердит списанный платёж. Статус устанавливается сразу, без второго изменения. Платежи всегда запрашиваются как прямая продажа (авторизация и списание).

Logging: Enable debug logging записывает все запросы к API и вебхуки в WooCommerce > Status > Logs, источник wcp_worldline_gateway. Ошибки и предупреждения записываются всегда, даже когда эта опция выключена. Ключи, данные карт и персональные данные маскируются. По умолчанию: выключено.

Delete Data: Delete the plugin settings and logs when the plugin is deleted. Деактивация плагина ничего не удаляет. Платёжные данные, сохранённые в заказах, остаются, так как они нужны для возвратов. По умолчанию: выключено.

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

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

Покупатель выбирает способ оплаты (по умолчанию Worldline) и оформляет заказ. Плагин создаёт размещённую страницу оплаты Worldline на сумму заказа в валюте заказа и отправляет покупателя на страницу оплаты Worldline. Там покупатель платит картой, электронным кошельком или другим способом оплаты, включённым в вашем аккаунте Worldline. Имя, адрес, e-mail и телефон для выставления счёта передаются в Worldline, а страница оплаты открывается на языке вашего магазина, если Worldline его поддерживает. Каждая попытка оплаты получает собственный референс, состоящий из ID заказа и случайной части.

После оплаты покупатель возвращается в ваш магазин. Плагин сверяет возврат с сохранённой попыткой и на сервере запрашивает статус платежа у Worldline. Заказ отмечается как оплаченный только после подтверждения Worldline: этой проверкой статуса или подписанным вебхуком. Затем покупатель видит страницу «Заказ получен».

Если оплата не была завершена, покупатель переходит на страницу Pay for order с сообщением:

Покупатель может повторно оплатить неоплаченный заказ со страницы Pay for order. Если предыдущая попытка тем временем оплачена, покупатель сразу переходит на страницу «Заказ получен» и не платит дважды. Если предыдущая страница оплаты всё ещё открыта на ту же сумму и в том же режиме и была создана менее 30 минут назад, покупатель возвращается на неё.

Если Worldline не может начать платёж, покупатель видит сообщение Payment error: Could not create checkout session. Please try again. и может выбрать другой способ оплаты. Причина добавляется в примечания к заказу и в журнал. Если учётные данные текущего режима не заданы, покупатель видит сообщение This payment method is not available at the moment. Please choose another payment method.

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

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

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

Order statuses

Pending payment: покупатель был отправлен в Worldline и ещё не оплатил или Worldline ещё не подтвердил платёж. Примечание показывает ID размещённой страницы оплаты, референс и режим (тестовый или боевой).

Processing or Completed: платёж списан. Статус соответствует настройке Order Status After Payment. Примечание к заказу показывает сумму, ID платежа Worldline и способ подтверждения (подписанный вебхук или проверка статуса). ID транзакции заказа — это ID платежа Worldline.

On hold, waiting for capture: Worldline сообщает, что платёж авторизован или списание запрошено, но ещё не выполнено. Примечание к заказу объясняет это. Заказ автоматически отмечается как оплаченный, когда вебхук подтверждает списание. Если в примечании написано, что платёж не списан, спишите его в Merchant Portal Worldline.

On hold, held for manual review: платёж не соответствует заказу, например сумма или валюта отличаются (заказ был изменён после начала оплаты) или платёж относится к другой попытке. Примечание показывает оплаченную сумму, итог заказа и референс. Проверьте заказ и выполните его или сделайте возврат платежа.

Failed: Worldline отклонил или отменил платёж последней попытки либо покупатель не подходил для выбранного способа оплаты.

Cancelled: заказ отменён вами или по тайм-ауту резервирования товара в WooCommerce. Если платёж поступает для отменённого или возвращённого заказа, заказ не открывается заново. Примечание просит вас вернуть или отменить платёж в Merchant Portal Worldline либо восстановить заказ вручную. Вернувшийся покупатель видит сообщение Your payment was received after this order had been cancelled. Please contact us — we will restore the order or refund the payment.

Если для уже оплаченного заказа поступает второй платёж, заказ больше не меняется. Примечание просит вас вернуть второй платёж в Merchant Portal Worldline.

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Worldline (Ingenico). Поддерживаются полные и частичные возвраты. Платёж должен быть списан. Возврат всегда отправляется в среду исходного платежа (тестовую или боевую) с учётными данными этого аккаунта, поэтому они должны быть заданы. Возврат, повторно отправленный после тайм-аута, не выполняется дважды. Если Worldline отклоняет возврат, WooCommerce показывает ошибку и возврат не записывается. Принятый возврат добавляется в примечания к заказу с ID и статусом возврата Worldline.

Изменения статуса возвратов приходят от Worldline через вебхук и добавляются в примечания к заказу. Возвраты, оформленные в Merchant Portal, автоматически не записываются как возвраты WooCommerce. При необходимости создайте ручной возврат в WooCommerce без использования Refund via Worldline (Ingenico).

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

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

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

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

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

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

Worldline не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён и в текущем режиме заданы Merchant ID, API Key ID и Secret API Key: тестовые поля в тестовом режиме, боевые поля в боевом режиме. Если их нет, список платежей помечает способ оплаты как требующий настройки.

Платёж прошёл, но заказ остаётся в Pending payment: вебхук не работает. В Merchant Portal аккаунта, который вы используете (тестового или боевого), проверьте, что эндпоинт существует и его URL точно совпадает с показанным в настройках, без перенаправлений. Проверьте, что секрет вебхука этого аккаунта указан в соответствующем поле (Test Webhook Secret или Live Webhook Secret) и что Webhook Key ID пуст или совпадает с ключом. Заказ также подтверждается, когда покупатель возвращается в магазин после оплаты.

Вебхук отвечает Webhook secret not configured: не задан ни один секрет вебхука. Введите секрет вебхука в настройках. Worldline повторяет вебхук.

Вебхук отвечает Invalid signature: секрет вебхука относится к другому аккаунту или другому ключу, либо Webhook Key ID не совпадает с ключом, которым был отправлен вебхук.

Вебхук отвечает Missing signature, Empty body или Invalid JSON: запрос пришёл не от Worldline в ожидаемом виде либо его изменил прокси или перенаправление. Проверьте, что URL отвечает без перенаправлений.

Вебхук отвечает Ignored: вебхук пришёл от Merchant ID, отличного от указанного в настройках этого режима. Проверьте Test Merchant ID (PSPID) или Live Merchant ID (PSPID).

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

Test credentials или Live credentials показывает ошибку: сначала сохраните настройки, затем проверьте, что Merchant ID, API Key ID и Secret API Key относятся к одному аккаунту и что тестовые значения введены в тестовые поля, а боевые — в боевые.

Покупатель видит ошибку при оформлении заказа: откройте примечания к заказу или WooCommerce > Status > Logs, источник wcp_worldline_gateway. Ошибки записываются в журнал, даже если отладочный журнал выключен. Для полных сведений о запросах включите Logging и повторите попытку.

Тестовые платежи не подтверждают боевой заказ: тестовый и боевой режимы разделены. Вебхук, подписанный тестовым секретом, никогда не подтверждает боевую попытку оплаты, и наоборот. Переключите Test Mode на нужный режим и используйте учётные данные и вебхук этого аккаунта.

Заказ в статусе On hold после оплаты: прочитайте примечание к заказу. Либо Worldline ещё не подтвердил списание (вебхук завершит заказ), либо оплаченная сумма или валюта не совпали с заказом.

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

Разработчикам: фильтр wlg_hosted_checkout_data изменяет запрос к размещённой странице оплаты, например чтобы ограничить показываемые способы оплаты, а wlg_gateway_icon меняет значок способа оплаты.

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

Удаление

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

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