VibeFox PayFast for WooCommerce — Помощь

Требования

WordPress: 6.2 или новее.

WooCommerce: 8.0 или новее, установлен и активен. Без него плагин не активируется.

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

Валюта: южноафриканский ранд (ZAR), задаётся в WooCommerce > Settings > General. PayFast производит расчёты только в рандах. Минимальная сумма заказа — R5.00.

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

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

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

Установка

1. В WordPress откройте Plugins > Add New > Upload Plugin, выберите ZIP-архив плагина и нажмите Install Now. Можно также загрузить папку wcp_payfast_pay в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Задайте валюту магазина — южноафриканский ранд — в WooCommerce > Settings > General.

4. Откройте настройки: WooCommerce > Settings > Payments > PayFast > Manage или нажмите Settings под названием плагина на странице Plugins.

5. Введите лицензионный ключ VibeFox в блоке лицензии в верхней части страницы и нажмите Activate.

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

7. Включите Enable/Disable и сохраните настройки. Проведите тестовый платёж, затем выключите тестовый режим, чтобы принимать реальные платежи.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > PayFast. Над полями страница предупреждает, если учётные данные текущего режима пусты (тогда PayFast скрыт на оформлении заказа), если валюта магазина не ZAR, если в рабочем режиме используется публичный тестовый Merchant ID 10000100, и если passphrase не задана; а пока тестовый режим включён, показывает Test mode is on: orders are paid in the PayFast sandbox, no real money is charged. В списке способов оплаты PayFast помечается как требующий настройки, пока не введены Merchant ID и Merchant Key текущего режима.

Общие

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: солевая passphrase из PayFast, Settings > Developer Settings. Настоятельно рекомендуется: она подписывает платежи и уведомления.

Sandbox (тестовый режим)

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

Test mode: Use the PayFast sandbox and the sandbox credentials below. На оформлении заказа покупатель видит TEST MODE: payments go to the PayFast sandbox, no real money is charged. По умолчанию: вкл.

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

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

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

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

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

PayFast подтверждает каждый платёж серверным уведомлением (сервер-сервер) на URL, который показан в этом разделе. Он выглядит так: https://your-site/wc-api/payfast_pay/. Адрес передаётся с каждым платежом, поэтому в PayFast ничего настраивать не нужно, но он должен быть доступен из интернета.

Проверка источника: Accept live notifications only from PayFast servers. Адреса берутся из DNS-записей PayFast. Отключайте эту опцию, только если ваш сайт находится за прокси или CDN, которые скрывают адрес посетителя. Подпись и серверное подтверждение проверяются всегда. Уведомления sandbox не проверяются по адресу. По умолчанию: вкл.

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

Debug log: Log payment steps записывает шаги в WooCommerce > Status > Logs, источник wcp_payfast_pay. Ошибки записываются всегда. Passphrase и данные покупателей не записываются. По умолчанию: выкл.

Uninstall: Delete the gateway settings and logs when the plugin is deleted. По умолчанию: выкл.

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

Покупатель выбирает способ оплаты (по умолчанию PayFast) и оформляет заказ. Он переходит на страницу Pay for order заказа, где отображается Thank you for your order. You are being redirected to PayFast to complete the payment., и подписанная форма платежа автоматически отправляется в PayFast. Если браузер не продолжает сам, покупатель нажимает Pay with PayFast; Cancel order отменяет заказ. Форма содержит сумму заказа в ZAR, Order # с номером заказа, имя и e-mail покупателя, а также ключ заказа. Она формируется заново каждый раз при открытии страницы, поэтому покупатель может открыть её снова, вернувшись из PayFast.

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

Возврат покупателя на страницу «Заказ получен» не меняет заказ. Пока уведомление не пришло, страница показывает 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.

Если покупатель отменяет платёж на странице PayFast, заказ отменяется стандартным для WooCommerce способом. Если покупатель уходит, не заплатив, заказ остаётся неоплаченным, и его можно оплатить со страницы Pay for order.

