VibeFox PayFast for OpenCart — Помощь
Требования
OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).
PHP: 8.0 или новее.
Currency: южноафриканский рэнд (ZAR). PayFast производит расчёты только в рэндах, поэтому заказ должен быть в ZAR. Добавьте валюту в разделе System > Localisation > Currencies, если её ещё нет в вашем магазине. Минимальная сумма заказа — R5.00.
PayFast account: Merchant ID и Merchant Key вашей учётной записи PayFast, которые находятся в разделе Settings > Developer Settings панели PayFast. Настоятельно рекомендуется использовать парольную фразу; если она задана в PayFast, то в расширении нужно ввести ту же самую фразу. Для тестов нужны учётные данные песочницы PayFast.
Reachable store: URL для уведомлений об оплате должен быть доступен из интернета, без базовой авторизации и без блокировки файрволом.
VibeFox license key: приобретается на vibefox.net. Один ключ работает на одном домене.
Установка
Загружаемый файл — это один zip-архив с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_payfast_pay-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_payfast_pay.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ одинаковый для обеих версий.
OpenCart 3
1. В административной части перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_payfast_pay-oc3-(version).ocmod.zip. Расширение не содержит модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload этого пакета в корневую папку вашего магазина.
2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox PayFast Pay Gateway и нажмите Install (зелёная кнопка +).
3. Нажмите Edit (кнопка с карандашом), чтобы открыть страницу настроек. Вставьте ваш лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы и нажмите Activate (см. раздел Лицензионный ключ).
4. Введите Merchant ID, Merchant Key и парольную фразу. Для тестирования оставьте включённым Test mode и введите учётные данные песочницы.
5. Включите Enable/Disable и нажмите Save. Выполните тестовый платёж, а затем выключите Test mode, чтобы принимать настоящие платежи.
OpenCart 4
1. В административной части перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_payfast_pay.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.
2. Пакет появится в списке установленных расширений на той же странице. Нажмите рядом с ним Install (зелёная кнопка +).
3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox PayFast Pay Gateway, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).
4. Введите лицензионный ключ и учётные данные PayFast и проверьте платёж, как в шагах с 3 по 5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только URL уведомления (см. поле Notification URL); он тоже передаётся в PayFast с каждым платежом.
После новой установки способ оплаты выключен, а тестовый режим включён.
Настройка
Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если учётные данные текущего режима не заполнены (тогда PayFast скрывается при оформлении заказа), если основная валюта магазина не ZAR, если в боевом режиме используется публичный Merchant ID песочницы 10000100 и если парольная фраза не задана. Пока включён тестовый режим, выводится сообщение Test mode is on: orders are paid in the PayFast sandbox, no real money is charged.
При сохранении поле Title не может быть пустым (до 128 символов), Sort Order должно быть целым числом (отрицательные числа допускаются), Total — числом не меньше 0, а выбранная географическая зона и статусы заказов должны существовать; иначе ничего не сохраняется, и страница указывает на поле. Если вы включите способ оплаты без учётных данных текущего режима, настройки сохранятся с предупреждением.
PayFast
Enable/Disable: Enable PayFast включает или выключает способ оплаты. По умолчанию: выключено.
Title: название способа оплаты, которое видят покупатели при оформлении заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: PayFast. Обязательное поле.
Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely by card, Instant EFT and other methods on the PayFast payment page.
Sort Order: положение PayFast среди способов оплаты при оформлении заказа. Оставьте поле пустым или введите целое число.
Geo Zone: предлагать PayFast только для платёжных адресов из выбранной географической зоны. По умолчанию: All zones. Географические зоны настраиваются в разделе System > Localisation > Geo Zones. В OpenCart 4, если магазин не запрашивает платёжный адрес, используется адрес доставки.
Total: сумма корзины в основной валюте магазина, которую должен достичь заказ, чтобы предлагался PayFast. Оставьте поле пустым, чтобы предлагать PayFast при любой сумме. Сам PayFast всегда требует не менее R5.00.
Учётная запись PayFast (боевой режим)
Merchant ID и Merchant Key можно найти в панели PayFast в разделе Settings > Developer Settings (там есть ссылки на нужный раздел). Если вы задали парольную фразу там, введите здесь точно такую же.
Merchant ID: ваш боевой Merchant ID PayFast.
Merchant Key: ваш боевой Merchant Key PayFast. Он передаётся в PayFast с каждой платёжной формой, поэтому это обычное текстовое поле.
Passphrase: парольная фраза (salt) PayFast из раздела Settings > Developer Settings. Настоятельно рекомендуется: она подписывает платежи и уведомления.
Sandbox (тестовый режим)
В тестовом режиме платежи направляются в песочницу PayFast, и реальные деньги не списываются. Учётные данные песочницы отображаются после входа в песочницу PayFast (публичный тестовый мерчант — 10000100 / 46f0cd694581a).
Test mode: Use the PayFast sandbox and the sandbox credentials below. Пока режим включён, покупатель на шаге Confirm Order видит сообщение TEST MODE: payments go to the PayFast sandbox, no real money is charged. По умолчанию: включено.
Sandbox Merchant ID: Merchant ID вашей учётной записи песочницы.
Sandbox Merchant Key: Merchant Key вашей учётной записи песочницы.
Sandbox Passphrase: только если парольная фраза задана в вашей учётной записи песочницы.
Сохранённые парольные фразы больше не отображаются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённую парольную фразу, отметьте под полем пункт Clear the saved passphrase on save и нажмите Save.
Уведомления об оплате (ITN)
Notification URL: PayFast подтверждает каждый платёж серверным уведомлением на URL, указанный здесь. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_payfast_pay/itn, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_payfast_pay/payment/wcp_payfast_pay.itn. Он формируется из адреса витрины вашей установки OpenCart. Адрес передаётся с каждым платежом, поэтому в PayFast ничего настраивать не нужно, но он должен быть доступен из интернета. Заказы получают статус только по этим проверенным уведомлениям; возврат покупателя в магазин статус заказа не меняет.
Source check: в боевом режиме уведомления принимаются только с серверов PayFast. Адреса берутся из DNS-записей PayFast (кэшируются на 6 часов; кэш сбрасывается при сохранении настроек) и из документированных PayFast диапазонов адресов. Отключайте проверку, только если магазин находится за прокси или CDN, которые скрывают адрес посетителя. Подпись и подтверждение на сервере проверяются всегда. Уведомления песочницы по адресу не проверяются. По умолчанию: включено.
Заказы
OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Статус он получает только из проверенного уведомления PayFast. Отменённый, неуспешный или брошенный платёж оставляет заказ без статуса, и покупатель может оплатить снова. Каждое поле ниже перечисляет ваши статусы заказов OpenCart.
Order Status (paid): статус после того, как PayFast подтвердил платёж, а сумма и валюта совпадают. По умолчанию: В обработке.
Awaiting PayFast payment: PayFast сообщил, что платёж ожидает обработки (например, Instant EFT). Когда PayFast его завершит, статус изменится на оплаченный. По умолчанию: Ожидание.
PayFast payment on hold: платёж, который требует вашей проверки (см. раздел Статусы заказов). Такой заказ не отмечается оплаченным; примечание объясняет причину. По умолчанию: Ожидание, так как в OpenCart нет статуса On hold. Вы можете создать свой статус в разделе System > Localisation > Order Statuses и выбрать его здесь.
Payment failed: ожидавший платёж не прошёл. Если PayFast завершит его позже, заказ перейдёт в оплаченный статус. По умолчанию: Неудачный.
Дополнительно
Debug log: записывает шаги платежа в файл payfast_p_debug.log.php в папке логов OpenCart (storage/logs). Файл нельзя открыть из браузера; при достижении 5 МБ он переименовывается в payfast_p_debug.old.log.php. Ошибки и предупреждения записываются всегда, даже когда переключатель выключен. Парольные фразы, ключи и данные покупателей не записываются. По умолчанию: выключено.
Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.
Uninstall: Delete the gateway settings when the extension is uninstalled (настройки, кэшированные адреса PayFast и журнал). Записи о платежах PayFast и заказы всегда сохраняются. По умолчанию: выключено.
Импорт / экспорт
Export: Download JSON сохраняет настройки в файл JSON. Парольные фразы не экспортируются.
Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые парольные фразы остаются без изменений.
Оформление заказа
На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию PayFast). На шаге Confirm Order покупатель видит ваше описание и примечание Thank you for your order. You will be redirected to PayFast to complete the payment. OpenCart создаёт заказ на этом шаге, всё ещё без статуса. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Когда покупатель нажимает Confirm Order, расширение отправляет подписанную платёжную форму в PayFast. Форма содержит сумму заказа в ZAR, Order # с номером заказа, имя и e-mail покупателя, платёжную ссылку (номер заказа и попытку) и случайный токен попытки. Каждая новая попытка получает новую ссылку и новый токен.
На странице PayFast покупатель платит картой, через Instant EFT или другим способом, подключённым к вашей учётной записи PayFast. Затем PayFast отправляет уведомление об оплате (ITN) в ваш магазин. Заказ отмечается оплаченным только после того, как PayFast подтвердит платёж уведомлением, которое проходит все проверки:
Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков на складе. Уведомления по одной корзине обрабатываются по очереди; если другое уведомление по той же корзине уже обрабатывается, PayFast получает ответ с ошибкой и отправляет уведомление повторно. URL уведомлений работает и тогда, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы платёжных расширений, а в OpenCart 4 расширение добавляет startup action, которое пропускает уведомления и возврат покупателя из PayFast.
Когда покупатель возвращается и у заказа есть статус, отображается страница успешного оформления заказа OpenCart. Если PayFast сообщил, что платёж ожидает обработки, также выводится сообщение PayFast 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. Если ожидавший платёж позже не прошёл, выводится Your PayFast payment was not completed. Please contact us about this order. (в OpenCart 4 покупатель вместо этого возвращается к оформлению заказа, см. ниже). Если уведомление ещё не пришло, открывается страница Payment confirmation, на которой сообщается, что PayFast подтверждает платёж, с кнопками Check again и Back to checkout.
Если покупатель отменяет платёж на странице PayFast, он возвращается к оформлению заказа с сообщением The PayFast payment was cancelled. You can try again or choose another payment method. Если PayFast сообщил, что платёж не прошёл, выводится The payment was not completed. You can try again or choose another payment method. Корзина сохраняется, и оплатить её можно снова. В OpenCart 4 эти сообщения выводятся над страницей оформления заказа. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order; OpenCart 4 сохраняет один заказ для оформления и обновляет его, поэтому после отменённого или неуспешного платежа покупатель оплачивает тот же заказ новой попыткой. Если другой заказ из той же корзины уже обработан PayFast (например, во второй вкладке браузера), покупатель переходит на страницу успеха вместо повторной оплаты.
OpenCart 4 сохраняет заказ в оформлении до тех пор, пока не будет показана страница успеха. Если этот заказ был закрыт без оплаты в это время (например, его ожидающий платёж не прошёл или вы его отменили), покупатель возвращается к оформлению заказа с сообщением Your previous order was cancelled or its payment failed. Please confirm the order again., а следующий Confirm Order оплачивает новый заказ. Если у этого заказа уже есть статус и в корзине теперь другие товары или количества, сообщение: Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again.
Способ оплаты скрывается, если отсутствуют учётные данные текущего режима, если валюта оформления заказа не ZAR или если сумма ниже R5.00. Если покупатель всё же дошёл до оплаты, над кнопкой появляется короткое сообщение с объяснением, например PayFast accepts payments from R5.00. Please choose another payment method.
Расширение принимает только разовые платежи в ZAR. Оно не поддерживает возвраты со страницы заказа, подписки, сохранённые (токенизированные) карты и разделённые платежи.
Заказы
Статусы заказов
No status (missing order): покупатель был направлен в PayFast, и уведомление об оплате ещё не пришло, либо PayFast сообщил, что платёж не прошёл. В разделе Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в значение Missing Orders.
В OpenCart 4 неоплаченный заказ оформления может получить статус Voided, который OpenCart 4 устанавливает, когда покупатель возвращается к шагу Confirm Order. Расширение считает такой заказ заказом без статуса, и последующий платёж всё равно его подтверждает.
Order Status (paid) (default Processing): PayFast подтвердил платёж. Примечание показывает ID платежа PayFast. Платёж песочницы получает примечание о том, что реальные деньги не списывались.
Awaiting PayFast payment (default Pending): PayFast сообщил, что платёж ожидает обработки. Заказ переходит в оплаченный статус, когда PayFast завершит платёж, или в Payment failed, если платёж не пройдёт; покупатель получает письмо об этих изменениях.
Payment failed (default Failed): ожидавший платёж не прошёл. Если PayFast завершит его позже, заказ перейдёт в оплаченный статус.
PayFast payment on hold (default Pending): оплаченная сумма отличается от суммы заказа или заказ не в ZAR; платёж пришёл для заказа, статус которого вы тем временем изменили (например, отменили), или чей способ оплаты уже не PayFast; либо платёж песочницы пришёл, пока шлюз работал в боевом режиме. Примечание объясняет это. Проверьте заказ и панель PayFast, затем переведите заказ в оплаченный статус или отмените его и оформите возврат в PayFast.
Повторное уведомление по тому же платежу ничего не меняет. Запоздавшие уведомления о неуспешных или ожидающих платежах никогда не меняют оплаченный заказ. Если для уже оплаченного заказа или для второго заказа уже оплаченной корзины приходит ещё один завершённый платёж, примечание в оплаченном заказе предлагает вам вернуть дубликат в PayFast.
Примечания — это записи в разделе History заказа, которые покупатель не видит.
Вкладка VibeFox PayFast Pay Gateway
В разделе Sales > Orders откройте заказ, оплаченный через PayFast. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox PayFast Pay Gateway показывает Payment reference (m_payment_id), PayFast payment ID, Environment (боевой режим или песочница), запрошенную сумму, статус, суммы брутто, комиссию и нетто в ZAR, а также PayFast notes. Для заказа на удержании там отображается напоминание проверить платёж. Вкладка видна пользователям, которым открыт доступ к расширению.
Возвраты
Возвраты со страницы заказа не поддерживаются. Верните платёж в панели PayFast, а затем вручную обновите заказ в OpenCart.
Лицензионный ключ
Расширение работает с лицензионным ключом VibeFox, полученным на vibefox.net. Блок лицензии License — VibeFox PayFast Pay Gateway является первым блоком в разделе Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-payment-payfast и ссылка 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.
Без активного ключа PayFast покупателям при оформлении заказа не показывается. Если платёж всё же запущен, покупатель видит This payment method is not available. Please choose another one. Администратор, вошедший в административную часть в том же браузере, по-прежнему видит способ оплаты в магазине, отмеченный как (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать расширение до покупки ключа. В OpenCart 4 такого предпросмотра нет: магазин не видит вход в административную часть, поэтому без активного ключа способ оплаты скрыт для всех. После однократного открытия страницы Edit на административной Dashboard появляется напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются.
Когда срок лицензии истекает, расширение продолжает работать, но для обновлений и поддержки нужно продление. Статус проверяется автоматически при открытии административной Dashboard или страницы Edit: раз в день в течение первых 14 дней после ввода ключа, затем раз в неделю. Задание cron не требуется. При удалении расширения лицензионный ключ и статус лицензии удаляются всегда.
Решение проблем
PayFast does not appear at checkout: проверьте, что лицензия активна, Enable/Disable включено, заполнены Merchant ID и Merchant Key текущего режима, валюта оформления заказа — ZAR, а сумма заказа не меньше R5.00. Страница настроек показывает предупреждение, если чего-то не хватает. Также убедитесь, что платёжный адрес входит в выбранную Geo Zone, а сумма заказа достигает значения Total, заданного в настройках.
The payment went through, but the order stays without a status: PayFast не смог доставить уведомление об оплате либо оно было отклонено. Посмотрите поле Log на странице расширения: ошибки и отклонённые уведомления записываются всегда, а Debug log добавляет каждый шаг. Типичные причины: магазин недоступен из интернета (базовая авторизация, файрвол), разные парольные фразы в PayFast и в расширении или, в боевом режиме за прокси или CDN, проверка источника. В этом случае отключите Source check.
The notification answers Invalid signature: парольная фраза в расширении не та, которая задана в PayFast для режима, в котором был совершён платёж.
The notification answers Invalid source: уведомление пришло не с адреса PayFast, либо прокси или CDN скрывает настоящий адрес. Отключите Source check, если магазин находится за прокси или CDN.
The notification answers Merchant mismatch or Order mismatch: платёж был направлен на другую учётную запись PayFast или не относится к этой попытке оплаты. Ничего не меняется.
The notification answers Order not found: платёжная ссылка неизвестна этому магазину. Ничего не меняется.
The notification answers Confirmation unavailable, Busy or Temporary error: не удалось обратиться к PayFast за подтверждением на сервере, в тот же момент обрабатывалось другое уведомление по той же корзине, либо не удалось установить статус заказа. PayFast повторит уведомление. Причина указана в журнале.
The notification answers Not configured: отсутствуют учётные данные режима, в котором был начат платёж. Введите их снова, например учётные данные песочницы для тестового платежа.
The customer sees PayFast accepts payments in South African rand (ZAR) only: заказ в другой валюте. Попросите покупателя оплатить в рэндах или выбрать другой способ оплаты.
The customer sees This payment method is not available. Please reload the checkout page. Сессия оформления заказа больше не соответствует заказу, либо способ оплаты тем временем был выключен. Покупатель должен перезагрузить страницу оформления заказа.
Order is in the on-hold status: прочитайте примечания на вкладке VibeFox PayFast Pay Gateway (см. раздел Статусы заказов) и панель PayFast, затем установите оплаченный статус или оформите возврат платежа.
A sandbox payment did not pay the order: шлюз работает в боевом режиме. Платежи песочницы никогда не оплачивают заказ в боевом режиме; примечание к заказу сообщает об этом.
Для разработчиков: перед подписанием платёжной формы расширение вызывает событие OpenCart payfast_p_payment_data с полями формы и заказом. Учётные данные мерчанта, URL, платёжная ссылка, сумма и токен через это событие изменить нельзя.
Удаление
Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox PayFast Pay Gateway. Лицензионный ключ и статус лицензии этого расширения удаляются всегда. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Orders, которые при повторной установке возвращаются к значениям по умолчанию. Также удаляется событие OpenCart расширения (в OpenCart 4 также удаляются его события и startup action, которое пропускает в режиме обслуживания уведомления и возврат покупателя). Если включено Delete the gateway settings when the extension is uninstalled, удаляются остальные настройки шлюза (название, описание, учётные данные, парольные фразы, тестовый режим, проверка источника, журналирование), кэшированные адреса PayFast и журнал. Если выключено, они сохраняются для повторной установки. Записи о платежах PayFast и заказы всегда сохраняются. Существующие заказы сохраняют свои платёжные примечания.
В OpenCart 4, чтобы удалить и файлы расширения, после удаления перейдите в Extensions > Installer, нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox PayFast Pay Gateway в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.
PayFast — товарный знак его правообладателя. Это расширение не связано с PayFast и не одобрено PayFast.