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

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее с расширением OpenSSL (используется для расшифровки вебхуков). Без них модуль не установится.

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

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

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

Установка

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

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Peach Payments Pay Gateway в списке модулей и нажмите Configure.

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

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

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

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

Настройки

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

Peach Payments

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 credentials

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

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 рабочей учётной записи.

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

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

Webhook

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

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

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

Payment form

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

Advanced

Logging: записывает запросы к API и результаты платежей в файл logs/peach_p_debug.log.php в папке модуля. Файл нельзя прочитать из браузера. Ошибки и предупреждения записываются всегда. Журналы не содержат данных карт, ключей и данных покупателей. По умолчанию: выключено.

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

Delete data on uninstall: если включено, при удалении модуля удаляются его настройки и журналы. Данные Peach Payments по заказам (попытки оплаты, ID платежей) и статусы заказов сохраняются, потому что относятся к заказам. По умолчанию: выключено.

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

Покупатель выбирает способ оплаты (по умолчанию Credit / Debit Card (Peach Payments)) и подтверждает заказ. В тестовом режиме способ оплаты показывает Test mode: no real payment will be made. Модуль создаёт checkout Peach Payments на сумму корзины в валюте корзины и показывает страницу Peach Payments payment вашего магазина с платёжной формой Peach Payments и выбранными платёжными системами карт, на языке покупателя, если Peach Payments его поддерживает. В тестовом режиме страница показывает Test mode: use a Peach Payments test card, no real payment will be made. Данные карты вводятся в форме Peach Payments, а скрипт формы загружается с хешем Subresource Integrity. Ссылка Choose another payment method возвращает к оформлению заказа. На этом этапе заказа ещё не существует. При перезагрузке страницы тот же checkout используется повторно в течение до 25 минут, если корзина не изменилась.

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

Если платёж не завершён, покупатель возвращается на оформление заказа с сообщением и может попробовать снова: 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. Если для режима платежа не задан ключ вебхука, покупателю вместо этого предлагается связаться с вами.

Если платёжную форму не удаётся подготовить, покупатель остаётся на оформлении заказа с коротким сообщением: 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. Техническая причина записывается в журнал.

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

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

Заказы

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

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

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

Awaiting Peach Payments payment: Peach Payments сообщил о платеже, который ждёт подтверждения. Позже вебхук переводит заказ в Payment accepted или отмечает его как неудачный.

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

Payment error: Peach Payments отклонил платёж, которого ждал заказ в ожидании. Отклонённая попытка никогда не меняет заказ, который оплачен, на удержании или отменён.

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

Блок платежа Peach Payments

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

Возвраты

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

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

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

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

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

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

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

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

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

Платёж прошёл, но заказ не создан: покупатель не вернулся в магазин, а вебхук не пришёл. Проверьте, что Peach Payments включил вебхуки Card именно для URL, который показан в настройках, что введён Webhook Decryption Key того режима, в котором был сделан платёж, и что файрвол или парольная защита не блокируют URL. Включите Logging и посмотрите поле Log на отклонённые вебхуки.

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

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

Вебхук отвечает Busy, retry later: корзину в этот момент обрабатывало возвращение покупателя, либо не удалось создать заказ (например, модуль выключен). Ничего не изменилось, Peach Payments отправит вебхук повторно. Причина указана в журнале.

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

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

URL вебхука в браузере показывает Method not allowed: это нормально. URL принимает только запросы от Peach Payments.

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

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

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

Удаление

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

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