VibeFox PayMongo for WooCommerce — Допомога

Вимоги

WordPress: 6.0 або новіша версія.

WooCommerce: 8.0 або новіша, встановлений і активний. Без нього плагін не активується.

PHP: 8.0 або новіша.

Валюта: філіппінське песо (PHP). Спосіб оплати приховується, якщо валюта магазину або валюта замовлення на сторінці Pay for order не PHP.

Обліковий запис PayMongo: потрібні секретні ключі API вашого облікового запису PayMongo та вебхук для кожного режиму (див. розділ Налаштування). Використовуються лише секретні ключі (sk_test_..., sk_live_...) та секрети підпису вебхуків (whsk_...). Публічні ключі не потрібні, оскільки платіжну сторінку розміщує PayMongo. Способи оплати, які ви пропонуєте, мають бути активовані у вашому обліковому записі PayMongo.

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

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

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

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > PayMongo > Manage або натисніть Settings під назвою плагіна на сторінці Plugins.

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

5. Вставте секретні ключі PayMongo, створіть вебхуки та вставте їхні секрети підпису (див. розділ Налаштування).

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

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

Усі налаштування розташовані на одній сторінці: WooCommerce > Settings > Payments > PayMongo. Над полями сторінка попереджає, якщо валюта магазину не PHP, якщо в поточному режимі немає секретного ключа (тоді PayMongo не відображається на сторінці оформлення замовлення) або секрету вебхука (тоді платежі підтверджуються лише під час повернення покупця), і показує Test mode is on: no real payments are made., поки ввімкнений тестовий режим. У списку способів оплати PayMongo позначено як такий, що потребує налаштування, доки в поточному режимі немає секретного ключа.

Загальні

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

Title: назва способу оплати, яку бачать покупці на сторінці оформлення замовлення. За замовчуванням: PayMongo (Card, GCash, GrabPay, Maya).

Description: текст, що відображається під способом оплати на сторінці оформлення замовлення. За замовчуванням: You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.

Payment methods: способи, що пропонуються на платіжній сторінці PayMongo. Обирайте лише ті, що активовані у вашому обліковому записі PayMongo, інакше PayMongo відхилить оформлення. За замовчуванням: Cards, GCash, GrabPay and Maya.

Cards (Visa, Mastercard): 3-D Secure обробляє PayMongo.

GCash, GrabPay, Maya, ShopeePay: електронні гаманці.

QR Ph: оплата за QR-кодом.

BillEase, Atome: купуйте зараз, платіть пізніше.

Direct online banking (BPI, UnionBank): оплата з банківського рахунку.

Ключі API

Скопіюйте секретні ключі з розділу PayMongo Dashboard > Developers > API keys. Публічні ключі не потрібні. Кожен ключ має починатися з очікуваного префікса. Значення з неправильним префіксом не зберігається: сторінка показує, що поле must start with має префікс, і що The previous value was kept.

Test mode: Enable test mode (no real payments). Нові платежі використовують тестові ключі. Платежі, здійснені раніше, зберігають режим, у якому були здійснені, тож перевірки статусу та повернення коштів використовують відповідний ключ. За замовчуванням: увімкнено. Вимкніть його, щоб приймати реальні платежі.

Test secret key: секретний ключ тестового режиму. Починається з sk_test_.

Test webhook secret: секрет підпису вебхука тестового режиму. Починається з whsk_.

Live secret key: секретний ключ робочого режиму. Починається з sk_live_.

Live webhook secret: секрет підпису вебхука робочого режиму. Починається з whsk_.

Webhook

Вебхук повідомляє вашому магазину, що платіж здійснено, навіть якщо покупець закрив браузер після оплати. Створіть вебхук у панелі PayMongo (або через API PayMongo) для кожного режиму, тестового та робочого, з URL, який відображається в цьому розділі налаштувань. Він має такий вигляд: https://your-site/?wc-api=paymongo_p_webhook.

