VibeFox Paytrail for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта: EUR. Paytrail приймає лише євро. Для кошика в іншій валюті спосіб оплати приховується на оформленні замовлення. Суми надсилаються в центах.

Доступ до магазину з інтернету: Paytrail підтверджує кожен платіж callback-викликом між серверами, тож магазин має бути доступним з інтернету. Без callback-викликів замовлення все одно створюються, коли покупець повертається з Paytrail.

Обліковий запис Paytrail: потрібні ваші Merchant ID і Secret key, які показано в панелі продавця Paytrail (дані облікового запису або інтеграції). Для тестування обліковий запис не потрібен: тестовий режим використовує публічний тестовий обліковий запис Paytrail. Самі способи оплати вмикаються у вашому обліковому записі Paytrail.

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

Встановлення

1. У Back Office перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

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

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

4. Щоб спершу спробувати модуль, увімкніть Test mode. Для реальних платежів вимкніть його та введіть ваш Merchant ID і Secret key. В Paytrail не потрібно налаштовувати жодну URL-адресу callback.

5. Увімкніть Enable/Disable і натисніть Save.

Під час встановлення модуль створює два статуси замовлення: Awaiting Paytrail payment і Paytrail payment on hold. PrestaShop пропонує новий платіжний модуль для всіх валют, країн і груп клієнтів. Його можна обмежити в розділі Payment > Preferences.

Налаштування

Усі параметри розміщено на сторінці модуля: Modules > Module Manager > VibeFox Paytrail Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує Test mode is active. Payments use the public Paytrail test account — no real money is charged., поки ввімкнено тестовий режим. У бойовому режимі вона попереджає, якщо не вказано Merchant ID або Secret key, якщо Merchant ID — публічний тестовий обліковий запис 375917, а також якщо валюта магазину не EUR. У всіх цих випадках Paytrail не показується на оформленні замовлення.

Під час збереження Merchant ID, що містить щось інше, ніж цифри, не зберігається, і з'являється помилка Paytrail merchant ID must contain digits only. The previous value was kept.. Поле Title не може бути порожнім.

Paytrail

Enable/Disable: Enable Paytrail вмикає або вимикає спосіб оплати. За замовчуванням: off.

Title: назва, яку бачить покупець під час оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Paytrail. Обов'язкове поле.

Description: текст, який покупець бачить під способом оплати на оформленні замовлення. За замовчуванням: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

Облікові дані API

Ваш Merchant ID та Secret key показано в панелі продавця Paytrail (дані облікового запису або інтеграції). Розділ містить посилання на панель продавця. Підтримуються лише платежі в EUR.

Test mode: використовує публічний тестовий обліковий запис Paytrail (Merchant ID 375917) для нових платежів замість ваших власних облікових даних. Реальні гроші не списуються, ключі не потрібні. Покупці бачать Test mode: no real payment will be made. під способом оплати. Secret key тестового облікового запису є публічним, тож будь-хто міг би імітувати платіж, здійснений у тестовому режимі. Ніколи не залишайте тестовий режим увімкненим у робочому магазині. За замовчуванням: off.

Merchant ID: ваш Merchant ID Paytrail (лише цифри). Використовується, коли тестовий режим вимкнено.

Secret key: ваш Secret key Paytrail. Використовується, коли тестовий режим вимкнено. Збережений ключ більше ніколи не показується. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Clear saved secret key: позначте Secret key і натисніть Save, щоб видалити збережений ключ. Порожнє поле зберігає збережене значення.

Callback-виклики та повернення коштів завжди використовують облікові дані того режиму, у якому було здійснено платіж, тож перемикання між тестовим і бойовим режимом не порушує старі замовлення.

Замовлення

Callback URL: показує адресу, за якою Paytrail підтверджує кожен платіж між серверами. З дружніми URL вона має такий вигляд: https://your-shop/module/wcp_paytrail_gateway/callback. Вона надсилається з кожним платежем, тож у панелі Paytrail нічого налаштовувати не потрібно, але магазин має бути доступним з інтернету.

Order status after payment: статус оплаченого замовлення.

Платежі в очікуванні чекають у статусі Awaiting Paytrail payment. Розбіжності сум та інші проблеми завжди переводять замовлення в статус Paytrail payment on hold.

Додатково

Debug log: записує запити до API та callback-виклики у файл logs/ptg_debug.log.php у папці модуля. Файл неможливо відкрити через веб. Персональні дані та ключі не записуються. Помилки та попередження завжди записуються. За замовчуванням: off.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб очистити його.

Delete data on uninstall: якщо ввімкнено, видалення модуля видаляє налаштування та журнал. Вимкнення модуля нічого не видаляє. Дані транзакцій Paytrail за замовленнями завжди зберігаються, бо для повернень коштів за старими замовленнями вони потрібні. За замовчуванням: off.

