VibeFox Omise for PrestaShop — Помощь

Требования

PrestaShop: от 8.0 до 9.x.

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

HTTPS: поля карты находятся на странице оформления заказа, поэтому она должна открываться по HTTPS. Данные карты при этом всё равно никогда не попадают на ваш сервер. Omise отправляет вебхуки только на адреса HTTPS, а страница 3-D Secure банка тоже должна быть адресом 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. В панели администратора перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. По окончании загрузки нажмите Configure или позже найдите VibeFox Omise Payment в списке модулей и нажмите Configure.

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

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

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

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Omise Payment > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает 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 включает или выключает способ оплаты. По умолчанию: off.

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: использует тестовые ключи, реальные списания не выполняются. Переключаются оба ключа. Списания, возвраты и проверки статуса заказа всегда используют ключи режима, в котором был оплачен заказ. По умолчанию: on.

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

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

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

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

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

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

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

Webhook URL: адрес вебхука вашего магазина. С удобными URL он выглядит так: https://your-shop/module/wcp_omise_payment/webhook. Скопируйте его точно так, как показано в настройках, и добавьте в панели Omise в разделе Settings > Webhooks (только HTTPS). Модуль обрабатывает следующие события (они также перечислены в этом разделе):

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

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

Per-charge webhook: отправляет URL вебхука с каждым платежом. Полезно, когда несколько магазинов используют один аккаунт Omise. Работает только если магазин использует HTTPS; иначе используется вебхук из панели. По умолчанию: off.

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

Debug log: записывает запросы к API и события платежей в logs/omise_p_debug.log.php в папке модуля. Файл нельзя прочитать из веба. Ключи, токены и данные карт никогда не записываются в журнал. По умолчанию: off. Пока журнал выключен, ничего не записывается, в том числе ошибки, поэтому включайте его, когда ищете проблему.

Log: показывает размер и последние записи журнала, а также кнопку очистки.

Delete data on uninstall: если включено, при удалении модуля удаляются настройки и журнал отладки. Списания и возвраты Omise по заказам являются историей платежей и всегда сохраняются. По умолчанию: off.

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

