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.

Спосіб оплати працює на класичному оформленні замовлення, у блоці Checkout і на сторінці 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.