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 для модуля. Тексти блоку відповідають мові back office (включено англійську та російську).

Якщо ключ не приймається, блок пояснює причину, наприклад 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 не знає, що ви ввійшли в back office, тож спосіб оплати приховано і для вас: модуль можна налаштувати до купівлі ключа, але не можна перевірити на етапі оформлення замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не зачіпаються: платежі, які вже розпочато, і далі підтверджуються, а повернення працюють.

Коли ліцензія спливає, модуль продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється, поки ви працюєте в back office: раз на день протягом перших 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 і не схвалений нею.