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

Вимоги

PrestaShop: 8.0–9.x.

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

Обліковий запис PayPal: бізнес-обліковий запис PayPal із застосунком REST API у PayPal Developer Dashboard. Потрібні Client ID та Secret застосунку. Застосунки sandbox і live мають різні облікові дані. Вебхук не потрібен: модуль підтверджує кожен платіж на вашому сервері, поки покупець перебуває в оформленні замовлення.

Валюта: одна з валют, які підтримує PayPal: AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, MYR, NOK, NZD, PHP, PLN, SEK, SGD, THB, TWD або USD.

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

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

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

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

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

4. У PayPal Developer Dashboard створіть застосунок REST API (sandbox та/або live) і скопіюйте його Client ID та Secret.

5. Введіть облікові дані режиму, який використовуєте, оберіть Capture або Authorize, увімкніть Enable/Disable і натисніть Save.

6. Перевірте роботу з тестовим покупцем sandbox PayPal, потім вимкніть Sandbox mode і введіть облікові дані live.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox PayPal Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, коли спосіб оплати увімкнено, але Client ID або Secret вибраного режиму порожні, а також коли PayPal не підтримує валюту магазину за замовчуванням. В обох випадках спосіб оплати приховується в оформленні замовлення. Поки увімкнено режим sandbox, сторінка показує Sandbox mode is on: payments go to the PayPal sandbox, no real money is moved. Збереження налаштувань скидає кешовані токени доступу PayPal, тож нові облікові дані використовуються одразу.

General

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

Title: назва способу оплати, яку бачать покупці в оформленні замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: PayPal. Обов'язково.

Description: текст, що відображається під способом оплати в оформленні замовлення. За замовчуванням: Pay with your PayPal account or a card via PayPal.

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

Створіть застосунок REST API у PayPal Developer Dashboard і скопіюйте його Client ID та Secret. У розділі є посилання на застосунки sandbox і застосунки live. Показуються лише поля вибраного режиму; облікові дані обох режимів залишаються збереженими.

Sandbox mode: платежі надсилаються до sandbox PayPal з обліковими даними sandbox; реальні кошти не переказуються. За замовчуванням: увімкнено. Вимкніть, щоб приймати реальні платежі. Захоплення, анулювання та повернення завжди використовують середовище, в якому було оплачено замовлення. Поки режим увімкнено, покупці бачать під способом оплати напис Sandbox mode: pay with a PayPal sandbox buyer account — no real money is charged.

Sandbox Client ID: Client ID вашого застосунку REST API для sandbox.

Sandbox Secret: Secret вашого застосунку REST API для sandbox.

Live Client ID: Client ID вашого застосунку REST API для live.

Live Secret: Secret вашого застосунку REST API для live.

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

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

Оплата

Payment action: що відбувається, коли покупець схвалює платіж. За замовчуванням: Capture.

Додатково

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

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням PayPal), і замість платіжної форми з'являється кнопка PayPal. Натискання кнопки створює на вашому сервері замовлення PayPal на суму кошика у валюті кошика. Сума завжди розраховується на сервері, а не в браузері. На цьому етапі замовлення ще не існує.

Покупець підтверджує платіж у вікні PayPal за допомогою облікового запису PayPal або іншого джерела фінансування, яке пропонує PayPal. Після цього оформлення замовлення показує PayPal payment approved. Completing your order… і створює замовлення. Якщо умови обслуговування ще не прийнято, оформлення замовлення показує PayPal payment approved. Click "Place order" to complete it. Якщо покупець натискає Place order, не схваливши платіж, з'являється повідомлення Please click the PayPal button and approve the payment first.

Далі ваш сервер зчитує замовлення PayPal і перевіряє, що воно схвалене, створене саме для цього кошика, не використовується іншим кошиком, а його сума та валюта збігаються з кошиком. Лише після цього платіж захоплюється (або авторизується), замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення.

Якщо сума кошика змінилася після схвалення, нічого не захоплюється. Покупець бачить The order total changed after you approved the payment in PayPal. Please click the PayPal button again to approve the new total. Якщо PayPal відхиляє платіж, покупець повертається до етапу оплати і отримує пропозицію натиснути кнопку PayPal та обрати інший спосіб оплати. Замовлення не створюється. Якщо покупець закриває вікно PayPal, оформлення замовлення показує You cancelled the PayPal payment.

Якщо PayPal не відповідає під час захоплення, покупець бачить We could not confirm your PayPal payment yet. Please try again in a moment — you will not be charged twice. Схвалення зберігається, навіть після перезавантаження сторінки, і Place order використовує його знову. Якщо PayPal вже завершив попередню спробу, використовується цей платіж, а нове схвалення не захоплюється. Якщо платіж списано, але замовлення створити не вдалося, покупець бачить Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. Наступна спроба створює замовлення зі збереженого платежу без повторного списання.

Скрипт PayPal завантажується лише на сторінці оформлення замовлення і у власному просторі імен, тож він не конфліктує з іншим модулем PayPal на сторінці. Модуль працює з темами Classic та Hummingbird.

