VibeFox Paysera for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

PHP: 8.0 или новее.

Проект Paysera: нужны ID проекта и пароль проекта (ключ подписи) вашего проекта Paysera. Способы оплаты, которые видит покупатель, — это способы, включённые в этом проекте. Для обратного вызова в Paysera ничего настраивать не нужно: его URL передаётся с каждым платёжным запросом.

Доступный магазин: заказы получают статус из обратного вызова Paysera, поэтому ваш магазин должен быть доступен из интернета, а не за логином, базовой аутентификацией или брандмауэром. Обратный вызов работает и тогда, когда магазин находится в режиме обслуживания.

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

Установка

Это один zip-файл с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_paysera_payment-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_paysera_payment.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ одинаков для обеих версий.

OpenCart 3

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

2. Перейдите в Extensions > Extensions, выберите тип Payments. Найдите VibeFox Paysera Payment и нажмите Install (зелёная кнопка +). Вашему администратору нужно право изменять список платёжных расширений.

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

4. Введите Project ID и Project password из вашего аккаунта Paysera (см. Конфигурация).

5. По желанию: включите Allow test payments в проекте Paysera и Test payments в расширении, чтобы проверить процесс без списания денег. Перед продажами выключите.

6. Включите Enable/Disable и нажмите Save.

OpenCart 4

1. В админке перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_paysera_payment.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появляется в списке установленных расширений на той же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Paysera Payment, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ, ID и пароль проекта и настройки тестирования так же, как в шагах 3–6 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только URL обратного вызова (см. Проект Paysera).

После новой установки способ оплаты выключен, тестовые платежи выключены, а среда — Production.

Конфигурация

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Paysera Payment > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница показывает Paysera is hidden at checkout until the project ID and the project password are entered., пока не заполнено одно из двух, и Test mode is on: customers are not charged. Turn off "Test payments" and select "Production" before accepting real orders., пока включены тестовые платежи или песочница. Без права изменять расширение страница показывает настройки, но не может их сохранить.

При сохранении Title должен содержать от 1 до 128 символов, Project ID — только цифры, Sort Order — целое число, Total — число не меньше 0, а статусы заказов должны существовать. Если какая-либо проверка не проходит, ничего не сохраняется, и страница показывает ошибки.

Paysera

Enable/Disable: Enable Paysera Payment включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое видит покупатель при оформлении заказа. Оно также сохраняется в заказе как название способа оплаты. По умолчанию: Paysera. Обязательное поле, до 128 символов.

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely via Paysera.

Sort Order: позиция Paysera среди способов оплаты при оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать Paysera только для платёжных адресов в выбранной гео-зоне. По умолчанию: All zones. Гео-зоны настраиваются в System > Localisation > Geo Zones.

Total: сумма заказа в валюте магазина по умолчанию, которую заказ должен достичь, чтобы предлагалась Paysera. Оставьте поле пустым, чтобы предлагать Paysera при любой сумме.

Проект Paysera

ID проекта и пароль проекта находятся в вашем аккаунте Paysera: Projects and activities, ваш проект, General project settings. В этом разделе есть ссылка на аккаунт Paysera.

Callback URL: адрес, по которому Paysera подтверждает каждый платёж. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_paysera_payment/callback, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_paysera_payment/payment/wcp_paysera_payment.callback. Он формируется из адреса магазина вашей установки OpenCart. Он автоматически передаётся с каждым платежом, поэтому в Paysera ничего настраивать не нужно, но он должен быть доступен из интернета. Заказы получают статус только из этих подписанных или зашифрованных обратных вызовов.

Project ID: числовой ID вашего проекта Paysera. Принимаются только цифры: любое другое значение даёт ошибку Project ID must contain digits only: the numeric ID of your Paysera project., и ничего не сохраняется.

Project password: пароль проекта (ключ подписи). Он подписывает платёжные запросы и проверяет обратные вызовы Paysera. Сохранённый пароль больше не показывается. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённый пароль, отметьте Clear saved password (tick and save; an empty field keeps the saved value) под полем и нажмите Save.

Тестирование

