VibeFox PayFast for PrestaShop — Помощь

Требования

PrestaShop: от 8.0 до 9.x.

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

Валюта: южноафриканский ранд (ZAR). PayFast проводит расчёты только в рандах, поэтому корзина должна быть в ZAR. Если валюты нет в магазине, добавьте её в разделе International > Localization > Currencies. Минимальная сумма заказа — R5,00.

Учётная запись PayFast: Merchant ID и Merchant Key вашей учётной записи PayFast; их можно найти в разделе Settings > Developer Settings панели PayFast. Passphrase настоятельно рекомендуется; если она задана в PayFast, ту же passphrase нужно указать в модуле. Для тестов нужны учётные данные песочницы PayFast (sandbox).

Доступный магазин: URL для уведомлений о платежах должен быть доступен из интернета, без basic auth и без блокировки файрволом.

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

Установка

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

2. По завершении загрузки нажмите Configure или позже найдите VibeFox PayFast Pay Gateway в списке модулей и нажмите Configure.

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

4. Введите Merchant ID, Merchant Key и passphrase. Для тестов оставьте Test mode включённым и введите учётные данные sandbox.

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

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если учётные данные текущего режима пусты (тогда PayFast скрыт при оформлении заказа), если валюта магазина по умолчанию не ZAR, если в рабочем режиме используется публичный Merchant ID песочницы 10000100 и если passphrase не задана. Пока включён тестовый режим и модуль активен, показывается сообщение: Тестовый режим включён: заказы оплачиваются в песочнице PayFast, реальные деньги не списываются. Пустое поле Title не принимается, выводится сообщение Введите название способа оплаты.

PayFast

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

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

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely by card, Instant EFT and other methods on the PayFast payment page.

Учётная запись PayFast (рабочий режим)

Merchant ID и Merchant Key можно найти в панели PayFast в разделе Settings > Developer Settings. Если вы задали passphrase там, введите здесь точно такую же.

Merchant ID: ваш рабочий Merchant ID PayFast.

Merchant Key: ваш рабочий Merchant Key PayFast. Он передаётся в PayFast с каждой формой платежа, поэтому это обычное текстовое поле.

Passphrase: salt passphrase из PayFast, Settings > Developer Settings. Настоятельно рекомендуется: она подписывает платежи и уведомления.

Песочница (тестовый режим)

В тестовом режиме платежи уходят в песочницу PayFast, реальные деньги не списываются. Учётные данные песочницы показываются после входа в песочницу PayFast (публичный тестовый мерчант — 10000100 / 46f0cd694581a).

Test mode: Use the PayFast sandbox and the sandbox credentials below. Пока режим включён, покупатель видит под способом оплаты: ТЕСТОВЫЙ РЕЖИМ: платежи уходят в песочницу PayFast, реальные деньги не списываются. По умолчанию: включено.

Sandbox Merchant ID: Merchant ID вашей учётной записи песочницы.

Sandbox Merchant Key: Merchant Key вашей учётной записи песочницы.

Sandbox Passphrase: только если passphrase задана в вашей учётной записи песочницы.

Сохранённые passphrase никогда не показываются повторно. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Clear saved passphrases: отметьте Passphrase или Sandbox Passphrase и нажмите Save, чтобы удалить её. Пустое поле сохраняет сохранённое значение.

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

Notification URL: PayFast подтверждает каждый платёж серверным уведомлением на URL, указанный здесь. При ЧПУ он выглядит так: https://your-shop/module/wcp_payfast_pay/itn, возможно, с кодом языка по умолчанию. Адрес передаётся с каждым платежом, поэтому в PayFast ничего настраивать не нужно, но он должен быть доступен из интернета. Заказы создаются только такими проверенными уведомлениями; возвращение покупателя в магазин не создаёт и не оплачивает заказ.

