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

Вимоги

PrestaShop: 8.0 – 9.x.

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

Обліковий запис 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. У бек-офісі відкрийте Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

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

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

4. Введіть облікові дані sandbox з Web Admin sandbox Datatrans (див. Налаштування).

5. Увімкніть Enable/Disable і натисніть Save. Здійсніть тестовий платіж у режимі sandbox. Коли все працює, введіть облікові дані робочого середовища та вимкніть Sandbox mode.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Datatrans Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Коли спосіб оплати увімкнено, але в поточному середовищі не заповнено 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.

Datatrans

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

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

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

Sandbox mode: використовує sandbox Datatrans: тестові платежі, без реальних грошей. Перемикач змінює і сервери Datatrans, і облікові дані, які використовуються для нових платежів. За замовчуванням: увімкнено. Вимкніть його, щоб приймати реальні платежі. Поки він увімкнений, покупці бачать під способом оплати Sandbox mode: no real payment is taken. Повернення коштів і списання завжди використовують те середовище, в якому було здійснено платіж, незалежно від положення цього перемикача.

Облікові дані 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.

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

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

URL вебхука

У цьому розділі показано URL вебхука вашого магазину. За увімкнених дружніх URL він має вигляд https://your-shop/module/wcp_datatrans_gateway/webhook, можливо з кодом мови, наприклад /en/. Модуль передає цей URL до Datatrans з кожною транзакцією, тож вводити його нікуди не потрібно. Ви також можете вказати його в налаштуваннях вебхуків Web Admin Datatrans, щоб отримувати оновлення щодо списань і скасувань, зроблених там; скопіюйте його точно так, як показують налаштування. Повернення коштів, зроблені у Web Admin Datatrans, у замовленні не відображаються.

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

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

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

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

Order status after payment: статус замовлення після підтвердження платежу.

Платежі лише з авторизацією та розбіжності суми чи валюти завжди переходять у Datatrans payment on hold.

Додатково

Logging: записує події платежів і виклики API до файлу logs/datatrans_p_debug.log.php у папці модуля. Файл не можна відкрити через веб. Помилки завжди записуються, навіть якщо цей перемикач вимкнено. Ключі, дані карток і дані покупців не записуються. За замовчуванням: вимкнено.

Log: показує розмір і останні записи журналу, а також кнопку для його очищення.

Delete data on uninstall: якщо увімкнено, під час видалення модуля видаляються його налаштування та журнал. Записи про платежі Datatrans у замовленнях (транзакції, повернення) і статус замовлення завжди зберігаються. За замовчуванням: вимкнено.

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Datatrans) і бачить примітку You will be redirected to the Datatrans payment page to complete the payment securely. Після підтвердження модуль створює транзакцію Datatrans на суму кошика у валюті кошика і надсилає покупця на платіжну сторінку Datatrans. Сторінка відкривається німецькою, англійською, французькою або італійською, якщо мова магазину є однією з них. Там покупець платить будь-яким способом, увімкненим у вашому обліковому записі Datatrans. На цьому етапі замовлення ще не існує.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Datatrans: вебхуком або серверним запитом до API статусів Datatrans, коли покупець повертається. Адреса повернення містить захищений ключ кошика, а саме повернення ніколи не створює замовлення. Потім замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення з повідомленням Your payment with Datatrans has been received. За платежу лише з авторизацією сторінка показує Your payment with Datatrans has been authorized. The amount will be charged when your order is processed. Якщо Datatrans ще не підтвердив платіж, сторінка Payment confirmation показує Your payment is being confirmed by Datatrans. You will receive an e-mail as soon as it is confirmed. Please do not pay again. з кнопкою Check again; вебхук створить замовлення, щойно він надійде.

Якщо покупець скасовує платіж на сторінці Datatrans, він повертається до оформлення замовлення з повідомленням 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; пізній платіж за попередньою спробою все одно розпізнається.

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

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

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

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

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

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

Payment accepted, Delivered або Datatrans payment on hold: платіж підтверджено. Статус відповідає Order status after payment. Платіж фіксується з ID транзакції Datatrans, а нотатка показує суму, спосіб оплати, середовище та спосіб підтвердження (вебхук або повернення).

Datatrans payment on hold після авторизації: Auto settle вимкнено, і платіж лише авторизовано. Списати або скасувати його можна в блоці замовлення.

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

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

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

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

Блок Datatrans payment

На сторінці замовлення відображається блок Datatrans payment з ID транзакції, статусом Datatrans, способом оплати, сумою, оплаченими та поверненими сумами, значком Sandbox для платежів sandbox, історією повернень і Datatrans notes замовлення. Дії блоку потребують права на редагування замовлень; доступ до сторінок модулів не потрібен.

Списання та скасування

Для платежу лише з авторизацією блок показує Capture Datatrans payment і Cancel Datatrans authorization. Списання проводить платіж на поточну суму замовлення, яка не може перевищувати авторизовану суму; після цього замовлення переходить у статус з Order status after payment. Скасування знімає авторизацію і переводить замовлення в статус Canceled. Обидві дії спрямовуються в середовище платежу. Якщо Datatrans відмовляє, блок показує помилку і додається нотатка.

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

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

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

Модуль не створює кредитових нот (credit slips). Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через Datatrans. Повернення, зроблені у Web Admin Datatrans, у PrestaShop не фіксуються.

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

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

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

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

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

Datatrans does not appear at checkout: перевірте, що ліцензія активна, Enable/Disable увімкнено і в поточному середовищі заповнені Merchant ID та пароль API: поля sandbox у режимі sandbox, поля робочого середовища в інших випадках. На сторінці налаштувань перелічено відсутні поля. У Payment > Preferences перевірте, що модуль дозволений для валюти кошика, країни покупця та групи покупця.

The payment went through, but no order was created: Datatrans не зміг достукатися до URL вебхука, а покупець не повернувся до магазину. Перевірте, що магазин доступний з інтернету і що брандмауер не блокує запити до URL вебхука. Перевірте, що ключ підпису в налаштуваннях належить до середовища платежу. Подивіться поле Log на сторінці модуля.

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

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

Webhook answers Busy, retry: замовлення в цей момент підтверджувалося іншим запитом, або замовлення не вдалося створити (наприклад, модуль вимкнено). Datatrans повторить вебхук. Журнал показує причину.

The webhook URL shows Method not allowed in the browser: це нормально. URL приймає лише запити від Datatrans.

The HMAC sign key is not saved: ключ має бути шістнадцятковим рядком. Скопіюйте його знову з Web Admin Datatrans.

The customer sees Datatrans payments are not configured yet: відсутні Merchant ID або пароль API поточного середовища.

The customer sees The payment could not be started: перегляньте поле Log. Типові причини: неправильні Merchant ID або пароль API чи облікові дані не того середовища.

Order is Datatrans payment on hold after payment: прочитайте Datatrans notes у блоці замовлення (див. Статуси замовлення), потім виконайте замовлення або поверніть платіж.

Capture is refused: сума замовлення перевищує авторизовану суму. Datatrans не може списати більше, ніж було авторизовано.

Refund or capture fails with a message about missing credentials: платіж було здійснено в іншому середовищі, а його Merchant ID або пароль API не заповнені. Введіть їх і спробуйте знову.

Видалення

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

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