VibeFox TrustPay for OpenCart — Помощь

Требования

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

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

Аккаунт finby (TrustPay): нужен проект в finby Merchant Portal с Project ID и Secret key. Для тестовых платежей нужен отдельный тестовый (playground) проект с собственными Project ID и Secret key. Другие ключи не нужны: Secret key используется и для доступа к API, и для проверки подписи уведомлений о платежах.

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

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

Установка

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

OpenCart 3

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

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

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

4. Введите Project ID и Secret key тестового проекта, а для реальных платежей — боевого проекта (см. раздел «Настройки»). URL уведомлений передаётся с каждым платежом, поэтому в Merchant Portal ничего настраивать не нужно.

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

OpenCart 4

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

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

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

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

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

Настройки

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox TrustPay Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если способ оплаты включён, но Project ID или Secret key текущего режима пусты, и если валюта магазина по умолчанию не поддерживается. В обоих случаях способ оплаты скрыт при оформлении заказа. Без права на изменение расширения страница показывает настройки, но не может их сохранить.

При сохранении Title не должен быть пустым и длиннее 128 символов, Sort order должен быть целым числом (отрицательные значения допускаются), Minimum total должен быть числом не меньше 0, а выбранная гео-зона и статусы заказов должны существовать. Иначе ничего не сохраняется, и страница показывает сообщение. Project ID должен содержать только цифры: если вы сохраните другое значение, страница покажет must contain digits only — the previous value was kept., а остальные поля сохранятся.

TrustPay / finby

Enable / Disable: Enable TrustPay / finby card payments. включает или выключает способ оплаты. По умолчанию: выключено.

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely by card on the TrustPay / finby payment page.

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

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

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

Данные API

Скопируйте Project ID и Secret key вашего проекта из finby (TrustPay) Merchant Portal. В разделе есть ссылка на Merchant Portal. Тестовые платежи используют отдельный тестовый (playground) проект с собственными Project ID и Secret key. Реальные деньги там не списываются.

Test mode: использует тестовый проект (без реальных платежей). Новые платежи и возвраты используют тестовые данные. Возвраты по заказу всегда идут в тот проект, через который был оплачен заказ. По умолчанию: включено. Пока режим включён, покупатели видят на шаге Confirm Order сообщение Test mode: no real payment will be taken.

Live Project ID: числовой Project ID вашего боевого проекта.

Live Secret key: Secret key боевого проекта. Он используется для получения токенов доступа к API и проверки уведомлений о платежах.

Test Project ID: числовой Project ID вашего тестового (playground) проекта.

Test Secret key: Secret key тестового проекта.

Secret key сохраняются точно в том виде, в каком введены; удаляются только пробелы в начале и в конце. Сохранённые Secret key больше никогда не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Сохранение настроек также сбрасывает кэш токенов доступа к API, поэтому новые данные применяются сразу.

Clear saved secrets: отметьте Secret key и нажмите Save, чтобы его удалить. Пустое поле оставляет сохранённое значение.

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

OpenCart создаёт заказ на шаге Confirm Order без статуса (заказ без статуса). Заказ получает статус только после того, как finby подтверждает его подписанным уведомлением. Каждое поле ниже содержит ваши статусы заказов OpenCart. У OpenCart нет собственных статусов для ожидающего или удерживаемого платежа TrustPay, поэтому оба используют статус «Ожидание» по умолчанию; примечания к заказу и вкладка заказа различают их. Собственные статусы можно создать в System > Localisation > Order Statuses и выбрать здесь.

Order status after payment: статус оплаченного заказа. По умолчанию: В обработке. Выберите Выполнен, если оплаченные заказы нужно сразу завершать. Статус устанавливается за один шаг, поэтому покупатель получает одно письмо.

Awaiting TrustPay payment: finby сообщил, что последний платёж ожидает обработки; заказ переходит в статус оплаты, когда finby подтверждает платёж. По умолчанию: Ожидание.

