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

Вимоги

PrestaShop: 8.0–9.x.

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

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

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

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

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

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

1. У бек-офісі перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

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

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

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

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

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Yoco Pay Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, коли валюта магазину не ZAR (тоді Yoco не пропонується на оформленні замовлення), і коли поточний режим не має секретного ключа, наприклад Enter the test secret key to offer Yoco at checkout (test mode). Під час збереження модуль перевіряє ключі та секрети вебхуків і реєструє вебхуки. Повідомлення про це з'являються у верхній частині сторінки.

Yoco

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

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: використовує тестовий секретний ключ. Реальні гроші не списуються; платіть тестовими картками Yoco. За замовчуванням: увімкнено. Вимкніть, щоб приймати реальні платежі. Поки режим увімкнено, покупці бачать під способом оплати Test mode — use a Yoco test card; no real money is charged.

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

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

Ключ, що не починається з очікуваного префікса, не зберігається: сторінка показує помилку, наприклад Yoco: the test secret key must start with sk_test_ — the previous value was kept. Якщо Yoco під час реєстрації вебхука повідомляє, що ключ належить іншому режиму, сторінка про це інформує.

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

Webhooks

Yoco підтверджує платежі та повернення на URL, який показано в полі Webhook URL у цьому розділі. З дружніми URL він виглядає так: https://your-shop/module/wcp_yoco_pay/webhook, можливо, з кодом мови, наприклад /en/. Створювати вебхук у порталі Yoco не потрібно. Під час збереження налаштувань модуль реєструє URL в Yoco для кожного режиму, у якого є секретний ключ, але немає секрету вебхука, і зберігає секрет підпису в полі цього режиму. Реєстрація повторюється, коли змінюється секретний ключ цього режиму або URL вебхука. Коли URL змінюється, стара реєстрація видаляється.

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

Модуль обробляє ці події (вони також перелічені в цьому розділі):

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

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

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

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

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

Додатково

Debug log: записує запити та вебхуки Yoco у файл logs/yoco_p_debug.log.php у папці модуля. Файл не можна відкрити з веб-браузера. Помилки та попередження, наприклад невдалі запити до Yoco і відхилені вебхуки, завжди записуються в журнал. Ключі, секрети вебхуків і адреси електронної пошти маскуються. За замовчуванням: вимкнено.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб його очистити.

Delete data: якщо увімкнено, при видаленні модуля видаляються налаштування, журнал і вебхуки, які модуль зареєстрував в Yoco. Дані замовлень (ID checkout і платежів Yoco, повернення) і статус замовлення Yoco payment on hold завжди зберігаються, бо потрібні для повернень. За замовчуванням: вимкнено.

Checkout

На кроці оплати покупець обирає спосіб оплати (за замовчуванням Card or Instant EFT (Yoco)) і підтверджує. Модуль створює checkout Yoco на суму кошика в центах і надсилає покупця на сторінку оплати Yoco, де він платить карткою або Instant EFT. На цьому етапі замовлення ще не існує.

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

Якщо покупець скасовує оплату на сторінці Yoco, він повертається до оформлення замовлення з повідомленням The Yoco payment was cancelled. Your cart is saved — you can pay again or choose another payment method. Якщо оплата не вдалася, з'являється повідомлення The Yoco payment was not successful. Please try again or choose another payment method. Кошик зберігається.

Перед новою спробою оплати того самого кошика модуль перевіряє попередню спробу в Yoco. Якщо її вже оплачено, замовлення створюється без нової сторінки оплати. Якщо вона ще відкрита на ту саму суму і створена менш ніж 30 хвилин тому, покупець знову отримує ту саму сторінку Yoco. Інакше створюється новий checkout 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.

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

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

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

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

No order yet: покупця відправили до Yoco, і він не платив, скасував оплату на сторінці Yoco або Yoco ще не підтвердила платіж. Існує лише кошик.

Payment accepted: платіж підтверджено. Він фіксується з ID платежу Yoco як ID транзакції, а примітка показує суму, ID платежу та checkout Yoco, режим і те, як платіж було підтверджено (повернення покупця, вебхук або перевірка перед новою спробою оплати).

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

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

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

Блок оплати Yoco

На сторінці замовлення показано блок Yoco payment з ID платежу та checkout Yoco, статусом, сумою оплати та повернення, значком Test mode для тестових платежів, історією повернень, спробами оплати кошика (якщо їх було більше однієї) і Yoco notes замовлення.

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

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

Успішне повернення додається до історії повернень і приміток разом з ID повернення Yoco. Повне повернення переводить замовлення в статус Refunded; часткове повернення статус не змінює. Якщо Yoco відхиляє повернення, блок показує Yoco refused the refund: з причиною, і повернення не фіксується. Якщо Yoco повідомляє, що повернення в обробці, блок вказує, що воно ще в обробці. Не повторюйте його: воно буде зафіксовано, коли Yoco підтвердить його вебхуком. Повернення доступні для замовлень, оплачених через checkout Yoco. Замовлення у статусі Yoco payment on hold не має оплаченого checkout для повернення; поверніть його в порталі Yoco.

Модуль не створює кредитні ноти. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через Yoco.

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

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

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

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

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

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

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

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

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

Вебхуки відхиляються: відхилені вебхуки записуються в журнал. 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 надішле вебхук повторно.

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

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

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

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

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

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

Розробникам: хук actionYocoPCheckoutPayload дає змогу іншому модулю змінити запит, який створює checkout Yoco.

Видалення

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

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