VibeFox Worldline for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

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

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

Установка

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

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Worldline Gateway в списке модулей и нажмите Configure.

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

4. Введите тестовые учётные данные, нажмите Save, а затем Test credentials.

5. Добавьте URL вебхука в Merchant Portal тестового аккаунта и введите ключ и секрет вебхука (см. раздел Конфигурация).

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

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

Конфигурация

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Worldline Gateway > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если учётные данные текущего режима (Merchant ID, API Key ID, Secret API Key) заполнены не полностью, потому что в этом случае способ оплаты скрывается при оформлении заказа. Пока включён тестовый режим, страница показывает Test mode is on (pre-production environment): no real money is charged.

Worldline (Ingenico)

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

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

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

Worldline Direct API

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

Test Mode: переключает и адрес 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: секрет вебхука боевого аккаунта.

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

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

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

Вебхуки

Вебхук сообщает вашему магазину о платежах даже тогда, когда покупатель не возвращается в магазин, например после закрытия браузера или когда платёж подтверждается позже. В Merchant Portal откройте Developer > Webhooks тестового аккаунта и добавьте URL, который указан в поле Endpoint URL в этом разделе. При использовании понятных URL он выглядит так: https://your-shop/module/wcp_worldline_gateway/webhook, возможно, с кодом языка, например /en/. Копируйте URL точно так, как он показан в настройках: он должен отвечать без перенаправлений. Затем введите ID и секрет ключа вебхука в поля Test Webhook Key ID и Test Webhook Secret. То же самое сделайте в боевом аккаунте, используя боевые поля.

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

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

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

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

Авторизованные платежи ожидают в статусе Awaiting Worldline capture. Несовпадения суммы или валюты всегда переводят заказ в Worldline payment on hold.

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

Logging: записывает все запросы к API и вебхуки в logs/wlg_debug.log.php в папке модуля. Этот файл нельзя открыть через браузер. Ошибки и предупреждения записываются всегда, даже когда опция выключена. Ключи, данные карт и персональные данные маскируются. По умолчанию: выключено.

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

Delete Data: если включено, при удалении модуля удаляются его настройки и журнал. Транзакции и возвраты Worldline, а также статусы заказов модуля всегда сохраняются, потому что существующим заказам они нужны для возвратов. По умолчанию: выключено.

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

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

После оплаты покупатель возвращается в ваш магазин. Модуль сверяет возврат с сохранённой попыткой и на сервере запрашивает у Worldline статус платежа. Заказ помечается как оплаченный только после подтверждения Worldline: этой проверкой статуса или подписанным вебхуком. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с сообщением Your payment with Worldline has been received. Если платёж авторизован, но ещё не захвачен, страница показывает Your payment is authorized. The order is confirmed as soon as Worldline confirms the capture. Если платёж такого заказа позже не пройдёт, страница показывает Your Worldline payment was not completed. Please contact us about this order.

Если платёж не был завершён, заказ не создаётся, корзина сохраняется, а покупатель возвращается к оформлению заказа с сообщением:

Если статус ещё не удалось проверить, страница Payment confirmation показывает We could not confirm your payment yet. If you completed the payment, please do not pay again — you will receive a confirmation as soon as Worldline confirms it. с кнопками Check again и Back to checkout. Вебхук создаст заказ сразу же, как только придёт.

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

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

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

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

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

No order yet: покупатель был отправлен в Worldline и не оплатил или Worldline ещё не подтвердил платёж. Существует только корзина.

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

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

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

Payment error: Worldline отклонил или отменил платёж по заказу, который ожидал захвата.

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

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

Блок оплаты Worldline

На странице заказа показан блок Worldline payment с ID платежа, референсом мерчанта, размещённой страницей оплаты, статусом попытки, списанной и возвращённой суммой, меткой Test environment для тестовых платежей, историей возвратов и Payment notes заказа.

Возвраты

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

Модуль не создаёт кредитовых счетов (credit slips). Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Worldline.

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

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

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

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

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

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

Worldline не появляется при оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включено и что в текущем режиме заполнены Merchant ID, API Key ID и Secret API Key: в тестовом режиме — тестовые поля, в боевом — боевые. Страница настроек показывает предупреждение, если они не заполнены. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

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

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

Если вебхук отвечает Invalid signature: секрет вебхука принадлежит другому аккаунту или другому ключу, либо ID ключа вебхука не совпадает с ключом, которым был отправлен вебхук. Проверьте, что тестовый и боевой секреты не перепутаны.

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

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

Если вебхук отвечает Retry later: заказ в этот момент подтверждался другим запросом или заказ не удалось создать (например, модуль отключён). Worldline повторит вебхук. Причину смотрите в поле Log.

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

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

Покупатель видит ошибку при выборе Worldline: посмотрите поле Log на странице модуля. Ошибки записываются в журнал, даже если Logging выключено. Чтобы увидеть подробности запросов, включите Logging и повторите попытку.

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

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

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

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

Удаление

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

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