TrustPay payment on hold: платёж только авторизован (его нужно списать в Merchant Portal), или оплаченная сумма или валюта не совпадают с запросом на оплату или суммой заказа. По умолчанию: Ожидание.

Payment error: finby отклонил последний платёж ожидающего заказа. Позже подтверждённый платёж всё равно переводит заказ в статус оплаты. По умолчанию: Неудачный.

Cancelled order status: расширение его не устанавливает. Заказ в этом статусе никогда не открывается заново поздним платежом; добавляется примечание. По умолчанию: Отменен.

Refunded order status: устанавливается после полного возврата со страницы заказа. По умолчанию: Возвращен.

Уведомления о платежах

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

Расширение само не запрашивает у finby статус платежа. Если уведомление не доходит до магазина, заказ остаётся без статуса, пока finby его не доставит. finby повторяет уведомления.

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

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

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Card payment (TrustPay)). Он предлагается только тогда, когда валюта покупателя входит в поддерживаемые: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF и USD. На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to the secure TrustPay / finby payment page to pay by card. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа.

Когда покупатель нажимает Confirm Order, расширение создаёт в finby запрос на оплату картой на сумму заказа в валюте заказа. Суммы в HUF передаются без десятичных знаков. Имя, адрес и e-mail покупателя передаются для 3-D Secure, а номер заказа OpenCart передаётся как ссылка. Для оплаты картой нужен адрес: если не указана улица, город, индекс или страна, покупатель видит Please enter your billing address (street, city, postcode and country) — it is required for card payments. В OpenCart 4, который по умолчанию не запрашивает платёжный адрес, недостающие поля берутся из адреса доставки. Покупатель перенаправляется на страницу оплаты finby и платит картой там. Страница открывается на языке магазина, если finby его поддерживает, иначе на английском.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после того, как finby подтверждает его подписанным уведомлением. Само возвращение никогда не меняет статус платежа. Если уведомление уже пришло, покупатель видит страницу успешного оформления заказа OpenCart. Если нет, открывается страница Payment confirmation с текстом TrustPay / finby is confirming your card payment. Your order is confirmed as soon as the payment is confirmed, and you will receive an e-mail — there is no need to pay again. На ней есть кнопка Check again и кнопка Back to checkout. Пока заказ находится в статусе ожидания или удержания, на странице успеха показывается Your card payment is being confirmed by TrustPay / finby. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Когда заказ в статусе ожидания или удержания потом оплачивается или finby отклоняет его платёж, покупатель получает письмо о новом статусе заказа. Если finby отклонил платёж или неоплаченный заказ был отменён, на странице успеха показывается Your card payment was not completed. Please contact us about this order. В OpenCart 4, когда покупатель возвращается со страницы оплаты finby, короткая промежуточная страница снова открывает адрес возврата в вашем магазине, поэтому корзина и вход покупателя сохраняются.

Если покупатель отменяет оплату на странице платежа, он возвращается к оформлению заказа с сообщением The card payment was cancelled. You can try again or choose another payment method. Если страница платежа возвращает ошибку или finby уже отклонил платёж, выводится The card payment was not completed. Please try again or choose another payment method. Корзина сохраняется, и покупатель может оплатить снова. В OpenCart 4 эти сообщения выводятся над страницей оформления заказа.

OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order; OpenCart 4 обновляет заказ оформления. Одна корзина оплачивается только одним заказом: как только у одного из заказов корзины появляется статус TrustPay, повторное подтверждение корзины ведёт на страницу успеха, а не на вторую оплату. Изменение корзины, в том числе новое количество, считается новой корзиной, которой нужна своя оплата.

