VibeFox 2C2P for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Учётная запись 2C2P: вам нужны Merchant ID и секретный ключ вашей учётной записи мерчанта 2C2P. Их выдаёт 2C2P при открытии учётной записи мерчанта. У тестовых (sandbox) и боевых учётных записей разные ключи. Документация для разработчиков и тестовые карты sandbox находятся на developer.2c2p.com.

Валюта: валюта корзины должна поддерживаться модулем и быть включена в вашей учётной записи 2C2P. Среди поддерживаемых, в частности, THB, SGD, MYR, PHP, IDR, VND, MMK, KHR, LAK, CNY, HKD, TWD, JPY, KRW, INR, AUD, NZD, USD, EUR и GBP. Если валюта корзины не поддерживается, способ оплаты не показывается на этапе оформления заказа.

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

Установка

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

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

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

4. Введите Merchant ID и Secret Key тестовой среды (sandbox), включите Enable/Disable, нажмите Save и оформите тестовый заказ.

5. Когда всё будет готово, введите боевые данные и выключите Sandbox Mode.

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

Настройка

Все параметры находятся на странице модуля: Modules > Module Manager > VibeFox 2C2P Payment > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает Sandbox mode is active. No real transactions will be processed., пока включён тестовый режим. Она предупреждает, если шлюз включён, но Merchant ID или Secret Key текущего режима пусты, а также если валюта магазина по умолчанию не поддерживается. В обоих случаях способ оплаты не показывается на этапе оформления заказа. Если вы сохраняете настройки при выключенном Sandbox Mode, модуль показывает Please enter your live Merchant ID. или Please enter your live Secret Key., если боевое поле пусто. Настройки всё равно сохраняются.

2C2P

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

Title: название способа оплаты, которое видит покупатель на этапе оформления заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: 2C2P Payment.

Description: текст под способом оплаты на этапе оформления заказа. По умолчанию: Pay securely via credit/debit card, e-wallet, or internet banking through 2C2P. В тестовом режиме к нему добавляется (TEST MODE).

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

Sandbox Mode: отправляет платежи в тестовую среду 2C2P (demo2.2c2p.com) с тестовыми данными, указанными ниже. По умолчанию: включено. Выключите, чтобы принимать реальные платежи.

Sandbox Merchant ID: ваш Merchant ID 2C2P для тестовой среды.

Sandbox Secret Key: ваш секретный ключ 2C2P для тестовой среды.

Боевые данные API

Используются, когда тестовый режим выключен.

Merchant ID: ваш боевой Merchant ID 2C2P.

Secret Key: ваш боевой секретный ключ 2C2P. Ключ сохраняется точно в том виде, в котором введён, включая кавычки и обратные слеши.

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

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

Результаты всегда проверяются по Merchant ID и секретному ключу того режима, в котором был совершён платёж. Платёж, начатый в тестовом режиме, после перехода на боевой режим по-прежнему проверяется тестовым ключом, а результат, подписанный ключом другого режима, отклоняется.

Страница оплаты

URL результатов: для справки показывает Frontend return URL и Backend notification URL. При использовании ЧПУ они выглядят так: https://your-shop/module/wcp_2c2p_payment/return и https://your-shop/module/wcp_2c2p_payment/notify, возможно с кодом языка, например /en/. Они автоматически передаются с каждым платежом.

Payment Page Language: язык страницы оплаты 2C2P. По умолчанию: English.

Redirect API version: оставьте 8.5, если 2C2P не сообщил, что ваша учётная запись всё ещё использует старую версию 7.0 (подписи SHA-1). Результаты платежей, начатых до переключения, по-прежнему проверяются.

Order ID prefix: необязательный, только буквы и цифры (не более 10), например SHOP1. 2C2P отклоняет ID заказа, который уже встречался. Задайте уникальный префикс, если несколько магазинов используют одну учётную запись 2C2P, а также в тестовой среде, где тестовые учётные записи мерчанта общие. Остальные символы удаляются при сохранении, с предупреждением.

