VibeFox PayU LATAM for WooCommerce — Допомога

Вимоги

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

WooCommerce: 7.0 або новіша версія, встановлена й активна. Без нього плагін не активується; якщо WooCommerce згодом вимкнути, плагін нічого не робить і показує повідомлення в адміністративній частині.

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

Currency: замовлення має бути в ARS, BRL, CLP, COP, MXN, PEN або USD — валютах, які PayU Latam обробляє в Аргентині, Бразилії, Чилі, Колумбії, Мексиці, Панамі та Перу. Для інших валют спосіб оплати приховується під час оформлення замовлення.

PayU Latam account: потрібні три значення вашого магазину в PayU: ідентифікатор мерчанта, ідентифікатор рахунку країни продажу та ключ API. Вони є в модулі PayU (панелі мерчанта PayU), у Settings > Technical configuration (ідентифікатор мерчанта, ключ API) та Accounts (ідентифікатор рахунку). Для тестування PayU публікує загальнодоступні тестові облікові дані й тестові картки на сторінці "Test your solution" документації для розробників. API Login та інші облікові дані API не потрібні, оскільки оплата здійснюється на сторінці PayU.

Internet access to your site: PayU надсилає результат платежу до магазину зі своїх серверів, тому сайт має бути доступним з інтернету (не локальний сайт, не захищений паролем чи сторінкою обслуговування).

VibeFox license key: придбаний на vibefox.net. Один ключ працює на одному домені.

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

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

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

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

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

5. Введіть тестові й робочі облікові дані (див. «Налаштування»). Налаштовувати URL підтвердження в PayU не потрібно.

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

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

Усі налаштування розміщено на одній сторінці: WooCommerce > Settings > Payments > PayU LATAM. Над полями сторінка попереджає про ввімкнений тестовий режим (Sandbox mode. Платежі надходять до тестового середовища PayU, реальні кошти не списуються.), відсутність ідентифікатора мерчанта, ідентифікатора рахунку або ключа API поточного середовища та про те, що PayU LATAM не обробляє валюту магазину. В останніх двох випадках PayU LATAM не показується під час оформлення замовлення. У списку способів оплати PayU LATAM позначено як такий, що потребує налаштування, доки не заповнено всі три значення облікових даних поточного середовища. Пробіли на початку та в кінці значення ігноруються.

Загальні налаштування

Enable/Disable: Enable PayU LATAM вмикає або вимикає спосіб оплати. Типово: off.

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

Description: опис способу оплати, який покупець бачить під час оформлення замовлення. Типово: Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

Середовище

Sandbox: Enable the PayU sandbox (test mode). Платежі надходять до тестового середовища PayU з указаними нижче тестовими обліковими даними, реальні кошти не списуються. Якщо вимкнено, використовуються робочі облікові дані та робоча сторінка оплати PayU. Типово: on.

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

Знайдіть їх у модулі PayU: Settings > Technical configuration (ідентифікатор мерчанта, ключ API) та Accounts (ідентифікатор рахунку країни продажу). Розділ містить посилання на панель мерчанта PayU.

Merchant ID: числовий ідентифікатор вашого магазину в PayU.

Account ID: ідентифікатор рахунку PayU. Для кожної країни є окремий рахунок.

API Key: секретний ключ для підписування платежів і перевірки сповіщень PayU.

Тестові облікові дані

PayU публікує загальнодоступні тестові облікові дані й картки для свого тестового середовища. Розділ містить посилання на сторінку "Test your solution" документації PayU.

Sandbox merchant ID: ідентифікатор мерчанта тестового середовища PayU.

Sandbox account ID: ідентифікатор рахунку тестового середовища PayU.

Sandbox API key: ключ API тестового середовища PayU.

Кожна спроба оплати запам'ятовує своє середовище. Підтвердження тестового платежу перевіряється тестовими ключем API та ідентифікатором мерчанта, а робочого — робочими, тому очікувані платежі продовжують оброблятися після перемикання. Під час оновлення з версії 1.0, яка мала один набір облікових даних, старі значення копіюються в тестові поля, якщо тестовий режим був увімкнений. Перевірте налаштування після оновлення.

URL підтвердження

Цей розділ показує URL, на який PayU повідомляє результат кожного платежу. Він має вигляд https://your-site/wc-api/payu_lp/. Плагін надсилає його PayU з кожним платежем, тому в PayU нічого налаштовувати не потрібно. Сторінка має бути доступною з інтернету. PayU підписує підтвердження вашим ключем API. Підтвердження без чинного підпису, з іншим ідентифікатором мерчанта або з платіжним ідентифікатором, який цей магазин не створював для замовлення, відхиляються. Плагін обробляє такі стани транзакцій PayU:

4 (approved): платіж здійснено. Замовлення позначається оплаченим, якщо сума та валюта збігаються.

6 (declined), 5 (expired), 104 (error): платіж не вдався. Неоплачене замовлення останньої спроби отримує статус «Невдале».

7 and other pending states: платіж очікується, наприклад покупець ще не завершив оплату готівкою чи через банк. Замовлення переводиться на утримання.

Інші стани лише додаються як примітка до замовлення. Без підтвердження замовлення ніколи не позначається оплаченим: воно залишається в статусі «Очікування оплати».

Додатково

Debug log: Log payment requests and PayU notifications записує подробиці до WooCommerce > Status > Logs, джерело wcp_payu_latam_payment, без ключів і персональних даних. Помилки й відхилені сповіщення записуються завжди. Типово: off.

Delete data: Delete the settings and logs when the plugin is deleted. Вимкнення плагіна ніколи нічого не видаляє. Дані PayU, збережені в замовленнях, залишаються. Типово: off.

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

