VibeFox Paymob for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

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

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

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

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

Установка

Файл — один ZIP-архив с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_paymob_pay-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_paymob_pay.ocmod.zip. Установите только пакет для вашей версии OpenCart. Лицензионный ключ одинаков для обеих версий.

OpenCart 3

1. В админке перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_paymob_pay-oc3-(version).ocmod.zip. У расширения нет модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload этого пакета в корневую папку вашего магазина.

2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Paymob Pay и нажмите Install (зелёная кнопка +).

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

4. Выберите Paymob country и введите API-ключ, ID интеграции, ID iFrame и секрет HMAC (см. Настройка).

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

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

OpenCart 4

1. В админке перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_paymob_pay.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите рядом Install (зелёная кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Paymob Pay, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ, ключи и ID Paymob и callback-URL, как в шагах 3–6 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только callback-URL (см. Callbacks).

Новая установка стартует с выключенным способом оплаты.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Paymob Pay > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если не хватает одного из четырёх значений Paymob (до этого Paymob скрыт при оформлении заказа), и если валюта магазина по умолчанию не принимается выбранной страной Paymob.

При сохранении Title не может быть длиннее 128 символов, Sort Order должен быть целым числом (отрицательные числа допускаются), Total — числом не меньше 0, а выбранная геозона и статусы заказов должны существовать. Иначе ничего не сохраняется, и страница называет поле.

Paymob

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

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

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

Sort Order: позиция Paymob среди способов оплаты при оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать Paymob только для платёжных адресов в выбранной геозоне. По умолчанию: All zones. Геозоны настраиваются в System > Localisation > Geo Zones. На OpenCart 4, если магазин не запрашивает платёжный адрес, используется адрес доставки.

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

Аккаунт Paymob

Все значения находятся в панели мерчанта Paymob. Отдельного тестового режима нет: для тестовых платежей введите 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-ключ и секрет HMAC никогда не показываются повторно. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённое значение, отметьте под полем Clear the saved API key on save или Clear the saved HMAC secret on save и нажмите Save.

Callbacks

Paymob сообщает в ваш магазин о каждой транзакции. В панели Paymob откройте Developers > Payment Integrations, выберите свою интеграцию, нажмите Edit и укажите и для Transaction processed callback, и для Transaction response callback адрес Callback URL, показанный в этом разделе. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_paymob_pay/callback, в OpenCart 4 — так: https://your-store/index.php?route=extension/wcp_paymob_pay/payment/wcp_paymob_pay.callback. Он формируется из адреса витрины вашей установки OpenCart. Скопируйте его кнопкой Copy. В разделе также есть ссылка на панель Paymob выбранной страны. Задайте URL в каждой используемой интеграции, включая тестовую.

Transaction processed callback отправляется сервером Paymob. Transaction response callback возвращает покупателя в ваш магазин. Оба подписаны вашим секретом HMAC и проверяются расширением. Callback без правильной подписи отклоняются и ничего не меняют. Если серверный callback приходит с опозданием или теряется, подписанный возврат покупателя тоже подтверждает платёж. URL callback работает и тогда, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы платёжных расширений, а в OpenCart 4 расширение добавляет startup-действие, которое пропускает callback и возврат покупателя.

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Статус он получает только после того, как Paymob сообщит о корректно подписанной транзакции. Отклонённый платёж оставляет заказ без статуса; покупатель возвращается к оформлению с сохранённой корзиной. Каждое поле ниже перечисляет ваши статусы заказов OpenCart.

Order Status After Payment: транзакция Paymob оплачена с ожидаемой суммой и валютой. По умолчанию: Обработка.

Awaiting Paymob Payment Status: транзакция в ожидании, например наличные или платёж через киоск. Заказ получает статус после оплаты, когда Paymob подтвердит платёж. По умолчанию: Ожидание.

Paymob Payment On Hold Status: Paymob только авторизовал сумму (спишите её в панели Paymob), оплаченная сумма или валюта не совпадают с заказом, либо платёж пришёл по отменённому заказу. Примечание объясняет причину. По умолчанию: Ожидание, потому что в OpenCart нет статуса On hold. Свой статус можно создать в System > Localisation > Order Statuses и выбрать его здесь.

Следующие три поля сообщают расширению, какие статусы использует ваш магазин. Расширение их никогда не устанавливает.

Payment Error Status: статус, который ваш магазин использует для заказов с ошибкой оплаты. Транзакция в ожидании может перевести такой заказ в статус ожидания. По умолчанию: Неудачно.

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

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

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

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

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

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

Импорт / Экспорт

Export: Download JSON сохраняет настройки в файл JSON. API-ключ и секрет HMAC не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые секреты остаются.

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Paymob). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to the secure Paymob payment page to pay by card or mobile wallet. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления. Когда покупатель нажимает Confirm Order, расширение регистрирует новый заказ Paymob на сумму заказа в валюте заказа, передаёт в Paymob имя, e-mail, телефон и платёжный адрес покупателя (в OpenCart 4, если магазин не запрашивает платёжный адрес, — адрес доставки) и отправляет покупателя на платёжную страницу Paymob вашей страны. Там он платит одним из способов вашей интеграции, например картой или мобильным кошельком.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после того, как Paymob подтвердит его подписанной транзакцией. Затем заказ получает статус обычным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления OpenCart. Платёж в ожидании (например, наличные или через киоск) или авторизованный платёж тоже присваивает заказу статус: ожидания или «на удержании», и ведёт на страницу успеха.