У модуля немає вебхуків PayPal, повідомлень Pay Later, полів для картки, а також Venmo, Apple Pay, Google Pay чи Fastlane, збережених способів оплати або підписок, і кнопок на сторінках товарів чи кошика. Використовуються адреси, введені в оформленні замовлення PrestaShop, а не адреса з PayPal.

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

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

No order yet: покупець не схвалив платіж, або PayPal його відхилив. Існує лише кошик.

Payment accepted: захоплення завершено. Замовлення позначається оплаченим лише після підтвердження PayPal. Платіж записується з ідентифікатором захоплення PayPal як ідентифікатором транзакції, а нотатка показує суму, замовлення PayPal і захоплення.

PayPal payment authorized: платіж авторизовано, він очікує на захоплення (дія з платежем Authorize).

Awaiting PayPal payment: захоплення має статус PENDING у PayPal, наприклад через перевірку платежу.

PayPal payment on hold: оплачена сума або валюта не збігаються із замовленням, або платіж не вдалося зчитати з відповіді PayPal. Нотатка пояснює причину. Коли PayPal списав кошти у валюті замовлення, фактично сплачена сума записується як платіж. Перевірте замовлення та виконайте його або поверніть платіж.

Canceled: авторизацію анульовано за допомогою Void PayPal authorization.

Payment error: очікуване захоплення відхилено або завершилося помилкою.

Refunded: платіж повністю повернуто через модуль.

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

Блок платежу PayPal

На сторінці замовлення є блок PayPal payment з ідентифікатором замовлення PayPal і наміром (intent), ідентифікатором захоплення (посилання на платіж у вашому обліковому записі PayPal, sandbox або live), ідентифікатором авторизації, статусом платежу, сумою, сплаченою та поверненою сумами, позначкою Sandbox для платежів sandbox, історією повернень і PayPal notes замовлення. Кнопки блоку потребують права редагувати замовлення, але не доступу до сторінок модулів. Результат кожної дії показується в блоці.

Повернення

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

Платіж, який лише авторизовано, повернути не можна: натомість скористайтеся Void PayPal authorization. Модуль не створює кредитових нот. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають кошти через PayPal. Повернення, суперечки та скасування, здійснені в обліковому записі PayPal, не синхронізуються з PrestaShop.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox PayPal Gateway є першим блоком на сторінці Modules > Module Manager > VibeFox PayPal Gateway > Configure, над налаштуваннями. Вставте ключ у поле License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) та кнопки Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розташовані рядок Product: presta-payment-paypal і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові back office (включено англійську та російську).

Якщо ключ не прийнято, блок пояснює причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on із датою. Після зміни адреси магазину або після звільнення слота домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль працює з останнім відомим статусом.

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

Без активного ключа PayPal не показується покупцям в оформленні замовлення. Якщо платіж усе ж розпочато, магазин відмовляється створити замовлення PayPal, і покупець бачить An error occurred during PayPal checkout. Please try again. Вітрина PrestaShop не знає, що ви ввійшли в back office, тож спосіб оплати приховано і для вас: ви можете налаштувати модуль до купівлі ключа, але не протестувати його в оформленні замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: повернення та дії в блоці PayPal продовжують працювати.

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

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

PayPal does not appear at checkout: перевірте, що ліцензія активна, Enable/Disable увімкнено, Client ID і Secret вибраного режиму заповнено, валюта кошика підтримується PayPal, а сума кошика більша за нуль. Сторінка налаштувань показує попередження, якщо проблема в облікових даних або валюті. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця. Розширення браузера, яке блокує www.paypal.com, також приховує кнопку.

The payment went through, but no order was created: модуль не має вебхука, тож платіж підтверджується лише під час оформлення замовлення. Це трапляється, коли PayPal не відповів під час захоплення або коли замовлення не вдалося створити. Увімкніть Debug log і перегляньте поле Log, перевірте платіж в обліковому записі PayPal або дайте покупцю повторити спробу: повторна спроба ніколи не списує кошти двічі і створює замовлення зі збереженого платежу.

PayPal could not be loaded: скрипт PayPal не завантажився в браузері, наприклад через блокувальник або проблему з мережею.

PayPal is not available right now: облікові дані неправильні або належать до іншого режиму. Скопіюйте Client ID і Secret потрібного застосунку ще раз.

Your PayPal approval could not be matched to this checkout: замовлення PayPal не було створено для цього кошика, наприклад після завершення сесії. Покупець знову натискає кнопку PayPal.

This payment is already being processed: той самий кошик було надіслано двічі одночасно. Покупець трохи почекає і перевірить електронну пошту, перш ніж повторити спробу.

The order is on hold after payment: прочитайте нотатки в блоці PayPal payment. Платіж було авторизовано (захопіть його через Capture PayPal payment), захоплення має статус PENDING у PayPal (пізніше скористайтеся Check PayPal payment status), або оплачена сума чи валюта не збіглися із замовленням (виконайте замовлення або поверніть сплачене).

Capture of an authorization fails: авторизація могла бути створена понад 29 днів тому або вже анульована. Блок і нотатки показують помилку PayPal.

Refund fails: у замовлення немає захоплення PayPal (лише авторизація), сума перевищує залишок до повернення, або відсутні облікові дані середовища, у якому було здійснено платіж. Блок вказує, який саме випадок.

Видалення

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

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