VibeFox TrustPay for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

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

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

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

Установка

1. В бэк-офисе перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox TrustPay Gateway в списке модулей и нажмите Configure.

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

4. Введите ID проекта и секретный ключ тестового проекта и, для реальных платежей, рабочего проекта (см. раздел Конфигурация).

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

При установке модуль создаёт два статуса заказа: Awaiting TrustPay payment и TrustPay payment on hold. PrestaShop привязывает новый платёжный модуль к странам, которые активны на момент установки. Для стран, добавленных позже, отметьте модуль в разделе Payment > Preferences. Там же можно ограничить модуль по валюте и группе клиентов.

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

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox TrustPay Gateway > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если модуль включён, но ID проекта или секретный ключ текущего режима пусты, а также если валюта магазина по умолчанию не поддерживается. В обоих случаях способ оплаты скрывается при оформлении заказа.

TrustPay / finby

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

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

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely by card on the TrustPay / finby payment page.

Учётные данные API

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

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

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

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

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

Test Secret key: секретный ключ тестового проекта.

ID проекта должен содержать только цифры. Если вы сохраните другое значение, страница покажет must contain digits only — the previous value was kept., а остальные поля будут сохранены. Секретные ключи сохраняются точно в том виде, в котором введены; удаляются только пробелы в начале и в конце. Сохранённые секретные ключи больше никогда не отображаются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Сохранение настроек также сбрасывает кэшированные токены доступа к API, поэтому новые учётные данные применяются сразу.

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

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

Заказ отмечается оплаченным только после того, как finby подтверждает платёж подписанным уведомлением. Модуль автоматически передаёт URL уведомлений с каждым платежом, поэтому настраивать его не нужно. Раздел показывает URL под Notification URL. При ЧПУ-адресах он выглядит так: https://your-shop/module/wcp_trustpay_gateway/callback, возможно с кодом языка. Его также можно указать как URL уведомлений ваших проектов в Merchant Portal. Уведомления без действительной подписи отклоняются.

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

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

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

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

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

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

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

На шаге оплаты покупатель выбирает способ оплаты (по умолчанию Card payment (TrustPay)) и подтверждает заказ. Способ оплаты предлагается только в поддерживаемых валютах: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF и USD. Суммы в HUF передаются без копеек.

Для оплаты картой нужен адрес. Если не указаны улица, город, почтовый индекс или страна, покупатель видит Please enter your billing address (street, city, postcode and country) — it is required for card payments.

Модуль создаёт в finby запрос на оплату картой на сумму корзины в валюте корзины. Имя, адрес и e-mail покупателя передаются для 3-D Secure, а номер корзины отправляется как ссылка. На этом этапе заказа ещё нет. Покупатель перенаправляется на страницу оплаты finby и оплачивает картой там. Страница открывается на языке корзины, если finby его поддерживает, в противном случае на английском.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после того, как finby подтверждает платёж подписанным уведомлением. Возврат покупателя сам по себе никогда не меняет статус оплаты. Если уведомление уже пришло, покупатель видит стандартную страницу подтверждения заказа. Если нет, появляется страница Payment confirmation, на которой сообщается, что finby подтверждает оплату картой и заказ будет создан сразу после подтверждения. На ней есть кнопка Check again и кнопка Back to checkout. Пока заказ находится в статусе Awaiting TrustPay payment или TrustPay payment on hold, страница подтверждения показывает 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 отклонил платёж или неоплаченный заказ был отменён, страница показывает Your card payment was not completed. Please contact us about this order.

Если покупатель отменяет платёж на странице оплаты, он возвращается к оформлению заказа с сообщением 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. Корзина сохраняется, и покупатель может оплатить снова.

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

Уведомления работают, пока магазин находится в режиме обслуживания, и не блокируются ограничением по странам вашего магазина.

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

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

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

No order yet: покупатель был направлен на finby и не оплатил, либо уведомление ещё не пришло. Существует только корзина.

Payment accepted or Delivered: finby подтвердил платёж, а сумма и валюта совпадают с запросом на оплату и суммой корзины. Статус следует за Order status after payment. Платёж записывается с ID запроса на оплату finby в качестве ID транзакции, а примечание показывает сумму, запрос на оплату и проект (тестовый или рабочий).

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

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

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

Refunded: платёж полностью возвращён через модуль.

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

Блок оплаты TrustPay / finby

На странице заказа отображается блок TrustPay / finby payment с ID запроса на оплату, ID платежа finby, проектом, статусом платежа, запрошенной и оплаченной суммами, возвращённой суммой, значком Test project для тестовых платежей, историей возвратов и TrustPay notes заказа.

Возвраты

В блоке TrustPay / finby payment введите сумму (ещё не возвращённая сумма подставляется автоматически), при желании причину, и нажмите Refund via TrustPay. Подтвердите вопрос Refund this amount through TrustPay? This cannot be undone. Поддерживаются полные и частичные возвраты. Вам нужно право редактировать заказы; доступ к страницам модулей не требуется. Возвраты выполняются в той сумме и валюте, которые finby указал для платежа, поэтому при расхождении сумм можно вернуть не больше того, что покупатель фактически оплатил, а не сумму заказа. Возвраты в HUF должны быть целыми суммами.

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

Модуль не создаёт корректирующих счетов (credit slips). Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через finby. Возвраты, сделанные в finby Merchant Portal, не фиксируются как возвраты. Если finby присылает об этом уведомление, оно добавляется как примечание, а статус заказа не меняется.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox TrustPay Gateway — это первый блок на странице Modules > Module Manager > VibeFox TrustPay Gateway > Configure, над настройками. Введите ключ в License key и нажмите Activate. После этого блок показывает ключ в маскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен), а также кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-trustpay и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только сотрудники с правом Configure для этого модуля. Тексты блока следуют языку бэк-офиса (включены английский и русский).

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

Один ключ работает на одном домене: домене основного магазина, в том числе при мультимагазинной настройке. Удаление ключа из магазина не освобождает его слот домена. Освободите слот в своём аккаунте vibefox.net.

Без активного ключа оплата картой не показывается покупателям при оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его при оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются уведомлением TrustPay и возвратом в магазин, а возвраты работают.

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

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

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

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

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

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

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

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

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

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

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

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

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox TrustPay Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Кэшированные токены доступа к API всегда удаляются. Если Delete data on uninstall включено, удаляются настройки модуля и журнал. Если выключено, все настройки сохраняются для будущей переустановки. Записи о платежах TrustPay и возвратах, а также статусы заказов Awaiting TrustPay payment и TrustPay payment on hold всегда сохраняются, поэтому заказы, оплаченные ранее, можно вернуть и после переустановки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

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