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 mode: payments are simulated, no real money is charged., поки вибрано Sandbox. У списку способів оплати 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. Технічна причина додається до приміток замовлення.

Спосіб оплати працює в класичному оформленні замовлення, у блоці Checkout і на сторінці 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.