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

Вимоги

PrestaShop: 8.0–9.x.

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

Обліковий запис finby (TrustPay): потрібен проєкт у finby Merchant Portal з його Project ID та Secret key. Для тестових платежів потрібен окремий тестовий проєкт (playground) з власними Project ID та Secret key. Інші ключі не потрібні: Secret key використовується і для доступу до API, і для перевірки підпису сповіщень про платежі.

Доступна URL сповіщень: finby має мати змогу звернутися до вашого магазину з інтернету. Брандмауер, логін для технічного обслуговування або HTTP-автентифікація перед магазином блокують сповіщення про платежі.

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

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

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

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

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

4. Введіть Project ID та Secret key свого тестового проєкту і, для реальних платежів, робочого проєкту (див. розділ Налаштування).

5. Увімкніть Enable / Disable і натисніть Save. Здійсніть тестовий платіж з увімкненим Test mode, а потім вимкніть Test mode, щоб приймати реальні платежі.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox TrustPay Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо модуль увімкнено, але Project ID або Secret key поточного режиму порожні, а також якщо валюта магазину за замовчуванням не підтримується. В обох випадках спосіб оплати приховується в оформленні замовлення.

TrustPay / finby

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

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

Description: текст під способом оплати в оформленні замовлення. За замовчуванням: Pay securely by card on the TrustPay / finby payment page.

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

Скопіюйте Project ID та Secret key вашого проєкту з finby (TrustPay) Merchant Portal. У розділі є посилання на Merchant Portal. Тестові платежі використовують окремий тестовий проєкт (playground) з власними Project ID та Secret key. Реальні кошти там не списуються.

Test mode: використовує тестовий проєкт (без реальних платежів). Нові платежі та повернення використовують тестові облікові дані. Повернення за замовленням завжди надсилаються на той проєкт, через який було оплачено замовлення. За замовчуванням: on. Поки він увімкнений, покупці бачать під способом оплати напис Test mode: no real payment will be taken.

Live Project ID: числовий Project ID вашого робочого проєкту.

Live Secret key: Secret key робочого проєкту. Він використовується для отримання токенів доступу до API та для перевірки сповіщень про платежі.

Test Project ID: числовий Project ID вашого тестового проєкту (playground).

Test Secret key: Secret key тестового проєкту.

Project ID має містити лише цифри. Якщо ви збережете інше значення, сторінка покаже must contain digits only — the previous value was kept., а решта полів буде збережена. Secret key зберігаються саме так, як ви їх ввели; видаляються лише пробіли на початку та в кінці. Збережені Secret key більше ніколи не показуються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Збереження налаштувань також скидає кешовані токени доступу до API, тож нові облікові дані застосовуються одразу.

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

Сповіщення про платежі

Замовлення позначається оплаченим лише після того, як finby підтверджує його підписаним сповіщенням. Модуль автоматично надсилає URL сповіщень із кожним платежем, тож налаштовувати його не потрібно. Розділ показує URL під Notification URL. При зрозумілих URL він має вигляд https://your-shop/module/wcp_trustpay_gateway/callback, можливо з кодом мови. Його також можна вказати як URL сповіщень ваших проєктів у Merchant Portal. Сповіщення без дійсного підпису відхиляються.

Модуль сам не запитує у finby статус платежу. Якщо сповіщення не може дійти до вашого магазину, замовлення не створюється, доки finby його не доставить. finby повторює сповіщення.

Додатково

Order status after payment: статус замовлення, який встановлюється після успішної оплати. Статус встановлюється за один крок, тож покупець отримує один лист.

Debug logging: записує запити до API та сповіщення в logs/trustpay_p_debug.log.php у папці модуля. Цей файл не можна відкрити з веб-браузера. Помилки записуються завжди, навіть якщо цю опцію вимкнено. Журнал не містить ключів, токенів, даних картки чи даних покупців. За замовчуванням: off.

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

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

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

