VibeFox Midtrans for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта: індонезійська рупія (IDR). Midtrans приймає оплату лише в IDR, тому спосіб оплати пропонується лише тоді, коли валюта кошика — IDR. Конвертація валют не виконується. Якщо в магазині немає валюти IDR, додайте її в розділі International > Localization.

Обліковий запис Midtrans: вам потрібен Server Key з розділу Midtrans Dashboard > Settings > Access Keys, як у панелі sandbox, так і в робочій панелі (production). Використовується лише Server Key. Client Key для Snap Redirect не потрібен. Самі способи оплати (GoPay, QRIS, віртуальні рахунки та інші) вмикаються у вашому обліковому записі Midtrans.

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

Встановлення

1. У бек-офісі перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox Midtrans Payment Gateway у списку модулів і натисніть Configure.

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

4. Введіть Server Key і скопіюйте URL сповіщень про оплату в панель Midtrans (див. розділ Налаштування).

5. Увімкніть Enable/Disable і натисніть Save. Перевірте роботу в Sandbox, потім перемкніть Environment на Production.

Під час встановлення модуль створює два статуси замовлення: Awaiting Midtrans payment і Midtrans payment on hold. PrestaShop пропонує новий модуль оплати для всіх валют, країн і груп клієнтів. Їх можна обмежити в розділі Payment > Preferences. Модуль має залишатися дозволеним для валюти IDR.

Налаштування

Усі налаштування розміщені на сторінці модуля: Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо Server Key обраного середовища відсутній (тоді спосіб оплати приховується при оформленні замовлення) або якщо валюта магазину за замовчуванням не IDR, а також показує Sandbox mode: payments are simulated, no real money is charged., поки обрано Sandbox.

Midtrans

Enable/Disable: Enable Midtrans payments вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

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. У розділі є посилання на робочу панель і на панель sandbox.

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

Sandbox: для тестування, без реальних грошей.

Production: реальні платежі.

Production Server Key: починається з Mid-server-. Тримайте його в таємниці.

Sandbox Server Key: починається з SB-Mid-server-.

Збережені ключі більше не показуються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Clear saved keys: позначте ключ і натисніть Save, щоб його видалити. Порожнє поле зберігає збережене значення.

URL сповіщень про оплату

Сповіщення повідомляє вашому магазину, що оплату здійснено. Поле Notification URL показує URL, який потрібно використовувати. За увімкнених зрозумілих URL він має вигляд https://your-shop/module/wcp_midtrans_payment_gateway/webhook, можливо з кодом мови, наприклад /en/. Скопіюйте URL точно так, як його показують налаштування, і вставте в Midtrans Dashboard > Settings > Payment > Notification URL — у панелі sandbox і в робочій панелі, яку ви використовуєте. Якщо відкрити URL у браузері, з'явиться коротке пояснення, тож ви можете перевірити його доступність. Кнопка Test notification URL у панелі Midtrans також отримає відповідь.

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

settlement, capture (accepted): оплату здійснено. Замовлення створюється як оплачене, коли сума (у цілих рупіях) і валюта збігаються з кошиком.

capture (challenge): платіж карткою, позначений системою виявлення шахрайства Midtrans. Замовлення переходить у Midtrans payment on hold, доки ви не схвалите або не відхилите його в панелі Midtrans.

pending: покупець обрав відкладений спосіб (віртуальний рахунок, магазин у шаговій доступності) і ще не сплатив. Замовлення створюється у статусі Awaiting Midtrans payment.

expire, cancel: неоплачена транзакція прострочена або скасована. Замовлення в очікуванні переходить у Canceled, для будь-якого способу оплати. Без замовлення закривається лише спроба, і покупець може знову оплатити кошик.

deny: оплату відхилено. Замовлення в очікуванні переходить у Payment error.

failure: оплата не вдалася. Замовлення в очікуванні переходить у Payment error.

refund, partial_refund: повернення, виконане в панелі Midtrans, фіксується в замовленні.

Без URL сповіщень замовлення створюється лише тоді, коли покупець повертається до магазину після оплати, а відкладений платіж, зроблений пізніше, не буде помічено, доки покупець не повернеться.

Налаштування оплати

Midtrans приймає оплату лише в IDR, а суми передаються в цілих рупіях. Якщо рядки замовлення не сходяться з округленою сумою, до Midtrans надсилається рядок Rounding adjustment.

Status after payment: статус замовлення після підтвердженої оплати.

Processing (default): Payment accepted, стандартний статус PrestaShop для оплачених замовлень.

Completed: кожне оплачене замовлення переходить у Delivered.

On hold: кожне оплачене замовлення переходить у Midtrans payment on hold для вашої ручної перевірки. Платіж при цьому залишається зафіксованим у замовленні.

Payment page expiry (minutes): скільки часу покупець може сплатити (сторінка Snap, віртуальний рахунок тощо). Залиште порожнім або введіть 0, щоб використовувати значення Midtrans за замовчуванням. Значення, яке не є цілим числом хвилин, відхиляється з помилкою під час збереження.

