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

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіша (перевірено на 4.1.0.3).

PHP: 8.0 або новіша.

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

Валюта: одна з валют, які підтримує 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. Один ключ працює на одному домені.

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

Завантаження — це один zip-архів із пакетами для обох версій OpenCart. Розпакуйте його на своєму комп'ютері. Він містить README.txt, пакет OpenCart 3 wcp_paypal_gateway-oc3-(version).ocmod.zip і пакет OpenCart 4 wcp_paypal_gateway.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_paypal_gateway-oc3-(version).ocmod.zip. Розширення не має модифікацій OCMOD, тому Extensions > Modifications не потребує оновлення. Замість інсталятора можна скопіювати вміст папки upload цього пакета в кореневу папку вашого магазину.

2. Перейдіть до Extensions > Extensions і оберіть тип Payments. Знайдіть VibeFox PayPal Gateway і натисніть Install (зелена кнопка +). Вашому адміністративному користувачу потрібне право змінювати список розширень оплати.

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

4. У PayPal Developer Dashboard створіть застосунок REST API (пісочниця та/або робочий режим) і скопіюйте його Client ID та Secret до розділу API credentials.

5. Оберіть Capture або Authorize, увімкніть Enable/Disable і натисніть Save.

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

OpenCart 4

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_paypal_gateway.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з назви файлу, і перейменований пакет не працює.

2. Пакет з'являється у списку встановлених розширень на тій самій сторінці. Натисніть поруч із ним Install (зелена кнопка +).

3. Перейдіть до Extensions > Extensions і оберіть тип Payments. Знайдіть VibeFox PayPal Gateway, натисніть Install (зелена кнопка +), потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ, облікові дані PayPal та дію оплати так само, як у кроках 3–6 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях. Розширення не змінює розширення PayPal, що постачається з OpenCart 4: обидва можна встановити в одному магазині.

Нова інсталяція починає роботу з вимкненим способом оплати та увімкненим режимом пісочниці.

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

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

Під час збереження Title не може бути порожнім (до 128 символів), Sort Order має бути цілим числом (від'ємні числа дозволені), Total має бути числом, не меншим за 0, а статуси замовлень мають існувати. Якщо якась перевірка не пройдена, нічого не зберігається, і сторінка перелічує помилки. Збереження налаштувань скидає кешовані токени доступу PayPal, тож нові облікові дані використовуються одразу.

Загальні

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

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

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

Sort Order: позиція PayPal серед способів оплати на оформленні замовлення. Залиште поле порожнім або введіть ціле число.

Geo Zone: пропонувати PayPal лише для адрес оплати у вибраній географічній зоні. За замовчуванням: All zones. Географічні зони налаштовуються в System > Localisation > Geo Zones.

Total: сума оформлення замовлення у валюті за замовчуванням магазину, якої має досягти замовлення, перш ніж буде запропоновано PayPal. Залиште поле порожнім, щоб пропонувати PayPal за будь-якої суми.

API credentials

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

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

Sandbox Client ID: Client ID вашого застосунку REST API пісочниці.

Sandbox Secret: Secret вашого застосунку REST API пісочниці.

Live Client ID: Client ID вашого робочого застосунку REST API.

Live Secret: Secret вашого робочого застосунку REST API.

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

Оплата

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

Замовлення

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення). Замовлення отримує статус лише після того, як PayPal відповість на захоплення або авторизацію на вашому сервері. Відхилений платіж залишає замовлення без статусу, і клієнт залишається на кроці Confirm Order. Кожне поле нижче перелічує ваші статуси замовлень OpenCart.

Order Status After Payment: захоплення завершено, також коли авторизацію захоплено або очікуване захоплення завершено на вкладці замовлення. За замовчуванням: В обробці.

Awaiting Payment Status: захоплення має статус PENDING у PayPal (перевірка платежу, кошти ще не зараховані). За замовчуванням: Очікування.

Authorized Status: дія оплати Authorize: кошти зарезервовано, але ще не сплачено. За замовчуванням: Очікування.

On Hold (Review) Status: PayPal списав кошти, але платіж не вдалося прочитати, або сума чи валюта не збігаються із замовленням. Примітка пояснює, що перевірити. За замовчуванням: Очікування, оскільки в OpenCart немає статусу On hold. Власні статуси можна створити в System > Localisation > Order Statuses і вибрати тут.

Voided Status: авторизацію анульовано на вкладці замовлення, а зарезервовані кошти звільнено. За замовчуванням: Скасовано.