Покупець вибирає спосіб оплати (типово PayU LATAM) та оформлює замовлення. У блоці Checkout у тестовому режимі він бачить Sandbox mode: no real payment is made. Замовлення залишається в статусі «Очікування оплати», а покупець переходить на платіжну сторінку магазину з текстом Thank you for your order. You are being redirected to PayU LATAM to complete the payment… Сторінка автоматично надсилає підписану форму на сторінку PayU WebCheckout. Якщо цього не сталося, покупець натискає Pay with PayU LATAM або Cancel order, щоб скасувати замовлення.

Форма містить загальну суму й валюту замовлення, податок і податкову базу замовлення (обидва значення 0 для замовлень без податку, щоб PayU не додавав типовий ПДВ), опис Order # з номером замовлення й назвою магазину, електронну пошту, ім'я, телефон і платіжну адресу покупця. Сторінка PayU відкривається іспанською, португальською або англійською відповідно до мови магазину. На ній покупець сплачує будь-яким способом, увімкненим у вашому обліковому записі PayU.

Кожне відвідування платіжної сторінки починає нову спробу оплати з власним ідентифікатором (номер замовлення й позначка часу). Зберігаються останні 30 спроб замовлення: якщо покупець сплатить у старій вкладці PayU, платіж усе одно приймається.

Замовлення позначається оплаченим лише після підписаного підтвердження PayU. Повернення покупця з PayU ніколи не позначає замовлення оплаченим. Коли покупець повертається:

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

Без транзакції PayU (покупець залишив сторінку PayU): покупець переходить на сторінку Pay for order з повідомленням Your PayU LATAM payment was not completed. You can try again or choose another payment method.

В інших випадках: покупець бачить сторінку отриманого замовлення. Поки замовлення має статус «Очікування оплати», показується We are waiting for PayU LATAM to confirm your payment. You will receive an e-mail as soon as it is confirmed. Для замовлення на утриманні показується Your PayU LATAM payment is pending (for example, a cash or bank payment that has not been completed yet). We will process the order as soon as PayU confirms the payment.

Якщо облікові дані поточного середовища відсутні, покупець бачить PayU LATAM is not available right now. Please choose another payment method. Для непідтримуваної валюти замовлення повідомлення — PayU LATAM does not accept payments in, а далі валюта. Уже оплачене замовлення не оплачується повторно: платіжна сторінка показує This order has already been paid.

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

У плагіні немає платіжної форми в магазині, повернень коштів із WooCommerce, збережених карток, підписок і налаштувань розстрочки (PayU показує розстрочку на своїй сторінці). Він не запитує стан платежу через API PayU: лише підписане підтвердження оновлює замовлення.

Замовлення

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

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

Processing: PayU підтвердив платіж, сума й валюта збігаються. Примітка до замовлення показує транзакцію PayU, суму, спосіб оплати та [sandbox] для тестових платежів. Ідентифікатор транзакції замовлення — це ідентифікатор транзакції PayU. Замовлення лише з віртуальними завантажуваними товарами отримують статус «Виконано», як типово передбачає WooCommerce.

On hold: PayU повідомляє про очікуваний платіж (готівка чи банк), сплачена сума або валюта не відповідає підсумку замовлення, або схвалено платіж за скасоване замовлення. Примітка вказує причину: перевірте платіж у модулі PayU, потім обробіть замовлення, відновіть його або поверніть кошти.

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

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

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

Повернення коштів не виконуються з WooCommerce. Поверніть кошти за транзакцією в модулі PayU та за потреби вручну зареєструйте повернення в WooCommerce.

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

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

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

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

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

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

PayU LATAM не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено й заповнені ідентифікатор мерчанта, ідентифікатор рахунку та ключ API поточного середовища: тестові облікові дані при ввімкненому Sandbox, робочі — при вимкненому. Перевірте, що валюта магазину (або замовлення на сторінці оплати замовлення) — ARS, BRL, CLP, COP, MXN, PEN або USD. Сторінка налаштувань показує попередження щодо кожної з цих проблем.

Платіж пройшов, але замовлення залишається в статусі Pending payment: підтвердження PayU не дійшло до магазину або було відхилене. Перевірте доступність URL підтвердження з налаштувань через інтернет (не локальний сайт, без режиму обслуговування, блокування брандмауером і захисту паролем). Перегляньте відхилені підтвердження в WooCommerce > Status > Logs, джерело wcp_payu_latam_payment. PayU повторно надсилає підтвердження після будь-якої відповіді з помилкою.

Підтвердження отримує відповідь Invalid signature: його підписано не ключем API середовища платежу. Перевірте API Key для робочих платежів і Sandbox API key для тестових.

Підтвердження отримує відповідь Merchant mismatch: ідентифікатор мерчанта в ньому відрізняється від Merchant ID або Sandbox merchant ID середовища платежу. Введіть ідентифікатор мерчанта облікового запису PayU, що обробляє платежі.

Підтвердження отримує відповідь Gateway not configured: відсутній ключ API або ідентифікатор мерчанта середовища платежу, наприклад тестові облікові дані видалено під час очікування тестового платежу. Введіть їх знову; PayU повторює підтвердження.

Підтвердження отримує відповідь Busy, retry later: інший запит одночасно оновлював замовлення. Нічого не змінено, і PayU надсилає підтвердження знову.

Підтвердження отримує відповідь Unknown reference: платіжний ідентифікатор не належить замовленню PayU LATAM цього магазину, наприклад замовлення переведено на інший спосіб оплати або видалено.

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

Інші валюти або поля форми: розробники можуть змінити список валют фільтром payu_lp_supported_currencies, значок оформлення замовлення фільтром payu_lp_icon, а поля форми WebCheckout фільтром payu_lp_payment_fields.

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

Видалення

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

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