VibeFox Peach Payments for WooCommerce — Допомога

Вимоги

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

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

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

Currency: валюта магазину має бути ZAR, KES або MUR. Для інших валют спосіб оплати приховано, про що повідомляє сторінка налаштувань.

Peach Payments account: потрібні облікові дані Card API вашого облікового запису Peach Payments: Entity ID та Access Token. Тестові дані беруться з панелі тестового середовища Peach Payments, робочі — з панелі Peach Payments; вони різні. Для вебхуків також потрібен ключ розшифрування, який Peach Payments надсилає під час увімкнення вебхуків Card для магазину (див. «Налаштування»). Сайт має бути доступним з інтернету для отримання вебхуків.

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

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

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

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

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

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

5. Введіть тестові Entity ID та Access Token з панелі тестового середовища Peach Payments і попросіть Peach Payments увімкнути вебхуки Card для URL зі сторінки налаштувань (див. «Налаштування»).

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

Після оновлення налаштування версії 1.0 автоматично переносяться до нових полів.

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

Усі налаштування на одній сторінці: WooCommerce > Settings > Payments > Peach Payments. Над полями є повідомлення: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.; про відсутність Entity ID або Access Token поточного режиму (доти спосіб оплати не показується під час оформлення); про відсутність ключа розшифрування вебхуків поточного режиму (тоді платежі підтверджуються лише після повернення покупця); і про непідтримувану валюту магазину. У списку способів оплати Peach Payments позначено як такий, що потребує налаштування, доки для поточного режиму не вказані Entity ID та Access Token. Під час збереження з облікових даних видаляються пробіли; якщо ключ вебхука не є шістнадцятковим значенням із 64 символів, показується помилка.

Enable/Disable: Enable Peach Payments вмикає або вимикає спосіб оплати. Типово: вимкнено.

Title: назва способу оплати, яку покупець бачить під час оформлення замовлення. Типово: Credit / Debit Card (Peach Payments).

Description: текст під способом оплати під час оформлення замовлення. Типово: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.

Облікові дані API

Access Token та Entity ID Card API показані в панелі Peach Payments (тестові дані — в панелі тестового середовища). Розділ містить посилання на обидві панелі та документацію Peach Payments для розробників.

Test mode: Enable test mode надсилає нові платежі до тестового середовища Peach Payments із тестовими даними, без списання реальних коштів. Зніміть прапорець для реальних платежів із робочими даними. Платіж завжди перевіряється в режимі, у якому його розпочато, навіть після перемикання. Типово: увімкнено.

Test Entity ID: Entity ID (канал 3-D Secure) вашого тестового облікового запису.

Test Access Token: токен доступу bearer вашого тестового облікового запису.

Test Webhook Decryption Key: шістнадцятковий ключ із 64 символів для розшифрування вебхуків Card тестового середовища.

Live Entity ID: Entity ID (канал 3-D Secure) вашого робочого облікового запису.

Live Access Token: токен доступу bearer вашого робочого облікового запису.

Live Webhook Decryption Key: шістнадцятковий ключ із 64 символів для розшифрування вебхуків Card робочого облікового запису.

Вебхук

Вебхуки підтверджують платежі, навіть якщо покупець закриває браузер до повернення в магазин. Розділ показує URL вебхука магазину на зразок https://your-site/wp-json/peach-pay/v1/webhook. Скопіюйте URL точно як у налаштуваннях. Попросіть Peach Payments (support@peachpayments.com) увімкнути вебхуки Card для вашого облікового запису з цим URL, а потім введіть отриманий ключ у поле Webhook Decryption Key того самого режиму.

Peach Payments шифрує кожен вебхук (AES-256-GCM). Вебхук, який не розшифровується тестовим або робочим ключем, відхиляється, тож лише Peach Payments може змінювати замовлення. Вебхук, розшифрований ключем одного режиму, застосовується лише до платежів цього режиму. Плагін використовує платіжні сповіщення:

Debit payment (DB): результат оплати замовлення карткою. Замовлення позначається оплаченим, переводиться в статус «На утриманні» або «Невдале» (див. «Замовлення»).

Refund (RF), reversal (RV), chargeback (CB): повернення чи анулювання в панелі Peach Payments або повідомлення про оскарження платежу. Додається примітка; статус замовлення не змінюється.

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

Платіжна форма

Card brands: системи карток у формі Peach Payments: Visa, Mastercard, American Express, Diners Club. Вибирайте лише ввімкнені для вашого Entity ID. Типово: Visa та Mastercard.

Додатково

Logging: Log API requests and payment results записує налагоджувальну інформацію в WooCommerce > Status > Logs, джерело wcp_peach_pay. Помилки та попередження записуються завжди. Журнали не містять даних карток, ключів чи покупців. Типово: вимкнено.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Вимкнення плагіна ніколи нічого не видаляє. Дані Peach Payments у замовленнях зберігаються. Типово: вимкнено.

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