Refunded Status: платіж повністю повернено. Часткові повернення лише додають примітку. За замовчуванням: Повернено.

Failed Status: очікуване захоплення відхилено PayPal. За замовчуванням: Невдалий.

Додатково

Debug log: записує запити до API у файл wc_plg_debug.log.php у папці журналів OpenCart (storage/logs). Файл не можна відкрити через веб; у разі досягнення 5 МБ його переміщують до wc_plg_debug.old.log.php. Помилки та попередження записуються завжди, навіть коли цей перемикач вимкнено. Облікові дані, токени та дані покупців ніколи не записуються. За замовчуванням: вимкнено.

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

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

Імпорт / експорт

Export: Download JSON зберігає налаштування у файл JSON. Секрети не експортуються.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування. Збережені секрети зберігаються.

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

На кроці Payment Method клієнт обирає спосіб оплати (за замовчуванням PayPal). OpenCart створює замовлення на кроці Confirm Order, ще без статусу. Там клієнт бачить ваш опис і кнопку PayPal. Натискання кнопки створює на вашому сервері замовлення PayPal на суму замовлення у валюті замовлення. Сума завжди розраховується на сервері, ніколи в браузері. На OpenCart 4 клієнт обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options; опис і кнопка PayPal тоді з'являються в блоці підтвердження внизу сторінки оформлення замовлення, поруч із кнопкою Confirm Order.

Клієнт підтверджує платіж у вікні PayPal з обліковим записом PayPal або іншим джерелом фінансування, яке пропонує PayPal. Потім оформлення показує PayPal payment approved. Completing your order… і завершує замовлення самостійно. Якщо клієнт натискає Confirm Order, не підтвердивши платіж, з'являється повідомлення Please click the PayPal button and approve the payment first.

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

Якщо сума замовлення змінилася після підтвердження, нічого не захоплюється. Клієнт бачить 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. Підтвердження зберігається для цього кошика, навіть після перезавантаження сторінки: оформлення показує PayPal payment approved. Click "Confirm Order" to complete it. і Confirm Order використовує його знову. Якщо PayPal вже завершив попередню спробу, використовується цей платіж, і нове підтвердження не захоплюється. Якщо платіж списано, але статус замовлення не вдалося встановити, клієнт бачить Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. Наступна спроба встановлює статус за збереженим платежем без повторного списання.

OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order, а OpenCart 4 оновлює замовлення оформлення, тож платіж належить кошику: підтвердження, зроблене для попереднього замовлення того самого кошика, оплачує поточне замовлення, якщо сума та сама, а кошик, який уже оплачено, ніколи не списується повторно. Зміна кошика, зокрема нова кількість, вважається новим кошиком, якому потрібен власний платіж. Скрипт PayPal завантажується з PayPal лише на кроці Confirm Order і у власному просторі імен, тож не конфліктує з іншим розширенням PayPal на сторінці.

OpenCart 4 зберігає замовлення оформлення доти, доки не буде показано сторінку успішного оформлення. Якщо це замовлення тим часом було закрите (наприклад, ви його скасували або очікуване захоплення було відхилено) або вже оплачене за раніший кошик, клієнт бачить Your previous order of this checkout is already closed or paid. Please refresh the page and confirm the order again — a new order will be created. Після перезавантаження сторінки наступний платіж оплачує нове замовлення. Оплачене замовлення ніколи не показується як оплачене для іншого кошика.

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

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

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

Без статусу (відсутнє замовлення): клієнт не підтвердив платіж, або PayPal його відхилив. У розділі Sales > Orders такі замовлення показуються лише з фільтром Order Status, встановленим на Missing Orders.

Статус замовлення після оплати (за замовчуванням В обробці): захоплення завершено. Примітка показує суму, замовлення PayPal та захоплення.

Авторизований статус (за замовчуванням Очікування): платіж авторизовано і очікує захоплення (дія оплати Authorize).

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

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

Статус анулювання (за замовчуванням Скасовано): авторизацію анульовано через Void PayPal authorization.

Статус невдачі (за замовчуванням Невдалий): очікуване захоплення відхилено або не вдалося.

Статус повернення (за замовчуванням Повернено): платіж повністю повернено через розширення.

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

Примітки — це записи в History замовлення, які клієнт не бачить. Зміни статусу, зроблені на вкладці замовлення (захоплення, анулювання, перевірка статусу, повернення), записуються безпосередньо, без повідомлення клієнта і без зміни складу.

Вкладка VibeFox PayPal Gateway