Дополнительные настройки

Enable Logging: записывает события 2C2P в файл logs/tc2p_p_debug.log.php в папке модуля. Файл нельзя открыть через браузер. Данные карт, секретные ключи, адреса электронной почты покупателей и платёжные токены не записываются. По умолчанию: выключено. Пока журнал выключен, ничего не записывается, в том числе ошибки.

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

Delete Data on Uninstall: если включено, при удалении модуля удаляются настройки шлюза и журнал. Транзакции 2C2P, заказы и статусы заказов модуля всегда сохраняются, поэтому поздний результат старого платежа обрабатывается и после повторной установки. По умолчанию: выключено.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию 2C2P Payment) и подтверждает выбор. Следующая страница показывает Thank you for your order. You will be redirected to 2C2P to complete your payment. и через мгновение отправляет покупателя на страницу оплаты 2C2P. Если этого не происходит, покупатель нажимает Pay via 2C2P. На странице также есть кнопка Back to checkout. На этом этапе заказа ещё не существует.

На странице 2C2P покупатель платит любым способом, включённым в вашей учётной записи 2C2P, например картами, электронными кошельками, QR-платежами, интернет-банкингом или наличными. Модуль передаёт сумму корзины в валюте корзины, адрес электронной почты покупателя и названия товаров в корзине. Платёж можно завершить в течение 24 часов. Каждая попытка оплаты получает собственный ID заказа в 2C2P (номер корзины и номер попытки, после необязательного префикса), потому что 2C2P никогда не принимает один и тот же ID заказа дважды.

2C2P сообщает результат дважды: браузер покупателя возвращается в магазин, и 2C2P отправляет серверное уведомление. Оба обрабатываются одинаково. Заказ помечается как оплаченный только после того, как 2C2P подтвердит его действительной подписью. Результат также должен относиться к этому платежу: ID заказа 2C2P должен был быть выдан вашим магазином, а Merchant ID и случайный токен попытки проверяются. Результаты без действительной подписи отклоняются. Уведомление работает, даже когда магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

После успешной оплаты заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с сообщением Your 2C2P payment has been received. Для платежа в ожидании страница показывает Your 2C2P payment is pending (for example a cash or bank payment that is not made yet). The order will be processed as soon as 2C2P confirms the payment. Для заказа в статусе «на удержании» она показывает Your payment was received and is being reviewed by the shop. Если платёж в ожидании позже был отменён, появляется Your 2C2P payment was not completed. Please contact us about this order.

Если платёж не был завершён, заказ не создаётся. Покупатель возвращается к оформлению заказа с сообщением Payment was not completed. Please try again or choose a different payment method. Корзина сохраняется, и покупатель может оплатить снова или выбрать другой способ оплаты. Если результат невозможно подтвердить, покупатель видит We could not confirm the payment result. If your account was charged, please contact us before paying again. Если платёж невозможно начать, например потому что валюта корзины не поддерживается, появляется сообщение This payment method is currently unavailable for this order. Please contact us or choose another payment method.

Если у корзины уже есть заказ (оплаченный или ожидающий платежа), вторая платёжная форма не создаётся. Покупатель перенаправляется на страницу подтверждения заказа.

В модуле нет возвратов из PrestaShop, сохранённых карт, регулярных платежей или подписок, полей для карт на вашем сайте и поддержки API 2C2P PGW 4.x.

Заказы

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

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

Payment accepted: 2C2P сообщил об успешном платеже (статус 000). Платёж регистрируется с референсом транзакции 2C2P в качестве ID транзакции. Внутреннее примечание к заказу показывает транзакцию 2C2P, код авторизации, дату и канал оплаты.

Awaiting 2C2P payment: платёж ожидает подтверждения в 2C2P (статус 001), например наличный платёж, который покупатель ещё не внёс. Заказ переходит в Payment accepted, когда 2C2P сообщает об оплате.

