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

Вимоги

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

WooCommerce: 7.0 або новіша, встановлений і активний.

PHP: 8.0 або новіша.

HTTPS: ваш сайт має бути доступним з інтернету через HTTPS, щоб Datatrans могла доставляти вебхуки.

Обліковий запис Datatrans: вам потрібні Merchant ID, пароль API для зв'язку між серверами та, бажано, ключ підпису HMAC-SHA256 для вебхуків. Облікові дані sandbox беруться з Web Admin sandbox Datatrans (admin.sandbox.datatrans.com), робочі облікові дані — з робочого Web Admin (admin.datatrans.com). Sandbox і робоче середовище — це окремі облікові записи Datatrans з різними Merchant ID і ключами.

Валюта: валюта магазину (або валюта замовлення вашого мультивалютного плагіна) має бути ввімкнена для вашого облікового запису мерчанта Datatrans.

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

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

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

2. Натисніть Activate. WooCommerce має бути активним.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Datatrans > Manage, або натисніть Settings під назвою плагіна на сторінці «Плагіни».

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

5. Введіть облікові дані sandbox і, для реальних платежів, робочі облікові дані (див. розділ «Налаштування»).

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

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

Усі налаштування розташовані на одній сторінці: WooCommerce > Settings > Payments > Datatrans. Якщо шлюз увімкнено, але бракує Merchant ID або пароля API поточного середовища, сторінка показує Datatrans is hidden at checkout until these settings are filled in: зі списком відсутніх полів. Поки режим sandbox увімкнено, вона показує Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.

Вебхук

Webhook URL показано вгорі налаштувань. Він має такий вигляд: https://your-site/wc-api/datatrans_payment_callback/. Плагін надсилає цю адресу до Datatrans з кожною транзакцією, тому вводити її деінде не потрібно. Також ви можете ввести її в налаштуваннях вебхука в Web Admin Datatrans, щоб отримувати оновлення про списання та скасування, виконані там.

Вебхук повідомляє стан транзакції. Плагін реагує на такі стани:

За наявності ключа підпису HMAC кожен вебхук перевіряється за заголовком Datatrans-Signature. Вебхуки без дійсного підпису відхиляються. Без ключа підпису плагін не довіряє вмісту вебхука і звіряє кожен вебхук зі статусним API Datatrans. Без вебхука замовлення підтверджується лише тоді, коли покупець повертається до магазину після оплати.

Загальні

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

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

Description: текст, що показується під способом оплати під час оформлення замовлення. За замовчуванням: Pay securely via Datatrans.

Sandbox mode: Use the Datatrans sandbox (test payments, no real money). Перемикає і хости API та платіжної сторінки, і наведені нижче облікові дані. Повернення коштів і списання завжди використовують те середовище, в якому було здійснено платіж. За замовчуванням: увімкнено. Зніміть прапорець, щоб приймати реальні платежі.

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

Скопіюйте їх з Web Admin sandbox Datatrans (admin.sandbox.datatrans.com). Ключ підпису розташований там у налаштуваннях безпеки.

Sandbox merchant ID: Merchant ID вашого облікового запису sandbox.

Sandbox API password: пароль API для зв'язку між серверами вашого облікового запису sandbox.

Sandbox HMAC sign key: шістнадцятковий ключ для перевірки заголовка Datatrans-Signature вебхуків. Без нього кожен вебхук повторно звіряється зі статусним API Datatrans.

Робочі облікові дані

Скопіюйте їх з робочого Web Admin Datatrans (admin.datatrans.com).

Production merchant ID: Merchant ID вашого робочого облікового запису.

Production API password: пароль API для зв'язку між серверами вашого робочого облікового запису.

Production HMAC sign key: шістнадцятковий ключ для перевірки заголовка Datatrans-Signature робочих вебхуків. Без нього кожен вебхук повторно звіряється зі статусним API Datatrans.

Ключ підпису має бути шістнадцятковим рядком, виданим Datatrans. Будь-яке інше значення не зберігається: сторінка показує помилку й залишає попереднє значення. Якщо ви оновлюєтеся з версії 1.0, єдиний набір облікових даних тієї версії переноситься до полів sandbox, якщо режим sandbox був увімкнений; в іншому разі він залишається в робочих полях.

Обробка платежу

Auto settle: Capture (settle) payments immediately. За замовчуванням: увімкнено. Якщо ви його вимкнете, платежі лише авторизуються: замовлення переходить у статус «Призупинено», і ви списуєте його пізніше дією замовлення Capture Datatrans payment або знімаєте авторизацію через Cancel Datatrans authorization.

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

Додатково

Logging: Log payment events and API calls записує подробиці до WooCommerce > Status > Logs, джерело wcp_datatrans_gateway. Помилки реєструються завжди. Ключі, дані карток і дані покупців не записуються. За замовчуванням: вимкнено.

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

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

Покупець обирає спосіб оплати (за замовчуванням Datatrans) і оформлює замовлення. Плагін створює транзакцію Datatrans на суму замовлення у валюті замовлення, із ID замовлення як посиланням, і перенаправляє покупця на платіжну сторінку Datatrans. Там покупець платить будь-яким способом, увімкненим у вашому обліковому записі Datatrans, наприклад карткою, TWINT або PostFinance. Платіжна сторінка відкривається німецькою, англійською, французькою або італійською, якщо ваш сайт використовує одну з цих мов; в іншому разі мову обирає Datatrans.