Оберіть ці події:

checkout_session.payment.paid: покупець оплатив на платіжній сторінці PayMongo.

payment.paid: платіж оплачено.

payment.failed: спроба оплати не вдалася.

Скопіюйте секрет підпису (whsk_...) кожного вебхука в Test webhook secret або Live webhook secret. Вебхуки без дійсного підпису відхиляються, а режим події має збігатися з режимом підпису. Кожна подія повторно перевіряється через API PayMongo, перш ніж замовлення буде змінено. PayMongo надсилає події всього облікового запису на кожен вебхук; події платежів, створених не цим магазином, ігноруються. Без вебхука платежі підтверджуються лише тоді, коли покупець повертається до вашого магазину.

Замовлення

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

Processing: значення WooCommerce за замовчуванням (варіант за замовчуванням).

Completed: підходить для віртуальних або завантажуваних товарів, які не потребують доставки.

Додатково

Debug log: Log API calls and webhook events записує їх у WooCommerce > Status > Logs, джерело wcp_paymongo_payment_gateway. Помилки записуються завжди. Ключі та дані покупців ніколи не записуються. За замовчуванням: вимкнено.

Delete data on uninstall: Delete the settings and logs when the plugin is deleted. ID PayMongo, збережені в замовленнях, залишаються, бо вони потрібні для повернень коштів і обліку. За замовчуванням: вимкнено.

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

Покупець обирає спосіб оплати (за замовчуванням PayMongo (Card, GCash, GrabPay, Maya)) і оформлює замовлення. У тестовому режимі на сторінці оформлення замовлення відображається Test mode: no real payment will be made. Плагін створює сесію оплати PayMongo на суму замовлення в PHP, з одним рядком Order # і номером замовлення, та спрямовує покупця на платіжну сторінку PayMongo. Ім'я, e-mail, телефон і платіжна адреса покупця передаються до PayMongo. Там покупець обирає один із вибраних способів і сплачує.

Спосіб оплати показується лише для замовлень від 100,00 ₱. Замовлення з меншою сумою не можна оплатити через PayMongo.

Після оплати покупець повертається на сторінку отриманого замовлення вашого магазину. Замовлення позначається оплаченим лише після підтвердження PayMongo: плагін запитує платіж через API PayMongo, коли покупець повертається, і коли надходить вебхук. Якщо PayMongo ще обробляє платіж або недоступний, покупець однаково потрапляє на сторінку отриманого замовлення, а вебхук завершить замовлення пізніше.

Якщо покупець скасував оплату на сторінці PayMongo або не завершив її, він потрапляє на сторінку Pay for order з повідомленням You cancelled the PayMongo payment. You can try again or choose another payment method. або Your PayMongo payment was not completed. You can try again or choose another payment method. Замовлення залишається неоплаченим. Нова спроба спершу перевіряє попередню: якщо її тим часом оплачено, замовлення завершується без нового платежу; інакше попереднє посилання на оплату PayMongo стає недійсним, тож покупець не може заплатити двічі. Поки попередній платіж обробляється, покупець бачить Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again.

Якщо PayMongo не може розпочати оплату, покупець бачить коротке повідомлення, наприклад The payment could not be started. Please try again or choose another payment method. або PayMongo could not be reached. Please try again in a moment. Технічна причина додається до приміток до замовлення.

Спосіб оплати працює на класичному оформленні замовлення, у блоці Checkout і на сторінці Pay for order. Він сумісний із WooCommerce High-Performance Order Storage (HPOS).

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

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

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

Pending payment: покупця перенаправлено до PayMongo, і він ще не оплатив, або PayMongo ще не підтвердив платіж. Примітка фіксує кожну сесію оплати PayMongo, створену для замовлення. Поки PayMongo обробляє платіж, примітка про це повідомляє.

