VibeFox Paymob for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Учётная запись Paymob: учётная запись мерчанта в одной из поддерживаемых стран: Египет, Объединённые Арабские Эмираты, Саудовская Аравия, Оман или Пакистан. Вам понадобятся четыре значения из панели Paymob: API key, integration ID онлайн-интеграции оплаты, iFrame ID страницы оплаты и HMAC secret.

Валюта: валюта корзины должна быть валютой вашей страны Paymob: EGP для Египта, AED для Объединённых Арабских Эмиратов, SAR для Саудовской Аравии, OMR для Омана, PKR для Пакистана. При другой валюте способ оплаты скрывается на оформлении заказа. Мультивалютные учётные записи Paymob не поддерживаются.

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

Установка

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

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

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

4. Выберите Paymob country и введите API key, integration ID, iFrame ID и HMAC secret (см. Настройка).

5. В панели Paymob укажите callback-адреса вашей интеграции — адрес, который показан на странице Configure (см. Callbacks).

6. Включите Enable/Disable и нажмите Save. Проверьте оплату с ID тестовой интеграции Paymob, затем введите ID вашей боевой интеграции.

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Paymob Pay > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если не заполнено одно из четырёх значений Paymob (до этого Paymob скрыт на оформлении заказа), и если выбранная страна Paymob не принимает валюту магазина по умолчанию. В блоке Callbacks показан callback-адрес с кнопкой Copy и ссылка на панель Paymob выбранной страны.

Paymob

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

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

Description: текст, который показывается под способом оплаты на оформлении заказа. По умолчанию: Pay securely by card or mobile wallet on the Paymob payment page. Оставьте поле пустым, если текст показывать не нужно.

Учётная запись Paymob

Все значения находятся в панели мерчанта Paymob. Отдельного тестового режима нет: для тестовых платежей введите integration ID интеграции в тестовом режиме. Другие настройки не меняются.

Paymob country: страна вашей учётной записи Paymob. Она выбирает сервер API и страницы оплаты, а валюта корзины должна быть валютой этой страны. По умолчанию: Egypt.

API key: в панели Paymob в разделе Settings > Account info > API Key.

Integration ID: в панели Paymob в разделе Developers > Payment Integrations: числовой ID онлайн-интеграции карт или кошельков. Способы оплаты, которые предлагаются на странице Paymob, — это способы этой интеграции.

iFrame ID: в панели Paymob в разделе Developers > iframes: числовой ID платёжного iFrame.

HMAC secret: в панели Paymob в разделе Settings > Account info > HMAC. Обязательно: заказы создаются как оплаченные только по callback, подписанным этим секретом.

Integration ID и iFrame ID должны содержать только цифры. Пробелы удаляются. Любое другое значение отклоняется при сохранении с сообщением, что поле must contain digits only — the previous value was kept. Остальные поля сохраняются.

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

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

Callbacks

Paymob сообщает о каждой транзакции в ваш магазин. В панели Paymob откройте Developers > Payment Integrations, выберите вашу интеграцию, нажмите Edit и укажите и в Transaction processed callback, и в Transaction response callback адрес из блока Callbacks. С понятными URL он выглядит так: https://your-shop/module/wcp_paymob_pay/callback, возможно с кодом языка, например /en/. Адрес формируется на языке магазина по умолчанию. Скопируйте его кнопкой Copy. Укажите адреса в каждой используемой интеграции, включая тестовую.

Transaction processed callback отправляется сервером Paymob. Transaction response callback возвращает покупателя в ваш магазин. Оба подписаны вашим HMAC secret и проверяются модулем. Callback без корректной подписи отклоняется и ничего не меняет. Если серверный callback опоздал или потерян, оплату также подтверждает подписанный возврат покупателя. Серверный callback работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

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

Debug log: записывает шаги оплаты и callback в logs/paymob_p_debug.log.php в папке модуля. Файл нельзя открыть из веба. Ошибки и отклонённые callback записываются всегда, даже когда опция выключена. Ключи, токены и данные покупателей никогда не записываются. По умолчанию: выключено.

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

Clean uninstall: если включено, при удалении модуля удаляются его настройки и журналы. ID Paymob, сохранённые для заказов (попыток оплаты), и статусы заказов всегда сохраняются. По умолчанию: выключено.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Paymob) и подтверждает. Модуль регистрирует новый заказ Paymob на сумму корзины в валюте корзины, передаёт в Paymob имя, e-mail, телефон и адрес для счёта покупателя и отправляет покупателя на страницу оплаты Paymob вашей страны. Там покупатель платит одним из способов вашей интеграции, например картой или мобильным кошельком. На этом этапе заказа ещё не существует.

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