OpenCart 4 сохраняет заказ в оформлении до показа страницы успеха. После отменённого или неудачного платежа покупатель оплачивает тот же заказ новым запросом на оплату finby. Если этот заказ к тому времени был закрыт, покупатель возвращается к оформлению, и следующее Confirm Order оплачивает новый заказ: после отклонённого платежа или отменённого неоплаченного заказа — с The card payment was not completed. Please try again or choose another payment method., в остальных случаях (например, если вы отменили или вернули заказ) — с Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order.

Если finby не может начать платёж, покупатель остаётся на шаге Confirm Order, а над кнопкой выводится We could not start the card payment. Please try again in a moment or choose another payment method. Техническая причина записывается в журнал.

Расширение принимает только платежи картами как одношаговую покупку на странице finby. Оно не поддерживает банковские переводы и другие способы оплаты finby, кнопки Apple Pay или Google Pay на вашем сайте, сохранённые карты, подписки или регулярные платежи, раздельную авторизацию и списание, а также опрос статуса.

Заказы и возвраты

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

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

Статус заказа после оплаты (по умолчанию В обработке): finby подтвердил платёж, а сумма и валюта совпадают с запросом на оплату и суммой заказа. Примечание показывает сумму, запрос на оплату и проект (тестовый или боевой).

Ожидающий платёж TrustPay (по умолчанию Ожидание): finby сообщил, что последний платёж ожидает обработки. Заказ переходит в статус оплаты, когда finby подтверждает платёж.

Платёж TrustPay на удержании (по умолчанию Ожидание): устанавливается в двух случаях. Платёж только авторизован, но не списан: спишите или отмените его в finby Merchant Portal, затем обновите заказ. Либо оплаченная сумма или валюта не совпадают с запросом на оплату или суммой заказа: проверьте платёж перед отправкой. Примечание объясняет случай. Деньги получены, поэтому возврат возможен.

Ошибка платежа (по умолчанию Неудачный): finby отклонил последний платёж ожидающего заказа. Примечание показывает причину, если finby её передаёт. Позже подтверждённый платёж всё равно переводит заказ в статус оплаты.

Статус возвращённого заказа (по умолчанию Возвращен): платёж полностью возвращён через расширение.

Отменённые или возвращённые заказы никогда не открываются заново поздним платежом. Примечание просит вас восстановить заказ или вернуть платёж в Merchant Portal. Если второй платёж приходит по уже оплаченному заказу или по другому заказу корзины, у которой уже есть оплаченный заказ, заказ не меняется, а примечание просит вас вернуть дубликат в Merchant Portal. Опротестования (чарджбэки) и споры, о которых сообщает finby, добавляются как примечания.

Примечания — это записи в History заказа, которые покупатель не видит. Они пишутся на языке магазина по умолчанию.

VibeFox TrustPay Gateway tab

В Sales > Orders откройте заказ, оплаченный через TrustPay. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox TrustPay Gateway показывает Payment request ID, Payment ID, Project с отметкой Test project для тестовых платежей, Status, суммы Requested / paid и Paid / refunded, форму возврата, историю возвратов, Payment requests of this order и TrustPay notes. Вкладка показывается пользователям, которые имеют доступ к расширению.

Возвраты

На вкладке VibeFox TrustPay Gateway введите Amount (подставляется сумма, которая ещё не возвращена), при необходимости Reason (optional), и нажмите Refund via TrustPay. Подтвердите вопрос Refund this amount through TrustPay? This cannot be undone. Поддерживаются полные и частичные возвраты. Нужно право на изменение расширения (задаётся в System > Users > User Groups). Возвраты выполняются в той сумме и валюте, которые finby указал для платежа, поэтому после расхождения суммы вы можете вернуть до фактически оплаченной покупателем суммы, а не суммы заказа. Возвраты в HUF должны быть целыми суммами.

Возврат направляется в тот проект, через который оплачен заказ (тестовый или боевой), даже если вы с тех пор переключили режим. Project ID и Secret key этого проекта должны быть заданы, а его Project ID не должен был измениться. Возврат фиксируется, только если finby его принимает. Иначе вкладка показывает TrustPay refused the refund: с причиной, и возврат не записывается. Успешный возврат добавляется в историю возвратов и примечания. Полный возврат переводит заказ в Refunded order status без уведомления покупателя и без возврата товаров на склад, как при ручной смене статуса. Частичный возврат статус не меняет.

