VibeFox PayPal for PrestaShop — Помощь

Требования

PrestaShop: 8.0 – 9.x.

PHP: 8.0 или новее. Модуль отказывается устанавливаться на более старых версиях PHP.

Аккаунт PayPal: бизнес-аккаунт PayPal с приложением 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. Один ключ работает на одном домене.

Установка

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 (для песочницы и/или рабочего режима) и скопируйте его Client ID и Secret.

5. Введите учётные данные режима, который вы используете, выберите Capture или Authorize, включите Enable/Disable и нажмите Save.

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

При установке модуль создаёт три статуса заказа: 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 mode is on: payments go to the PayPal sandbox, no real money is moved. Сохранение настроек сбрасывает кэшированные токены доступа PayPal, поэтому новые учётные данные используются сразу.

Общие

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 mode: платежи уходят в песочницу PayPal с учётными данными песочницы; реальные деньги не переводятся. По умолчанию: включено. Выключите, чтобы принимать реальные платежи. Списания, аннуляции и возвраты всегда используют среду, в которой был оплачен заказ. Пока режим включён, покупатели видят под способом оплаты надпись 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 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 в качестве ID транзакции, а заметка показывает сумму, заказ 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 для платежей из песочницы, историей возвратов и PayPal notes заказа. Кнопки блока требуют права редактировать заказы, но не доступа к страницам модулей. Результат каждого действия показывается в блоке.

Возвраты

В блоке PayPal payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via PayPal. Подтвердите вопрос Refund this amount through PayPal? This cannot be undone. Поддерживаются полные и частичные возвраты. Причина передаётся в PayPal как примечание для покупателя. Возвраты выполняются в сумме и валюте, которые списал PayPal, поэтому после расхождения по сумме или валюте вы можете вернуть не больше того, что покупатель фактически оплатил, а не сумму заказа. Возврат отправляется в ту среду PayPal, в которой был произведён платёж (песочница или рабочий режим), поэтому учётные данные этой среды должны быть заполнены. Если 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 всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои платёжные заметки и ID транзакций.

PayPal — товарный знак его правообладателя. Этот модуль не связан с PayPal и не одобрен PayPal.