Если заказ подтверждается callback Paymob в тот же момент, покупатель видит страницу с текстом Paymob accepted your payment and we are confirming it. You will receive an e-mail as soon as your order is confirmed — there is no need to pay again. Для ожидающего платежа текст такой: Your Paymob payment is pending (for example a cash or kiosk payment). Complete it as Paymob instructed you: your order is confirmed as soon as Paymob reports the payment. На странице есть кнопка Check again и кнопка Back to checkout.

Если платёж отклонён, покупатель возвращается на оформление заказа с той же корзиной и сообщением Your Paymob payment was not completed. Please try again or choose another payment method. Каждая новая попытка создаёт свой заказ Paymob, поэтому покупатель может оплатить корзину снова. Если ответ от Paymob невозможно проверить, покупатель видит We could not verify the response from Paymob. If you were charged, your order will be updated as soon as Paymob confirms the payment.

Если Paymob не может начать оплату, покупатель остаётся на оформлении заказа с коротким сообщением, например Paymob could not start the payment. Please check your billing details and try again, or choose another payment method. или Could not connect to Paymob. Please try again in a moment. Техническая причина записывается в журнал.

Модуль принимает разовые платежи на странице Paymob. Сохранённых карт, подписок, встроенной формы карты на вашем сайте и возвратов из back office нет.

Заказы

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

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

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

Awaiting Paymob payment: платёж ожидает подтверждения в Paymob, например оплата наличными или через киоск. Заказ переходит в статус Payment accepted, когда Paymob подтверждает оплату.

Paymob payment on hold: Paymob только авторизовал сумму и не списал её (спишите её в панели Paymob; заказ перейдёт в статус Payment accepted, когда придёт callback о списании); или оплаченная сумма или валюта отличаются от корзины (например, корзину изменили после начала оплаты); или поступил платёж для отменённого заказа. Причина объясняется в примечании. Проверьте заказ и выполните его или сделайте возврат платежа в панели Paymob.

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

Блок оплаты Paymob

На странице заказа показан блок Paymob payment с каждой попыткой оплаты Paymob по этому заказу: заказ Paymob, номер заказа мерчанта и страна, ID транзакции Paymob, статус, запрошенная сумма, сумма, которую Paymob сообщил по карте, и сообщение Paymob. Ниже находятся Notes модуля для этого заказа.

Возвраты

Возвраты из back office не поддерживаются. Сделайте возврат или отмену платежа в панели Paymob. Когда Paymob сообщает о возврате или отмене, к заказу добавляется примечание, а статус заказа не меняется. Обновите заказ вручную, например его статус или создайте кредит-ноту.

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

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

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

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

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

Paymob не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, все четыре значения (API key, integration ID, iFrame ID, HMAC secret) заполнены и валюта корзины совпадает с валютой выбранной Paymob country. Страница настроек показывает предупреждение, если чего-то не хватает. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: callback не доходят до вашего магазина. Проверьте, что Transaction processed callback и Transaction response callback используемой интеграции в точности совпадают с адресом из блока Callbacks, и что HMAC secret принадлежит той же учётной записи Paymob. Отклонённые callback записываются в журнал как предупреждения, даже когда Debug log выключен. Посмотрите поле Log на странице модуля.

Callback отвечает Invalid signature: HMAC secret в настройках не совпадает с учётной записью Paymob или выбрана учётная запись другой страны. Скопируйте HMAC secret заново.

Callback отвечает Not configured: HMAC secret пуст. Введите секрет; Paymob повторит callback.

Callback отвечает locked или retry: заказ в этот момент обновлялся другим запросом, например возвратом покупателя, или заказ не удалось создать (например, модуль отключён). Paymob повторит callback. Причина записывается в журнал.

Открытие callback-адреса в браузере ведёт на оформление заказа с сообщением could not verify: это нормально. Адрес принимает только подписанные запросы от Paymob.

Покупатель видит ошибку при выборе Paymob: включите Debug log и посмотрите журнал. Paymob payments are temporarily unavailable означает неверный API key или отсутствующее значение. Paymob could not start the payment означает, что Paymob отклонил запрос, например из-за неверного integration ID или неполных платёжных данных. This order cannot be paid with Paymob означает, что сумма заказа равна нулю. Paymob does not accept payments in и далее валюта означает, что валюта корзины не совпадает с валютой выбранной страны Paymob.

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

Тестовые платежи: введите ID тестовой интеграции Paymob в поле Integration ID и укажите callback-адреса в этой интеграции. Для реальных платежей снова введите ID вашей боевой интеграции.

Удаление

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

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