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

Вимоги

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

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

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

Валюта магазину: південноафриканський ранд (ZAR). Yoco приймає лише ZAR. У будь-якій іншій валюті спосіб оплати не показується на оформленні замовлення. Сума замовлення має бути не меншою за R2,00.

Обліковий запис Yoco: обліковий запис Yoco з онлайн-платежами. Потрібні його секретні ключі, які знаходяться в Yoco Business Portal у розділі Selling Online > Payment Gateway. Вводяться лише секретні ключі. Вебхук реєструє плагін, а його секрет підпису заповнюється автоматично.

Публічний сайт: Yoco надсилає вебхуки на ваш сайт, тож він має бути доступний з інтернету. URL вебхука має приймати POST без перенаправлень.

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

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

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

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

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Yoco > Manage.

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

5. Вставте тестовий секретний ключ (sk_test_...) і, коли будете готові, робочий секретний ключ (sk_live_...). Збережіть налаштування. Вебхук реєструється для кожного режиму, для якого є ключ.

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

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

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

Загальні

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

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

Description: текст під способом оплати на оформленні замовлення. За замовчуванням: You will be redirected to the secure Yoco page to pay by card or Instant EFT.

Ключі API

Скопіюйте секретні ключі з Yoco Business Portal у розділі Selling Online > Payment Gateway. Yoco має один API для обох режимів: ключ визначає, чи є платіж тестовим або реальним. Тестовий режим використовує лише тестовий ключ, робочий — лише робочий.

Test mode: Use the test secret key (no real payments). Реальні кошти не списуються; платіть тестовими картками Yoco. За замовчуванням: on. Зніміть позначку, щоб приймати реальні платежі.

Test secret key: секретний ключ тестового режиму. Починається з sk_test_.

Live secret key: секретний ключ робочого режиму. Починається з sk_live_.

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

Вебхуки

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

Для кожного режиму розділ показує стан вебхука:

Плагін обробляє такі події:

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

Test webhook secret: заповнюється автоматично під час реєстрації вебхука. Вставляйте секрет (whsec_...) лише якщо ви самі зареєстрували URL вебхука.

Live webhook secret: заповнюється автоматично під час реєстрації вебхука. Очистіть поле і збережіть, щоб зареєструвати вебхук знову.

Секрет вебхука має виглядати як whsec_ і далі текст у base64. Будь-яке інше значення не зберігається, попереднє лишається.

Додатково

Debug log: Log Yoco requests and webhooks записує запити та вебхуки в WooCommerce > Status > Logs, джерело wcp_yoco_pay. Помилки та попередження, наприклад невдалі запити до Yoco та відхилені вебхуки, завжди записуються. Ключі, секрети вебхуків та адреси електронної пошти маскуються. За замовчуванням: off.

Delete data: Delete the settings and logs of this plugin when it is deleted. Деактивація ніколи нічого не видаляє. Дані замовлень (ID checkout і платежу Yoco) завжди зберігаються, бо вони потрібні для повернень. За замовчуванням: off.

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

Покупець обирає спосіб оплати (за замовчуванням Card or Instant EFT (Yoco)) і оформлює замовлення. У тестовому режимі на оформленні замовлення показується Test mode — use a Yoco test card; no real money is charged. Плагін створює checkout Yoco на суму замовлення в центах і надсилає покупця на сторінку оплати Yoco, де він платить карткою або Instant EFT.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Yoco: плагін запитує у Yoco checkout, коли покупець повертається, і знову, коли надходить підписаний вебхук. Якщо Yoco ще не підтвердила платіж, сторінка «Замовлення отримано» показує We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again.

Якщо покупець скасовує платіж на сторінці Yoco, замовлення лишається неоплаченим, а покупець потрапляє на сторінку Pay for order з повідомленням The Yoco payment was cancelled. Your order is saved — you can pay again below or choose another payment method. Якщо платіж не вдався, повідомлення: The Yoco payment was not successful. Please try again or choose another payment method. і до замовлення додається примітка.

Покупець може знову оплатити неоплачене замовлення на сторінці Pay for order. Перед новою спробою плагін перевіряє попередню у Yoco. Якщо її вже оплачено, замовлення завершується без нової сторінки оплати. Якщо вона ще відкрита на ту саму суму і створена менш ніж 30 хвилин тому, покупець знову отримує ту саму сторінку Yoco.