Способ оплаты работает в классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Он скрывается, если учётные данные текущего режима не заполнены, если валюта магазина или заказа не ZAR, или если сумма меньше R5.00. Он совместим с HPOS (High-Performance Order Storage) в WooCommerce.

Плагин принимает только разовые платежи в ZAR. Он не поддерживает возвраты из WooCommerce, подписки, сохранённые (токенизированные) карты, предзаказы и разделённые платежи.

Заказы

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

Pending payment: покупатель был отправлен в PayFast, а уведомление об оплате ещё не пришло.

Processing: PayFast подтвердил платёж. Это стандартный статус WooCommerce после оплаты; заказы, содержащие только виртуальные скачиваемые товары, переходят в «Выполнен». В заметке к заказу указан ID платежа PayFast, который также является ID транзакции заказа. Платёж в sandbox получает заметку о том, что реальные деньги не списывались. Комиссия PayFast и чистая сумма сохраняются в заказе.

On hold: PayFast сообщил, что платёж находится в ожидании; либо оплаченная сумма отличается от суммы заказа, либо заказ не в ZAR; либо платёж поступил за уже отменённый заказ. Заметка к заказу объясняет причину. Проверьте заказ и панель PayFast, затем отправьте заказ или верните платёж в PayFast.

Failed: PayFast сообщил, что платёж не выполнен, пока заказ был неоплачен. Покупатель может заплатить повторно.

Cancelled: покупатель отменил платёж на странице PayFast, либо заказ был отменён вами или по истечении времени резервирования остатков WooCommerce.

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

Возвраты

Возвраты из WooCommerce не поддерживаются. Верните платёж в панели PayFast, затем создайте ручной возврат в WooCommerce.

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

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Payments > PayFast. Вставьте ключ в поле License key и нажмите Activate. В блоке отображается статус, например дата, до которой лицензия действует, и ваш домен. Кнопка Check now повторно проверяет статус, Change key позволяет ввести другой ключ, а Remove key удаляет его с этого сайта. Ссылка Manage licenses and domains in your account открывает вашу учётную запись на vibefox.net.

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

Без активного ключа PayFast не показывается покупателям при оформлении заказа. Если оплата всё же начата, покупатель видит This payment method is not available. Please choose another one. Авторизованные администраторы магазина по-прежнему видят способ оплаты с пометкой (unlicensed — visible to admins only), поэтому вы можете настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются.

Когда лицензия истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется в фоновом режиме.

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

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

Оплата прошла, но заказ остаётся в статусе «Ожидает оплаты»: PayFast не смог доставить уведомление об оплате, либо оно было отклонено. Включите Debug log и проверьте WooCommerce > Status > Logs, источник wcp_payfast_pay. Типичные причины: сайт недоступен из интернета (режим обслуживания, базовая аутентификация, межсетевой экран), в PayFast и в плагине указаны разные passphrase или, в рабочем режиме за прокси или CDN, проверка источника. В этом случае отключите Source check.

Уведомление отвечает Invalid signature: passphrase в плагине не совпадает с той, что задана в PayFast для этого режима.

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

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

Уведомление отвечает Confirmation unavailable или Busy: не удалось связаться с PayFast для серверного подтверждения, либо другое уведомление по тому же заказу в этот момент обрабатывалось. PayFast повторит уведомление.

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

Покупатель видит PayFast accepts payments from R5.00: сумма заказа меньше минимальной суммы PayFast.

Заказ в статусе On hold: PayFast подтвердил платёж, который не соответствует заказу (другая сумма или валюта, отличная от ZAR), либо платёж поступил за уже отменённый заказ. Проверьте заметки к заказу и панель PayFast.

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

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите место в учётной записи на vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза, остальные параметры плагина, кэшированные адреса PayFast и журналы удаляются, только если была включена опция Delete the gateway settings and logs when the plugin is deleted. В противном случае они сохраняются для повторной установки. Существующие заказы сохраняют свои заметки об оплате и ID транзакций.

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