Order ID prefix: додається до номера, який надсилається в Midtrans, щоб кілька магазинів могли використовувати один обліковий запис Midtrans. Номер складається з ID кошика та позначки часу, наприклад WC-123-1700000000. Дозволені лише літери, цифри та символи - _ . ~, до 20 знаків; інші символи видаляються під час збереження. Сповіщення інших магазинів ігноруються. За замовчуванням: WC-.

Додатково

Debug log: записує виклики API та сповіщення у файл logs/midtrans_p_debug.log.php у папці модуля. Файл не можна відкрити з веб-браузера. Помилки записуються завжди. Ключі та дані покупців ніколи не записуються. За замовчуванням: вимкнено.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб його очистити.

Delete data on uninstall: якщо увімкнено, під час видалення модуля видаляються його налаштування та журнал. Замовлення, їхні посилання на платежі Midtrans і повернення, а також статуси замовлень модуля завжди зберігаються, щоб старі замовлення можна було повернути й після повторного встановлення. За замовчуванням: вимкнено.

Оформлення замовлення

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Midtrans) і підтверджує. Модуль створює транзакцію Midtrans Snap на суму кошика в цілих рупіях, з рядками замовлення, доставкою, знижками, подарунковим пакуванням, податком і платіжними та адресними даними покупця, і надсилає покупця на сторінку оплати Midtrans. Там покупець обирає будь-який спосіб, увімкнений у вашому обліковому записі Midtrans. На цьому етапі замовлення ще не існує.

Після оплати покупець повертається до вашого магазину. Посилання повернення саме по собі ніколи не позначає замовлення оплаченим: замовлення позначається оплаченим лише після підтвердження Midtrans — підписаним сповіщенням або запитом до API статусу 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. Для замовлення, закритого без оплати, — Your Midtrans payment was not completed. Please contact us about this order. Якщо Midtrans недоступний, коли покупець повертається, сторінка Payment confirmation показує We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again. з кнопкою Check again.

Якщо покупець залишив сторінку Snap, не сплативши, він повертається до оформлення замовлення з повідомленням 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 тим часом оплачено, замовлення створюється і нова транзакція не робиться. Якщо замовлення вже існує і було закрито без оплати, повідомлення таке: Your Midtrans payment was declined or has expired. Please place a new order or contact us.

Якщо 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. Технічна причина записується в журнал. Кошик не в IDR показує Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.

Сповіщення працює, коли магазин перебуває в режимі обслуговування, і не блокується обмеженням за країнами вашого магазину.

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

Замовлення та повернення

Статуси замовлення

No order yet: покупця перенаправили до Midtrans, і він не сплатив, або Midtrans ще не підтвердив оплату. Існує лише кошик.

Awaiting Midtrans payment: покупець обрав відкладений спосіб (віртуальний рахунок, магазин у шаговій доступності) або почав платіж карткою, який не завершено. Замовлення стає оплаченим, коли Midtrans повідомляє про платіж.

Payment accepted, Delivered або Midtrans payment on hold: оплату підтверджено. Статус відповідає Status after payment. Платіж фіксується з ID транзакції Midtrans, а примітка показує спосіб оплати та ID замовлення в Midtrans.

Midtrans payment on hold: також встановлюється, коли платіж карткою перебуває на перевірці на шахрайство (challenge, оплату ще не зафіксовано), коли сплачена сума або валюта не збіглися із замовленням (замовлення не позначається оплаченим) або коли надходить платіж за скасоване замовлення (замовлення автоматично не відкривається знову). Примітка пояснює причину. Перевірте замовлення, потім виконайте його або поверніть платіж.

Canceled: неоплачена транзакція прострочена або скасована. Коли ви самі скасовуєте неоплачене замовлення Midtrans, його очікувана транзакція в Midtrans, наприклад виданий віртуальний рахунок, прострочується, тож її більше не можна оплатити.

Payment error: оплата не вдалася або платіж карткою, що перебував на перевірці, відхилено.

Refunded: платіж повністю повернено.

Якщо для вже оплаченого замовлення надходить другий платіж, замовлення не змінюється. Примітка просить вас повернути другий платіж у панелі Midtrans. Платіж за повернене замовлення лише додає примітку.

Блок оплати Midtrans

На сторінці замовлення показано блок Midtrans payment з ID замовлення в Midtrans, ID транзакції (з посиланням на транзакцію в панелі Midtrans середовища платежу), способом оплати, статусом, сплаченою та поверненою сумою, позначкою Sandbox для тестових платежів, історією повернень і Midtrans notes замовлення.

Повернення коштів

У блоці Midtrans payment введіть суму (підставляється сума, яку ще не повернуто), за бажання причину, і натисніть Refund via Midtrans. Підтвердьте запитання Refund this amount through Midtrans? This cannot be undone. Повні та часткові повернення підтримуються в цілих рупіях; сума з десятковими знаками відхиляється. Вам потрібне право редагувати замовлення. Можна повернути суму не більше тієї, яку Midtrans фактично списав, навіть якщо замовлення редагували пізніше. Повернення надсилається в тому середовищі, де було здійснено платіж, тож для нього має бути задано Server Key. Midtrans дозволяє повернення через API лише для окремих способів оплати та станів транзакцій (наприклад, для розрахованих платежів карткою, GoPay, QRIS або ShopeePay). Якщо Midtrans не приймає повернення, блок показує помилку, і повернення не фіксується; тоді оформіть повернення в панелі Midtrans. Успішне повернення додається до історії повернень і приміток. Повне повернення переводить замовлення у Refunded. Часткове повернення статус не змінює. Повернення доступні, коли Midtrans повідомив, що платіж розрахований.

