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.

Срок вашей сессии истёк. Обновите страницу и попробуйте снова: страница оформления была открыта слишком долго. Покупатель перезагружает страницу.

Этот платёж уже обрабатывается: та же корзина отправлена дважды в один и тот же момент. Покупатель немного подождёт и проверит почту, прежде чем повторять попытку.

Заказ находится в статусе проверки или ожидания после оплаты: прочитайте примечания на вкладке 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.