VibeFox Peach Payments for WooCommerce — Помощь

Требования

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

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

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

Currency: валюта магазина должна быть ZAR, KES или MUR. В других валютах способ оплаты скрыт, о чём сообщается на странице настроек.

Peach Payments account: нужны учётные данные Card API вашей учётной записи Peach Payments: Entity ID и Access Token. Тестовые данные берутся из панели тестовой среды Peach Payments, рабочие — из панели Peach Payments; они различаются. Для вебхуков также нужен ключ расшифровки, который Peach Payments отправляет при включении вебхуков Card для магазина (см. «Настройка»). Для получения вебхуков сайт должен быть доступен из интернета.

VibeFox license key: приобретается на vibefox.net. Один ключ работает на одном домене.

Установка

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

2. Нажмите Activate.

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

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

5. Введите тестовые Entity ID и Access Token из панели тестовой среды Peach Payments и попросите Peach Payments включить вебхуки Card для URL вебхука со страницы настроек (см. «Настройка»).

6. Включите Enable/Disable и сохраните. Оставьте Test mode включённым и выполните платёж тестовой картой тестовой среды Peach Payments. Затем снимите флажок Test mode, введите рабочие учётные данные и рабочий ключ вебхука и сохраните.

После обновления настройки версии 1.0 автоматически переносятся в новые поля.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Peach Payments. Над полями показаны уведомления: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.; уведомление об отсутствии Entity ID или Access Token текущего режима (до их ввода способ оплаты не показывается при оформлении заказа); об отсутствии ключа расшифровки вебхуков текущего режима (тогда платежи подтверждаются только при возвращении покупателя); и о неподдерживаемой валюте магазина. В списке способов оплаты Peach Payments отмечен как требующий настройки, пока для текущего режима не указаны Entity ID и Access Token. При сохранении из учётных данных удаляются пробелы; если ключ вебхука не является шестнадцатеричным значением из 64 символов, выводится ошибка.

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

Title: название способа оплаты, которое покупатель видит при оформлении заказа. По умолчанию: Credit / Debit Card (Peach Payments).

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.

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

Access Token и Entity ID Card API указаны в панели Peach Payments (тестовые данные — в панели тестовой среды). Раздел содержит ссылки на обе панели и документацию Peach Payments для разработчиков.

Test mode: Enable test mode отправляет новые платежи в тестовую среду Peach Payments с тестовыми учётными данными, без списания реальных денег. Снимите флажок для приёма реальных платежей с рабочими данными. Платёж, начатый в одном режиме, всегда проверяется в нём, даже после переключения. По умолчанию: включено.

Test Entity ID: Entity ID (канал 3-D Secure) вашей тестовой учётной записи.

Test Access Token: токен доступа bearer вашей тестовой учётной записи.

Test Webhook Decryption Key: шестнадцатеричный ключ из 64 символов для расшифровки вебхуков Card тестовой среды.

Live Entity ID: Entity ID (канал 3-D Secure) вашей рабочей учётной записи.

Live Access Token: токен доступа bearer вашей рабочей учётной записи.

Live Webhook Decryption Key: шестнадцатеричный ключ из 64 символов для расшифровки вебхуков Card рабочей учётной записи.

Вебхук

Вебхуки подтверждают платежи, даже если покупатель закроет браузер до возвращения в магазин. Раздел показывает URL вебхука магазина вида https://your-site/wp-json/peach-pay/v1/webhook. Скопируйте его точно как в настройках. Попросите Peach Payments (support@peachpayments.com) включить вебхуки Card для вашей учётной записи с этим URL, затем введите полученный ключ расшифровки в поле Webhook Decryption Key того же режима.

Peach Payments шифрует каждый вебхук (AES-256-GCM). Вебхук, который не удаётся расшифровать тестовым или рабочим ключом, отклоняется, поэтому только Peach Payments может менять ваши заказы. Вебхук, расшифрованный ключом одного режима, применяется только к платежам, начатым в этом режиме. Плагин использует уведомления о платежах:

Остальные уведомления, например тестовое при активации вебхука, получают ответ OK и игнорируются. Без ключа вебхука заказ подтверждается только при возвращении покупателя после оплаты.

Платёжная форма

Card brands: платёжные системы в форме Peach Payments: Visa, Mastercard, American Express, Diners Club. Выбирайте только включённые для вашего Entity ID. По умолчанию: Visa и Mastercard.

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

Logging: Log API requests and payment results записывает отладочную информацию в WooCommerce > Status > Logs, источник wcp_peach_pay. Ошибки и предупреждения регистрируются всегда. Журналы не содержат данных карт, ключей и данных покупателей. По умолчанию: выключено.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Отключение плагина никогда ничего не удаляет. Данные Peach Payments в заказах сохраняются. По умолчанию: выключено.

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

Покупатель выбирает способ оплаты (по умолчанию Credit / Debit Card (Peach Payments)) и нажимает Continue to payment. Он переходит на страницу Pay for order вашего магазина. Там плагин создаёт платёжную сессию Peach Payments на сумму заказа в его валюте и показывает форму карты Peach Payments с выбранными платёжными системами на языке сайта, если он поддерживается Peach Payments. В тестовом режиме страница показывает Test mode: use a Peach Payments test card, no real payment will be made.. Данные карты вводятся в форме Peach Payments; скрипт формы загружается с хешем Subresource Integrity.

После оплаты покупатель возвращается в магазин. Заказ отмечается оплаченным только после подтверждения Peach Payments: магазин получает результат платёжной сессии этого заказа через Peach Payments API в режиме её создания и проверяет принадлежность платежа заказу. Вебхук делает то же независимо: первый применяет результат, второй ничего не меняет. Оплативший покупатель видит страницу Order received.

