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

Вимоги

PrestaShop: від 8.0 до 9.x.

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

Валюта: філіппінське песо (PHP). PayMongo показується на оформленні замовлення лише для кошиків у PHP. Якщо основна валюта вашого магазину не PHP, на сторінці налаштувань з'явиться попередження, і покупцям потрібно перемкнутися на PHP, щоб побачити PayMongo.

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

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

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

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

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

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

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

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

Під час встановлення модуль створює два статуси замовлення: Awaiting PayMongo payment і PayMongo payment on hold. У Payment > Preferences перевірте, що модуль дозволений для філіппінського песо, країн ваших покупців і їхніх груп.

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо основна валюта магазину не 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.

Ключі 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_.

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

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

Webhook

Вебхук повідомляє вашому магазину, що платіж здійснено, у тому числі коли покупець закрив браузер після оплати. Створіть вебхук у панелі PayMongo (або через API PayMongo) для кожного режиму, тестового та робочого, з URL, який показано в полі Webhook URL у цьому розділі. З увімкненими ЧПУ URL виглядає так: https://your-shop/module/wcp_paymongo_payment_gateway/webhook, можливо, з кодом мови, наприклад /en/. Скопіюйте URL точно так, як він показаний у налаштуваннях.

Оберіть ці події (вони також перелічені в цьому розділі):

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

Замовлення

Order status after payment: статус замовлення, який встановлюється після успішної оплати.

Платежі, які ще обробляються, очікують у статусі Awaiting PayMongo payment. Невідповідності суми чи валюти та тестові платежі в робочому магазині завжди потрапляють у PayMongo payment on hold.

Додатково

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

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням PayMongo (Card, GCash, GrabPay, Maya)) і бачить його опис. У тестовому режимі оформлення замовлення також показує Test mode: no real payment will be made. PayMongo пропонується лише для кошиків у PHP із сумою щонайменше 100,00 ₱.

Після підтвердження модуль створює PayMongo Checkout Session на суму кошика в PHP, з одним рядком Cart # і номером кошика, і надсилає покупця на платіжну сторінку PayMongo. Ім'я, e-mail, телефон і платіжна адреса покупця передаються до PayMongo. Там покупець обирає один із вибраних способів і сплачує. На цьому етапі замовлення ще не існує.

Після оплати покупець повертається до вашого магазину. Замовлення позначається як оплачене лише після підтвердження PayMongo: модуль запитує в API PayMongo інформацію про платіж, коли покупець повертається і коли надходить вебхук. Тоді замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення з Your PayMongo payment has been received. Якщо PayMongo ще обробляє платіж, коли покупець повертається, замовлення створюється в статусі Awaiting PayMongo payment, а на сторінці показується PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. Якщо цей платіж згодом не вдасться, сторінка показує Your PayMongo payment was not completed. Please contact us about this order. Якщо PayMongo недоступний, коли покупець повертається, з'являється сторінка Payment confirmation, яка просить покупця не платити повторно, і кнопка Check again; вебхук створює замовлення, щойно він надійде.

Якщо покупець скасовує оплату на сторінці PayMongo або не завершує платіж, він повертається до оформлення замовлення з повідомленням 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. Технічна причина записується в журнал.

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

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

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

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

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

Payment accepted or Delivered: платіж підтверджено. Статус відповідає Order status after payment. Платіж записується з ідентифікатором PayMongo (pay_...) як ID транзакції, а примітка показує платіж, суму, спосіб, режим і те, як його було підтверджено (вебхуком чи поверненням).

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

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

Payment error: підписаний вебхук payment.failed повідомив, що остання спроба оплати замовлення в статусі Awaiting PayMongo payment не вдалася. Примітка показує код і повідомлення про помилку PayMongo. Якщо та сама оплата згодом пройде успішно, замовлення переходить в оплачений статус.

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

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

Блок PayMongo payment

На сторінці замовлення показано блок PayMongo payment з ідентифікатором і способом платежу PayMongo, payment intent, checkout, режимом, статусом, сплаченою сумою та сумою повернення, позначкою Test mode для тестових платежів, примітками PayMongo щодо замовлення та історією повернень.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вебхук відповідає Busy, retry: замовлення в цей момент підтверджував інший запит, або замовлення не вдалося створити (наприклад, модуль вимкнено). PayMongo автоматично повторює вебхук. Причина вказана в Log.

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

URL вебхука в браузері показує Method not allowed: це нормально. URL приймає лише запити від PayMongo.

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

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

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

Замовлення в PayMongo payment on hold після оплати: прочитайте примітки в блоці PayMongo payment (див. Статуси замовлення), потім опрацюйте замовлення або поверніть платіж.

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

Розробники можуть змінити дані Checkout Session за допомогою хука actionPaymongoPCheckoutSessionData.

Видалення

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

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