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

Вимоги

PrestaShop: 8.0–9.x.

PHP: 8.0 або новіша версія з розширенням OpenSSL (потрібне для розшифрування вебхуків). Без них модуль не встановлюється.

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

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

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

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

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

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

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

4. Введіть тестові Entity ID та Access Token із sandbox-панелі Peach Payments і попросіть Peach Payments увімкнути вебхуки Card для URL вебхука, який показано на сторінці налаштувань (див. Налаштування).

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

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

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

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

Peach Payments

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 credentials

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

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

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

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

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

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

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

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

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

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

Webhook

Вебхуки підтверджують платежі, навіть коли покупець закриває браузер до повернення в магазин. Поле Webhook URL показує URL вебхука вашого магазину. З дружніми URL він має такий вигляд: https://your-shop/module/wcp_peach_pay/webhook, можливо, з кодом мови, наприклад /en/. Скопіюйте URL точно так, як він показаний у налаштуваннях. Попросіть Peach Payments (support@peachpayments.com) увімкнути вебхуки Card для вашого облікового запису з цим URL, а потім введіть отриманий ключ розшифрування в поле Webhook Decryption Key того самого режиму.

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

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

Payment form

Card brands: системи, які показуються у формі Peach Payments: Visa, Mastercard, American Express, Diners Club. Обирайте лише ті системи, які увімкнено для вашого Entity ID. За замовчуванням: Visa та Mastercard. Якщо не обрано жодної системи, під час збереження з’являється попередження, а форма показує Visa та Mastercard.

Advanced

Logging: записує запити до API та результати платежів у файл logs/peach_p_debug.log.php у папці модуля. Файл не можна прочитати з веб-браузера. Помилки та попередження записуються завжди. Журнали не містять даних карток, ключів чи даних покупців. За замовчуванням: вимкнено.

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

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

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

Клієнт обирає спосіб оплати (за замовчуванням Credit / Debit Card (Peach Payments)) і підтверджує замовлення. У тестовому режимі спосіб оплати показує Test mode: no real payment will be made. Модуль готує checkout Peach Payments на суму кошика у валюті кошика та показує сторінку Peach Payments payment вашого магазину з платіжною формою карток Peach Payments і обраними системами карток, мовою покупця, якщо Peach Payments її підтримує. У тестовому режимі сторінка показує Test mode: use a Peach Payments test card, no real payment will be made. Дані картки вводяться у формі Peach Payments, а скрипт форми завантажується з хешем Subresource Integrity. Посилання Choose another payment method повертає до оформлення замовлення. На цьому етапі замовлення ще не існує. Перезавантаження сторінки повторно використовує той самий checkout протягом до 25 хвилин, якщо кошик не змінився.

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

Якщо платіж не завершено, покупець повертається до оформлення замовлення з повідомленням і може спробувати знову: 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. Якщо для режиму платежу не задано ключа вебхука, покупцеві натомість пропонують зв’язатися з вами.

Якщо платіжну форму не вдається підготувати, покупець залишається на оформленні замовлення з коротким повідомленням: 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. Технічна причина записується в журнал.

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

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

Замовлення

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

No order yet: покупець не оплатив, платіж відхилено або не завершено, чи Peach Payments ще не підтвердив його. Існує лише кошик, і покупець може оплатити знову.

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

Awaiting Peach Payments payment: Peach Payments повідомив про платіж, який очікує на підтвердження. Пізніше вебхук переводить замовлення в Payment accepted або позначає його як невдале.

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

Payment error: Peach Payments відхилив платіж, на який чекало замовлення в очікуванні. Відхилена спроба ніколи не змінює замовлення, яке оплачене, на утриманні або скасоване.

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

Блок платежу Peach Payments

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

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

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

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

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

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

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

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

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

Платіж пройшов, але замовлення не створено: покупець не повернувся в магазин, а вебхук не надійшов. Перевірте, що Peach Payments увімкнув вебхуки Card саме для URL, показаного в налаштуваннях, що введено Webhook Decryption Key того режиму, в якому було зроблено платіж, і що жоден брандмауер або захист паролем не блокує URL. Увімкніть Logging і перегляньте поле Log на відхилені вебхуки.

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

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

Вебхук відповідає Busy, retry later: кошик у той самий момент обробляло повернення покупця, або не вдалося створити замовлення (наприклад, модуль вимкнено). Нічого не змінилося, і Peach Payments надішле вебхук знову. Причину показано в журналі.

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

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

URL вебхука в браузері показує Method not allowed: це нормально. URL приймає лише запити від Peach Payments.

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

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

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

Видалення

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

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