На шаге оплаты покупатель выбирает способ оплаты (по умолчанию 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 превращает карту в одноразовый токен в браузере, используя адрес выставления счёта из корзины. Поля карты никогда не отправляются на ваш магазин. Незаполненные или неверные поля показываются под формой, например Please enter a valid card number.

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

Заказ отмечается оплаченным, только когда Omise это подтверждает: платёж должен быть списан, а его сумма и валюта должны совпадать с корзиной. Покупатель видит стандартную страницу подтверждения заказа с Your card payment has been received. При Authorize only страница говорит Your card payment has been authorized. The amount will be charged when your order is processed. Если Omise всё ещё считает платёж ожидающим, заказ создаётся в статусе Awaiting Omise payment, а страница показывает Your payment is being confirmed by Omise. You will receive an e-mail as soon as it is confirmed — please do not pay again. Если платёж не удаётся подтвердить сразу после 3-D Secure, появляется страница Payment confirmation с текстом We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again. и кнопкой Check again.

Если карта отклонена, заказ не создаётся. Покупатель остаётся на оформлении заказа с сообщением Payment failed: и причиной, например недостаточно средств, неверный код безопасности или отказ банка-эмитента карты, и может повторить попытку с той же корзиной. Если 3-D Secure не прошёл, покупатель возвращается на оформление заказа с причиной; если платёж тем временем истёк или был аннулирован, сообщение: The payment was not completed. Please try again.

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

Вебхук работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

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

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

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

No order yet: покупатель находится на 3-D Secure или карта была отклонена. Существует только корзина.

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

Omise payment authorized: карта авторизована с Authorize only. Используйте Capture payment или Void authorization.

Awaiting Omise payment: Omise ещё не подтвердил платёж. Вебхук или Sync payment status обновляет заказ.

Omise payment on hold: сумма или валюта списания не совпадают с заказом, например корзина была изменена во время 3-D Secure. Заметка показывает оба значения. Списанный платёж всё равно записывается в заказ. Проверьте заказ и выполните его или верните платёж.

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

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

Refunded: платёж полностью возвращён через модуль.

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

Блок оплаты Omise

На странице заказа показан блок Omise payment с ID списания, действием оплаты, статусом списания, брендом и последними цифрами карты, суммами списания, заказа и возврата, значком Test mode для тестовых платежей и историей возвратов. Кнопки блока требуют права редактировать заказы и секретного ключа режима, в котором была произведена оплата. Доступ к страницам модулей не нужен. Результат каждого действия показывается в верхней части блока.

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

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

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

Возвраты

В блоке Omise payment введите сумму (подставляется сумма, которая ещё не возвращена), при желании причину, и нажмите Refund via Omise. Подтвердите вопрос Refund this amount through Omise? This cannot be undone. Поддерживаются полный и частичный возврат. Возвраты выполняются в сумме и валюте, в которых Omise списал деньги, поэтому после расхождения суммы или валюты можно вернуть до той суммы, которую покупатель фактически заплатил, а не до суммы заказа. Возврат отправляется в режиме, в котором был сделан платёж, поэтому секретный ключ этого режима должен быть задан. Причина сохраняется вместе с возвратом в Omise. Успешный возврат добавляется в историю возвратов и заметки с ID возврата Omise. Полный возврат переводит заказ в статус Refunded; частичный возврат статус не меняет. Для авторизации, которая ещё не списана, возможен только полный возврат, и он аннулирует авторизацию. Если Omise отклоняет возврат, блок показывает Refund failed. с сообщением Omise, и возврат не записывается.

Модуль не создаёт кредит-ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Omise. Возвраты, сделанные в панели Omise, не записываются в PrestaShop; Sync payment status показывает сумму возвратов.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Omise Payment — первый блок на странице Modules > Module Manager > VibeFox Omise Payment > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен), а также кнопки Check now — проверить статус ещё раз, Change key — ввести другой ключ и Remove key — удалить ключ из этого магазина. Ниже находятся строка Product: presta-payment-omise и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Изменять ключ могут только сотрудники с правом Configure для модуля. Тексты блока соответствуют языку панели администратора (английский и русский включены).

Если ключ не принимается, блок объясняет причину, например Ключ не найден, Этот ключ принадлежит другому продукту, Достигнут лимит доменов или Срок действия лицензии истёк с указанием даты. После изменения адреса магазина или после освобождения слота домена в аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

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

Без активного ключа Omise не показывается покупателям при оформлении заказа. Если всё же начат платёж, покупатель видит Этот способ оплаты недоступен. Выберите другой. Витрина PrestaShop не знает, что вы вошли в панель администратора, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать на оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты продолжают работать.

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

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

Omise does not appear at checkout: проверьте, что лицензия активна, включён Enable/Disable, введены оба ключа текущего режима (тестовые в тестовом режиме, рабочие в остальных случаях) и валюта корзины входит в поддерживаемые. Страница настроек показывает предупреждение, если ключи не заполнены. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

The payment went through, but no order was created or the order stays Awaiting Omise payment: вебхук не работает. В панели Omise проверьте, что URL вебхука точно совпадает с показанным в Webhook URL и использует HTTPS. Для существующего заказа нажмите Sync payment status. Включите Debug log, чтобы увидеть ответы вебхука.

Webhook answers Charge ID does not match order or Order not found: списание в событии не было создано этим магазином для этой корзины. Ничего не меняется.

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

Webhook answers The order could not be created, retry later: заказ не удалось создать, например потому что модуль отключён. Включите Debug log, чтобы увидеть причину.

The webhook URL shows Method not allowed in the browser: это нормально. URL принимает только запросы от Omise.

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

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

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

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

Order is Omise payment on hold after payment: прочитайте заметку в заказе (см. Статусы заказа), затем выполните заказ или верните платёж.

Refund fails with a message about the mode: платёж был сделан в тестовом или рабочем режиме, а секретный ключ этого режима не задан. Введите его и повторите попытку.

Partial refund of an authorized order fails: платёж только авторизован. Сначала спишите его или верните полную сумму, чтобы аннулировать.

Удаление

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

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