Test payments: отправляет платежи в тестовом режиме, поэтому деньги не списываются. Paysera возвращает успешный тестовый платёж без списания у покупателя. Сначала включите Allow test payments в настройках проекта Paysera. Пока эта опция включена, тестовые платежи отмечают заказы оплаченными; когда она выключена, тестовый платёж переводит заказ в «On hold». По умолчанию: выключено. Пока опция включена, покупатель видит на шаге Confirm Order сообщение TEST MODE — no money will be charged.

Environment: куда отправляется покупатель. Для обычного проекта Paysera оставляйте Production, в том числе для тестовых платежей. По умолчанию: Production.

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Заказ получает статус только из обратного вызова Paysera. Отменённый или не исполненный платёж оставляет заказ без статуса, и покупатель может оплатить снова. Каждое поле ниже перечисляет ваши статусы заказов OpenCart.

Order Status After Payment: статус, который устанавливается, когда Paysera подтверждает платёж с ожидаемыми суммой и валютой. По умолчанию: Processing.

Awaiting Payment Status: банк принял платёжное поручение, но ещё не исполнил его. Заказ отмечается оплаченным, когда Paysera подтверждает платёж. По умолчанию: Pending.

On Hold Status: ТЕСТОВЫЙ платёж, пока Test payments выключено, другая сумма или валюта либо платёж после отмены покупателем. Заказ не отмечается оплаченным; примечание объясняет причину. По умолчанию: Pending, так как в OpenCart нет статуса On hold. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

Cancelled Order Status: расширение никогда не устанавливает этот статус, только читает его: платёж, поступивший для заказа в этом статусе, не открывает заказ заново, а лишь добавляет примечание. По умолчанию: Canceled.

Дополнительно

Debug log: записывает события оплаты в файл wc_psr_debug.log.php в папке журналов OpenCart (storage/logs). Файл нельзя открыть через веб. Ошибки и предупреждения записываются всегда; остальные шаги — только пока эта опция включена. Пароли и данные покупателя никогда не записываются. По умолчанию: выключено.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Delete data: если включено, при удалении расширения удаляются его настройки и журнал. Данные заказов (заказы, записи о платежах Paysera) всегда сохраняются. По умолчанию: выключено.

Импорт / Экспорт

Export: Download JSON сохраняет настройки в файл JSON. Пароль проекта не экспортируется.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённый пароль проекта остаётся.

Оформление заказа

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Paysera). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to the Paysera payment window (bank links, cards and other Paysera methods) to complete the payment. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Когда покупатель нажимает Confirm Order, расширение формирует подписанный платёжный запрос с номером заказа, суммой заказа в наименьшей денежной единице валюты заказа, именем, e-mail и платёжным адресом покупателя, а также языком страницы магазина (литовский, латышский, эстонский, русский, немецкий, польский; иначе английский). Покупатель переходит в окно оплаты Paysera и выбирает там банк, карту или другой способ.

Paysera подтверждает платёж серверным обратным вызовом. Заказ отмечается оплаченным только после подписанного подтверждения от Paysera; возврат покупателя в магазин никогда не оплачивает заказ. Затем заказ получает статус обычным для OpenCart способом, с обычными письмами о заказе и обновлением остатков. Когда покупатель возвращается после обратного вызова, показывается страница успешного оформления заказа OpenCart. Если банк принял платёжное поручение, но ещё не исполнил его, заказ получает Awaiting Payment Status, а страница показывает Paysera is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Для заказа на проверке страница показывает Your payment is being reviewed. We will contact you if anything else is needed.

Если покупатель возвращается до обратного вызова, появляется страница Payment confirmation, которая объясняет, что заказ будет подтверждён, как только Paysera подтвердит платёж, и предлагает Check again и Back to checkout.

Если покупатель отменяет оплату в окне Paysera, он возвращается к оформлению заказа с сообщением The Paysera payment was cancelled. You can try again or choose another payment method. Если Paysera сообщает, что платёж не исполнен, сообщение: The payment was not completed. You can try again or choose another payment method. Корзина сохраняется в обоих случаях. В OpenCart 4 эти сообщения показываются над страницей оформления заказа. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, а OpenCart 4 обновляет заказ оформления (новая попытка оплачивает тот же заказ); если другой заказ той же корзины уже оплачен, ожидает оплаты или находится на проверке, новая попытка сразу ведёт на страницу успеха, а не к повторной оплате. Изменение корзины, в том числе новое количество, считается новой корзиной, которой нужна собственная оплата.

