VibeFox Yoco for WooCommerce — Помощь

Требования

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

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

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

Валюта магазина: южноафриканский ранд (ZAR). Yoco принимает только ZAR. При любой другой валюте способ оплаты не показывается при оформлении заказа. Сумма заказа должна быть не менее R2,00.

Учётная запись Yoco: учётная запись Yoco с онлайн-платежами. Нужны её секретные ключи, которые находятся в Yoco Business Portal в разделе Selling Online > Payment Gateway. Вводятся только секретные ключи. Вебхук регистрирует плагин, а его секрет подписи заполняется автоматически.

Публичный сайт: Yoco отправляет вебхуки на ваш сайт, поэтому он должен быть доступен из интернета. URL вебхука должен принимать POST без перенаправлений.

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

Установка

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

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > Yoco > Manage.

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

5. Вставьте тестовый секретный ключ (sk_test_...) и, когда будете готовы, рабочий секретный ключ (sk_live_...). Сохраните настройки. Вебхук регистрируется для каждого режима, для которого есть ключ.

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

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Yoco. Над полями страница предупреждает, если валюта магазина не ZAR (тогда Yoco не предлагается при оформлении заказа), и если в текущем режиме нет секретного ключа. В списке способов оплаты Yoco помечается как требующий настройки, пока в текущем режиме нет секретного ключа. При сохранении плагин проверяет ключи и секреты вебхуков и регистрирует вебхуки. Сообщения об этом появляются вверху страницы.

Общие

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

Title: название способа оплаты, которое видит покупатель при оформлении заказа. По умолчанию: Card or Instant EFT (Yoco).

Description: текст под способом оплаты при оформлении заказа. По умолчанию: You will be redirected to the secure Yoco page to pay by card or Instant EFT.

Ключи API

Скопируйте секретные ключи из Yoco Business Portal в разделе Selling Online > Payment Gateway. У Yoco один API для обоих режимов: ключ определяет, является платёж тестовым или реальным. Тестовый режим использует только тестовый ключ, рабочий — только рабочий.

Test mode: Use the test secret key (no real payments). Реальные деньги не списываются; платите тестовыми картами Yoco. По умолчанию: on. Снимите отметку, чтобы принимать реальные платежи.

Test secret key: секретный ключ тестового режима. Начинается с sk_test_.

Live secret key: секретный ключ рабочего режима. Начинается с sk_live_.

Ключ, который начинается не с ожидаемого префикса, не сохраняется: страница показывает ошибку и оставляет прежнее значение. Если Yoco при регистрации вебхука сообщает, что ключ относится к другому режиму, страница вам об этом сообщит.

Вебхуки

Yoco подтверждает платежи и возвраты на URL вебхука, показанный в этом разделе. Он выглядит так: https://your-site/wc-api/yoco_pay_webhook/. Создавать вебхук в портале Yoco не нужно. При сохранении настроек плагин регистрирует URL в Yoco для каждого режима, у которого есть секретный ключ, но нет секрета вебхука, и сохраняет секрет подписи в поле этого режима. URL регистрируется заново, когда меняется секретный ключ этого режима или URL вебхука. Когда URL меняется, старая регистрация удаляется.

Для каждого режима раздел показывает состояние вебхука:

Плагин обрабатывает такие события:

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

Test webhook secret: заполняется автоматически при регистрации вебхука. Вставляйте секрет (whsec_...) только если вы сами зарегистрировали URL вебхука.

Live webhook secret: заполняется автоматически при регистрации вебхука. Очистите поле и сохраните, чтобы зарегистрировать вебхук заново.

Секрет вебхука должен выглядеть как whsec_ и далее текст в base64. Любое другое значение не сохраняется, прежнее значение остаётся.

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

Debug log: Log Yoco requests and webhooks записывает запросы и вебхуки в WooCommerce > Status > Logs, источник wcp_yoco_pay. Ошибки и предупреждения, например неудачные запросы к Yoco и отклонённые вебхуки, всегда записываются. Ключи, секреты вебхуков и адреса e-mail маскируются. По умолчанию: off.

Delete data: Delete the settings and logs of this plugin when it is deleted. Деактивация никогда ничего не удаляет. Данные заказов (ID checkout и платежа Yoco) всегда сохраняются, потому что они нужны для возвратов. По умолчанию: off.

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

Покупатель выбирает способ оплаты (по умолчанию Card or Instant EFT (Yoco)) и оформляет заказ. В тестовом режиме при оформлении заказа показывается Test mode — use a Yoco test card; no real money is charged. Плагин создаёт checkout Yoco на сумму заказа в центах и отправляет покупателя на страницу оплаты Yoco, где он платит картой или Instant EFT.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Yoco: плагин запрашивает у Yoco checkout, когда покупатель возвращается, и снова, когда приходит подписанный вебхук. Если Yoco ещё не подтвердила платёж, страница «Заказ получен» показывает We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again.

Если покупатель отменяет платёж на странице Yoco, заказ остаётся неоплаченным, и покупатель попадает на страницу Pay for order с сообщением The Yoco payment was cancelled. Your order is saved — you can pay again below or choose another payment method. Если платёж не прошёл, сообщение: The Yoco payment was not successful. Please try again or choose another payment method. и к заказу добавляется примечание.

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

