VibeFox Midtrans for WooCommerce — Помощь

Требования

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

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

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

Валюта магазина: индонезийская рупия (IDR). Для других валют способ оплаты скрывается при оформлении заказа. Конвертации валют нет.

Аккаунт Midtrans: нужен Server Key из Midtrans Dashboard > Settings > Access Keys, из панели sandbox и из панели production. Используется только Server Key. Client Key для Snap Redirect не нужен. Сами способы оплаты (GoPay, QRIS, виртуальные счета и другие) включаются в вашем аккаунте Midtrans.

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

Установка

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

2. Нажмите Activate.

3. Установите валюту магазина: индонезийская рупия (IDR).

4. Откройте настройки: WooCommerce > Settings > Payments > Midtrans > Manage или нажмите Settings под названием плагина на странице «Плагины».

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

6. Введите Server Key и скопируйте URL уведомлений об оплате в панель Midtrans (см. Настройки).

7. Включите Enable/Disable. Проверьте работу в Sandbox, затем переключите Environment на Production.

Настройки

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Midtrans. Над полями страница предупреждает, если отсутствует Server Key выбранной среды (тогда способ оплаты скрыт при оформлении заказа) и если валюта магазина не IDR, а при выбранном Sandbox показывает Sandbox mode: payments are simulated, no real money is charged. В списке способов оплаты Midtrans помечен как требующий настройки, пока не введён Server Key, а в Sandbox отображает Test mode.

Общие

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

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

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more. В Sandbox добавляется строка SANDBOX MODE: no real money is charged.

Учётные данные API

Скопируйте Server Key из Midtrans Dashboard > Settings > Access Keys. В разделе есть ссылки на панели production и sandbox.

Environment: среда Midtrans, которую используют новые платежи. При переключении используются ключ и API выбранной среды. Заказы сохраняют среду, в которой были оплачены, для возвратов и уведомлений. По умолчанию: Sandbox.

Production Server Key: начинается с Mid-server-. Храните его в секрете.

Sandbox Server Key: начинается с SB-Mid-server-.

URL уведомлений об оплате

Уведомление сообщает вашему магазину, что платёж выполнен. В разделе показан URL, который нужно использовать. Он выглядит так: https://your-site/wc-api/midtrans_p_callback/. Вставьте его в Midtrans Dashboard > Settings > Payment > Notification URL в панели sandbox и в панели production, которую вы используете. Если открыть URL в браузере, появится краткое пояснение, так что можно проверить, что адрес доступен. Кнопка Test notification URL в панели Midtrans также получает ответ.

Каждое уведомление должно содержать действительную подпись, созданную одним из ваших Server Key, и среда ключа должна совпадать со средой заказа. Уведомления без действительной подписи отклоняются. Затем статус повторно запрашивается через API статуса Midtrans. Плагин обрабатывает следующие статусы транзакций Midtrans:

Без URL уведомлений заказ подтверждается, только если покупатель возвращается в магазин после оплаты.

Настройки оплаты

Midtrans принимает оплату только в IDR, суммы передаются в целых рупиях. Если позиции заказа не сходятся с округлённой суммой, в Midtrans отправляется строка Rounding adjustment.

Status after payment: статус заказа после подтверждённой оплаты. Статус устанавливается в один шаг, без двойных писем покупателю.

Payment page expiry (minutes): сколько времени у покупателя на оплату (страница Snap, виртуальный счёт и т. д.). Оставьте пустым или укажите 0 для значения Midtrans по умолчанию.

Order ID prefix: добавляется к номеру заказа, отправляемому в Midtrans, чтобы несколько магазинов могли использовать один аккаунт Midtrans. Только буквы, цифры и символы - _ . ~, до 20 знаков; остальные символы удаляются при сохранении. Уведомления других магазинов игнорируются. По умолчанию: WC-.

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

Debug log: Log API calls and notifications записывает в WooCommerce > Status > Logs, источник wcp_midtrans_payment_gateway. Ошибки записываются всегда. Ключи и данные покупателей никогда не записываются. По умолчанию: off.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (deactivation keeps everything). Order data is kept. По умолчанию: off.

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

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

После оплаты покупатель возвращается на страницу подтверждения заказа в вашем магазине. Сама ссылка возврата никогда не отмечает заказ оплаченным: плагин запрашивает API статуса Midtrans, и заказ отмечается оплаченным только после подтверждения Midtrans. Пока оплата не подтверждена, страница показывает We are waiting for Midtrans to confirm your payment. If you chose a bank transfer, virtual account or convenience store, please complete the payment using the instructions from Midtrans. You will receive an e-mail once the payment is confirmed. Страница также показывает использованный способ оплаты.