Если заказ ещё подтверждается, когда покупатель возвращается, страница Payment confirmation показывает 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, поэтому покупатель может оплатить корзину снова. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order; OpenCart 4 оставляет один заказ для оформления и обновляет его, поэтому покупатель оплачивает тот же заказ новой попыткой. Если ответ от 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. Если другой заказ из той же корзины уже оплачен или ждёт оплаты (например, во второй вкладке браузера), покупатель переходит на страницу успеха вместо повторной оплаты. В OpenCart 4 сообщения после возврата из Paymob показываются над страницей оформления.

OpenCart 4 сохраняет заказ в оформлении до показа страницы успеха. Если этот заказ был закрыт без оплаты (например, вы его отменили), покупатель возвращается к оформлению с сообщением Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., и следующее Confirm Order оплачивает новый заказ. Если у этого заказа уже есть статус, а в корзине теперь другие товары или количества, покупатель тоже возвращается к оформлению, и новая корзина получает новый заказ.

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

Заказы

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

No status (missing order): покупатель был отправлен в Paymob и не оплатил, платёж был отклонён, либо Paymob ещё не подтвердил платёж. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в Missing Orders.

В OpenCart 4 неоплаченный заказ оформления может получить статус Voided, который OpenCart 4 устанавливает, когда покупатель возвращается к шагу Confirm Order. Расширение считает такой заказ заказом без статуса, и последующий платёж всё равно его подтверждает.

Order Status After Payment (default Processing): Paymob подтвердил платёж. Примечание показывает транзакцию, сумму и тип карты с последними четырьмя цифрами.

Awaiting Paymob Payment Status (default Pending): платёж ожидает в Paymob, например наличные или платёж через киоск. Заказ переходит в статус после оплаты, когда Paymob подтверждает платёж.

Paymob Payment On Hold Status (default Pending): Paymob только авторизовал сумму и не списал её (спишите её в панели Paymob; заказ переходит в статус после оплаты, когда придёт callback списания); либо оплаченная сумма или валюта не совпадает с заказом; либо платёж пришёл по отменённому заказу. Примечание объясняет причину. Проверьте заказ и либо выполните его, либо верните платёж в панели Paymob.

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

Примечания — это записи во вкладке History заказа, которые покупатель не видит.

Вкладка VibeFox Paymob Pay

В Sales > Orders откройте заказ, оплаченный через Paymob. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Paymob Pay показывает каждую попытку Paymob по заказу: Paymob order с ID заказа мерчанта и страной, Paymob transaction ID, Status, запрошенную сумму Requested, Amount reported by Paymob с картой и Paymob message. Ниже показаны Notes расширения по этому заказу. Вкладка видна пользователям, имеющим доступ к расширению.

Возвраты

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

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Paymob Pay — первый блок в Extensions > Extensions > Payments > VibeFox Paymob Pay > Edit, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-payment-paymob и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Изменить ключ могут только администраторы с правом Modify для расширения. Тексты блока следуют языку админки (включены английский и русский).

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

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

Без активного ключа Paymob не показывается покупателям при оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Администратор, вошедший в админку в том же браузере, всё равно видит способ оплаты в магазине, помеченный (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать расширение до покупки ключа. В OpenCart 4 этот предпросмотр недоступен: магазин не видит вход в админку, поэтому без активного ключа способ оплаты скрыт для всех. После однократного открытия страницы Edit на Dashboard админки появляется напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются: уже начатые платежи продолжают подтверждаться.

Когда лицензия истекает, расширение продолжает работать, но обновления и поддержка требуют продления. Статус автоматически проверяется снова при открытии Dashboard или страницы Edit в админке: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Задача cron не нужна. Удаление расширения всегда удаляет лицензионный ключ и статус лицензии.

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

Paymob не появляется при оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включён, что заполнены все четыре значения (API-ключ, ID интеграции, ID iFrame, секрет HMAC) и что валюта оформления — валюта выбранной страны Paymob country. Страница настроек показывает предупреждение, если чего-то не хватает. Также проверьте, что платёжный адрес входит в выбранную Geo Zone, и что заказ достигает Total, заданного в настройках.

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

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

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

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

Открытие URL callback в браузере приводит к оформлению заказа с сообщением о невозможности проверки: это нормально. URL принимает только подписанные запросы от Paymob.

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

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

Тестовые платежи: введите ID тестовой интеграции Paymob в поле Integration ID и задайте callback-URL в этой интеграции. Для настоящих платежей введите ID рабочей интеграции снова.

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Paymob Pay. Лицензионный ключ и статус лицензии этого расширения удаляются всегда. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов в разделе Orders, которые при повторной установке возвращаются к значениям по умолчанию. В OpenCart 4 также удаляются событие OpenCart этого расширения и его startup-действие, которое пропускает callback и возврат покупателя в режиме обслуживания. Если Clean uninstall включено, удаляются остальные настройки шлюза (title, description, страна, ключи и ID, журналирование) и журнал. Если выключено, они сохраняются для повторной установки. Попытки оплаты Paymob по заказам всегда сохраняются. Существующие заказы сохраняют свои примечания об оплате и ID Paymob.

В OpenCart 4, чтобы удалить также файлы расширения, перейдите в Extensions > Installer после удаления, нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Paymob Pay в списке установленных расширений, затем Delete (красная кнопка корзины), чтобы удалить загруженный пакет.

Paymob — торговая марка её владельца. Это расширение не связано с Paymob и не одобрено Paymob.