VibeFox Omise for WooCommerce — Помощь

Требования

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

WooCommerce: 8.0 или новее, установлен и активен. Плагин не активируется без него; если WooCommerce отключить позже, шлюз не загружается и показывается уведомление администратора.

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

HTTPS: поля карты находятся на вашей странице оформления заказа, поэтому она должна открываться по HTTPS и не содержать недоверенных скриптов. Данные карты всё равно никогда не попадают на ваш сервер. Omise отправляет вебхуки только на адреса HTTPS.

Валюта магазина: одна из THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD. Для других валют способ оплаты скрывается при оформлении заказа.

Учётная запись Omise: нужны открытый и секретный ключи вашей учётной записи Omise для тестового и рабочего режимов; их можно найти в разделе Settings > Keys панели Omise. Также нужна конечная точка вебхука в разделе Settings > Webhooks (см. раздел «Настройка»).

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

Установка

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

2. Нажмите Activate.

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

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

5. Введите тестовые и рабочие ключи Omise и добавьте в панели Omise URL вебхука, который показан на странице настроек (см. раздел «Настройка»).

6. Включите Enable/Disable. Проверьте оплату в тестовом режиме тестовой картой Omise, например 4242 4242 4242 4242, а затем снимите отметку с Test mode.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Omise. Над полями страница показывает Test mode is on — orders are charged with the test keys, no real money is moved., пока включён тестовый режим, и предупреждает, если не заполнен открытый или секретный ключ текущего режима либо если валюта магазина не поддерживается Omise. В обоих случаях способ оплаты скрывается при оформлении заказа. В списке способов оплаты Omise отмечен как требующий настройки, пока не заполнены оба ключа текущего режима.

Общие

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

Title: название способа оплаты, которое видят покупатели при оформлении заказа. По умолчанию: Credit / Debit Card.

Description: текст над формой карты при оформлении заказа. По умолчанию: Pay securely with your credit or debit card via Omise.

Ключи API

Ключи находятся в панели Omise в разделе Settings > Keys. Тестовые ключи начинаются с pkey_test_ и skey_test_, рабочие — с pkey_ и skey_. При сохранении ключ с неверным префиксом (например, тестовый ключ в поле рабочего) отклоняется с ошибкой, и сохраняется прежнее значение.

Test mode: Use the test keys (no real charges). Переключает оба ключа. Возвраты, списания и проверки статуса заказа всегда используют ключи режима, в котором был оплачен заказ. По умолчанию: включено.

Test public key: открытый ключ тестового режима, pkey_test_...

Test secret key: секретный ключ тестового режима, skey_test_...

Live public key: открытый ключ рабочего режима, pkey_...

Live secret key: секретный ключ рабочего режима, skey_...

Оплата и вебхук

В этом разделе показан URL вебхука вашего магазина. Он выглядит примерно так: https://your-site/wp-json/omise-payment/v1/webhook. Скопируйте его точно так, как показано в настройках, и добавьте в панели Omise в разделе Settings > Webhooks (только HTTPS). Плагин обрабатывает эти события:

Содержимое вебхука никогда не считается достоверным: платёж должен совпадать с сохранённым в заказе, а его статус повторно запрашивается через API Omise с ключами режима заказа. Без вебхука заказ, у которого покупатель закрыл браузер во время 3-D Secure, остаётся На удержании, пока вы не запустите Omise: Sync payment status, а списания, сделанные в панели Omise, не подхватываются автоматически.

Payment action: что происходит с суммой на карте.

Per-charge webhook: Send the webhook URL with every charge. Полезно, когда несколько магазинов используют одну учётную запись Omise. Работает только если сайт использует HTTPS; иначе используется вебхук из панели. По умолчанию: отключено.

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

Debug log: Log API requests and payment events записывает шаги оплаты в WooCommerce > Status > Logs, источник wcp_omise_payment. Ключи, токены и данные карт никогда не записываются в журнал. По умолчанию: отключено.

Delete data on uninstall: Remove the settings and debug logs when the plugin is deleted. По умолчанию: отключено.

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

Покупатель выбирает способ оплаты (по умолчанию Credit / Debit Card) и заполняет форму карты: Name on card, Card number, Expiry month (MM), Expiry year (YYYY) и Security code (CVV). В тестовом режиме форма показывает TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made.. При оформлении заказа Omise.js в браузере превращает карту в одноразовый токен. Поля карты никогда не передаются на ваш сервер.

Ваш магазин создаёт платёж с секретным ключом на сумму заказа в валюте заказа. Описание платежа — название магазина и номер заказа, а ID заказа сохраняется в метаданных платежа. Если банк требует 3-D Secure, покупатель перенаправляется в банк и обратно в ваш магазин. Результат всегда повторно запрашивается через API Omise.

Заказ отмечается оплаченным только после подтверждения Omise: платёж должен быть списан, а его сумма и валюта должны совпадать с заказом. При Authorize only заказ переходит в На удержании после успешной авторизации. Покупатель видит страницу «Заказ получен».

Если карта отклонена, покупатель остаётся на оформлении заказа с сообщением Payment failed: и причиной, например недостаточно средств, неверный код безопасности или отказ банка-эмитента, и может повторить попытку. После неудачного 3-D Secure покупатель переходит на страницу Pay for order. Если оплату не удаётся подтвердить сразу после 3-D Secure, покупатель видит We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again.