Модуль не створює кредитових нот. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через Midtrans.

Повернення, виконані в панелі Midtrans, надходять через сповіщення і автоматично додаються до історії повернень з причиною Refunded in the Midtrans dashboard. Коли весь платіж повертається там, замовлення переходить у Refunded.

Ліцензійний ключ

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

Якщо ключ не прийнято, блок пояснює причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on з датою. Після зміни адреси магазину або після звільнення слота домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль працює далі за останнім відомим статусом.

Один ключ працює на одному домені: домені основного магазину, також у мультимагазинній конфігурації. Видалення ключа з магазину не звільняє слот домену. Звільніть слот у своєму обліковому записі vibefox.net.

Без активного ключа Midtrans не показується покупцям під час оформлення замовлення. Якщо платіж все ж розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви ввійшли в бек-офіс, тому спосіб оплати приховано і для вас: ви можете налаштувати модуль до купівлі ключа, але не можете перевірити його на оформленні замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: платежі, які вже розпочато, як і раніше підтверджуються, а повернення працюють.

Коли ліцензія спливає, модуль продовжує працювати, але оновлення та підтримка потребують продовження. Статус автоматично перевіряється знову, поки ви працюєте в бек-офісі: раз на день протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення або скидання модуля завжди видаляє ліцензійний ключ і статус ліцензії.

Усунення несправностей

Midtrans does not appear at checkout: перевірте, що ліцензія активна, що Enable/Disable увімкнено і що для обраного Environment є Server Key. Перевірте, що валюта кошика — IDR. У розділі Payment > Preferences перевірте, що модуль дозволено для IDR, для країни покупця та для його групи. Сторінка налаштувань показує попередження, якщо ключ відсутній або валюта магазину не IDR.

The payment went through, but no order was created: сповіщення не працює. Перевірте, що URL сповіщень про оплату вказано в панелі Midtrans того середовища, яким ви користуєтесь (sandbox або production), що він точно збігається з URL в Notification URL і що він доступний: відкрийте його в браузері, має з'явитися коротке пояснення. Увімкніть Debug log, щоб побачити сповіщення. Замовлення також створюється, коли покупець повертається до магазину після оплати.

Notification answers Invalid signature: сповіщення не підписано вашим Server Key Sandbox або Production. Перевірте, що ключі в налаштуваннях належать до того самого облікового запису Midtrans, що й панель, яка надсилає сповіщення.

Notification answers Server key not configured: Server Key не задано. Введіть його в налаштуваннях; Midtrans повторить сповіщення.

Notification answers Order not found — ignored: ID замовлення Midtrans видав не цей магазин, наприклад інший магазин в тому ж обліковому записі Midtrans. Призначте кожному магазину окремий Order ID prefix.

Notification answers Environment mismatch — ignored: сповіщення підписано ключем іншого середовища, ніж те, в якому здійснено платіж.

Notification answers Verification failed, please retry: API статусу Midtrans був недоступний. Midtrans повторить сповіщення.

Notification answers Busy, please retry: кошик у цей момент оновлював інший запит, або замовлення не вдалося створити (наприклад, модуль вимкнено). Midtrans повторить сповіщення. Причину дивіться в журналі.

The order is Midtrans payment on hold: прочитайте Midtrans notes у блоці. Платіж карткою перебуває на перевірці на шахрайство, сплачена сума або валюта не збігаються із замовленням, або платіж надійшов після скасування замовлення.

The customer sees an error when choosing Midtrans: перегляньте поле Log на сторінці модуля; помилки записуються завжди. Неправильний Server Key показує повідомлення, що платежі Midtrans тимчасово недоступні.

Refund fails: спосіб оплати або стан транзакції не дозволяє повернення через API; оформіть повернення в панелі Midtrans, і воно буде автоматично зафіксовано в замовленні. Якщо повідомлення каже, що для середовища, в якому сплачено замовлення, не налаштовано Server Key, введіть цей ключ і повторіть спробу.

Розробники можуть змінити дані, що надсилаються до Midtrans, за допомогою хука actionWcpMidtransSnapPayload; ID замовлення та суму змінити не можна.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Midtrans Payment Gateway і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete data on uninstall увімкнено, налаштування модуля та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для подальшого повторного встановлення. Посилання на платежі Midtrans і повернення замовлень, а також статуси замовлень Awaiting Midtrans payment і Midtrans payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна буде повернути й після повторного встановлення. Наявні замовлення зберігають свої платіжні примітки та ID транзакцій.

Midtrans — торговельна марка її власника. Цей модуль не пов'язаний з Midtrans і не схвалений нею.