Якщо Yoco не може розпочати платіж, покупець бачить Yoco could not start the payment. Please try again in a moment or choose another payment method. і причина додається до приміток замовлення. Замовлення меншою за R2,00 отримує Yoco requires an order total of at least R2.00.

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

Платежі списуються одразу на сторінці Yoco. У плагіні немає збережених карток, підписок і регулярних платежів, форми введення картки на сайті, окремої авторизації та списання, і він не працює у валютах, відмінних від ZAR.

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

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

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

Processing or Completed: платіж підтверджено. WooCommerce ставить «Обробляється» або «Виконано» для замовлень, що містять лише віртуальні товари для завантаження. Примітка до замовлення показує суму, ID платежу та checkout Yoco, режим і спосіб підтвердження (повернення покупця, вебхук або перевірка перед новою спробою оплати). ID транзакції — це ID платежу Yoco.

On hold: Yoco повідомила суму або валюту, що відрізняються від суми замовлення, наприклад через те, що замовлення було змінено після початку платежу. Примітка це пояснює, а покупець, що повернувся з Yoco, бачить We received your payment and are reviewing it. We will contact you if anything else is needed. Перевірте платіж перед відправленням.

Cancelled or Refunded: платіж, що надходить для такого замовлення, його не змінює. Примітка просить повернути платіж у порталі Yoco або відновити замовлення вручну. Покупець, що повернувся з Yoco, бачить Your payment was received after the order had been cancelled. Please contact us — do not pay again.

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

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

Відкрийте замовлення, натисніть Refund, введіть суму і натисніть кнопку Refund via з назвою вашого способу оплати (за замовчуванням Card or Instant EFT (Yoco)). Підтримуються повні та часткові повернення. Повернення надсилається в тому режимі, в якому було здійснено платіж (тестовому або робочому), тому секретний ключ цього режиму має бути заповнений. Повернення, повторене після втраченої відповіді, не виплачується двічі.

Успішне повернення додається до приміток замовлення з ID повернення Yoco. Якщо Yoco відхиляє повернення, WooCommerce показує Yoco refused the refund: з причиною, і повернення не фіксується. Якщо Yoco повідомляє, що повернення очікує на обробку, WooCommerce показує, що воно ще очікує, і нічого не фіксує. Не повторюйте його: воно буде додано до замовлення, коли Yoco підтвердить його вебхуком.

Повернення, зроблені в порталі Yoco, надходять через вебхук refund.succeeded і автоматично фіксуються як повернення WooCommerce, без повернення товарів на склад. Повернення більше за суму, що ще доступна до повернення, не фіксується, і примітка просить перевірити замовлення. Невдале повернення додає примітку, що кошти покупцю не повернуто.

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

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

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

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

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

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

Yoco не з'являється на оформленні замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і в поточному режимі є секретний ключ: Test secret key у тестовому режимі, Live secret key у робочому. Валюта магазину або замовлення має бути ZAR, а сума замовлення — не меншою за R2,00. Сторінка налаштувань показує попередження, якщо ключа немає або валюта не ZAR.

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

Не вдалося зареєструвати вебхук: платежі все одно підтверджуються, коли покупці повертаються до магазину. Усуньте причину, вказану в повідомленні, наприклад сайт має бути доступний з інтернету через HTTPS, і збережіть знову. Також можна зареєструвати URL самостійно і вставити секрет підпису.

Вебхуки відхиляються: відхилені вебхуки записуються в журнал, джерело wcp_yoco_pay. webhook secret not configured означає, що жодного секрету вебхука не задано. invalid signature означає, що секрет належить іншій реєстрації або режиму. timestamp outside the tolerance означає, що годинник сервера неправильний: підписи приймаються в межах 5 хвилин від часу сервера. checkout not completed yet — retry і could not confirm the checkout with Yoco — retry тимчасові; Yoco надішле вебхук знову.

The secret key must start with sk_test_ / sk_live_ error on save: ключ вставлено не в те поле. Тестовий ключ починається з sk_test_, робочий — з sk_live_. Попереднє значення збережено.

Покупець бачить помилку під час оформлення замовлення: прочитайте примітки до замовлення або WooCommerce > Status > Logs, джерело wcp_yoco_pay. Yoco is not available at the moment. Please choose another payment method. означає, що в поточному режимі немає секретного ключа.

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

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

Повернення не проходить з повідомленням No answer from Yoco: у WooCommerce нічого не зафіксовано. Якщо Yoco все ж обробила повернення, повторіть те саме повернення: його не буде виконано двічі.

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

Видалення

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

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