Повторная попытка никогда не списывает деньги дважды: если предыдущий платёж заказа уже оплачен или авторизован, заказ завершается без нового списания. Незавершённая попытка 3-D Secure аннулируется до создания нового платежа.

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

Плагин принимает только карты. В нём нет других способов оплаты Omise (PromptPay, TrueMoney, мобильный банкинг, рассрочка, Konbini, PayNow), нет сохранённых карт и клиентов Omise, подписок и частичного списания.

Заказы и возвраты

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

Ожидает оплаты: покупатель на странице 3-D Secure или ещё не оплатил заказ.

В обработке: оплата подтверждена. Заказы только с виртуальными загружаемыми товарами переходят в статус «Выполнен», как обычно в WooCommerce. В заметке к заказу указаны сумма, ID платежа и способ подтверждения (оформление заказа, возврат с 3-D Secure, вебхук, ручное списание или ручная синхронизация). ID транзакции — это ID платежа Omise (chrg_...).

На удержании, ожидает списания: карта авторизована с помощью Authorize only. Используйте Omise: Capture payment или Omise: Void authorization.

На удержании, ожидает подтверждения: Omise ещё не подтвердила оплату, например покупатель закрыл браузер во время 3-D Secure. Заказ обновят вебхук или Omise: Sync payment status.

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

Неудачный: оплата отклонена. Оплаченный заказ никогда не переводится в более низкий статус из-за последующего события об ошибке.

Отменён: срок платежа истёк или авторизация отменена.

Если для уже отменённого или возвращённого заказа приходит оплаченный или авторизованный платёж, заказ не переоткрывается. Заметка просит вас проверить панель Omise и вручную вернуть оплату или переоткрыть заказ.

Действия с заказом

Omise: Capture payment: списывает всю авторизованную сумму. Показывается только для авторизованных заказов.

Omise: Void authorization: отменяет авторизацию; деньги не списываются, заказ отменяется. Показывается только для авторизованных заказов.

Omise: Sync payment status: считывает платёж из Omise и обновляет заказ. В заметке также показана общая сумма возвратов в Omise.

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Omise. Поддерживаются полный и частичный возвраты. Возврат отправляется в режиме, в котором была произведена оплата, поэтому секретный ключ этого режима должен быть заполнен. Успешный возврат добавляется в заметки заказа вместе с ID возврата Omise. Для непроведённой авторизации возможен только полный возврат, и он отменяет авторизацию. Если Omise отклоняет возврат, WooCommerce показывает Refund failed. с сообщением Omise, и возврат не регистрируется.

Возвраты, сделанные в панели Omise, не импортируются как возвраты WooCommerce. Omise: Sync payment status показывает сумму возвратов; при необходимости создайте соответствующие ручные возвраты в WooCommerce.

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

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

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

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

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

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

Omise не отображается при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён, заполнены оба ключа текущего режима (тестовые в тестовом режиме, иначе рабочие) и валюта поддерживается. На странице Pay for order учитывается валюта заказа. На странице настроек появляется предупреждение, если ключи или валюта неверны.

Оплата прошла, но заказ остаётся в статусе Ожидает оплаты или На удержании: вебхук не работает. В панели Omise проверьте, что URL вебхука точно совпадает с показанным в настройках и использует HTTPS. Затем выполните Omise: Sync payment status для заказа. Включите Debug log, чтобы видеть ответы вебхука.

Вебхук отвечает Earlier charge of the order, order not changed: событие относится к более ранней попытке заказа, которая была заменена повторной. В заказе ничего не меняется. Если этот более ранний платёж в Omise всё ещё оплачен или авторизован, одна заметка к заказу сообщит об этом: проверьте панель Omise на двойную оплату и верните или отмените её там.

Вебхук отвечает Charge ID does not match order: платёж в событии принадлежит другому заказу. Ничего не меняется.

Вебхук отвечает Order is being processed, retry later или Failed to verify charge: заказ был заблокирован другим запросом, или API Omise было недоступно. Omise повторит вебхук.

Ошибка при сохранении: key must start with ... или must be a live key: ключ вставлен в неверное поле. Тестовые ключи начинаются с pkey_test_ / skey_test_, рабочие — с pkey_ / skey_.

Покупатель видит Card payments are temporarily unavailable: ключи неверны или токен карты относится к другому режиму (тестовый токен в рабочем режиме или наоборот). Проверьте ключи и Test mode.

Покупатель видит We could not reach the payment provider: при создании платежа от Omise не пришёл корректный ответ. Платёж мог быть создан; заметка к заказу просит проверить панель Omise, прежде чем списывать деньги за заказ повторно.

Покупатель видит This order is already being paid: оформление заказа было отправлено дважды одновременно. Покупателю нужно подождать и проверить электронную почту, прежде чем пробовать снова.

Заказ На удержании после оплаты: прочитайте заметку к заказу. Заказ ждёт списания, Omise ещё не подтвердила оплату, или сумма либо валюта отличаются от заказа.

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

Частичный возврат авторизованного заказа не выполняется: оплата только авторизована. Сначала спишите её или верните полную сумму, чтобы отменить авторизацию.

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

Удаление

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

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