Если платёж не завершён, покупатель возвращается на страницу Pay for order с сообщением и может повторить попытку: Payment failed: затем причина от Peach Payments и Please try again or use another card. либо The payment was not completed. Please try again.. Если результат пока нельзя подтвердить (например, Peach Payments не ответил или вебхук сейчас обрабатывает тот же заказ), сообщение будет We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again.. Если для режима не задан ключ вебхука, покупателя вместо этого просят связаться с вами и сообщить номер заказа.

Если форму оплаты не удаётся подготовить, покупатель видит короткое сообщение и кнопку Try again: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (неверные учётные данные), сообщение о непринятых платёжным провайдером реквизитах плательщика либо The payment form could not be loaded. Please try again in a moment.. В заказ добавляется примечание с кодом и описанием Peach Payments.

Способ оплаты работает при классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Совместим с WooCommerce High-Performance Order Storage (HPOS).

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

Заказы

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

Pending payment: покупатель ещё не оплатил заказ или платёж не завершён. Покупатель может повторно оплатить тот же заказ.

Processing: платёж подтверждён, сумма и валюта совпадают с заказом. Примечание показывает код результата, описание и ID платежа Peach Payments; этот ID является ID транзакции заказа. Если Peach Payments отметил платёж для ручной проверки, примечание просит проверить его в панели Peach Payments перед отправкой товара.

On hold: платёж ожидает подтверждения Peach Payments (вебхук позже завершит его или отметит неудачным); сумма или валюта отличаются от заказа (примечание amount/currency mismatch — manual review required); либо платёж пришёл после отмены заказа. Примечание объясняет, что проверить.

Failed: Peach Payments отклонил платёж заказа в статусе «Ожидание оплаты» либо ожидаемый платёж заказа «На удержании». Отклонённая попытка никогда не меняет оплаченный, удерживаемый по другой причине или отменённый заказ. Покупатель может заплатить снова.

При успешной второй оплате уже оплаченного заказа заказ не меняется. Примечание сообщает о дублирующем платеже и просит вернуть его в панели Peach Payments. Платёж по возвращённому заказу только фиксируется в примечании.

Возвраты

Возвраты с экрана заказа WooCommerce недоступны. Верните платёж в панели Peach Payments и зарегистрируйте ручной возврат в WooCommerce. При настроенном вебхуке возвраты, отмены и чарджбэки Peach Payments добавляются в заказ как примечания с суммой и ID; статус заказа не меняется.

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

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

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

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

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

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

Peach Payments не появляется при оформлении заказа: проверьте активность лицензии, включение Enable/Disable, наличие Entity ID и Access Token текущего режима (Test Entity ID и Test Access Token в тестовом, Live Entity ID и Live Access Token в рабочем) и валюту магазина ZAR, KES или MUR. Уведомления вверху настроек указывают проблему. Разработчики могут изменить список валют фильтром peach_p_supported_currencies; добавляйте только валюты, которые обрабатывает ваша учётная запись Peach Payments.

Платёж прошёл, но заказ остаётся Pending payment: покупатель не вернулся, а вебхук не пришёл. Проверьте, что Peach Payments включил вебхуки Card для точного URL из настроек, указан Webhook Decryption Key режима оплаты и URL не блокируется режимом обслуживания, брандмауэром или паролем. Ищите отклонённые вебхуки в WooCommerce > Status > Logs, источник wcp_peach_pay.

Вебхук отвечает Decryption failed: его не удалось расшифровать тестовым или рабочим ключом. Ключ неверен либо принадлежит другой учётной записи или режиму. Введите ключ, присланный Peach Payments для этого URL вебхука.

Вебхук отвечает Webhook key not configured: ни один ключ вебхука не задан или не действителен. Введите ключ из 64 символов. Peach Payments отправит вебхук позже повторно.

Вебхук отвечает Order busy, retry later: заказ одновременно обновлялся при возвращении покупателя. Ничего не изменилось; Peach Payments отправит вебхук повторно.

Вебхук отвечает Missing or malformed data: в запросе отсутствовало зашифрованное тело или заголовки X-Initialization-Vector / X-Authentication-Tag, например из-за изменения прокси-сервером. Ничего не изменилось.

Вебхук отвечает ignored: уведомление подлинное, но не относится к платёжной сессии этого магазина (другой магазин с тем же Entity ID, удалённый заказ) либо пришло из другого режима. Ничего не изменилось.

Покупатель видит The payment form is not available right now: Access Token или Entity ID текущего режима неверен. Проверьте данные и режим, прочитайте код Peach Payments в примечании к заказу.

После оплаты заказ имеет статус On hold: прочитайте примечание. Сумма или валюта отличались от заказа, платёж пришёл после отмены либо Peach Payments ещё ожидает подтверждения. Проверьте платёж в панели Peach Payments, затем обработайте заказ или верните платёж.

При сохранении требуется шестнадцатеричный ключ вебхука из 64 символов: значение не является ключом Peach Payments. До исправления вебхуки нельзя расшифровать.

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

Удаление

Отключение плагина сохраняет все данные. Для удаления отключите и удалите его на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки и журналы (файлы и записи журнала в базе данных источника wcp_peach_pay) удаляются только при включённом Delete data on uninstall. Иначе сохраняются для повторной установки. Существующие заказы сохраняют платёжные примечания, ID транзакций и данные платёжных сессий Peach Payments.

Peach Payments является товарным знаком соответствующего владельца. Этот плагин не связан с Peach Payments и не одобрен этой компанией.