OpenCart 4 сохраняет заказ в оформлении до показа страницы успеха. Если этот заказ к тому времени был закрыт (например, вы отменили заказ, который ожидал банковского платежа), покупатель возвращается к оформлению с сообщением Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order. Следующее нажатие Confirm Order оплачивает новый заказ. Если этот заказ уже был оплачен за прежнюю корзину и корзина с тех пор изменилась, покупатель возвращается к оформлению, а следующее Confirm Order оплачивает новый заказ текущей корзины. Закрытый заказ никогда не показывается как оплаченный.

Если платёж не может быть начат, покупатель остаётся на шаге Confirm Order с сообщением Paysera payments are temporarily unavailable. Please choose another payment method. или, при недопустимой сумме заказа, с сообщением This order cannot be paid via Paysera. Причина записывается в журнал.

Обратный вызов работает и тогда, когда магазин находится в режиме обслуживания, потому что OpenCart пропускает запросы платёжных расширений (в OpenCart 4 расширение для этого добавляет собственное стартовое действие, которое также пропускает возврат покупателя из Paysera).

Расширение не поддерживает возвраты из админ-панели, выбор банка или способа оплаты на странице оформления заказа, подписки, сохранённые карты и службы доставки или курьерские службы Paysera.

Заказы

Статусы заказов

Нет статуса (отсутствующий заказ): покупатель был отправлен в Paysera, а обратный вызов ещё не пришёл, или покупатель отменил оплату, или платёж не был исполнен. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в значение Missing Orders.

Order Status After Payment (по умолчанию Processing): Paysera подтвердила платёж с совпадающими суммой и валютой. Примечание показывает запрос и способ оплаты, для тестовых платежей с пометкой (TEST — no money charged).

Awaiting Payment Status (по умолчанию Pending): Paysera приняла платёжное поручение, но банк ещё не исполнил его. Заказ переходит в Order Status After Payment, когда Paysera подтверждает платёж.

On Hold Status (по умолчанию Pending): платёж требует ручной проверки. Оплаченная сумма или валюта отличаются от суммы заказа; ТЕСТОВЫЙ платёж поступил, пока Test payments выключено (деньги не списывались); либо платёж подтверждён после того, как покупатель его отменил. Примечание объясняет это, а вкладка заказа предлагает проверить платёж в вашем аккаунте Paysera, после чего либо перевести заказ в оплаченный статус, либо отменить его и вернуть платёж в Paysera. Последующий корректный платёж для того же заказа отмечает его оплаченным.

Cancelled Order Status (по умолчанию Canceled): платёж, подтверждённый позже для отменённого заказа, не меняет его статус. Примечание предлагает восстановить заказ (перевести в оплаченный статус) или вернуть платёж в Paysera. Если способ оплаты заказа уже не Paysera, подтверждённый платёж лишь добавляет примечание.

Если для уже оплаченного заказа или для другого заказа уже оплаченной корзины поступает ещё один успешный платёж, оплаченный заказ не меняется, а примечание просит вернуть дубликат в вашем аккаунте Paysera. Другие статусы Paysera (платёж не исполнен, дополнительная информация) лишь добавляют примечание. Примечания — это записи в History заказа, которые покупатель не видит.

Вкладка VibeFox Paysera Payment

В Sales > Orders откройте заказ, оплаченный через Paysera. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Paysera Payment показывает Paysera order ID (номер заказа и попытку), Paysera request ID, Environment и метку TEST payment, Status платежа, суммы Requested / paid, Payment method и Notes расширения. Для заказа на проверке она показывает, что нужно проверить. Вкладка только показывает информацию и видна пользователям, имеющим доступ к расширению.

Возвраты

Возвраты из админ-панели не поддерживаются: протокол окна оплаты Paysera не имеет API возвратов. Оформляйте возвраты в вашем аккаунте Paysera. Когда Paysera сообщает о возврате, в заказ добавляется примечание с возвращённой суммой, а статус заказа не меняется. При необходимости зафиксируйте возврат в OpenCart вручную. Возвраты товаров в Sales > Returns не возвращают деньги через Paysera.