Після оплати покупець повертається на сторінку отриманого замовлення вашого магазину. Замовлення позначається оплаченим лише після підтвердження від Datatrans: через вебхук або через серверний запит до статусного API Datatrans, коли покупець повертається. Адреса повернення містить ключ замовлення, а саме повернення ніколи не позначає замовлення оплаченим.

Якщо покупець скасовує оплату на платіжній сторінці, він потрапляє на сторінку Pay for order з повідомленням The payment was canceled. You can try again or choose another payment method. Після невдалого платежу повідомлення таке: The payment was not completed. Please try again or choose another payment method. Замовлення залишається доступним для оплати, і покупець може спробувати ще раз.

Якщо Datatrans не може розпочати платіж, покупець бачить The payment could not be started. Please try again or choose another payment method. Причину записано до журналу.

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

Плагін приймає лише одноразові платежі на платіжній сторінці Datatrans. Він не підтримує збережені картки чи аліаси, підписки, інтеграцію Lightbox або Secure Fields, вибір способів оплати в налаштуваннях та часткове списання авторизації.

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

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

Pending payment: покупця перенаправлено до Datatrans, і він ще не заплатив, скасував оплату на платіжній сторінці або Datatrans ще не підтвердила платіж. Кожна нова транзакція фіксується в замовленні з її ID та середовищем.

Processing, Completed or On Hold: платіж розраховано. Статус відповідає параметру Order status after payment. Нотатка замовлення показує суму, спосіб оплати, ID транзакції Datatrans і середовище (sandbox або робоче). ID транзакції зберігається в замовленні.

On hold, authorized: якщо Auto settle вимкнено, платіж авторизовано, але не списано. Відкрийте замовлення та виберіть Capture Datatrans payment або Cancel Datatrans authorization у діях замовлення. Списання використовує поточну суму замовлення, яка не має перевищувати авторизовану суму. Якщо перевищує або якщо Datatrans відхиляє списання чи скасування, причина додається до нотаток замовлення.

On hold after payment: Datatrans повідомила іншу суму або валюту, ніж у замовленні (наприклад, замовлення відредагували після початку платежу), або платіж надійшов після скасування замовлення. Нотатка замовлення це пояснює. Перевірте транзакцію в Web Admin Datatrans і виконайте замовлення або поверніть кошти за платіж.

Failed: платіж не вдався або був відхилений. Покупець може спробувати ще раз.

Cancelled: авторизацію знято дією замовлення або в Web Admin Datatrans.

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

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

Відкрийте замовлення, натисніть Refund, введіть суму та натисніть Refund via Datatrans. Підтримуються повні та часткові повернення. Повернення надсилається в те середовище, в якому було здійснено платіж, тож облікові дані цього середовища мають бути задані. Повторна спроба повернення не зараховується двічі. Якщо Datatrans не приймає повернення, WooCommerce показує помилку, і повернення не записується. Успішне повернення додається до нотаток замовлення із сумою та ID транзакції повернення Datatrans.

Для платежу, який лише авторизовано, повернення повної суми скасовує авторизацію. Часткове повернення неможливе, доки платіж не списано.

Повернення, виконані в Web Admin Datatrans, не записуються в WooCommerce. За потреби створіть ручне повернення в WooCommerce без Refund via Datatrans.

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

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

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

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

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

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

Datatrans не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, а Merchant ID і пароль API поточного середовища задані: поля sandbox у режимі sandbox, робочі поля — в інших випадках. Сторінка налаштувань наводить список відсутніх полів.

Платіж пройшов, але замовлення залишається в статусі «Очікує на оплату»: Datatrans не змогла звернутися до URL вебхука, а покупець не повернувся до магазину. Перевірте, що сайт доступний з інтернету через HTTPS і що жоден плагін безпеки чи брандмауер не блокує запити до /wc-api/datatrans_payment_callback/. Перевірте, що ключ підпису в налаштуваннях належить до середовища платежу. Увімкніть Logging і перегляньте WooCommerce > Status > Logs, джерело wcp_datatrans_gateway.

Вебхук відповідає Invalid signature: ключ підпису HMAC у налаштуваннях не збігається з ключем у Web Admin Datatrans або належить до іншого середовища. Скопіюйте ключ ще раз.

Вебхук відповідає Not configured або Verification failed: вебхук потрібно було перевірити за статусним API Datatrans, але облікові дані цього середовища відсутні або Datatrans не відповіла. Datatrans повторює вебхук.

Ключ підпису HMAC не зберігається: ключ має бути шістнадцятковим рядком. Скопіюйте його ще раз із Web Admin Datatrans.

Покупець бачить The payment could not be started: Merchant ID або пароль API неправильні, належать до іншого середовища, або валюта не ввімкнена для вашого облікового запису Datatrans. Увімкніть Logging, щоб побачити причину.

Замовлення після оплати в статусі «Призупинено»: прочитайте нотатку замовлення. Сплачена сума або валюта відрізнялися від замовлення, платіж надійшов після скасування замовлення, або платіж лише авторизовано й він очікує списання.

Списання неможливе: сума замовлення перевищує авторизовану суму. Списання використовує поточну суму замовлення, тому зменште її до авторизованої суми або менше.

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

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

Для розробників: у readme згадано фільтр wcp_datatrans_gateway_init_request, наприклад, для обмеження способів оплати, що показуються на сторінці Datatrans.

Видалення

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

Datatrans є торговою маркою відповідного власника. Цей плагін не пов'язаний із Datatrans і не схвалений нею.