Оформлення замовлення

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Paytrail) і підтверджує вибір. Модуль створює платіж Paytrail на суму кошика в євро та надсилає з ним рядки замовлення: товари після правил кошика, доставку та подарункове пакування, кожен із власною ставкою ПДВ з точністю до одного десяткового знака. Рядки завжди в сумі дають суму платежу; різниця округлення включається до одного з рядків або надсилається як окремий рядок Rounding. Адреси для виставлення рахунку та доставки надсилаються лише тоді, коли вони повні, а задовгі значення скорочуються до обмежень Paytrail. Мова платіжної сторінки — фінська, шведська або англійська, залежно від мови кошика. На цьому етапі замовлення ще не існує.

Покупець переходить на платіжну сторінку Paytrail, обирає спосіб оплати, увімкнений для вашого облікового запису Paytrail, і сплачує. Потім Paytrail підтверджує платіж двічі: повертає покупця до вашого магазину та викликає URL callback між серверами. Обидва підтвердження приймаються лише з дійсним підписом, створеним обліковими даними цієї спроби оплати, і лише для спроби, створеної для цього кошика. Сплачена сума порівнюється із загальною сумою кошика. Замовлення позначається як оплачене лише після такого підтвердження від Paytrail. Модуль обробляє такі статуси Paytrail:

Після успішної оплати покупець бачить стандартну сторінку підтвердження замовлення з написом Your Paytrail payment has been received. Для платежу в очікуванні сторінка показує Your Paytrail payment is pending confirmation by the payment provider. The order is updated automatically — please do not pay again. Якщо callback саме зараз фіксує платіж, сторінка Payment confirmation просить покупця не платити знову та пропонує кнопку Check again.

Після скасованого або невдалого платежу покупець повертається до оформлення замовлення з повідомленням The Paytrail payment was cancelled or failed. You can try again or choose another payment method. Якщо платіж ще не завершено, повідомлення таке: The Paytrail payment has not been completed yet. You can try again or choose another payment method. Кошик зберігається. Повернення, яке неможливо перевірити, показує Payment verification failed. і нічого не змінює.

Якщо Paytrail не може розпочати платіж, покупець залишається на оформленні замовлення з коротким повідомленням, наприклад Could not connect to Paytrail. Please try again in a moment., Paytrail is temporarily unavailable. Please choose another payment method. (неправильні облікові дані) або Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method. Технічна причина записується в журнал. Сума поза межами Paytrail показує This order total cannot be paid with Paytrail. Please choose another payment method.

Платіж Paytrail не можна скасувати через API. Кожна нова спроба для кошика — це новий платіж Paytrail. Якщо покупець також оплатить старішу, але ще відкриту платіжну сторінку, другий платіж позначається в замовленні як дублікат для повернення коштів.

Callback працює, поки магазин перебуває в режимі обслуговування, і не блокується обмеженням за країнами вашого магазину.

Покупець обирає спосіб оплати на сторінці Paytrail, а не у вашому оформленні замовлення. Модуль не має токенізації карток та збережених карток, підписок, shop-in-shop, ручної активації рахунків-фактур і звітів про взаєморозрахунки.

Замовлення та повернення коштів

Статуси замовлення

Замовлення ще немає: покупця було перенаправлено до Paytrail, і він не сплатив, або Paytrail ще не підтвердив платіж. Існує лише кошик.

Payment accepted or Delivered: платіж підтверджено. Статус відповідає Order status after payment. Платіж записується з ідентифікатором транзакції Paytrail, а примітка показує транзакцію, спосіб оплати в Paytrail та суму.

Awaiting Paytrail payment: платіж очікує в провайдера (рахунок або відкладений платіж). Замовлення переходить в оплачений статус, коли Paytrail підтверджує платіж, або в Payment error, якщо платіж не пройшов.

Paytrail payment on hold: сплачена сума відрізняється від загальної суми замовлення (фіксується фактично сплачена сума), платіж надійшов після скасування замовлення, або тестовий платіж отримано, поки магазин працює в бойовому режимі (реальних грошей немає, нічого не записується). Примітка пояснює причину. Перевірте замовлення, потім опрацюйте його або поверніть платіж.

Payment error: платіж в очікуванні не пройшов або був скасований.

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

Повторні або паралельні callback-виклики ніколи не створюють друге замовлення чи дублікати приміток. Якщо оплачено другу спробу вже оплаченого кошика, замовлення не змінюється; примітка Duplicate payment просить вас повернути цей платіж у панелі продавця Paytrail.

Блок платежу Paytrail

На сторінці замовлення показано блок Paytrail payment з ідентифікатором транзакції, режимом (позначка TEST mode для тестових платежів), способом оплати, статусом Paytrail, сплаченою та поверненою сумою, формою повернення, історією повернень, спробами оплати кошика та Paytrail notes замовлення.

Повернення коштів