Если оплата не была завершена, покупатель переходит на страницу Pay for order с сообщением The Midtrans payment was not completed. You can try again below. Если платёж был отклонён или истёк, сообщение: Your Midtrans payment was declined or has expired. Please try again or choose another payment method. Когда покупатель платит снова, повторно используется неиспользованный или ожидающий Snap на ту же сумму. Если сумма изменилась, сначала в Midtrans истекает ожидающая транзакция. Если предыдущий Snap тем временем был оплачен, заказ подтверждается и новая транзакция не создаётся.

Если Midtrans не может начать оплату, покупатель видит Could not connect to Midtrans. Please try again in a moment., Midtrans payments are temporarily unavailable. Please choose another payment method or contact us. (например, при неверном Server Key) или причину от Midtrans. Техническая причина добавляется в примечания к заказу.

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

Плагин использует только Snap Redirect. У него нет всплывающего окна Snap, формы карты на вашем сайте, сохранённых карт и платежей в один клик, настроек рассрочки или промоакций (способы оплаты настраиваются в панели Midtrans) и WooCommerce Subscriptions. Платежи картами списываются сразу, без раздельной авторизации и списания.

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

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

Pending payment: покупатель отправлен в Midtrans и ещё не выбрал способ оплаты.

On hold: покупатель выбрал отложенный способ и ещё не оплатил, платёж картой находится на проверке мошенничества (challenge), или сумма либо валюта оплаты не совпали с заказом. Статус «На удержании» также ставится, если платёж пришёл на отменённый заказ; заказ автоматически не открывается заново. Примечание к заказу объясняет причину.

Processing, Completed or On hold after payment: оплата подтверждена. Статус соответствует Status after payment. Примечание к заказу показывает способ оплаты и идентификаторы Midtrans. ID транзакции — это ID транзакции Midtrans, и на экране заказа он ведёт к транзакции в панели Midtrans той среды, где оплачен заказ.

Failed: оплата не прошла или платёж картой на проверке был отклонён.

Cancelled: неоплаченная транзакция истекла или была отменена. Товар возвращается на склад. Если вы отменяете неоплаченный заказ Midtrans в WooCommerce (или это делает таймер неоплаченных заказов), его ожидающая транзакция Midtrans, например выпущенный виртуальный счёт, истекает, чтобы его уже нельзя было оплатить.

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

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Midtrans (на кнопке отображается ваше Title). Полные и частичные возвраты поддерживаются в целых рупиях; сумма с десятичными знаками отклоняется. Возврат отправляется в среде, где был оплачен заказ, поэтому Server Key этой среды должен быть задан. Midtrans разрешает возвраты через API только для некоторых способов оплаты и состояний транзакций (например, для расчётных платежей картой, GoPay, QRIS или ShopeePay). Если Midtrans не принимает возврат, WooCommerce показывает ошибку и возврат не записывается; тогда оформите возврат в панели Midtrans. Успешный возврат добавляется в примечания к заказу.

Возвраты, оформленные в панели Midtrans, приходят через уведомление и автоматически записываются как возвраты WooCommerce с причиной Refunded in the Midtrans dashboard.

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

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

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

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

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

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

Midtrans не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён и у выбранной Environment есть Server Key. Проверьте, что валюта магазина (или валюта заказа на странице Pay for order) — IDR. Страница настроек показывает предупреждение для каждой из этих проблем.

Платёж прошёл, но заказ остаётся в статусе Pending payment: уведомление не работает. Проверьте, что URL уведомлений об оплате указан в панели Midtrans нужной среды (sandbox или production) и что он доступен: откройте его в браузере, появится краткое пояснение. Включите Debug log, чтобы видеть уведомления. Заказ также подтверждается, когда покупатель возвращается в магазин после оплаты.

Уведомление отвечает Invalid signature: уведомление не подписано вашим Sandbox или Production Server Key. Проверьте, что ключи в настройках принадлежат тому же аккаунту Midtrans, что и панель, которая отправляет уведомления.

Уведомление отвечает Server key not configured: Server Key не задан. Введите его в настройках; Midtrans повторит уведомление.

Уведомление отвечает Order not found — ignored: ID заказа Midtrans не принадлежит заказу этого магазина, например, он из другого магазина на том же аккаунте Midtrans. Задайте каждому магазину свой Order ID prefix.

Уведомление отвечает Environment mismatch — ignored: уведомление подписано ключом другой среды, а не той, в которой оплачен заказ.

Уведомление отвечает Verification failed, please retry: API статуса Midtrans недоступен. Midtrans повторит уведомление.

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

Покупатель видит ошибку при оформлении заказа: откройте примечания к заказу или включите Debug log и посмотрите WooCommerce > Status > Logs, источник wcp_midtrans_payment_gateway. Заказ не в IDR выдаёт Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.

Возврат не проходит: способ оплаты или состояние транзакции не допускают возвратов через API; оформите возврат в панели Midtrans, и он автоматически запишется в WooCommerce. Если сообщение говорит, что для среды, в которой оплачен заказ, не задан Server Key, введите этот ключ и повторите попытку.

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

Удаление

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

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