Source check: принимать уведомления рабочего режима только с серверов PayFast. Адреса берутся из DNS-записей PayFast (кэшируются 6 часов) и из задокументированных PayFast диапазонов адресов. Отключайте проверку, только если магазин стоит за прокси или CDN, которые скрывают адрес посетителя. Подпись и серверное подтверждение проверяются всегда. Уведомления песочницы по адресу не проверяются. По умолчанию: включено.

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

Debug log: записывает шаги платежа в logs/payfast_p_debug.log.php в папке модуля. Файл нельзя открыть из веба. Ошибки и предупреждения записываются всегда, даже когда переключатель выключен. Passphrase и данные покупателей не записываются. По умолчанию: выключено.

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

Uninstall: Delete the gateway settings when the module is uninstalled (настройки, кэш адресов PayFast и журнал). Записи платежей PayFast, заказы и статусы заказов всегда сохраняются. По умолчанию: выключено.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию PayFast) и подтверждает. Страница с сообщением Спасибо за заказ. Вы перенаправляетесь на PayFast для завершения оплаты. автоматически отправляет подписанную форму платежа в PayFast. Если браузер не продолжает сам, покупатель нажимает Pay with PayFast; Cancel возвращает к оформлению заказа. Форма содержит сумму корзины в ZAR, Cart # с номером корзины, имя и e-mail покупателя, референс платежа (номер корзины и попытка) и случайный токен попытки. На этом этапе заказа ещё нет. Каждая новая попытка получает новые референс и токен.

На странице PayFast покупатель платит картой, Instant EFT или другим способом, включённым в вашей учётной записи PayFast. Затем PayFast отправляет уведомление о платеже (ITN) вашему магазину. Заказ отмечается оплаченным только после того, как PayFast подтвердит платёж уведомлением, которое прошло все проверки:

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

Когда покупатель возвращается и заказ существует, показывается стандартная страница подтверждения заказа. Если PayFast отметил платёж как ожидающий, выводится: PayFast подтверждает ваш платёж. Вы получите письмо, как только он будет подтверждён — повторно платить не нужно. Если заказ на удержании, выводится: Ваш платёж проверяется. Мы свяжемся с вами, если потребуется что-то ещё. Если ожидающий платёж позже не прошёл, выводится: Ваш платёж PayFast не был завершён. Свяжитесь с нами по этому заказу. Если уведомление ещё не пришло, показывается страница Payment confirmation, где сообщается, что PayFast подтверждает платёж и заказ будет создан, как только PayFast его подтвердит, с кнопками Check again и Back to checkout.

Если покупатель отменяет платёж на странице PayFast, он возвращается к оформлению заказа с сообщением Платёж PayFast отменён. Вы можете повторить попытку или выбрать другой способ оплаты. Если PayFast отметил платёж как неуспешный, выводится Платёж не был завершён. Вы можете повторить попытку или выбрать другой способ оплаты. Корзина сохраняется, и её можно оплатить снова.

Способ оплаты скрыт, если учётные данные текущего режима отсутствуют, если валюта корзины не ZAR или не разрешена для модуля, или если сумма меньше R5,00. Если покупатель всё же дойдёт до оплаты, короткое сообщение объяснит причину, например PayFast принимает платежи от R5,00. Выберите другой способ оплаты.

Модуль принимает только разовые платежи в ZAR. Возвратов со страницы заказа, подписок, сохранённых (токенизированных) карт и разделённых платежей он не поддерживает.

Заказы

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

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

Payment accepted: PayFast подтвердил платёж. Платёж записывается с ID платежа PayFast в качестве ID транзакции, а примечание показывает ID платежа. Платёж в sandbox получает примечание о том, что реальные деньги не списаны.

Awaiting PayFast payment: PayFast отметил платёж как ожидающий. Заказ переходит в статус Payment accepted, когда PayFast завершит платёж.

Payment error: ожидающий платёж не прошёл. Если PayFast завершит его позже, заказ станет Payment accepted.