У блоці Paytrail payment введіть суму (підставляється сума, яка ще не повернута), за потреби причину для примітки до замовлення, і натисніть Refund via Paytrail. Підтвердьте питання Refund this amount through Paytrail? This cannot be undone. Підтримуються повні та часткові повернення, лише за сумою. Потрібне право редагувати замовлення; доступ до сторінок модулів не потрібен. Можна повернути не більше суми, яку Paytrail фактично отримав, тож після розбіжності за сумою межею буде сума, сплачена покупцем, а не загальна сума замовлення. Повернення використовує облікові дані того режиму, у якому пройшов платіж, тому для бойового платежу мають бути вказані бойові облікові дані. Повернення доступні після підтвердження платежу Paytrail.

Якщо спосіб оплати не підтримує прямі повернення, модуль автоматично запускає повернення електронною поштою: Paytrail надсилає покупцеві лист із проханням вказати банківський рахунок. Для цього в замовленні потрібна електронна адреса покупця. У примітці зазначено, який вид повернення запущено.

Повернення може бути виконано одразу або оброблено пізніше. Подальше підтвердження від Paytrail додається приміткою. Якщо Paytrail не зміг виконати повернення, примітка повідомить, що гроші покупцеві не повернуто, і повернення більше не вважається виконаним; поверніть кошти покупцеві іншим способом. Якщо Paytrail одразу відхиляє повернення, блок показує помилку, і повернення не реєструється. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює.

Модуль не створює кредитні ноти. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через Paytrail. Повернення, здійснені в панелі продавця Paytrail, не синхронізуються назад із PrestaShop.

Ліцензійний ключ

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

Без активного ключа Paytrail не показується покупцям на оформленні замовлення. Якщо оплату все ж розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви увійшли до back office, тож спосіб оплати приховано і для вас: модуль можна налаштувати до купівлі ключа, але протестувати його на оформленні замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: платежі, що вже розпочато, як і раніше підтверджуються callback-викликами та поверненням покупця, а повернення коштів працюють.

Коли ліцензія спливає, модуль продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється знову, поки ви працюєте в back office: раз на день протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення або скидання модуля завжди видаляє ліцензійний ключ і статус ліцензії.

Усунення несправностей

Paytrail не з'являється на оформленні замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і або Test mode увімкнено, або Merchant ID та Secret key заповнені (а не публічний тестовий обліковий запис 375917). Перевірте, що валюта кошика — EUR. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця. На сторінці налаштувань з'являється попередження при відсутніх облікових даних та неправильній валюті магазину.

Платіж пройшов, але замовлення не створено: callback не може достукатися до вашого магазину, а покупець не повернувся до магазину. Callback URL з розділу Замовлення має бути доступним з інтернету (без базової автентифікації та без блокування файрволом).

Callback або повернення відповідає Payment verification failed.: підпис недійсний, або платіж не належить до спроби оплати цього кошика. Нічого не змінюється. Перевірте, що Secret key правильний і належить до Merchant ID.

Callback відповідає Temporarily unavailable: замовлення в цей момент підтверджувалося іншим запитом, або замовлення не вдалося створити (наприклад, модуль вимкнено). Paytrail викличе ще раз. Причину дивіться в полі Log.

Покупець бачить помилку під час вибору Paytrail: дивіться поле Log на сторінці модуля. Наприклад, Paytrail API error (401) означає неправильні облікові дані. Увімкніть Debug log для деталей.

Merchant ID не зберігається: він має містити лише цифри. Скопіюйте його знову з панелі продавця Paytrail.

Замовлення має статус Paytrail payment on hold: прочитайте примітки в блоці Paytrail payment. Причина — інша сплачена сума, платіж після скасування або тестовий платіж у бойовому режимі.

Повернення не вдається: прочитайте повідомлення. This order has no confirmed Paytrail payment. Refund it manually. означає, що немає підтвердженого платежу Paytrail для повернення. The live Paytrail credentials used for this payment are missing. Enter them in the Paytrail settings. означає, що платіж пройшов у бойовому режимі, а бойові облікові дані не вказано. Invalid refund amount: at most … означає, що сума більша за залишок для повернення. Якщо спосіб оплати підтримує лише повернення електронною поштою, замовленню потрібна електронна адреса покупця.

Хук для розробників: хук actionWcpPaytrailPaymentRequest змінює запит на оплату до підписання та надсилання.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Paytrail Gateway і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete data on uninstall увімкнено, налаштування та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для майбутнього повторного встановлення. Транзакції та повернення Paytrail, а також статуси замовлення Awaiting Paytrail payment і Paytrail payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна буде повернути й після повторного встановлення. Наявні замовлення зберігають свої примітки про платежі та ідентифікатори транзакцій.

Paytrail — торговельна марка її власника. Цей модуль не пов'язаний із Paytrail і не схвалений нею.