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

Вимоги

WordPress: 6.0 або новіша.

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

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

Валюта магазину: чилійське песо (CLP). Webpay Plus списує лише цілі песо, тому встановіть Number of decimals у 0 у розділі WooCommerce > Settings > General. У магазинах з іншою валютою спосіб оплати не відображається.

Рахунок Transbank: для реальних платежів потрібен стандартний комерційний обліковий запис Webpay Plus (миттєве списання) з його робочим Commerce Code і API Key Secret. Transbank надає Commerce Code після схвалення вашої афіліації, а API Key Secret — після процесу валідації інтеграції (див. документацію для розробників Transbank). Для тестів облікові дані не потрібні. Коди комерції Webpay Plus Mall, Oneclick і з відкладеним списанням не підтримуються.

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

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

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

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

3. Встановіть валюту магазину — чилійське песо, а Number of decimals — 0 у розділі WooCommerce > Settings > General.

4. Відкрийте налаштування: WooCommerce > Settings > Payments > Transbank Webpay Plus > Manage або натисніть Settings під назвою плагіна на сторінці Plugins.

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

6. Увімкніть Enable / Disable і перевірте оплату при увімкненому Integration (test) mode, використовуючи тестові картки з документації для розробників Transbank.

7. Щоб перейти до реальних платежів, введіть Production Commerce Code і Production API Key Secret, зніміть позначку з Integration (test) mode і збережіть.

В Transbank не потрібно налаштовувати URL повернення або вебхук. Плагін передає свій URL повернення з кожною транзакцією.

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

Усі налаштування розташовані на одній сторінці: WooCommerce > Settings > Payments > Transbank Webpay Plus. Над полями сторінка попереджає, коли вибрано робоче середовище, але Production Commerce Code або API Key відсутній чи недійсний (тоді Webpay приховується під час оформлення замовлення), коли валюта магазину не CLP (спосіб оплати приховано) і коли ціни в CLP мають десяткові знаки (суми округлюються до цілих песо). Поки ввімкнено режим інтеграції, сторінка показує Integration (test) environment: реальні кошти не списуються. Після збереження попередження враховують нові налаштування. У списку способів оплати шлюз позначено як такий, що потребує налаштування, якщо вибрано робоче середовище без дійсних облікових даних.

Загальні

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

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

Description: текст під способом оплати під час оформлення замовлення. За замовчуванням: Pay with credit, debit or prepaid card via Webpay.

Середовище та облікові дані

Текст розділу містить посилання на документацію для розробників Transbank і пояснює, коли Transbank надає робочі облікові дані.

Integration (test) mode: Use the Transbank integration environment. Платежі йдуть до тестового середовища інтеграції Transbank з його публічним тестовим кодом комерції (597055555532), який заповнюється автоматично. Робочі облікові дані нижче не використовуються, реальні кошти не списуються. За замовчуванням: увімкнено. Зніміть позначку, щоб перейти до реальних платежів.

Production Commerce Code: ваш робочий код комерції (Tbk-Api-Key-Id): 12 цифр, починається з 5970. Якщо у вас 8 цифр, введіть як є; плагін додасть префікс 5970 під час збереження. Пробіли та інші символи видаляються. Публічні тестові коди комерції Transbank у робочому середовищі не приймаються.

Production API Key Secret: Tbk-Api-Key-Secret вашої робочої комерції. Тримайте його в таємниці. Пробіли видаляються під час збереження.

Додатково

Debug log: Log API requests and returns (errors are always logged). Деталі записуються в WooCommerce > Status > Logs, джерело wcp_transbank_gateway; у полі є посилання view logs. Помилки та попередження записуються навіть тоді, коли цю опцію вимкнено. До журналу не потрапляють дані карток, API-ключі чи повні токени. За замовчуванням: вимкнено.

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

Тест і робоче середовище

Integration (test) mode визначає, куди надходять нові платежі. Кожен платіж запам'ятовує своє середовище: підтвердження та повернення платежу завжди виконуються в тому середовищі (інтеграція або робоче) і з тими обліковими даними, з якими його створено, навіть якщо ви пізніше зміните режим.

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

Покупець вибирає спосіб оплати (за замовчуванням Webpay Plus) і оформлює замовлення. У режимі інтеграції оформлення замовлення показує TEST MODE: Integration environment. Реальних списань немає. Плагін створює транзакцію Transbank на суму замовлення в цілих песо (сума з десятковими знаками округлюється до найближчого песо) і надсилає покупця на коротку сторінку Redirecting to Webpay. Please wait..., яка переадресує його на форму Webpay. Без JavaScript покупець натискає Proceed to Webpay. На Webpay покупець сплачує кредитною, дебетовою або передплаченою карткою.

Коли покупець повертається, плагін підтверджує (commit) транзакцію в Transbank від сервера до сервера. Замовлення позначається оплаченим лише після підтвердження Transbank: відповідь має бути схвалена, а сума, buy order та сесія мають збігатися з тим, що магазин надіслав для цієї спроби. Потім покупець бачить сторінку «Замовлення отримано». Якщо запит підтвердження не вдався, наприклад через тайм-аут, плагін запитує в Transbank статус транзакції. Якщо статус досі невідомий, замовлення не змінюється, а покупець бачить We could not confirm your Webpay payment with Transbank. Please try again in a moment; if your card was charged, contact us before paying again.

Якщо покупець скасовує оплату на Webpay, форма Webpay прострочується або повідомляє про помилку, нічого не списується. Замовлення залишається в статусі очікування оплати, а покупець повертається на сторінку Pay for order з повідомленням, наприклад You cancelled the Webpay payment. Nothing was charged — you can try again or choose another payment method. Відхилена картка показує Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method. Покупець може оплатити знову з тієї самої сторінки. Кожна нова спроба — це нова транзакція Webpay.