На кроці оплати покупець обирає спосіб оплати (за замовчуванням Card payment (TrustPay)) і підтверджує замовлення. Спосіб оплати пропонується лише у підтримуваних валютах: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF та USD. Суми в HUF надсилаються без копійок.

Для оплати карткою потрібна адреса. Якщо немає вулиці, міста, поштового індексу або країни, покупець бачить Please enter your billing address (street, city, postcode and country) — it is required for card payments.

Модуль створює у finby запит на оплату карткою на суму кошика у валюті кошика. Ім'я, адреса та e-mail покупця передаються для 3-D Secure, а номер кошика надсилається як посилання. На цьому етапі замовлення ще не існує. Покупець перенаправляється на сторінку оплати finby і сплачує карткою там. Сторінка відкривається мовою кошика, якщо finby її підтримує, інакше англійською.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після того, як finby підтверджує його підписаним сповіщенням. Саме повернення ніколи не змінює статус оплати. Якщо сповіщення вже надійшло, покупець бачить стандартну сторінку підтвердження замовлення. Якщо ні, з'являється сторінка Payment confirmation, яка повідомляє, що finby підтверджує оплату карткою і що замовлення буде створено одразу після підтвердження. На ній є кнопка Check again і кнопка Back to checkout. Поки замовлення має статус Awaiting TrustPay payment або TrustPay payment on hold, сторінка підтвердження показує Your card payment is being confirmed by TrustPay / finby. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Якщо finby відхилив платіж або неоплачене замовлення було скасовано, вона показує Your card payment was not completed. Please contact us about this order.

Якщо покупець скасовує платіж на сторінці оплати, він повертається до оформлення замовлення з повідомленням The card payment was cancelled. You can try again or choose another payment method. Якщо сторінка оплати повертає помилку або finby вже відхилив платіж, з'являється повідомлення The card payment was not completed. Please try again or choose another payment method. Кошик зберігається, і покупець може оплатити знову.

Якщо finby не може розпочати платіж, покупець залишається в оформленні замовлення з повідомленням We could not start the card payment. Please try again in a moment or choose another payment method. Технічна причина записується в журнал.

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

Модуль приймає лише оплату картками як покупку в один крок на сторінці finby. Він не підтримує банківські перекази та інші способи оплати finby, кнопки Apple Pay чи Google Pay на вашому сайті, збережені картки, підписки або періодичні платежі, окремі авторизацію та списання, а також перевірку статусу.

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

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

No order yet: покупця перенаправили до finby, і він не сплатив, або сповіщення ще не надійшло. Існує лише кошик.

Payment accepted or Delivered: finby підтвердив платіж, а сума та валюта збігаються із запитом на оплату і сумою кошика. Статус відповідає Order status after payment. Платіж записується з ID запиту на оплату finby як ID транзакції, а примітка показує суму, запит на оплату та проєкт (тестовий або робочий).

Awaiting TrustPay payment: finby повідомив, що останній платіж очікує обробки. Замовлення переходить в оплачений статус, коли finby підтверджує платіж.

TrustPay payment on hold: встановлюється в двох випадках. Платіж лише авторизовано, але не списано: спишіть або скасуйте його у finby Merchant Portal, а потім оновіть замовлення. Або сплачена сума чи валюта відрізняються від запиту на оплату або суми кошика, наприклад тому, що кошик змінили після того, як покупця перенаправили на сторінку оплати: перевірте платіж перед відправленням. Примітка пояснює випадок.

Payment error: finby відхилив останній платіж за замовленням, що очікувало оплати. Примітка показує причину, коли finby її надсилає. Підтверджений пізніше платіж усе одно переводить замовлення в оплачений статус.

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

Скасовані або повернені замовлення ніколи не відкриваються знову через запізнілий платіж. Примітка просить відновити замовлення або повернути платіж у Merchant Portal. Якщо надходить другий платіж за вже оплачене замовлення, замовлення не змінюється, а примітка просить повернути дублікат у Merchant Portal. Чарджбеки та спори, про які повідомляє finby, додаються як примітки.