Покупець вибирає спосіб оплати (типово Credit / Debit Card (Peach Payments)) і натискає Continue to payment. Він переходить на сторінку Pay for order вашого магазину. Там плагін готує платіжну сесію Peach Payments на загальну суму у валюті замовлення та показує форму картки Peach Payments з вибраними системами мовою сайту, якщо Peach Payments її підтримує. У тестовому режимі показується Test mode: use a Peach Payments test card, no real payment will be made.. Дані картки вводяться у формі Peach Payments, скрипт якої завантажується з хешем Subresource Integrity.

Після оплати покупець повертається до магазину. Замовлення позначається оплаченим лише після підтвердження Peach Payments: магазин отримує результат платіжної сесії цього замовлення через Peach Payments API в режимі її створення й перевіряє належність платежу замовленню. Вебхук робить те саме незалежно: перший застосовує результат, другий нічого не змінює. Покупець, який оплатив, бачить сторінку Order received.

Якщо платіж не завершено, покупець повертається на сторінку Pay for order з повідомленням і може спробувати знову: Payment failed: після якого вказана причина від Peach Payments та Please try again or use another card., або The payment was not completed. Please try again.. Якщо результат ще не підтверджено (наприклад, Peach Payments не відповів або вебхук обробляє те саме замовлення), повідомлення буде We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again.. Якщо ключ вебхука для режиму не заданий, покупця натомість просять зв'язатися з вами та вказати номер замовлення.

Якщо форму не вдалося підготувати, покупець бачить коротке повідомлення й кнопку Try again: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (неправильні облікові дані), повідомлення про відхилення провайдером окремих платіжних реквізитів або The payment form could not be loaded. Please try again in a moment.. Замовлення отримує примітку з кодом і описом Peach Payments.

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

Плагін не має форми картки на самій сторінці оформлення, збережених карток, підписок, попередньої авторизації та захоплення, EFT, BNPL, QR чи інших способів без картки.

Замовлення

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

Pending payment: покупець ще не заплатив або платіж не завершено. Він може оплатити те саме замовлення знову.

Processing: платіж підтверджено, сума й валюта відповідають замовленню. Примітка показує код результату, опис та ID платежу Peach Payments; цей ID є ID транзакції замовлення. Якщо Peach Payments позначив платіж для ручної перевірки, примітка просить перевірити його в панелі Peach Payments перед відправленням.

On hold: платіж очікує підтвердження Peach Payments (вебхук завершить його пізніше або позначить невдалим); сума чи валюта відрізняються (примітка amount/currency mismatch — manual review required); або платіж надійшов після скасування замовлення. Примітка пояснює, що перевірити.

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

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

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

Повернення коштів з екрана замовлення WooCommerce недоступні. Поверніть платіж у панелі Peach Payments і зареєструйте ручне повернення в WooCommerce. За налаштованого вебхука повернення, анулювання й оскарження платежів у Peach Payments додаються як примітки із сумою та ID; статус не змінюється.

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

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

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

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

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

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

Peach Payments не з'являється під час оформлення: перевірте активність ліцензії, увімкнення Enable/Disable, наявність Entity ID та Access Token поточного режиму (Test Entity ID і Test Access Token у тестовому, Live Entity ID і Live Access Token у робочому) й валюту ZAR, KES або MUR. Повідомлення вгорі налаштувань вказують проблему. Розробники можуть змінити валюти фільтром peach_p_supported_currencies; додавайте лише оброблювані вашим обліковим записом Peach Payments.

Платіж пройшов, але замовлення залишається Pending payment: покупець не повернувся і вебхук не надійшов. Перевірте, що Peach Payments увімкнув вебхуки Card для точного URL з налаштувань, задано Webhook Decryption Key режиму оплати й URL не блокується обслуговуванням, брандмауером або паролем. Шукайте відхилені вебхуки в WooCommerce > Status > Logs, джерело wcp_peach_pay.

Вебхук відповідає Decryption failed: його не розшифровано тестовим або робочим ключем. Ключ неправильний чи належить іншому обліковому запису або режиму. Введіть ключ Peach Payments для цього URL.

Вебхук відповідає Webhook key not configured: жоден ключ не заданий або не чинний. Введіть ключ із 64 символів. Peach Payments повторно надішле вебхук пізніше.

Вебхук відповідає Order busy, retry later: замовлення одночасно оновлювалося після повернення покупця. Нічого не змінено, Peach Payments надішле вебхук знову.

Вебхук відповідає Missing or malformed data: у запиті не було зашифрованого тіла чи заголовків X-Initialization-Vector / X-Authentication-Tag, наприклад через зміни проксі. Нічого не змінено.

Вебхук відповідає ignored: сповіщення справжнє, але не належить платіжній сесії цього магазину (інший магазин із тим самим Entity ID, видалене замовлення) або надійшло з іншого режиму. Нічого не змінено.

Покупець бачить The payment form is not available right now: Access Token чи Entity ID поточного режиму неправильний. Перевірте дані й режим, прочитайте код Peach Payments у примітці.

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

Під час збереження вимагається шістнадцятковий ключ вебхука з 64 символів: значення не є ключем Peach Payments. До виправлення вебхуки не розшифровуються.

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

Видалення

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

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