Кожна спроба Webpay підтверджується не більше одного разу. Перезавантаження сторінки повернення, кнопка «Назад» у браузері або друге повернення одночасно ніколи не підтверджують платіж двічі і не змінюють замовлення. Якщо замовленню більше не потрібна оплата (уже оплачено іншою спробою, скасовано або повернено), пізнє повернення не підтверджується, тож Transbank його не списує. Покупець бачить This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged.

Якщо Webpay не може почати платіж, покупець бачить коротке повідомлення, наприклад Could not connect to Webpay. Please try again in a moment. або Webpay payments are not available at the moment. Please choose another payment method. Технічна причина записується в журнал.

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

У Transbank немає вебхука для платежів: результат обробляється, коли покупець повертається з Webpay. Якщо покупець закрив браузер на Webpay і не повернувся, транзакція не підтверджується, а замовлення залишається в очікуванні; за даними Transbank, непідтверджені транзакції не розраховуються. Плагін не підтримує Webpay Plus Mall, збережені картки Oneclick, підписки, відкладене списання та конвертацію валют.

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

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

Pending payment: покупця було перенаправлено на Webpay, і він ще не сплатив, скасував, дозволив формі прострочитися або платіж поки що не вдалося підтвердити. Примітка фіксує кожну закриту спробу з її buy order.

Processing or Completed: Transbank схвалив платіж. Статус встановлює WooCommerce: «В обробці» або «Виконано» для замовлень, що містять лише віртуальні товари для завантаження. У примітці до замовлення вказано код авторизації, останні чотири цифри картки, buy order, суму, тип платежу та кількість платежів. ID транзакції — це токен Webpay.

On hold: Transbank авторизував платіж, який не відповідає замовленню (сума, buy order або ID сесії), наприклад тому, що замовлення змінили після початку оплати. У примітці перелічено розбіжності. Перевірте портал Transbank і зробіть повернення коштів або завершіть замовлення.

Failed: платіж відхилено. Нічого не списано. У примітці вказано код відповіді та статус.

Якщо Webpay повертає платіж для замовлення, яке вже оплачене, скасоване або повернене, платіж не підтверджується, а примітка просить перевірити портал Transbank, якщо покупець повідомляє про списання. Існуючі замовлення наступними спробами не змінюються.

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

Кнопка повернення коштів пропонується лише для замовлень, оплачених через Webpay. Відкрийте замовлення, натисніть Refund, введіть суму та натисніть Refund via Webpay Plus (кнопка використовує назву способу оплати). Повні та часткові повернення підтримуються в цілих песо. Часткова сума з десятковими знаками відхиляється з повідомленням Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. Останній залишок від суми замовлення з десятковими знаками округлюється так само, як і списання. Повернення йде до середовища, в якому було здійснено платіж, тож у робочому середовищі мають бути збережені робочі облікові дані.

Transbank відповідає реверсом (REVERSED) або анулюванням (NULLIFIED). Успішне повернення додається до приміток замовлення із сумою, типом, кодом авторизації та залишком у Transbank. Якщо Transbank не приймає повернення, WooCommerce показує помилку, і повернення не фіксується. Повернення, зроблені в порталі Transbank, у WooCommerce не імпортуються.

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

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

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

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

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

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

Webpay Plus не з'являється під час оформлення замовлення: перевірте, чи ліцензія активна, чи увімкнено Enable / Disable, чи валюта магазину CLP (на сторінці Pay for order — валюта замовлення) і, якщо режим інтеграції вимкнено, чи збережено дійсний Production Commerce Code (12 цифр, починається з 5970) та Production API Key Secret. На сторінці налаштувань для кожної відсутньої умови показується попередження.

Платіж пройшов, але замовлення залишається Pending payment: у Transbank немає вебхука, тому замовлення підтверджується лише тоді, коли покупець повертається з Webpay. Якщо покупець закрив браузер на Webpay, транзакція не була підтверджена і, за даними Transbank, не розраховується. Перевірте примітки до замовлення, журнал і транзакцію в порталі Transbank.

Покупець бачить We could not confirm your Webpay payment with Transbank: запит підтвердження не вдався, і статус не вдалося перевірити. Замовлення не змінено, додано примітку. Покупець може повторити спробу за мить. Якщо портал Transbank показує транзакцію як авторизовану, підтвердьте її там перед відправленням.

Покупець бачить помилку під час оформлення замовлення: увімкніть Debug log і перегляньте WooCommerce > Status > Logs, джерело wcp_transbank_gateway. Повідомлення Webpay payments are not available at the moment зазвичай означає неправильні робочі облікові дані. Could not connect to Webpay означає, що Transbank недоступний. Замовлення у валюті, відмінній від CLP, не можна оплатити через Webpay.

Суми та повернення відрізняються на кілька песо: ціни в CLP мають десяткові знаки. Webpay списує цілі песо, тому суми округлюються. Встановіть Number of decimals у 0.

Повернення не проходить із помилкою The production Commerce Code / API Key are missing: платіж було здійснено в робочому середовищі, а робочі облікові дані не збережені. Введіть їх і повторіть спробу.

Повернення не проходить із помилкою Transbank refused the refund або Transbank did not approve the refund: Transbank не прийняв повернення; повідомлення показує причину або тип і код відповіді. Нічого не повернуто. Перевірте транзакцію в порталі Transbank.

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

Видалення

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

Transbank і Webpay є торговельними марками їхніх відповідних власників. Цей плагін не афільований із Transbank і не схвалений Transbank.