Блок оплати TrustPay / finby

На сторінці замовлення відображається блок TrustPay / finby payment з ID запиту на оплату, ID платежу finby, проєктом, статусом платежу, запитаною та сплаченою сумами, сумою повернення, позначкою Test project для тестових платежів, історією повернень і TrustPay notes замовлення.

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

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

Повернення надсилається на той проєкт, через який було оплачено замовлення (тестовий або робочий), навіть якщо ви з того часу змінили режим. Для цього проєкту мають бути вказані Project ID та Secret key, а його Project ID не мав змінитися. Повернення фіксується лише тоді, коли finby його приймає. Інакше блок показує TrustPay refused the refund: з причиною, і повернення не записується. Успішне повернення додається до історії повернень і приміток. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює.

Модуль не створює кредитових нот (credit slips). Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через finby. Повернення, здійснені у finby Merchant Portal, не фіксуються як повернення. Якщо finby надсилає про них сповіщення, воно додається як примітка, а статус замовлення не змінюється.

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

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

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

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

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

Card payment (TrustPay) не з'являється в оформленні замовлення: перевірте, що ліцензія активна, Enable / Disable увімкнено і поточний режим має Project ID та Secret key: Test Project ID та Test Secret key у тестовому режимі, Live Project ID та Live Secret key у робочому режимі. Валюта кошика має бути однією з підтримуваних. Сторінка налаштувань показує попередження, коли облікових даних немає або валюта за замовчуванням не підтримується. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: сповіщення не дійшло до вашого магазину. Перевірте, що URL, який показано під Notification URL, доступний з інтернету (без брандмауера, логіна для обслуговування та HTTP-автентифікації). finby повторює сповіщення, і замовлення створюється, коли воно надходить. Увімкніть Debug logging і перегляньте поле Log на сторінці модуля.

Журнал показує Notification rejected: invalid signature or unknown project: сповіщення надійшло від проєкту, Project ID якого немає в налаштуваннях, або Secret key цього проєкту невірний. Магазин відповідає Invalid signature, і нічого не змінюється. Перевірте Project ID та Secret key того режиму, у якому було здійснено платіж.

Журнал показує Notification ignored: сповіщення належить до запиту на оплату, який цей магазин не створював для цього кошика, або до іншого проєкту чи режиму, ніж той, з яким було розпочато платіж. Нічого не змінюється.

Сповіщення отримує відповідь Busy, retry later або Temporary error: кошик у цей момент оновлювало інше сповіщення, або замовлення не вдалося створити (наприклад, модуль вимкнено). finby повторить сповіщення. Журнал показує причину.

Покупець бачить We could not start the card payment: відкрийте журнал. Невірний Project ID або Secret key дають повідомлення, що finby відхилив облікові дані проєкту. Перевірте, що тестові дані внесено в тестові поля, а робочі — в робочі.

Card payment is temporarily unavailable: покупець бачить це, коли в поточному режимі немає Project ID або Secret key. Введіть їх і збережіть.

Замовлення має статус TrustPay payment on hold: прочитайте примітки в блоці TrustPay / finby payment (див. Статуси замовлень). Перевірте платіж у Merchant Portal перед відправленням, а потім виконайте замовлення або поверніть платіж.

Повернення не виконується з повідомленням про проєкт: замовлення було оплачено через тестовий або робочий проєкт, а Project ID чи Secret key цього режиму не встановлено, або там тепер збережено інший Project ID. Введіть облікові дані цього проєкту або поверніть платіж у finby Merchant Portal.

Invalid refund amount: at most … can be refunded: сума більша за сплачену мінус повернення, уже здійснені через модуль.

Видалення

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

TrustPay і finby є торговельними марками своїх власників. Цей модуль не пов'язаний із TrustPay чи finby і не схвалений ними.