VibeFox Yoco for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

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

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

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

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

Установка

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

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

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

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

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

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

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Yoco Pay Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если валюта магазина не ZAR (тогда Yoco не предлагается на оформлении заказа), и если в текущем режиме нет секретного ключа, например Enter the test secret key to offer Yoco at checkout (test mode). При сохранении модуль проверяет ключи и секреты вебхуков и регистрирует вебхуки. Сообщения об этом появляются вверху страницы.

Yoco

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

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: использует тестовый секретный ключ. Реальные деньги не списываются; платите тестовыми картами Yoco. По умолчанию: включено. Выключите, чтобы принимать реальные платежи. Пока режим включён, покупатели видят под способом оплаты Test mode — use a Yoco test card; no real money is charged.

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

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

Ключ, который не начинается с ожидаемого префикса, не сохраняется: страница показывает ошибку, например Yoco: the test secret key must start with sk_test_ — the previous value was kept. Если Yoco сообщает при регистрации вебхука, что ключ относится к другому режиму, страница сообщает об этом.

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

Webhooks

Yoco подтверждает платежи и возвраты на URL, который показан в поле Webhook URL в этом разделе. При понятных URL он выглядит так: https://your-shop/module/wcp_yoco_pay/webhook, возможно, с кодом языка, например /en/. Создавать вебхук в портале Yoco не нужно. При сохранении настроек модуль регистрирует URL в Yoco для каждого режима, у которого есть секретный ключ, но нет секрета вебхука, и сохраняет секрет подписи в поле этого режима. Регистрация повторяется, когда меняется секретный ключ этого режима или URL вебхука. Когда URL меняется, старая регистрация удаляется.

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

Модуль обрабатывает эти события (они также перечислены в этом разделе):

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

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

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

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

Clear saved secrets: отметьте ключ или секрет и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение. Очистка секрета вебхука и сохранение регистрируют вебхук заново.

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

Debug log: записывает запросы и вебхуки Yoco в файл logs/yoco_p_debug.log.php в папке модуля. Файл нельзя открыть из браузера. Ошибки и предупреждения, например неудачные запросы к Yoco и отклонённые вебхуки, всегда записываются в журнал. Ключи, секреты вебхуков и адреса e-mail маскируются. По умолчанию: выключено.

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

Delete data: если включено, при удалении модуля удаляются настройки, журнал и вебхуки, которые модуль зарегистрировал в Yoco. Данные заказов (ID checkout и платежей Yoco, возвраты) и статус заказа Yoco payment on hold всегда сохраняются, потому что нужны для возвратов. По умолчанию: выключено.

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

На шаге оплаты покупатель выбирает способ оплаты (по умолчанию Card or Instant EFT (Yoco)) и подтверждает. Модуль создаёт checkout Yoco на сумму корзины в центах и отправляет покупателя на страницу оплаты Yoco, где он платит картой или Instant EFT. На этом этапе заказа ещё не существует.

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

Если покупатель отменяет платёж на странице Yoco, он возвращается на оформление заказа с сообщением The Yoco payment was cancelled. Your cart is saved — you can pay again or choose another payment method. Если платёж не прошёл, появляется сообщение The Yoco payment was not successful. Please try again or choose another payment method. Корзина сохраняется.

Перед новой попыткой оплаты той же корзины модуль проверяет предыдущую попытку в Yoco. Если она уже оплачена, заказ создаётся без новой страницы оплаты. Если она всё ещё открыта на ту же сумму и создана менее 30 минут назад, покупатель снова получает ту же страницу Yoco. Иначе создаётся новый checkout 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.

Вебхук работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по странам в вашем магазине.

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

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

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

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

Payment accepted: платёж подтверждён. Он записывается с ID платежа Yoco в качестве ID транзакции, а примечание показывает сумму, ID платежа и checkout Yoco, режим и то, как платёж был подтверждён (возврат покупателя, вебхук или проверка перед новой попыткой оплаты).

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

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

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

Блок оплаты Yoco

На странице заказа показан блок Yoco payment с ID платежа и checkout Yoco, статусом, оплаченной и возвращённой суммой, значком Test mode для тестовых платежей, историей возвратов, попытками оплаты корзины (если их было больше одной) и Yoco notes заказа.

Возвраты

В блоке Yoco payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via Yoco. Подтвердите вопрос Refund this amount through Yoco? This cannot be undone. Поддерживаются полные и частичные возвраты. Нужно право на редактирование заказов. Возвраты рассчитываются от суммы, которую списала Yoco, поэтому можно вернуть не больше того, что покупатель фактически заплатил, даже если заказ потом редактировался. Возврат отправляется в том режиме, в котором прошёл платёж (тестовом или рабочем), поэтому секретный ключ этого режима должен быть задан. Повторный возврат после потерянного ответа не выплачивается дважды.

Успешный возврат добавляется в историю возвратов и примечания вместе с ID возврата Yoco. Полный возврат переводит заказ в статус Refunded; частичный возврат статус не меняет. Если Yoco отклоняет возврат, блок показывает Yoco refused the refund: с причиной, и возврат не записывается. Если Yoco сообщает, что возврат в обработке, блок указывает, что он ещё в обработке. Не повторяйте его: он будет записан, когда Yoco подтвердит его вебхуком. Возвраты доступны для заказов, оплаченных через checkout Yoco. У заказа в статусе Yoco payment on hold нет оплаченного checkout для возврата; верните его в портале Yoco.

Модуль не создаёт кредит-ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Yoco.

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

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Yoco Pay Gateway — первый блок на странице Modules > Module Manager > VibeFox Yoco Pay Gateway > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-yoco и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Менять ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку бэк-офиса (включены английский и русский).

Если ключ не принят, блок объясняет причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения места для домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

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

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

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

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

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

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

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

Вебхуки отклоняются: отклонённые вебхуки записываются в журнал. 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 отправит вебхук повторно.

URL вебхука в браузере показывает только POST: это нормально. URL принимает только запросы от Yoco.

Ошибка при сохранении «The secret key must start with sk_test_ / sk_live_»: ключ вставлен не в то поле. Тестовый ключ начинается с sk_test_, рабочий — с sk_live_. Предыдущее значение сохранено.

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

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

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

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

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

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Yoco Pay Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete data включено, удаляются настройки, журнал и вебхуки, которые модуль зарегистрировал в Yoco. Если выключено, все настройки сохраняются для повторной установки. Checkout и возвраты Yoco и статус заказа Yoco payment on hold всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

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