Если Yoco не может начать платёж, покупатель видит Yoco could not start the payment. Please try again in a moment or choose another payment method. и причина добавляется в примечания к заказу. Заказ меньше R2,00 получает Yoco requires an order total of at least R2.00.

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

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

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

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

Pending payment: покупатель отправлен в Yoco и ещё не оплатил, отменил платёж на странице Yoco, или Yoco ещё не подтвердила платёж.

Processing or Completed: платёж подтверждён. WooCommerce ставит «В обработке», или «Выполнен» для заказов только с виртуальными загружаемыми товарами. В примечании к заказу указаны сумма, ID платежа и checkout Yoco, режим и способ подтверждения (возврат покупателя, вебхук или проверка перед новой попыткой оплаты). ID транзакции — это ID платежа Yoco.

On hold: Yoco сообщила сумму или валюту, отличные от суммы заказа, например потому что заказ был изменён после начала оплаты. Примечание объясняет это, а покупатель, вернувшийся из Yoco, видит We received your payment and are reviewing it. We will contact you if anything else is needed. Проверьте платёж перед отправкой.

Cancelled or Refunded: платёж, пришедший по такому заказу, его не меняет. Примечание просит вас вернуть платёж в портале Yoco или восстановить заказ вручную. Покупатель, вернувшийся из Yoco, видит Your payment was received after the order had been cancelled. Please contact us — do not pay again.

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

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите кнопку Refund via с названием вашего способа оплаты (по умолчанию Card or Instant EFT (Yoco)). Поддерживаются полные и частичные возвраты. Возврат отправляется в том режиме, в котором прошёл платёж (тестовом или рабочем), поэтому секретный ключ этого режима должен быть заполнен. Возврат, повторённый после потерянного ответа, не выплачивается дважды.

Успешный возврат добавляется в примечания к заказу с ID возврата Yoco. Если Yoco отклоняет возврат, WooCommerce показывает Yoco refused the refund: с причиной, и возврат не записывается. Если Yoco сообщает, что возврат в ожидании, WooCommerce показывает, что он всё ещё в ожидании, и ничего не записывает. Не повторяйте его: он будет добавлен к заказу, когда Yoco подтвердит его вебхуком.

Возвраты, сделанные в портале Yoco, приходят через вебхук refund.succeeded и автоматически записываются как возвраты WooCommerce, без возврата товаров на склад. Возврат больше остатка, доступного к возврату, не записывается, и примечание просит проверить заказ. Неудачный возврат добавляет примечание о том, что деньги покупателю не возвращены.

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

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

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

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

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

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

Yoco не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён, и в текущем режиме есть секретный ключ: Test secret key в тестовом режиме, Live secret key в рабочем. Валюта магазина или заказа должна быть ZAR, а сумма заказа — не менее R2,00. Страница настроек показывает предупреждение, если ключа нет или валюта не ZAR.

Платёж прошёл, но заказ остаётся Pending payment: вебхук не работает. Откройте раздел Webhooks настроек и проверьте состояние режима, который вы используете. Если он не зарегистрирован или зарегистрирован для другого URL, сохраните настройки. Если регистрация не удалась, страница показывает причину. Если вы ввели секрет сами, проверьте, что он принадлежит вебхуку этого URL и режима. Заказ также подтверждается, когда покупатель возвращается в магазин после оплаты и когда пытается оплатить снова.

Не удалось зарегистрировать вебхук: платежи по-прежнему подтверждаются, когда покупатели возвращаются в магазин. Устраните причину, указанную в сообщении, например сайт должен быть доступен из интернета по HTTPS, и сохраните снова. Также можно зарегистрировать URL самостоятельно и вставить секрет подписи.

Вебхуки отклоняются: отклонённые вебхуки записываются в журнал, источник wcp_yoco_pay. webhook secret not configured означает, что ни один секрет вебхука не задан. invalid signature означает, что секрет принадлежит другой регистрации или режиму. timestamp outside the tolerance означает, что часы сервера неверны: подписи принимаются в пределах 5 минут от времени сервера. checkout not completed yet — retry и could not confirm the checkout with Yoco — retry временные; Yoco отправит вебхук повторно.

The secret key must start with sk_test_ / sk_live_ error on save: ключ вставлен не в то поле. Тестовый ключ начинается с sk_test_, рабочий — с sk_live_. Прежнее значение сохранено.

Покупатель видит ошибку при оформлении заказа: прочитайте примечания к заказу или WooCommerce > Status > Logs, источник wcp_yoco_pay. Yoco is not available at the moment. Please choose another payment method. означает, что в текущем режиме нет секретного ключа.

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

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

Возврат не проходит с сообщением No answer from Yoco: в WooCommerce ничего не записано. Если Yoco всё же обработала возврат, повторите тот же возврат: он не будет выполнен дважды.

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

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить его, деактивируйте и удалите его на странице Plugins. Лицензионный ключ и статус лицензии этого плагина всегда удаляются. Настройки шлюза, регистрации вебхуков в Yoco и журналы, включая ротированные файлы журнала, удаляются только если была включена опция Delete data. Иначе они сохраняются для повторной установки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

Yoco — товарный знак соответствующего правообладателя. Этот плагин не связан с Yoco и не одобрен ею.