Processing або Completed: платіж підтверджено. Статус відповідає Order status after payment. Примітка до замовлення показує платіж PayMongo, суму, спосіб і режим. ID транзакції — це ID платежу PayMongo (pay_...). На екрані замовлення під платіжною адресою відображаються сесія оплати PayMongo, намір оплати і режим.

On hold: оплачена сума або валюта не збігаються із замовленням (примітка amount/currency mismatch); або платіж було здійснено в тестовому режимі, поки магазин працює в робочому, тож грошей не отримано; або платіж надійшов після скасування замовлення, наприклад через закінчення часу резервування товару. Примітка до замовлення пояснює причину. Перевірте замовлення та обробіть його або поверніть кошти за платежем.

Failed: підписаний вебхук payment.failed повідомив, що остання спроба оплати замовлення, яке очікує оплати, не вдалася. Примітка показує код і повідомлення про помилку PayMongo. Покупець може оплатити знову.

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

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

Відкрийте замовлення, натисніть Refund, введіть суму і натисніть Refund via PayMongo (Card, GCash, GrabPay, Maya) (на кнопці відображається назва вашого способу оплати). Підтримуються повні та часткові повернення. Повернення надсилається з секретним ключем режиму, у якому було здійснено платіж (тестовий або робочий), тож цей ключ має бути вказаний. Якщо PayMongo не приймає повернення, WooCommerce показує помилку, і повернення не реєструється. Успішне повернення додається до приміток замовлення разом з ID та статусом повернення PayMongo.

Повернення коштів, здійснені в панелі PayMongo, не переносяться до WooCommerce. Оформлюйте повернення з замовлення WooCommerce або створіть ручне повернення в WooCommerce.

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

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

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

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

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

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

PayMongo не відображається на сторінці оформлення замовлення: переконайтеся, що ліцензія активна, Enable/Disable увімкнено, у поточному режимі вказано секретний ключ (Test secret key у тестовому режимі, Live secret key у робочому), валюта магазину — PHP, а сума замовлення становить щонайменше 100,00 ₱. Розробники можуть змінити мінімум фільтром paymongo_p_minimum_amount.

Платіж пройшов, але замовлення залишається у статусі Pending payment: вебхук не працює, а покупець не повернувся до магазину. У панелі PayMongo перевірте, що вебхук існує в режимі, який ви використовуєте, що його URL точно збігається з показаним у налаштуваннях і що вибрано всі три події. Перевірте, що його секрет підпису вказано в потрібному полі (Test webhook secret або Live webhook secret).

Вебхук відповідає Invalid signature: секрет підпису для цього режиму відсутній або належить іншому вебхуку. Вставте секрет підпису вебхука в поле його режиму.

Вебхук відповідає Mode mismatch: тестову подію підписано як робочу або навпаки. Перевірте, що кожен вебхук належить до правильного режиму.

Вебхук відповідає Temporary error: платіж не вдалося перевірити через API PayMongo, або замовлення в цей момент обробляв інший запит. PayMongo автоматично повторює вебхук.

Значення не збережено: ключ вставили в неправильне поле. Секретні ключі починаються з sk_test_ або sk_live_, секрети вебхуків — з whsk_.

Покупець бачить помилку під час оформлення замовлення: відкрийте примітки до замовлення або перегляньте WooCommerce > Status > Logs, джерело wcp_paymongo_payment_gateway. Неправильний секретний ключ дає повідомлення, що спосіб оплати тимчасово недоступний. Спосіб оплати, не активований у вашому обліковому записі PayMongo, призводить до відмови PayMongo в оформленні; видаліть його з Payment methods.

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

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

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

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

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна видаляються завжди. Налаштування шлюзу, тимчасові дані та журнали видаляються лише тоді, коли була увімкнена опція Delete data on uninstall. Інакше вони зберігаються для повторного встановлення. Наявні замовлення зберігають свої примітки про оплату, ID транзакцій і ID PayMongo.

PayMongo є торговою маркою її власника. Цей плагін не пов'язаний із PayMongo і не схвалений компанією PayMongo.