Лицензионный ключ

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Paysera Payment — это первый блок на странице Extensions > Extensions > Payments > VibeFox Paysera Payment > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в маскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now, чтобы снова проверить статус, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: opencart-payment-paysera и ссылка 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.

Без действующего ключа Paysera не показывается покупателям при оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Администратор, вошедший в админ-панель в том же браузере, всё ещё видит способ оплаты в магазине, помеченный (unlicensed — visible to admins only), чтобы вы могли настроить и проверить расширение до покупки ключа. В OpenCart 4 этот предпросмотр недоступен: магазин не видит вход администратора, поэтому без действующего ключа способ оплаты скрыт для всех. После того как вы один раз откроете страницу Edit, на Dashboard админ-панели появится напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются обратным вызовом.

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

Устранение неполадок

Paysera не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и заполнены и Project ID, и Project password. Страница настроек показывает предупреждение, пока что-либо из них не заполнено. Также проверьте, что платёжный адрес входит в выбранную Geo Zone, и что сумма заказа достигает Total, заданного в настройках.

Платёж прошёл, но заказ остаётся без статуса: заказ получает статус из обратного вызова Paysera, а не из возврата покупателя. Проверьте, что магазин доступен из интернета по Callback URL, указанному в настройках (не за логином, базовой аутентификацией или брандмауэром), и посмотрите поле Log на странице расширения.

Обратный вызов отвечает Invalid signature: Project password не соответствует проекту, либо обратный вызов не от Paysera. Скопируйте пароль проекта заново. Если вы меняли проект или пароль, платежи, начатые до изменения, больше не могут быть проверены.

Обратный вызов отвечает Project ID mismatch: Project ID в настройках отличается от проекта, который совершил платёж.

Обратный вызов отвечает Order not found: заказ из обратного вызова не имеет платежа Paysera в этом магазине, например платёж был начат в другом магазине с тем же проектом.

Обратный вызов отвечает Gateway not configured, Busy или Temporary error: ID или пароль проекта пуст, другой обратный вызов для той же корзины ещё выполняется, либо не удалось установить статус заказа. Paysera повторяет обратный вызов. Включите Debug log, чтобы увидеть причину.

Paysera отклоняет окно оплаты или сообщает, что проекта не существует: проверьте Environment. Обычный проект Paysera работает только с Production; для Sandbox нужен проект, созданный в песочнице Paysera.

Тестовый платёж не оплачивает заказ: ТЕСТОВЫЙ платёж оплачивает заказ, только пока включены Test payments. Иначе заказ переводится в «On hold» с примечанием, что деньги не списаны. Также включите Allow test payments в проекте Paysera.

Заказ на проверке с примечанием о несовпадении суммы или валюты: Paysera подтвердила платёж, сумма или валюта которого отличаются от суммы заказа. Сравните платёж в вашем аккаунте Paysera и примите заказ или вручную верните платёж.

Покупатель видит Paysera payments are temporarily unavailable: посмотрите поле Log. ID или пароль проекта могут быть пустыми, либо один из адресов магазина, переданных в Paysera, длиннее 255 символов.

Покупатель видит This payment method is not available. Please reload the checkout page.: сессия оформления больше не соответствует заказу, либо способ оплаты тем временем был выключен. Покупатель перезагружает страницу оформления.

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Paysera Payment. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов в разделе Orders, которые при повторной установке возвращаются к значениям по умолчанию. Событие OpenCart расширения также удаляется (в OpenCart 4 также его события и стартовое действие, которое пропускает обратный вызов и возврат покупателя в режиме обслуживания). Если Delete data включено, удаляются остальные настройки (название, описание, ID и пароль проекта, тестирование, логирование) и журнал. Если выключено, они сохраняются для будущей повторной установки. Записи о платежах Paysera всегда сохраняются. Существующие заказы сохраняют свои примечания об оплате.

Чтобы в OpenCart 4 удалить также файлы расширения, после удаления перейдите в Extensions > Installer, нажмите в списке установленных расширений рядом с VibeFox Paysera Payment кнопку Uninstall (оранжевая кнопка −), затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

Paysera — товарный знак её владельца. Это расширение не связано с Paysera и не одобрено Paysera.