Возвраты товаров в Sales > Returns не отправляют деньги через finby. Возвраты, выполненные в finby Merchant Portal, не фиксируются как возвраты. Если finby присылает об этом уведомление, оно добавляется как примечание, а статус заказа не меняется.

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

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

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

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

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

Card payment (TrustPay) не появляется при оформлении: проверьте, что лицензия активна, Enable / Disable включено, а в текущем режиме заданы Project ID и Secret key: Test Project ID и Test Secret key в тестовом режиме, Live Project ID и Live Secret key в боевом. Валюта покупателя должна входить в поддерживаемые. На странице настроек появляется предупреждение, если данные не заданы или валюта по умолчанию не поддерживается. Также проверьте, что платёжный адрес входит в выбранную Geo zone и что заказ достигает Minimum total.

Платёж прошёл, но заказ остаётся без статуса: уведомление не дошло до магазина. Проверьте, что URL под Notification URL доступен из интернета (без межсетевого экрана, логина для обслуживания и HTTP-аутентификации). finby повторяет уведомление, и заказ получает статус, когда оно приходит. Ошибки всегда записываются в журнал; посмотрите поле Log на странице расширения.

Журнал показывает Notification rejected: invalid signature or unknown project: уведомление пришло от проекта, чей Project ID не указан в настройках, либо Secret key этого проекта неверен. Магазин отвечает Invalid signature, и ничего не меняется. Проверьте Project ID и Secret key того режима, в котором был сделан платёж.

Журнал показывает Notification ignored: уведомление относится к запросу на оплату, который этот магазин не создавал для данного заказа, либо к другому проекту или режиму, чем тот, с которым был начат платёж. Ничего не меняется.

Уведомление получает ответ Busy, retry later или Temporary error: корзина в тот же момент обновлялась другим уведомлением, либо не удалось установить статус заказа. finby повторит уведомление. Причина указана в журнале.

Покупатель видит We could not start the card payment: откройте журнал. Неверные Project ID или Secret key дают сообщение о том, что finby отклонил данные проекта. Проверьте, что тестовые данные введены в тестовые поля, а боевые — в боевые.

Card payment is temporarily unavailable: покупатель видит это, когда в текущем режиме нет Project ID или Secret key. Введите их и сохраните.

Заказ в статусе удержания: прочитайте примечания на вкладке VibeFox TrustPay Gateway (см. Статусы заказов). Проверьте платёж в Merchant Portal до отправки, затем выполните заказ или верните платёж.

Возврат не проходит с сообщением о проекте: заказ оплачен через тестовый или боевой проект, а Project ID или Secret key этого режима не заданы, либо сейчас там сохранён другой Project ID. Введите данные этого проекта или верните платёж в finby Merchant Portal.

Invalid refund amount: at most … can be refunded: сумма больше оплаченной за вычетом возвратов, уже выполненных через расширение.

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox TrustPay Gateway. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable / Disable, Sort order, Geo zone, Minimum total и статусы заказов, которые при повторной установке возвращаются к значениям по умолчанию. Также удаляются событие OpenCart расширения и кэш токенов доступа к API (в OpenCart 4 также его события и стартовое действие, которое пропускает уведомление и возврат покупателя в режиме обслуживания). Если включено Delete data on uninstall, удаляются остальные настройки (название, описание, тестовый режим, Project ID, Secret key, журналирование) и журнал. Если выключено, они сохраняются для повторной установки. Записи о платежах TrustPay и возвраты всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои примечания о платежах.

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

TrustPay и finby являются товарными знаками их владельцев. Это расширение не связано с TrustPay или finby и не одобрено ими.