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

Вимоги

WordPress: 6.0 або новіша версія.

WooCommerce: 7.0 або новіша версія, встановлений і активний. Плагін не активується без нього.

PHP: 8.0 або новіша версія.

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

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

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

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

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна та натисніть Install Now. Також можна завантажити папку wcp_trustpay_gateway до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > TrustPay / finby або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії вгорі сторінки та натисніть Activate.

5. Введіть Project ID та Secret key робочого проєкту, а для тестів — тестового проєкту (див. розділ Configuration).

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

Під час оновлення з версії 1.0 ваші Project ID та Secret key зберігаються як робочі облікові дані, а тестовий режим вимикається. Перевірте налаштування після оновлення.

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

Усі налаштування розміщені на одній сторінці: WooCommerce > Settings > Payments > TrustPay / finby. Над полями сторінка попереджає, якщо шлюз увімкнено, але Project ID або Secret key поточного режиму порожні, а також коли валюта магазину не підтримується. В обох випадках спосіб оплати приховується під час оформлення замовлення. У списку способів оплати шлюз позначено як такий, що потребує налаштування, доки в поточному режимі не буде Project ID та Secret key.

General

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

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

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

API credentials

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

Test mode: Use the test project (no real payments). Нові платежі та повернення використовують тестові облікові дані. Повернення за замовленням завжди надсилаються на той проєкт, через який було оплачено замовлення. За замовчуванням: увімкнено.

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

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

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

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

Project ID має містити лише цифри. Якщо ви збережете інше значення, сторінка покаже помилку, а попереднє значення збережеться. Secret key зберігаються саме так, як ви їх ввели; видаляються лише пробіли на початку та в кінці.

Payment notifications

Замовлення позначається оплаченим лише після того, як finby підтвердить платіж підписаним сповіщенням. Плагін автоматично надсилає URL для сповіщень з кожним платежем, тому налаштовувати його не потрібно. У розділі показано URL, наприклад https://your-site/wc-api/trustpay_payment_callback/. Ви також можете вказати його як URL сповіщень ваших проєктів у Merchant Portal. Сповіщення без дійсного підпису відхиляються.

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

Advanced

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

Debug logging: Log API requests and notifications додає деталі до журналу. Помилки завжди записуються в журнал, навіть коли ця опція вимкнена. Журнали розташовані в WooCommerce > Status > Logs, джерело wcp_trustpay_gateway, і не містять ключів, токенів, даних картки чи покупців. За замовчуванням: вимкнено.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (order data is kept). За замовчуванням: вимкнено.

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

Покупець обирає спосіб оплати (за замовчуванням Card payment (TrustPay)) і оформлює замовлення. У тестовому режимі під описом на сторінці оформлення відображається Test mode: no real payment will be taken.

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

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

Після оплати покупець повертається на сторінку «Замовлення отримано» вашого магазину, а кошик очищується. Замовлення позначається оплаченим лише тоді, коли finby підтверджує оплату підписаним сповіщенням. Саме повернення ніколи не змінює статус оплати.

Якщо покупець скасовує оплату на сторінці оплати або сторінка оплати повертає помилку, покупець повертається на сторінку Pay for order з повідомленням The card payment was cancelled. You can try again or choose another payment method. або 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. Технічна причина записується в журнал.

Валюти: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF та USD. Суми в HUF надсилаються без десяткових знаків. На сторінці Pay for order перевіряється валюта замовлення.

Спосіб оплати працює в класичному оформленні замовлення, у блоці Checkout і на сторінці Pay for order. Він сумісний з WooCommerce High-Performance Order Storage (HPOS). Плагін постачається з перекладами англійською, словацькою та чеською.

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

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

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

Pending payment: покупця перенаправлено до finby, і він ще не сплатив, або сповіщення ще не надійшло.

Processing or Completed: finby підтвердив оплату, а сума та валюта збігаються із запитом на оплату та сумою замовлення. Статус відповідає налаштуванню Order status after payment. У примітці до замовлення показано суму, запит на оплату та проєкт. ID транзакції — це ID запиту на оплату finby.

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

Failed: finby відхилив останній платіж за замовленням. Примітка показує причину, якщо finby її надіслав. Покупець може повторно оплатити через Pay for order.

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

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

Відкрийте замовлення, натисніть Refund, введіть суму та натисніть Refund via Card payment (TrustPay) (на кнопці відображається ваш Title). Підтримуються повні та часткові повернення. Повернення надсилається на той проєкт, через який було оплачено замовлення (тестовий або робочий), навіть якщо ви з того часу змінили режим, тож Project ID та Secret key цього режиму мають бути заповнені. Повернення в HUF мають бути цілими сумами.

Повернення фіксується лише тоді, коли finby його приймає. Інакше WooCommerce показує TrustPay refused the refund: з причиною, і повернення не створюється. Успішне повернення додається до приміток замовлення.

Повернення, зроблені в finby Merchant Portal, не фіксуються як повернення WooCommerce. Якщо finby надсилає про них сповіщення, воно додається як примітка до замовлення, а статус замовлення не змінюється.

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розташований угорі сторінки WooCommerce > Settings > Payments > TrustPay / finby. Вставте ключ у поле License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, і ваш домен. Скористайтеся Check now, щоб перевірити статус ще раз, Change key, щоб ввести інший ключ, і Remove key, щоб видалити його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.

Один ключ працює на одному домені. Видалення ключа з сайту не звільняє місце для домену. Звільніть його у своєму обліковому записі vibefox.net.

Без активного ключа спосіб оплати не показується покупцям під час оформлення замовлення. Якщо оплату все ж розпочато, покупець бачить This payment method is not available. Please choose another one. Авторизовані менеджери магазину й далі бачать спосіб оплати з позначкою (unlicensed — visible to admins only), щоб ви могли налаштувати й протестувати плагін до купівлі ключа. Нагадування з'являється на сторінці Plugins і на сторінках WooCommerce. Наявні замовлення не змінюються: вже розпочаті платежі все одно підтверджуються, а повернення працюють.

Коли ліцензія закінчується, плагін продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється знову у фоновому режимі.

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

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

Платіж пройшов, але замовлення залишається в статусі Pending payment: сповіщення не дійшло до вашого магазину. Перевірте, що https://your-site/wc-api/trustpay_payment_callback/ доступний з інтернету (без брандмауера, режиму обслуговування та захисту паролем). finby повторює сповіщення. Перегляньте WooCommerce > Status > Logs, джерело wcp_trustpay_gateway.

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

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

Сповіщення отримує відповідь Busy, retry later: замовлення в цей момент оновлювало інше сповіщення. finby повторить його.

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

Оплата карткою тимчасово недоступна: покупець бачить це повідомлення, коли в поточному режимі немає Project ID або Secret key. Введіть їх і збережіть.

Замовлення має статус On hold з приміткою про розбіжність суми або валюти: сповіщення було справжнім, але сплачена сума чи валюта відрізняються від запиту на оплату або суми замовлення. Перевірте платіж у Merchant Portal перед відправкою, а потім виконайте замовлення або поверніть платіж.

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

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть місце у своєму обліковому записі vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін працює за останнім відомим статусом.

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть його на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна, а також кешовані токени доступу до API завжди видаляються. Налаштування шлюзу та журнали плагіна (файли журналів, зокрема старі архівні файли, і записи журналу в базі даних) видаляються лише тоді, коли була увімкнена опція Delete data on uninstall. Інакше вони зберігаються для повторного встановлення. Дані замовлень зберігаються: наявні замовлення зберігають свої примітки про оплату, ID запитів на оплату та ID транзакцій.

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