У розділі Sales > Orders відкрийте замовлення, оплачене через PayPal. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox PayPal Gateway показує PayPal order ID та намір (intent), з позначкою Sandbox для платежів пісочниці, Capture ID (посилання на платіж в обліковому записі PayPal, пісочниця або робочий режим), Authorization ID, Status платежу, Amount, суми Paid / refunded, історію повернень і PayPal notes замовлення. Вкладка показується користувачам, які мають доступ до розширення; її кнопки потребують права змінювати розширення (встановлюється в System > Users > User Groups). Результат кожної дії показується на вкладці.

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

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

Платіж, який лише авторизовано, повернути не можна: натомість використовуйте Void PayPal authorization. Повернення товарів у розділі Sales > Returns не повертають кошти через PayPal. Повернення, суперечки та відміни платежів, зроблені у вашому обліковому записі PayPal, не синхронізуються з OpenCart.

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

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

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

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

Без активного ключа PayPal не показується клієнтам на оформленні замовлення. Якщо все ж запускається оплата, магазин відмовляється створити замовлення PayPal, і клієнт бачить An error occurred during PayPal checkout. Please try again. Адміністратор, який увійшов в адмін-панель у тому самому браузері, усе ще бачить спосіб оплати в магазині, позначений як (unlicensed — visible to admins only), тож ви можете налаштувати та перевірити розширення до купівлі ключа. В OpenCart 4 цей попередній перегляд недоступний: магазин не бачить вхід адміністратора, тому без активного ключа спосіб оплати прихований для всіх. Після того як ви один раз відкриєте сторінку Edit, на Dashboard адмін-панелі з'явиться нагадування. Закрийте його кнопкою ×, щоб приховати на 7 днів. Наявні замовлення не змінюються: повернення та дії на вкладці замовлення продовжують працювати.

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

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

PayPal не з'являється на оформленні замовлення: перевірте, що ліцензія активна, що Enable/Disable увімкнено, що Client ID та Secret вибраного режиму заповнені, що валюта замовлення підтримується PayPal і що сума замовлення більша за нуль. Сторінка налаштувань показує попередження, якщо проблема в облікових даних або валюті магазину. Також перевірте, що платіжна адреса входить до вибраної Geo Zone і що замовлення досягає Total, встановленого в налаштуваннях.

Платіж пройшов, але замовлення залишається без статусу: у розширення немає вебхука, тому платіж підтверджується лише під час оформлення. Це відбувається, коли PayPal не відповів під час захоплення або не вдалося встановити статус замовлення. Увімкніть Debug log і перегляньте поле Log, перевірте платіж у вашому обліковому записі PayPal або дайте клієнту повторити спробу: повторна спроба ніколи не списує кошти двічі та встановлює статус за збереженим платежем.

Не вдалося завантажити PayPal: скрипт PayPal не завантажився в браузері, наприклад через те, що розширення браузера блокує www.paypal.com, або через проблему з мережею.

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

Ваше підтвердження PayPal не вдалося зіставити з цим оформленням: замовлення PayPal не було створено в цьому оформленні, наприклад після завершення сесії. Клієнт знову натискає кнопку PayPal.

Ваша сесія завершилася. Оновіть сторінку та спробуйте знову: сторінка оформлення була відкрита занадто довго. Клієнт перезавантажує сторінку.

Цей платіж уже обробляється: той самий кошик надіслано двічі в один і той самий момент. Клієнт трохи чекає і перевіряє e-mail, перш ніж повторити спробу.

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

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

На вкладці немає кнопок: вкладка пояснює причину: ваша група користувачів не має права змінювати розширення, платіж повністю повернено, або не налаштовано Client ID та Secret середовища, в якому відбувся платіж.

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

Видалення

Перейдіть до Extensions > Extensions, оберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox PayPal Gateway. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total і статуси замовлень розділу Orders, які при повторному встановленні повертаються до значень за замовчуванням. Кешовані токени доступу PayPal завжди видаляються. Якщо Delete data on uninstall увімкнено, видаляються інші налаштування шлюзу (режим пісочниці, облікові дані, дія оплати, журналювання) та журнал. Якщо вимкнено, вони зберігаються для наступного встановлення. Транзакції та повернення PayPal завжди зберігаються, тож замовлення, оплачені раніше, можна повернути, захопити або анулювати й після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату.

На OpenCart 4, щоб видалити також файли розширення, перейдіть до Extensions > Installer після видалення та натисніть Uninstall (помаранчева кнопка −) поруч із VibeFox PayPal Gateway у списку встановлених розширень, потім Delete (червона кнопка з кошиком), щоб видалити завантажений пакет.

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