PayFast payment on hold: оплаченная сумма отличается от суммы корзины, или корзина не в ZAR; платёж поступил для заказа, который был отменён, или способ оплаты которого уже не PayFast; или платёж в sandbox поступил, пока шлюз работает в рабочем режиме. Сумма, полученная от PayFast, записывается в заказ (не для платежа в sandbox), примечание объясняет ситуацию. Проверьте заказ и панель PayFast, затем переведите заказ в Payment accepted или отмените его и сделайте возврат платежа в PayFast.

Повторное уведомление по тому же платежу ничего не меняет. Запоздалые уведомления о неудаче или ожидании никогда не меняют оплаченный заказ. Если для уже оплаченного заказа поступает ещё один завершённый платёж, примечание предлагает вернуть дубликат в PayFast. Платёж по возвращённому заказу только добавляет примечание.

Блок платежа PayFast

На странице заказа показан блок PayFast payment с референсом платежа (m_payment_id), ID платежа PayFast, средой (live или sandbox), статусом, суммами брутто, комиссии и нетто в ZAR, а также примечаниями модуля. Для заказа на удержании показывается напоминание проверить платёж.

Возвраты

Возвраты со страницы заказа не поддерживаются. Сделайте возврат платежа в панели PayFast, затем вручную обновите заказ в PrestaShop.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox PayFast Pay Gateway — первый блок на странице Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now, чтобы проверить статус ещё раз, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: presta-payment-payfast и ссылка 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.

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

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

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

PayFast не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, заполнены Merchant ID и Merchant Key текущего режима, корзина в ZAR и сумма заказа не меньше R5,00. Страница настроек показывает предупреждение, если чего-то не хватает. В Payment > Preferences проверьте, что модуль разрешён для ранда, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: PayFast не смог доставить уведомление о платеже или уведомление было отклонено. Посмотрите поле Log на странице модуля; ошибки и отклонённые уведомления записываются всегда, а Debug log добавляет каждый шаг. Типичные причины: магазин недоступен из интернета (basic auth, файрвол), разные passphrase в PayFast и в модуле или, в рабочем режиме за прокси или CDN, проверка источника. В этом случае отключите Source check.

Уведомление отвечает Invalid signature: passphrase в модуле не совпадает с той, что задана в PayFast для режима, в котором был сделан платёж.

Уведомление отвечает Invalid source: уведомление пришло не с адреса PayFast, или прокси либо CDN скрывает реальный адрес. Отключите Source check, если магазин стоит за прокси или CDN.

Уведомление отвечает Merchant mismatch или Order mismatch: платёж был сделан на другую учётную запись PayFast или не относится к этой попытке оплаты. Ничего не меняется.

Уведомление отвечает Order not found: референс платежа неизвестен этому магазину. Ничего не меняется.

Уведомление отвечает Confirmation unavailable, Busy или Temporary error: не удалось связаться с PayFast для серверного подтверждения, в тот же момент обрабатывалось другое уведомление по той же корзине, или заказ не удалось создать (например, модуль отключён). PayFast повторит уведомление. В журнале указана причина.

Уведомление отвечает Not configured: отсутствуют учётные данные режима, в котором был начат платёж. Введите их заново, например учётные данные песочницы для тестового платежа.

Покупатель видит сообщение PayFast принимает платежи только в южноафриканских рандах (ZAR): корзина в другой валюте. Попросите покупателя платить в рандах или выбрать другой способ оплаты.

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

Платёж в sandbox не оплатил заказ: шлюз работает в рабочем режиме. Платежи в sandbox никогда не оплачивают заказ в рабочем режиме; примечание к заказу сообщает об этом.

Для разработчиков: хук actionPayfastPPaymentData может изменить поля формы платежа до подписи. Учётные данные мерчанта, URL, референс платежа, сумму и токен через него изменить нельзя.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox PayFast Pay Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete the gateway settings when the module is uninstalled включено, настройки шлюза, кэш адресов PayFast и журнал удаляются. Если выключено, все настройки сохраняются для повторной установки. Записи платежей PayFast, заказы и статусы заказов Awaiting PayFast payment и PayFast payment on hold всегда сохраняются. Существующие заказы сохраняют примечания об оплате и ID транзакций.

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