2C2P payment on hold: 2C2P сообщил сумму или валюту, которые не совпадают с суммой заказа. В примечании показаны полученные и ожидаемые значения. Проверьте заказ и транзакцию в портале 2C2P.

Canceled: платёж в ожидании впоследствии был отклонён, отменён или не прошёл (статусы 002, 003, 999). В примечании указаны статус и причина. Неуспешный результат более старой попытки не отменяет заказ, созданный другой попыткой.

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

Блок платежа 2C2P

На странице заказа показывается блок 2C2P payment с ID заказа 2C2P, транзакцией, статусом платежа, каналом, кодом авторизации, маскированным номером карты, датой, ответом канала и полученной суммой, а также бейдж Sandbox для платежей в тестовом режиме.

Возвраты

Возвраты из PrestaShop не поддерживаются. Верните платёж в портале мерчанта 2C2P, затем вручную зафиксируйте возврат в PrestaShop.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox 2C2P Payment — это первый блок на странице Modules > Module Manager > VibeFox 2C2P Payment > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки: Check now — проверить статус ещё раз, Change key — ввести другой ключ, Remove key — удалить ключ из этого магазина. Ниже находятся строка Product: presta-payment-2c2p и ссылка 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.

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

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

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

2C2P не появляется на этапе оформления заказа: проверьте, что лицензия активна, Enable/Disable включено и в текущем режиме есть Merchant ID и Secret Key: поля sandbox в тестовом режиме, боевые поля в боевом режиме. Проверьте, что валюта корзины поддерживается. Страница настроек показывает предупреждение в обоих случаях. В разделе Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: в ваш магазин не пришёл ни один действительный результат. Проверьте, что Merchant ID и Secret Key того режима, в котором был совершён платёж, совпадают с учётной записью 2C2P, и что Redirect API version соответствует вашей учётной записи. Результат с неверной подписью или для другого Merchant ID отклоняется. Включите Enable Logging и найдите сообщения о hash или Merchant ID в поле Log. Также проверьте, что ваш сервер принимает запросы от 2C2P на URL серверного уведомления.

Серверное уведомление отвечает 400 FAIL: в результате отсутствуют поля, неверная подпись, другой Merchant ID или неверный токен. 404 FAIL означает, что ID заказа 2C2P не был выдан этим магазином. 503 RETRY означает, что заказ в этот момент подтверждался другим запросом, или что заказ не удалось создать (например, модуль отключён); 2C2P повторит попытку позже. Включите Enable Logging, чтобы увидеть причину.

URL уведомления показывает FAIL в браузере: это нормально. URL принимает только POST-запросы от 2C2P.

2C2P сообщает, что ID заказа уже существует: 2C2P не принимает один и тот же ID заказа дважды. Это случается, когда несколько магазинов используют одну учётную запись 2C2P или в тестовой среде, где демонстрационные учётные записи мерчантов используются многими разработчиками. Задайте уникальный Order ID prefix.

Платёж совершён, но заказ в статусе Awaiting 2C2P payment или 2C2P payment on hold: либо платёж всё ещё ожидает подтверждения в 2C2P (например, наличный платёж, который покупатель ещё не внёс), либо оплаченные сумма или валюта не совпали с заказом. Проверьте примечания к заказу и транзакцию в портале 2C2P.

Покупатель видит This payment method is currently unavailable for this order: валюта корзины не поддерживается, Merchant ID или Secret Key текущего режима пусты, либо сумма корзины равна нулю.

Please enter your live Merchant ID или Please enter your live Secret Key при сохранении: тестовый режим выключен, а боевое поле пусто. Введите боевые данные или оставьте Sandbox Mode включённым.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox 2C2P Payment и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete Data on Uninstall включено, настройки шлюза и журнал удаляются. Если выключено, все настройки сохраняются для последующей повторной установки. Транзакции 2C2P и статусы заказов Awaiting 2C2P payment и 2C2P payment on hold всегда сохраняются. Существующие заказы сохраняют свои примечания к платежам и ID транзакций.

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