VibeFox Paymob for WooCommerce — Помощь

Требования

WordPress: 6.2 или новее.

WooCommerce: 8.0 или новее, установлен и активен. Без него плагин не активируется.

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

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

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

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

Установка

1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-архив плагина и нажмите Install Now. Можно также загрузить папку wcp_paymob_pay в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > Paymob > Manage или нажмите Settings под названием плагина на странице Plugins.

4. Введите лицензионный ключ VibeFox в блоке лицензии в верхней части страницы и нажмите Activate.

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

6. В панели управления Paymob укажите URL колбэков вашей интеграции — тот, что показан на странице настроек (см. раздел Callbacks).

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

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Paymob. Над полями страница предупреждает, если не заполнено одно из четырёх значений Paymob (до этого Paymob не отображается на странице оформления заказа), и если валюта магазина не принимается выбранной страной Paymob. В блоке показан URL колбэка с кнопкой Copy и ссылка на панель управления Paymob выбранной страны.

Общие

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

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

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

Учётная запись 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. Обязательное поле: заказы помечаются оплаченными только по колбэкам, подписанным этим секретом.

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

Callbacks

Paymob передаёт информацию о каждой транзакции в ваш магазин. В панели управления Paymob откройте Developers > Payment Integrations, выберите свою интеграцию, нажмите Edit и укажите и в Transaction processed callback, и в Transaction response callback URL, который показан на странице настроек. Он выглядит так: https://your-site/wc-api/paymob_pay/. Скопируйте его кнопкой Copy. Укажите URL во всех используемых интеграциях, включая тестовую.

Колбэк обработанной транзакции отправляется серверами Paymob. Колбэк ответа на транзакцию возвращает покупателя в ваш магазин. Оба подписаны вашим секретом HMAC и проверяются плагином. Колбэки без корректной подписи отклоняются и ничего не меняют. Если серверный колбэк опоздал или потерян, подтверждает оплату и подписанный возврат покупателя.

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

Debug log: Log payment steps and callbacks записывает шаги оплаты и колбэки в WooCommerce > Status > Logs, источник wcp_paymob_pay. Ошибки и отклонённые колбэки записываются всегда. Ключи, токены и данные покупателей никогда не записываются. По умолчанию: выкл.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. Деактивация плагина ничего не удаляет. ID Paymob, сохранённые в заказах, остаются. По умолчанию: выкл.

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

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

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

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

Способ оплаты работает на классическом оформлении заказа, в блоке оформления заказа и на странице Pay for order. На странице Pay for order проверяется валюта заказа, а не валюта магазина. Плагин совместим с WooCommerce High-Performance Order Storage (HPOS).

Плагин принимает разовые платежи на странице Paymob. В нём нет сохранённых карт, подписок, встроенной формы карты на вашем сайте и возвратов из WooCommerce.

Заказы

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

Pending payment: покупатель был отправлен в Paymob и ещё не оплатил, или Paymob ещё не подтвердил платёж.

Processing: Paymob подтвердил оплату. Заказы, в которых есть только виртуальные загружаемые товары, переходят в статус «Выполнен» — значение WooCommerce по умолчанию. В примечании к заказу указаны транзакция Paymob, сумма и тип карты с последними четырьмя цифрами. ID транзакции — это ID транзакции Paymob.

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

Failed: Paymob отклонил платёж по ожидающему заказу. Покупатель может оплатить снова.

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

Возвраты

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

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

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится в верхней части страницы WooCommerce > Settings > Payments > Paymob. Вставьте ключ в поле License key и нажмите Activate. В блоке отображается статус, например дата окончания действия лицензии, и ваш домен. Нажмите Check now, чтобы проверить статус ещё раз, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить его с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

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

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

Когда срок лицензии истекает, плагин продолжает работать, но обновления и поддержка требуют продления. Статус автоматически проверяется в фоновом режиме.

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

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

Платёж прошёл, но заказ остаётся в статусе Pending payment: колбэки не доходят до вашего магазина. Проверьте, что Transaction processed callback и Transaction response callback используемой интеграции в точности совпадают с URL на странице настроек, и что HMAC secret принадлежит той же учётной записи Paymob. Отклонённые колбэки записываются как предупреждения в WooCommerce > Status > Logs, источник wcp_paymob_pay, даже если журнал отладки выключен.

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

Колбэк отвечает Not configured: секрет HMAC пуст. Введите секрет; Paymob повторит колбэк.

Колбэк отвечает locked: заказ в тот же момент обновлялся другим запросом, например возвратом покупателя. Paymob повторит колбэк.

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

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

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

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите слот в аккаунте на vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза и журналы удаляются, только если была включена опция Clean uninstall. Иначе они сохраняются для повторной установки. Существующие заказы сохраняют свои примечания об оплате, ID транзакций и ID Paymob.

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